Usando a CLI

Esta página aborda a mecânica de entrada e saída da CLI ant que se aplica a todos os endpoints. Para instalar e autenticar, consulte o Início rápido. Para encadear comandos e controlar versões de recursos, consulte Scripts e automação com a CLI.

Estrutura de comandos

Os comandos seguem um padrão resource action. Recursos aninhados usam dois-pontos:

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

Execute ant --help para ver a lista completa de recursos, ou acrescente --help a qualquer subcomando para ver suas flags.

Recursos em beta (incluindo agents, sessions, deployments e environments) ficam sob o prefixo beta:. Os comandos nesse namespace enviam automaticamente o cabeçalho anthropic-beta apropriado para aquele recurso, então você não precisa passá-lo por conta própria. Use --beta <header> apenas para substituir o padrão (por exemplo, para optar por uma versão de schema diferente).

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...

Flags globais

Formatos de saída

auto imprime JSON formatado e é o padrão para comandos que criam ou modificam recursos. Comandos de listagem e recuperação usam por padrão o explorador interativo ao escrever em um terminal, e JSON formatado quando a saída é redirecionada por pipe. Substitua qualquer um dos padrões com --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"
...

Endpoints de listagem paginam automaticamente. Nos formatos padrão, cada item é escrito separadamente (um objeto JSON compacto por linha no modo jsonl, um fluxo de documentos YAML no modo yaml), o que flui de forma limpa para head, grep e filtros --transform.

Explorador interativo

O explorador é uma TUI com recolhimento e busca para navegar por respostas grandes. As teclas de seta expandem e recolhem nós, / faz buscas, q sai. Comandos de listagem e recuperação o abrem por padrão quando conectados a um terminal. Passe --format explore para abri-lo explicitamente:

ant models list --format explore

Transformar a saída com GJSON

Use --transform para remodelar as respostas antes de imprimi-las. A expressão é um caminho GJSON. Para endpoints de listagem, a transformação é executada em cada item individualmente, não no 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"}

Extrair um escalar

Para capturar um único campo como uma string sem aspas (por exemplo, o ID de um recurso recém-criado), combine --transform com --raw-output. O resultado é impresso sem aspas JSON e está pronto para ser atribuído a uma variável de shell:

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

Passando corpos de requisição

O mecanismo de entrada adequado depende do formato dos dados: use flags para campos escalares e valores estruturados curtos, redirecione um documento via stdin para corpos aninhados ou com várias linhas, e use referências @file para inserir o conteúdo de arquivos em qualquer campo de string ou binário.

Flags

Campos escalares são mapeados diretamente para flags. Campos estruturados aceitam uma sintaxe relaxada semelhante a YAML (chaves sem aspas, aspas opcionais em strings) ou JSON estrito:

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

Flags repetíveis constroem arrays. Cada --tool ou --event acrescenta um elemento:

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

Redirecione um documento JSON ou YAML para o stdin para fornecer o corpo completo da requisição. Os campos do stdin são mesclados com as flags, e as flags têm precedência. Aqui, version é o token de bloqueio otimista retornado por um retrieve anterior, e $AGENT_ID foi capturado como em Extrair um escalar:

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

Heredocs funcionam da mesma forma e são convenientes para YAML com várias linhas. Coloque o delimitador entre aspas (como em <<'YAML') para desativar a expansão de variáveis dentro do corpo.

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

Referências de arquivo

Flags que recebem um caminho de arquivo, como --file no comando de upload, aceitam um caminho simples:

ant files upload --file ./report.pdf

Para inserir o conteúdo de um arquivo em um campo com valor de string, prefixe o caminho com @:

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

Dentro de valores de flags estruturados, coloque o caminho entre aspas. Para enviar um PDF para a Messages API:

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."}
  ]}'

A CLI detecta o tipo de arquivo e codifica arquivos binários como base64 automaticamente. Para forçar uma codificação específica, use @file:// para texto simples ou @data:// para base64. Escape um @ literal no início com uma barra invertida (\@username).

Depuração

Adicione --debug a qualquer comando para imprimir a requisição e a resposta HTTP exatas (cabeçalhos e corpo) no stderr. As chaves de API são ocultadas.

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: 2026-10-21
Authorization: Bearer <REDACTED>
...

Recursos disponíveis

Todos os recursos da API que a CLI expõe estão documentados na referência da API. Para uma listagem local, execute ant --help e acrescente --help a qualquer subcomando para ver suas flags e parâmetros.

Próximos passos