---
title: Scripts e automação com a CLI
url: https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/scripting
description: Versione recursos da API como arquivos com ant apply, encadeie comandos da CLI ant em scripts, opere sobre recursos a partir do Claude Code e autentique chamadas curl com credenciais da CLI.
---

Esta página aborda fluxos de trabalho orientados a tarefas construídos sobre a CLI `ant`. Para as flags subjacentes e opções de saída, consulte [Usando a CLI](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/using).

## Controle de versão de recursos da API

Para manter agentes, ambientes e outros recursos do Claude Managed Agents como arquivos no seu repositório, consulte [Gerencie recursos como código com ant apply](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/apply).

### Execute o agente aplicado a partir do shell

Depois que um agente e um ambiente existirem, você pode conduzir uma sessão a partir do shell:

<Steps>
  <Step title="Inicie uma sessão">
    Passe os IDs do agente e do ambiente para o comando de criação de sessão. Após `ant apply`, leia-os de `claude-lock.json`: cada entrada em `resources` tem um `id`, e para o projeto em [Gerencie recursos como código com ant apply](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/apply) as entradas são `./agents/summarizer.md` e `./environments/cloud.yaml`.

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

    ```json Output
    {
      "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
      "status": "running"
      /* ... */
    }
    ```
  </Step>

  <Step title="Envie uma mensagem de usuário">
    Copie o `id` da sessão da saída anterior para `--session-id`:

    ```bash
    ant beta:sessions:events send \
      --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
      --event '{type: user.message, content: [{type: text, text: "Summarize the benefits of type safety in one sentence."}]}'
    ```
  </Step>

  <Step title="Leia a conversa">
    Depois que o agente responder, liste os eventos. `--transform` é executado sobre cada evento listado, então isto imprime o texto de cada mensagem em ordem. `--format auto` substitui o explorador interativo que os comandos de listagem abrem por padrão em um terminal:

    ```bash
    ant beta:sessions:events list \
      --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
      --transform 'content.0.text' \
      --raw-output \
      --format auto
    ```

    ```text Output wrap
    Summarize the benefits of type safety in one sentence.
    Type safety catches errors at compile time rather than runtime, reducing bugs, improving code clarity, enabling better tooling support, and making codebases easier to maintain and refactor with confidence.
    ```

    <Tip>
      Para acompanhar uma sessão enquanto ela é executada, use `ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K --format jsonl`, que grava cada evento no stdout à medida que ele chega. Sem `--format`, um terminal abre o explorador interativo em vez disso.
    </Tip>
  </Step>
</Steps>

## Padrões de scripting

A CLI foi projetada para se compor com ferramentas de shell padrão.

### Encadeie a saída de listagem em um segundo comando

`--transform id --raw-output` em um endpoint de listagem emite um ID simples por linha, de modo que ferramentas padrão como `head` e `xargs` se aplicam diretamente. Capture o primeiro resultado e, em seguida, passe-o para um comando subsequente:

```bash
FIRST_AGENT=$(ant beta:agents list --transform id --raw-output | head -1)

ant beta:agents:versions list \
  --agent-id "$FIRST_AGENT" \
  --transform "{version,created_at}" --format jsonl
```

### Inspecione erros

As flags `--transform-error` e `--format-error` aplicam a mesma filtragem às respostas de erro. `--raw-output` não se aplica a erros, portanto use `--format-error yaml` para obter um escalar sem aspas. Extraia apenas a mensagem de erro:

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

```text Output wrap
GET "https://api.anthropic.com/v1/agents/bogus?beta=true": 404 Not Found
Agent not found.
```

## Use a CLI a partir do Claude Code

O [Claude Code](https://code.claude.com/docs/en/overview) pode usar a CLI `ant` imediatamente. Com a CLI instalada e autenticada, você pode pedir ao Claude Code que opere diretamente nos seus recursos da API. Por exemplo:

* "Liste minhas sessões de agente recentes e resuma quais delas apresentaram erro."
* "Faça upload de todos os PDFs em `./reports` para a Files API e imprima os IDs resultantes."
* "Obtenha os eventos da sessão `session_01...` e me diga onde o agente travou."

O Claude Code executa `ant` no shell, analisa a saída estruturada e raciocina sobre os resultados (nenhum código de integração personalizado é necessário).

## Autentique requisições curl com credenciais da CLI

Scripts que chamam a API com `curl` ou outro cliente HTTP podem usar as credenciais armazenadas por [`ant auth login`](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/quickstart#authentication) em vez de uma "API key" (chave de API) estática. O token de acesso OAuth vai no cabeçalho `Authorization` como um bearer token; o cabeçalho `x-api-key` é apenas para chaves de API estáticas.

`ant auth print-credentials --access-token` imprime o token de acesso do perfil ativo, atualizando-o primeiro se estiver expirado ou próximo de expirar:

```bash cURL
curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "hi"}]
  }'
```

<Note>
  Mantenha `ANTHROPIC_API_KEY` e `ANTHROPIC_AUTH_TOKEN` não definidas ao trabalhar a partir de um login da CLI. Qualquer uma dessas variáveis tem precedência sobre o login para comandos `ant` (consulte [Precedência de credenciais](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#credential-precedence)) e pode direcioná-los silenciosamente para uma organização ou workspace diferente.
</Note>

Execute [`ant auth status`](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/authentication#check-authentication-status) para confirmar em qual organização e workspace você está conectado; ele avisa quando uma variável de ambiente está substituindo seu login.