---
title: Usando a CLI
url: https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/using
description: Estrutura de comandos, formatos de saída, transformações GJSON, corpos de requisição e depuração para a CLI ant.
---

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](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/quickstart). Para encadear comandos e versionar recursos, consulte [Scripts e automação com a CLI](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/scripting).

## Estrutura de comandos

Os comandos seguem um padrão `resource action` (recurso ação). Recursos aninhados usam dois-pontos:

```text wrap
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).

```bash
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

| Flag                                  | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile`                           | Perfil nomeado a ser usado nesta invocação (equivalente a definir `ANTHROPIC_PROFILE`). Consulte [Alternar entre workspaces](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/authentication#switch-between-workspaces).                                                                                                                                                                                                                                                                                           |
| `--format`                            | Formato de saída: `auto`, `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore`                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--transform`                         | Filtra ou remodela a resposta com um [caminho GJSON](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/using#transform-output-with-gjson)                                                                                                                                                                                                                                                                                                                                                                           |
| `-r`, `--raw-output`                  | Imprime resultados de string sem aspas ao redor, como `jq -r`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--base-url`                          | Sobrescreve a URL base da API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--workspace-id`                      | Opcional. ID do workspace (`wrkspc_...`) a ser enviado como o cabeçalho `anthropic-workspace-id`, para chaves de API com acesso a múltiplos workspaces (equivalente a definir `ANTHROPIC_WORKSPACE_ID`). Consulte [Selecionar um workspace](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#select-a-workspace). Os comandos da [Admin API](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api) recebem seu próprio `--workspace-id`, que, em vez disso, indica o workspace que eles gerenciam. |
| `--debug`                             | Imprime a requisição e a resposta HTTP completas em stderr                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--format-error`, `--transform-error` | Iguais a `--format` e `--transform`, mas aplicados a [respostas de erro](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/scripting#inspect-errors)                                                                                                                                                                                                                                                                                                                                                                |

## 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](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/using#interactive-explorer) ao escrever em um terminal, e JSON formatado quando redirecionados por pipe. Sobrescreva qualquer um dos padrões com `--format`:

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

```yaml Output
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 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:

```bash
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](https://github.com/tidwall/gjson/blob/master/SYNTAX.md). Para endpoints de listagem, a transformação é executada em cada item individualmente, não no envelope:

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

```jsonl Output
{"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:

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

printf '%s\n' "$AGENT_ID"
```

```text Output wrap
agent_011CYm1BLqPXpQRk5khsSXrs
```

<Note>
  `--raw-output` é diferente de `--format raw`. `--raw-output` remove as aspas JSON de resultados de string, como `jq -r`. `--format raw` imprime os bytes JSON brutos do corpo da resposta sem paginar automaticamente; em endpoints de listagem, ele aplica `--transform` ao envelope de paginação em vez de a cada item.
</Note>

## 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:

```bash
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:

```bash
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

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](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/using#extract-a-scalar):

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

```bash
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 a arquivos

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

```bash
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 `@`:

```bash
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 à Messages API:

```bash
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
```

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.

```bash
ant --debug beta:agents list
```

```text Output wrap
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](https://platform.claude.com/docs/pt-BR/api/cli/messages/create). Para uma listagem local, execute `ant --help` e acrescente `--help` a qualquer subcomando para ver suas flags e parâmetros.

## Próximos passos

<CardGroup cols={3}>
  <Card title="Scripts e automação com a CLI" icon="code" href="https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/scripting">
    Versionamento de recursos da API, padrões de scripting e uso a partir do Claude Code
  </Card>

  <Card title="Referência da API" icon="book" href="https://platform.claude.com/docs/pt-BR/api/cli/messages/create">
    Parâmetros específicos de endpoints, campos de requisição e schemas de resposta
  </Card>

  <Card title="Opções de autenticação da CLI" icon="lock" href="https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/authentication">
    Chaves de API, hosts headless, múltiplos workspaces e perfis nomeados
  </Card>
</CardGroup>