CLI 스크립팅과 자동화

ant CLI 위에 세운 작업 중심 워크플로를 알아보아요. API 리소스를 파일로 버전 관리하고, 스크립트에서 CLI 명령을 연결하고, Claude Code에서 리소스를 다루거나, CLI 자격 증명으로 curl 호출을 인증하는 방법을 다뤄요. 기본 플래그와 출력 옵션은 CLI 사용하기를 참고하세요.

출처: 문서

본문

API 리소스를 코드로 버전 관리하기

에이전트, 환경, 그 밖의 Claude Managed Agents 리소스를 저장소의 파일로 유지하려면 ant apply로 리소스를 코드로 관리하기를 참고하세요.

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

에이전트와 환경이 준비되면 셸에서 세션을 구동할 수 있어요:

세션 생성 명령에 에이전트와 환경 ID를 넘기세요. `ant apply` 이후에는 `claude-lock.json`에서 읽어요. `resources` 아래의 각 항목에 `id`가 있고, [ant apply로 리소스를 코드로 관리하기](https://platform.claude.com/docs/en/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"
  /* ... */
}
```

이전 출력에서 세션 `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."}]}'
```

에이전트가 답하면 이벤트를 나열하세요. `--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>

스크립팅 패턴

CLI는 표준 셸 도구와 조합되도록 설계됐어요.

목록 출력을 다음 명령으로 연결하기

목록 엔드포인트에서 --transform id --raw-output는 줄마다 하나의 순수 ID를 출력하므로 head, xargs 같은 표준 도구가 바로 적용돼요. 첫 결과를 잡아 후속 명령으로 넘기세요:

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을 쓰세요. 오류 메시지만 추출해 봐요:

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

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

Claude Code에서 CLI 사용하기

Claude Code는 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이 저장한 자격 증명을 쓸 수 있어요. OAuth 액세스 토큰은 bearer 토큰으로 Authorization 헤더에 들어가요. x-api-key 헤더는 정적 API 키 전용이에요.

ant auth print-credentials --access-token은 활성 프로파일의 액세스 토큰을 출력하며, 만료됐거나 만료가 가까우면 먼저 갱신해요:

curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer *** 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"}]
  }'

CLI 로그인으로 작업할 때는 `ANTHROPIC_API_KEY`와 `ANTHROPIC_AUTH_TOKEN`을 설정하지 않은 채로 두세요. 두 변수는 `ant` 명령에서 로그인보다 우선하며(자격 증명 우선순위 참고), 조용히 다른 조직이나 워크스페이스로 라우팅될 수 있어요.

어느 조직과 워크스페이스로 로그인했는지 확인하려면 ant auth status를 실행하세요. 환경 변수가 로그인을 덮어쓰고 있으면 경고해 줘요.

CLI 스크립팅과 자동화