CLI, SDK 및 라이브러리ant CLI

CLI 스크립팅 및 자동화

API 리소스를 YAML로 버전 관리하고, 스크립트에서 ant CLI 명령을 연결하고, Claude Code에서 리소스를 조작하고, CLI 자격 증명으로 curl 호출을 인증합니다.

이 페이지는 ant CLI를 기반으로 구축된 작업 중심 워크플로를 다룹니다. 기본 플래그와 출력 옵션에 대해서는 CLI 사용하기를 참조하세요.

API 리소스 버전 관리

CLI를 사용하여 스킬, 에이전트, 환경 또는 배포와 같은 API 리소스를 저장소의 YAML 파일로 버전 관리하고 Claude API와 동기화 상태를 유지할 수 있습니다.

이러한 리소스에 대한 자세한 내용은 Managed Agents를 참조하세요.

에이전트 정의하기

에이전트 정의를 summarizer.agent.yaml에 작성합니다:

summarizer.agent.yaml

name: Summarizer
model: claude-opus-5
system: |
  You are a helpful assistant that writes concise summaries.
tools:
  - type: agent_toolset_20260401

에이전트 생성하기
ant beta:agents create < summarizer.agent.yaml
Output
{ "id": "agent_011CYm1BLqPXpQRk5khsSXrs", "version": 1, "name": "Summarizer", "model": "claude-opus-5" /* ... */ }
응답의 id를 기록해 두세요. 이후 단계에서 세션 생성 명령에 전달하게 됩니다.
summarizer.agent.yaml을 저장소에 체크인하고 CI 파이프라인에서 API와 동기화 상태를 유지하세요. 업데이트 명령에는 에이전트 ID와 현재 버전이 플래그로 필요합니다:
CLI
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
환경 정의하기
세션은 실행되는 샌드박스를 정의하는 환경에서 실행됩니다. 환경 정의를 summarizer.environment.yaml에 작성합니다:
summarizer.environment.yaml
name: summarizer-env config: type: cloud networking: type: unrestricted
환경 생성하기
ant beta:environments create < summarizer.environment.yaml
Output
{ "id": "env_01595EKxaaTTGwwY3kyXdtbs", "name": "summarizer-env" /* ... */ }
응답의 id를 기록해 두세요. 이후 단계에서 세션 생성 명령에 전달하게 됩니다.
summarizer.environment.yaml을 저장소에 체크인하고 CI 파이프라인에서 API와 동기화 상태를 유지하세요. 업데이트 명령에는 환경 ID가 플래그로 필요합니다:
CLI
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

세션 시작하기

이전 출력에서 얻은 에이전트 id와 환경 id를 세션 생성 명령에 붙여넣습니다:

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

Output

{
  "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
  "status": "running"
  /* ... */
}

사용자 메시지 보내기

이전 출력의 세션 id를 --session-id에 복사합니다:

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는 터미널에서 list 명령이 기본적으로 여는 대화형 탐색기를 재정의합니다:
ant beta:sessions:events list \ --session-id session_01JZCh78XvmxJjiXVy3oSi7K \ --transform 'content.0.text' --format auto --raw-output
Output
```
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.
```
실행 중인 세션을 관찰하려면 ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K를 사용하세요. 이벤트가 도착하는 대로 stdout에 기록됩니다.

스크립팅 패턴

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

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

list 엔드포인트에서 --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

Output

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 액세스 토큰은 Authorization 헤더에 bearer 토큰으로 들어가며, x-api-key 헤더는 정적 API 키 전용입니다.

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

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",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "hi"}]
  }'

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

ant auth status를 실행하여 어떤 조직과 워크스페이스에 로그인되어 있는지 확인하세요. 환경 변수가 로그인을 재정의하고 있는 경우 경고를 표시합니다.

Was this page helpful?

CLI, SDK 및 라이브러리ant CLI

CLI 스크립팅 및 자동화

API 리소스를 YAML로 버전 관리하고, 스크립트에서 ant CLI 명령을 연결하고, Claude Code에서 리소스를 조작하고, CLI 자격 증명으로 curl 호출을 인증합니다.

이 페이지는 ant CLI를 기반으로 구축된 작업 중심 워크플로를 다룹니다. 기본 플래그와 출력 옵션에 대해서는 CLI 사용하기를 참조하세요.

API 리소스 버전 관리

CLI를 사용하여 스킬, 에이전트, 환경 또는 배포와 같은 API 리소스를 저장소의 YAML 파일로 버전 관리하고 Claude API와 동기화 상태를 유지할 수 있습니다.

이러한 리소스에 대한 자세한 내용은 Managed Agents를 참조하세요.

에이전트 정의하기

에이전트 정의를 summarizer.agent.yaml에 작성합니다:

summarizer.agent.yaml

name: Summarizer
model: claude-opus-5
system: |
  You are a helpful assistant that writes concise summaries.
tools:
  - type: agent_toolset_20260401

에이전트 생성하기
ant beta:agents create < summarizer.agent.yaml
Output
{ "id": "agent_011CYm1BLqPXpQRk5khsSXrs", "version": 1, "name": "Summarizer", "model": "claude-opus-5" /* ... */ }
응답의 id를 기록해 두세요. 이후 단계에서 세션 생성 명령에 전달하게 됩니다.
summarizer.agent.yaml을 저장소에 체크인하고 CI 파이프라인에서 API와 동기화 상태를 유지하세요. 업데이트 명령에는 에이전트 ID와 현재 버전이 플래그로 필요합니다:
CLI
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
환경 정의하기
세션은 실행되는 샌드박스를 정의하는 환경에서 실행됩니다. 환경 정의를 summarizer.environment.yaml에 작성합니다:
summarizer.environment.yaml
name: summarizer-env config: type: cloud networking: type: unrestricted
환경 생성하기
ant beta:environments create < summarizer.environment.yaml
Output
{ "id": "env_01595EKxaaTTGwwY3kyXdtbs", "name": "summarizer-env" /* ... */ }
응답의 id를 기록해 두세요. 이후 단계에서 세션 생성 명령에 전달하게 됩니다.
summarizer.environment.yaml을 저장소에 체크인하고 CI 파이프라인에서 API와 동기화 상태를 유지하세요. 업데이트 명령에는 환경 ID가 플래그로 필요합니다:
CLI
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

세션 시작하기

이전 출력에서 얻은 에이전트 id와 환경 id를 세션 생성 명령에 붙여넣습니다:

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

Output

{
  "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
  "status": "running"
  /* ... */
}

사용자 메시지 보내기

이전 출력의 세션 id를 --session-id에 복사합니다:

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는 터미널에서 list 명령이 기본적으로 여는 대화형 탐색기를 재정의합니다:
ant beta:sessions:events list \ --session-id session_01JZCh78XvmxJjiXVy3oSi7K \ --transform 'content.0.text' --format auto --raw-output
Output
```
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.
```
실행 중인 세션을 관찰하려면 ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K를 사용하세요. 이벤트가 도착하는 대로 stdout에 기록됩니다.

스크립팅 패턴

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

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

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

오류 검사하기

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

Output

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

Claude Code에서 CLI 사용하기

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

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

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

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

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",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "hi"}]
  }'

Was this page helpful?

API 리소스 버전 관리

스크립팅 패턴

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

오류 검사하기

Claude Code에서 CLI 사용하기

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

API 리소스 버전 관리

스크립팅 패턴

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

오류 검사하기

Claude Code에서 CLI 사용하기

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

API 리소스 버전 관리

스크립팅 패턴

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

오류 검사하기

Claude Code에서 CLI 사용하기

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

API 리소스 버전 관리

스크립팅 패턴

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

오류 검사하기

Claude Code에서 CLI 사용하기

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