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 versionar recursos, consulte Scripts e automação com a CLI.

Estrutura de comandos

Os comandos seguem um padrão resource action (recurso ação). 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 manualmente. Use --beta <header> apenas para sobrescrever o padrão (por exemplo, para optar por uma versão de schema diferente).

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

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 redirecionados por pipe. Sobrescreva qualquer um dos padrões com --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"
...

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 de expandir/recolher e busca para navegar por respostas grandes. As teclas de seta expandem e recolhem nós, / busca, 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 respostas antes de imprimir. 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"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-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}' \
  --transform id --raw-output)

printf '%s\n' "$AGENT_ID"

agent_011CYm1BLqPXpQRk5khsSXrs

Passando corpos de requisição

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

Flags

Campos escalares mapeiam diretamente para flags. Campos estruturados aceitam uma sintaxe flexível semelhante a YAML (chaves sem aspas, aspas opcionais em torno de 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}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

Stdin

Envie um documento JSON ou YAML via pipe para stdin para fornecer o corpo completo da requisição. Os campos de stdin são mesclados com as flags, com as flags tendo 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 de múltiplas 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
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

Referências a arquivos

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}' \
  --system @./prompts/researcher.txt

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

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

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) em 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: 2023-06-01
X-Api-Key: <REDACTED>
...

Recursos disponíveis

Todo recurso da API que a CLI expõe está documentado 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