CLI 사용하기

이 페이지는 모든 엔드포인트에 적용되는 ant CLI의 입력 및 출력 메커니즘을 다룹니다. 설치 및 인증에 대해서는 빠른 시작을 참조하세요. 명령어 체이닝 및 리소스 버전 관리에 대해서는 CLI 스크립팅 및 자동화를 참조하세요.

명령어 구조

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

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

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

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

ant models list
ant messages create --model claude-opus-4-8 --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-4-8 --format yaml

type: model
id: claude-opus-4-8
display_name: Claude Opus 4.8
created_at: "2026-02-04T00:00:00Z"
...

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

대화형 탐색기

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

ant models list --format explore

GJSON으로 출력 변환하기

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

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

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

스칼라 값 추출하기

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

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-sonnet-4-6}' \
  --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-4-8}' \
  --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에서 반환된 낙관적 잠금 토큰이며, $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-4-8
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

파일 참조

upload 명령어의 --file과 같이 파일 경로를 받는 플래그는 일반 경로를 허용합니다:

ant beta:files upload --file ./report.pdf

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

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

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

ant messages create \
  --model claude-opus-4-8 \
  --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.0.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를 추가하세요.