---
title: CLI 스크립팅 및 자동화
url: https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/scripting
description: ant apply로 API 리소스를 파일로 버전 관리하고, 스크립트에서 ant CLI 명령을 연결하고, Claude Code에서 리소스를 조작하고, CLI 자격 증명으로 curl 호출을 인증합니다.
---

이 페이지는 `ant` CLI를 기반으로 구축된 작업 중심 워크플로를 다룹니다. 기본 플래그 및 출력 옵션에 대해서는 [CLI 사용하기](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/using)를 참조하세요.

## API 리소스 버전 관리

에이전트, 환경 및 기타 Claude Managed Agents 리소스를 저장소에 파일로 보관하려면 [ant apply로 리소스를 코드로 관리하기](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/apply)를 참조하세요.

### 셸에서 적용된 에이전트 실행하기

에이전트와 환경이 생성되면 셸에서 세션을 진행할 수 있습니다:

<Steps>
  <Step title="세션 시작하기">
    에이전트 ID와 환경 ID를 세션 생성 명령에 전달합니다. `ant apply` 실행 후에는 `claude-lock.json`에서 이 ID를 읽어 옵니다. `resources` 아래의 각 항목에는 `id`가 있으며, [ant apply로 리소스를 코드로 관리하기](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/apply)의 프로젝트에서는 해당 항목이 `./agents/summarizer.md`와 `./environments/cloud.yaml`입니다.

    ```bash
    ant beta:sessions create \
      --agent agent_011CYm1BLqPXpQRk5khsSXrs \
      --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
      --title "Summarization task"
    ```

    ```json Output
    {
      "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
      "status": "running"
      /* ... */
    }
    ```
  </Step>

  <Step title="사용자 메시지 보내기">
    이전 출력의 세션 `id`를 `--session-id`에 복사합니다:

    ```bash
    ant beta:sessions:events send \
      --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
      --event '{type: user.message, content: [{type: text, text: "Summarize the benefits of type safety in one sentence."}]}'
    ```
  </Step>

  <Step title="대화 읽기">
    에이전트가 응답하면 이벤트 목록을 조회합니다. `--transform`은 조회된 각 이벤트에 대해 실행되므로, 이 명령은 모든 메시지의 텍스트를 순서대로 출력합니다. `--format auto`는 터미널에서 목록 명령이 기본적으로 여는 대화형 탐색기를 재정의합니다:

    ```bash
    ant beta:sessions:events list \
      --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
      --transform 'content.0.text' \
      --raw-output \
      --format auto
    ```

    ```text Output wrap
    Summarize the benefits of type safety in one sentence.
    Type safety catches errors at compile time rather than runtime, reducing bugs, improving code clarity, enabling better tooling support, and making codebases easier to maintain and refactor with confidence.
    ```

    <Tip>
      실행 중인 세션을 지켜보려면 `ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K --format jsonl`을 사용하세요. 이 명령은 각 이벤트가 도착하는 대로 stdout에 기록합니다. `--format`을 지정하지 않으면 터미널에서 대신 대화형 탐색기가 열립니다.
    </Tip>
  </Step>
</Steps>

## 스크립팅 패턴

CLI는 표준 셸 도구와 조합하여 사용할 수 있도록 설계되었습니다.

### list 출력을 두 번째 명령으로 연결하기

list 엔드포인트에서 `--transform id --raw-output`을 사용하면 한 줄에 하나의 ID만 출력되므로, `head` 및 `xargs`와 같은 표준 도구를 바로 적용할 수 있습니다. 첫 번째 결과를 캡처한 다음 후속 명령에 전달합니다:

```bash
FIRST_AGENT=$(ant beta:agents list --transform id --raw-output | head -1)

ant beta:agents:versions list \
  --agent-id "$FIRST_AGENT" \
  --transform "{version,created_at}" --format jsonl
```

### 오류 검사하기

`--transform-error` 및 `--format-error` 플래그는 오류 응답에 동일한 필터링을 적용합니다. `--raw-output`은 오류에 적용되지 않으므로, 따옴표 없는 스칼라 값을 얻으려면 `--format-error yaml`을 사용하세요. 오류 메시지만 추출합니다:

```bash
ant beta:agents retrieve --agent-id bogus \
  --transform-error error.message --format-error yaml 2>&1
```

```text Output wrap
GET "https://api.anthropic.com/v1/agents/bogus?beta=true": 404 Not Found
Agent not found.
```

## Claude Code에서 CLI 사용하기

[Claude Code](https://code.claude.com/docs/ko/overview)는 별도 설정 없이 `ant` CLI를 사용할 수 있습니다. CLI가 설치되고 인증되어 있으면 Claude Code에 API 리소스를 직접 조작하도록 요청할 수 있습니다. 예를 들어:

* "최근 에이전트 세션을 나열하고 어떤 세션에서 오류가 발생했는지 요약해 줘."
* "`./reports`에 있는 모든 PDF를 Files API에 업로드하고 결과 ID를 출력해 줘."
* "세션 `session_01...`의 이벤트를 가져와서 에이전트가 어디에서 막혔는지 알려 줘."

Claude Code는 `ant`를 셸에서 실행하고, 구조화된 출력을 파싱하며, 결과를 바탕으로 추론합니다(별도의 통합 코드가 필요하지 않습니다).

## CLI 자격 증명으로 curl 요청 인증하기

`curl` 또는 다른 HTTP 클라이언트로 API를 호출하는 스크립트는 정적 API 키 대신 [`ant auth login`](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/quickstart#authentication)으로 저장된 자격 증명을 사용할 수 있습니다. OAuth 액세스 토큰은 `Authorization` 헤더에 bearer 토큰으로 들어가며, `x-api-key` 헤더는 정적 API 키 전용입니다.

`ant auth print-credentials --access-token`은 활성 프로필의 액세스 토큰을 출력하며, 토큰이 만료되었거나 만료가 임박한 경우 먼저 갱신합니다:

```bash cURL
curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "hi"}]
  }'
```

<Note>
  CLI 로그인으로 작업할 때는 `ANTHROPIC_API_KEY`와 `ANTHROPIC_AUTH_TOKEN`을 설정하지 않은 상태로 유지하세요. 두 변수 중 어느 것이든 `ant` 명령에 대해 로그인보다 우선 적용되며([자격 증명 우선순위](https://platform.claude.com/docs/ko/manage-claude/wif-reference#credential-precedence) 참조), 명령을 다른 조직이나 워크스페이스로 조용히 라우팅할 수 있습니다.
</Note>

[`ant auth status`](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/authentication#check-authentication-status)를 실행하여 어떤 조직과 워크스페이스에 로그인되어 있는지 확인하세요. 환경 변수가 로그인을 재정의하고 있는 경우 경고를 표시합니다.