CLI 사용하기

ant CLI의 모든 엔드포인트에 적용되는 입력·출력 메커니즘을 알아보아요. 설치와 인증은 퀵스타트, 명령 연결과 리소스 버전 관리는 CLI 스크립팅과 자동화를 참고하세요.

출처: 문서

본문

명령 구조

명령은 resource action 패턴을 따라요. 중첩 리소스는 콜론을 써요:

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

전체 리소스 목록은 ant --help를, 어떤 하위 명령의 플래그는 그 명령에 --help를 붙이세요.

베타 리소스(에이전트, 세션, 배포, 환경 포함)는 beta: 접두사 아래 있어요. 이 네임스페이스의 명령은 그 리소스를 위한 적절한 anthropic-beta 헤더를 자동으로 보내므로 직접 넘길 필요가 없어요. --beta <header>는 기본값을 덮어쓸 때만 쓰세요(예: 다른 스키마 버전 선택).

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

전역 플래그

플래그	설명
`--profile`	이 호출에 사용할 이름 붙은 프로파일(`ANTHROPIC_PROFILE` 설정과 동일). 워크스페이스 전환하기 참고.
`--format`	출력 포맷: `auto`, `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore`
`--transform`	GJSON 경로로 응답 필터링 또는 재구성
`-r`, `--raw-output`	문자열 결과를 주변 따옴표 없이 출력 ( `jq -r`처럼)
`--base-url`	API 기본 URL 덮어쓰기
`--workspace-id`	선택. 여러 워크스페이스 액세스가 있는 API 키를 위해 `anthropic-workspace-id` 헤더로 보낼 워크스페이스 ID(`wrkspc_...`)(`ANTHROPIC_WORKSPACE_ID` 설정과 동일). 워크스페이스 선택하기 참고. Admin API 명령은 자체 `--workspace-id`를 받으며, 그것은 관리할 워크스페이스를 이름 붙여요.
`--debug`	전체 HTTP 요청·응답을 stderr로 출력
`--format-error`, `--transform-error`	`--format`, `--transform`과 같지만 오류 응답에 적용

출력 포맷

auto는 JSON을 예쁘게 출력하며 리소스를 만들거나 수정하는 명령의 기본값이에요. 목록·검색 명령은 터미널에 쓸 때 대화형 탐색기를, 파이프로 넘길 때는 예쁘게 출력된 JSON을 기본으로 해요. 둘 다 --format으로 덮어쓰세요:

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

type: model
id: claude-opus-5-5
display_name: Claude Opus 5.5
created_at: "2026-09-22T00:00:00Z"
...

목록 엔드포인트는 자동 페이징돼요. 기본 포맷에서는 각 항목이 따로 쓰여져(jsonl 모드에서는 줄마다 하나의 컴팩트 JSON 객체, yaml 모드에서는 YAML 문서 스트림) head, grep, --transform 필터로 깔끔하게 흘러 들어가요.

대화형 탐색기

탐색기는 큰 응답을 둘러보기 위한 접기·검색 TUI예요. 화살표 키로 노드를 펼치고 접으며, /로 검색하고, q로 나가요. 목록·검색 명령은 터미널에 연결돼 있을 때 기본으로 열어요. --format explore로 명시적으로 열 수도 있어요:

ant models list --format explore

GJSON으로 출력 변환하기

출력 전에 응답을 재구성하려면 --transform을 쓰세요. 식은 GJSON 경로예요. 목록 엔드포인트에서 변환은 봉투(envelope)가 아니라 각 항목에 개별적으로 실행돼요:

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

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

스칼라 추출하기

단일 필드를 따옴표 없는 문자열로 잡으려면(예: 새로 만든 리소스의 ID) --transform과 --raw-output을 함께 쓰세요. 결과는 JSON 따옴표 없이 출력되고 셸 변수에 바로 할당할 수 있어요:

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

printf '%s\n' "$AGENT_ID"

agent_011CYm1BLqPXpQRk5khsSXrs

`--raw-output`는 `--format raw`와 달라요. `--raw-output`는 문자열 결과에서 JSON 따옴표를 벗겨 `jq -r`처럼 동작해요. `--format raw`는 자동 페이징 없이 응답 본문의 원시 JSON 바이트를 출력하고, 목록 엔드포인트에서는 각 항목이 아니라 페이징 봉투에 `--transform`을 적용해요.

요청 본문 넘기기

올바른 입력 메커니즘은 데이터의 모양에 달려 있어요: 스칼라 필드와 짧은 구조적 값은 플래그, 중첩·여러 줄 본문은 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-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가 반환한 낙관적 잠금 토큰이고, $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-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-5}' \
  --system @./prompts/researcher.txt

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

ant messages create \
  --model claude-opus-5-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).

디버깅

어느 명령에 --debug를 추가하면 정확한 HTTP 요청·응답(헤더와 본문)을 stderr로 출력해요. 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: ***
...

사용 가능한 리소스

CLI가 노출하는 모든 API 리소스는 API 레퍼런스에 문서화돼 있어요. 로컬 목록은 ant --help를, 하위 명령의 플래그·파라미터는 --help를 붙여 보세요.

다음 단계

API 리소스 버전 관리, 스크립팅 패턴, Claude Code에서 사용하기 엔드포인트별 파라미터, 요청 필드, 응답 스키마 API 키, 헤드리스 호스트, 여러 워크스페이스, 이름 붙은 프로파일

CLI 사용하기