CLI ant da Claude Platform: Guia Oficial do Desenvolvedor

O que foi lançado

A versão resumida: A Claude Platform agora possui uma CLI de API oficial chamada ant.

O tweet de lançamento é útil porque explica a finalidade do produto: chamadas de API,

The new workflow shape:

terminal command
  -> ant resource action
  -> Claude API endpoint
  -> structured JSON/YAML/raw output
  -> shell pipeline, CI step, or Claude Code agent

Definição em uma frase

A ant CLI is Anthropic's command-line interface for calling Claude API resources from a terminal.Ela não substitui os SDKs de Python ou TypeScript. É uma interface nativa de shell

Modelo Mental: Quatro Peças

Leitura ant como um pequeno adaptador entre fluxos de trabalho de shell e a Claude Platform.

[credentials/profile]
        |
        v
[ant resource:subresource action] --flags < stdin.yaml
        |
        v
[Claude API resource]
        |
        v
[formatted output] --transform -> shell, CI, or Claude Code

• Credenciais: Login OAuth, API key, federação ou perfil nomeado.
• Comandos: um resource action padrão, com recursos aninhados separados por dois-pontos.
• Entrada: flags, YAML/JSON via stdin e @file referências para conteúdos de arquivos inline.
• Saída: JSON formatado, YAML, JSONL, saída bruta, explorador interativo e transformações GJSON.

Instalação e Verificação

The CLI docs show install paths for Homebrew on macOS, curl on Linux/WSL, and Go. The least ambiguous official commands are Homebrew and Go, followed by the version check:

# macOS
brew install anthropics/tap/ant

# Go
go install github.com/anthropics/anthropic-cli/cmd/ant@latest

# Verify
ant --version

A documentação também afirma que todo recurso de API exposto aparece na saída de ajuda local. ant --help, então adicione --help ao recurso ant messages create --help.

Autenticação: OAuth, API Keys e Perfis

A documentação oficial divide a autenticação em desenvolvimento local e cargas de trabalho não interativas. Para uma máquina de desenvolvedor, ant auth login abre um fluxo de OAuth baseado em navegador no Claude Console. Para hosts remotos sem um navegador local, a --no-browser flag exibe uma URL de autorização e solicita que você cole o código retornado.

ant auth login
ant auth login --no-browser
ant auth login --workspace-id wrkspc_01...
ant auth login --profile platform-dev

ant auth status
ant auth logout
ant auth logout --all

O detalhe importante do workspace: durante o login via OAuth, você escolhe uma organização e um workspace. O token é limitado a esse workspace. Para trabalhar em vários workspaces, crie um perfil por workspace e alterne os perfis explicitamente.

ant auth login --profile other-ws
ant profile activate other-ws

ant --profile other-ws models list
ANTHROPIC_PROFILE=other-ws ant models list

Para CI, containers e servidores, a documentação da CLI desencoraja o login interativo e recomenda o Workload Identity Federation. Isso mantém a regra pós-instalação limpa: OAuth para sua máquina, federação para automação e API keys quando você desejar intencionalmente uma autenticação baseada em chaves.

Requisição de ponta a ponta mais simples

Uma vez que ant esteja instalado e autenticado, a documentação começa com a Messages API. Este é o formato mínimo: modelo, max tokens e uma mensagem do usuário.

ant messages create \
  --model claude-opus-4-8 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

A documentação mostra a resposta como o objeto completo da API: ID do modelo, ID da mensagem, função do assistente, array de conteúdo, motivo da parada e uso. A CLI formata esse objeto de forma legível quando o stdout é um terminal.

Estrutura de Comandos

Os comandos seguem um formato resource action . Recursos aninhados usam dois-pontos, e recursos beta residem sob beta:. A documentação classifica agents, sessions, deployments, environments e skills como recursos beta.

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

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

O prefixo beta é importante porque esses comandos enviam automaticamente o cabeçalho anthropic-beta apropriado para aquele recurso. A documentação diz para usar --betaapenas quando você precisar substituir a versão do esquema padrão.

Formatos de Saída e Transformações GJSON

A saída é onde ant torna-se mais do que apenas um wrapper de conveniência em torno curl. auto, json, jsonl, yaml, pretty, raw, e explore. Os endpoints de listagem paginam automaticamente, e a saída da lista pode

A linguagem de transformação é GJSON. Para endpoints de listagem, a transformação é executada em cada

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

Minha visão prática: use --format jsonl quando o próximo comando for uma ferramenta de shell, --transform id --raw-output quando você precisar de um ID de recurso para o próximo ant invocação.

Passando corpos de requisição sem JSON escrito manualmente

A documentação da CLI descreve três modos de entrada: flags, stdin e referências de arquivo. Campos escalares são mapeados para flags. Campos estruturados aceitam uma sintaxe flexível semelhante a YAML ou JSON estrito. Corpos de requisição completos podem ser enviados via pipe através de stdin como JSON ou 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

Para conteúdos de arquivo, a documentação usa @path. Isso permite que você incorpore um arquivo de prompt em um campo de string, ou envie um PDF para a Messages API, onde a CLI detecta e codifica arquivos binários em base64 automaticamente.

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

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

Controle de versão de recursos da API

O detalhe de lançamento mais importante para equipes de plataforma não é a chamada de Messages de uma linha. É a seção da documentação sobre manter recursos da API em arquivos YAML. O exemplo cobre um Managed Agent, um ambiente, uma sessão, um evento de usuário e uma listagem de eventos de sessão.

# summarizer.agent.yaml
name: Summarizer
model: claude-sonnet-4-6
system: |
  You are a helpful assistant that writes concise summaries.
tools:
  - type: agent_toolset_20260401

ant beta:agents create < summarizer.agent.yaml
ant beta:agents update --agent-id agent_011... --version 1 < summarizer.agent.yaml

# summarizer.environment.yaml
name: summarizer-env
config:
  type: cloud
  networking:
    type: unrestricted

ant beta:environments create < summarizer.environment.yaml

ant beta:sessions create \
  --agent agent_011CYm1BLqPXpQRk5khsSXrs \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "Summarization task"

Esse padrão transforma recursos de plataforma em arquivos que você pode revisar, armazenar em um repositório e atualizar via CI. A CLI não elimina a necessidade de governança, mas torna o modelo de objeto operacional visível para scripts de shell.

Use ant do Claude Code

O tweet de lançamento diz ant é bem compreendido por agentes de codificação, e a documentação da CLI torna o comportamento do Claude Code explícito: com ant instalado e autenticado, o Claude Code pode executar comandos nele, analisar saídas estruturadas e raciocinar sobre os resultados.

Prompts the docs say are now reasonable:

"List my recent agent sessions and summarize which ones errored."
"Upload every PDF in ./reports to the Files API and print the resulting IDs."
"Pull the events for session session_01... and tell me where the agent got stuck."

A implicação prática: o Claude Code não precisa mais de um script personalizado para entender muitos recursos da Claude Platform. Instale ant, autentique-o no workspace correto e o Claude Code obtém uma superfície de comando estruturada que ele pode usar.

O que eu entendi errado ao ler o lançamento

Minha primeira suposição errada foi que ant era apenas um wrapper mais elegante da Messages API. A documentação deixa claro o objetivo mais amplo: operações de recursos da API, Managed Agents em beta, ambientes, sessões, arquivos, perfis, transforms e a transferência para o Claude Code.

A segunda suposição errada foi que a troca de perfil sempre prevalece. Não é verdade. Se ANTHROPIC_API_KEY estiver presente, a documentação diz que os perfis são ignorados. Essa é a primeira coisa que eu verificaria quando um comando atingir o workspace errado.

A terceira suposição errada foi que --format raw e --raw-output são a mesma coisa. --raw-output com jq -r para strings. --format raw imprime os bytes brutos da resposta e se comporta de maneira diferente nos endpoints de lista.

Depuração e Autocompletar no Shell

Para depuração, adicione --debug. A documentação diz que isso imprime a requisição HTTP exata e a --format-error e --transform-error para filtrar respostas de erro.

ant --debug beta:agents list

ant beta:agents retrieve --agent-id bogus \
  --transform-error error.message --format-error yaml 2>&1

A documentação também diz que scripts de autocompletar são fornecidos para bash, zsh, fish e PowerShell. Isso é importante

O Veredito

Ignore se você precisar de integração de aplicação tipada, abstrações de SDK de longa duração ou comportamento de tempo de execução

FAQ

Glossário

ant

Ferramenta de linha de comando da Anthropic para recursos da API da Claude Platform.

Messages API

O endpoint da Claude API usado para enviar mensagens ao modelo e receber respostas do assistente.

Managed Agent

Um recurso de agente da Claude Platform configurado com modelo, system prompt, ferramentas e comportamento de runtime.

Workspace

Um escopo do Claude Console que controla quais recursos da API as credenciais podem acessar.

Profile

Uma configuração de CLI nomeada usada para alternar credenciais, workspace e configurações relacionadas.

GJSON

Uma sintaxe de caminho usada pelo --transform para extrair ou remodelar respostas JSON.

JSONL

JSON delimitado por nova linha, útil quando cada item listado deve ser transmitido como uma única linha.

Workload Identity Federation

Um caminho de autenticação não interativo que a documentação recomenda para CI, servidores e containers.

Todas as fontes e links oficiais

Conforme a restrição de lançamento para este post, não foram utilizados sites da comunidade, threads do Reddit, comentários no Hacker News, posts de blog não oficiais ou tutoriais de terceiros.