CLI 사용하기

이 페이지에서는 모든 엔드포인트에 공통으로 적용되는 ant CLI의 입력 및 출력 메커니즘을 다룹니다. 설치 및 인증 방법은 빠른 시작을 참조하세요. 명령을 연결하고 리소스를 버전 관리하는 방법은 CLI 스크립팅 및 자동화를 참조하세요.

명령 구조

명령은 resource action 패턴을 따릅니다. 중첩된 리소스는 콜론을 사용합니다:

ant <resource>[:<subresource>] <action> [flags]

전체 리소스 목록을 보려면 ant --help를 실행하고, 하위 명령의 플래그를 보려면 해당 하위 명령에 --help를 추가하세요.

베타 상태의 리소스(agents, sessions, deployments, environments 포함)는 beta: 접두사 아래에 있습니다. 이 네임스페이스의 명령은 해당 리소스에 적합한 anthropic-beta 헤더를 자동으로 전송하므로 직접 전달할 필요가 없습니다. --beta <header>는 기본값을 재정의할 때만 사용하세요(예: 다른 스키마 버전을 선택하는 경우).

ant models list
ant messages create --model claude-opus-5 --max-tokens 1024 ...
ant beta:agents retrieve --agent-id agent_01...
ant beta:sessions:events list --session-id session_01...

전역 플래그

출력 형식

auto는 JSON을 보기 좋게 출력하며, 리소스를 생성하거나 수정하는 명령의 기본값입니다. 목록 조회(list) 및 단건 조회(retrieve) 명령은 터미널에 출력할 때는 대화형 탐색기를, 파이프로 연결될 때는 보기 좋게 출력된 JSON을 기본값으로 사용합니다. 두 기본값 모두 --format으로 재정의할 수 있습니다:

ant models retrieve --model-id claude-opus-5 --format yaml

type: model
id: claude-opus-5
display_name: Claude Opus 5
created_at: "2026-07-24T00:00:00Z"
...

목록 엔드포인트는 자동으로 페이지네이션됩니다. 기본 형식에서는 각 항목이 개별적으로 출력되며(jsonl 모드에서는 한 줄에 하나의 압축된 JSON 객체, yaml 모드에서는 YAML 문서 스트림), 이는 head, grep 및 --transform 필터로 깔끔하게 스트리밍됩니다.

대화형 탐색기

탐색기는 대용량 응답을 탐색하기 위한 접기 및 검색 기능의 TUI입니다. 화살표 키로 노드를 펼치고 접으며, /로 검색하고, q로 종료합니다. 목록 조회 및 단건 조회 명령은 터미널에 연결되어 있을 때 기본적으로 탐색기를 엽니다. 명시적으로 열려면 --format explore를 전달하세요:

ant models list --format explore

GJSON으로 출력 변환

출력 전에 응답을 재구성하려면 --transform을 사용하세요. 표현식은 GJSON 경로입니다. 목록 엔드포인트의 경우 변환은 엔벨로프가 아닌 각 항목에 대해 개별적으로 실행됩니다:

ant beta:agents list \
  --transform "{id,name,model}" \
  --format jsonl

{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-opus-5"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-5"}

스칼라 값 추출

단일 필드를 따옴표 없는 문자열로 캡처하려면(예: 새로 생성된 리소스의 ID) --transform을 --raw-output과 함께 사용하세요. 결과는 JSON 따옴표 없이 출력되어 셸 변수에 바로 할당할 수 있습니다:

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-opus-5}' \
  --transform id --raw-output)

printf '%s\n' "$AGENT_ID"

agent_011CYm1BLqPXpQRk5khsSXrs

요청 본문 전달

적절한 입력 메커니즘은 데이터의 형태에 따라 달라집니다. 스칼라 필드와 짧은 구조화된 값에는 플래그를 사용하고, 중첩되거나 여러 줄로 된 본문에는 stdin 문서를 파이프로 전달하며, 파일 내용을 문자열 또는 바이너리 필드로 가져오려면 @file 참조를 사용하세요.

플래그

스칼라 필드는 플래그에 직접 매핑됩니다. 구조화된 필드는 느슨한 YAML 유사 구문(따옴표 없는 키, 문자열 주위의 선택적 따옴표) 또는 엄격한 JSON을 허용합니다:

ant beta:sessions create \
  --agent '{type: agent, id: agent_011CYm1BLqPXpQRk5khsSXrs, version: 1}' \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "CLI docs test session"

반복 가능한 플래그는 배열을 만듭니다. 각 --tool 또는 --event는 요소 하나를 추가합니다:

ant beta:agents create \
  --name "Research Agent" \
  --model '{id: claude-opus-5}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

Stdin

전체 요청 본문을 제공하려면 JSON 또는 YAML 문서를 stdin으로 파이프하세요. stdin의 필드는 플래그와 병합되며, 플래그가 우선합니다. 여기서 version은 이전 retrieve에서 반환된 낙관적 잠금(optimistic-locking) 토큰이며, $AGENT_ID는 스칼라 값 추출에서와 같이 캡처된 값입니다:

echo '{"description": "Updated test agent.", "version": 1}' | \
  ant beta:agents update --agent-id "$AGENT_ID"

Heredoc도 같은 방식으로 동작하며 여러 줄 YAML에 편리합니다. 본문 내 변수 확장을 비활성화하려면 구분자를 따옴표로 감싸세요(<<'YAML'처럼).

ant beta:agents create <<'YAML'
name: Research Agent
model: claude-opus-5
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

파일 참조

업로드 명령의 --file처럼 파일 경로를 받는 플래그는 경로를 그대로 허용합니다:

ant files upload --file ./report.pdf

파일 내용을 문자열 값 필드에 인라인으로 넣으려면 경로 앞에 @를 붙이세요:

ant beta:agents create \
  --name "Researcher" --model '{id: claude-opus-5}' \
  --system @./prompts/researcher.txt

구조화된 플래그 값 내부에서는 경로를 따옴표로 감싸세요. Messages API에 PDF를 보내려면:

ant messages create \
  --model claude-opus-5 \
  --max-tokens 1024 \
  --message '{role: user, content: [
    {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
    {type: text, text: "Extract the text from this scanned document."}
  ]}' \
  --transform 'content.#(type=="text").text' --raw-output

CLI는 파일 유형을 감지하여 바이너리 파일을 자동으로 base64로 인코딩합니다. 특정 인코딩을 강제하려면 일반 텍스트에는 @file://을, base64에는 @data://를 사용하세요. 리터럴 선행 @는 백슬래시로 이스케이프하세요(\@username).

디버깅

정확한 HTTP 요청 및 응답(헤더와 본문)을 stderr에 출력하려면 명령에 --debug를 추가하세요. API 키는 가려집니다.

ant --debug beta:agents list

GET /v1/agents?beta=true HTTP/1.1
Host: api.anthropic.com
Anthropic-Beta: managed-agents-2026-04-01
Anthropic-Version: 2023-06-01
X-Api-Key: <REDACTED>
...

사용 가능한 리소스

CLI가 노출하는 모든 API 리소스는 API 레퍼런스에 문서화되어 있습니다. 로컬에서 목록을 보려면 ant --help를 실행하고, 하위 명령의 플래그와 매개변수를 보려면 해당 하위 명령에 --help를 추가하세요.

다음 단계