---
title: "Automação de CLI e saída"
description: "Execute a CLI do AI Glot com segurança em scripts e CI usando JSON ou NDJSON, credenciais de ambiente, perfis, códigos de saída e tentativas limitadas."
canonical: "https://ai-glot.com/docs/pt/cli/automation"
updated: "2026-08-12"
---

# Automação de CLI e saída

A CLI exibe tabelas legíveis no terminal e JSON quando a saída é redirecionada (piped), permitindo que o mesmo comando funcione de forma interativa e em automações.

```bash
aiglot batches list                    # tabela no terminal
aiglot batches list | jq '.data[0].id' # JSON quando redirecionado
aiglot batches list --output ndjson    # um objeto por linha
aiglot account --json                  # JSON explícito
```

Falhas são enviadas para a saída de erro padrão (stderr), assim como avisos que o usuário ainda precise ver, como uma página de resultados truncada. Portanto, a saída padrão (stdout) permanece segura para ser redirecionada para outro programa.

## Paginação

`batches list` e `glossaries list` são baseados em cursor. Passe o `next_cursor` da resposta anterior exatamente como recebido com `--cursor`, ou use `--all` para que a CLI siga o cursor automaticamente até que `has_more` seja `false` (limitado a 200 páginas como medida de segurança):

```bash
aiglot batches list --status completed --all
aiglot glossaries list --all --output ndjson
```

No modo `--output ndjson`, o `--all` imprime cada linha de cada página conforme ela chega. Nos modos `table` e `json`, ele imprime um resultado combinado com `has_more: false`, `next_cursor: null` e uma contagem de `pages_fetched` no lugar de `request_id`, já que nenhuma requisição única pode ser nomeada após a execução de várias.

> **Warning: Páginas truncadas geram avisos no erro padrão**
>
> Sem o `--all`, sempre que uma página tiver `has_more: true`, a CLI escreverá um aviso informando o `next_cursor` na saída de erro padrão, em qualquer modo de saída. Isso é especialmente importante para o `ndjson`, cuja saída padrão contém apenas as linhas puras: o aviso é o único sinal de que uma página parcial não é a lista completa.

## Autenticação em CI

Crie uma chave de API dedicada com o escopo mínimo necessário e armazene-a no gerenciador de segredos do seu provedor de CI:

```bash
export AIGLOT_API_KEY="aig_live_…"
aiglot account --json
```

A CLI verifica as credenciais nesta ordem: `AIGLOT_API_KEY`, keychain do SO e, por fim, seu arquivo de configuração protegido.

## Códigos de saída

| Código | Significado                                   |
| -----: | --------------------------------------------- |
|      0 | Sucesso                                       |
|      1 | Erro de API ou servidor                       |
|      2 | Comando ou argumentos inválidos               |
|      3 | Falha de autenticação ou permissão            |
|      4 | Recurso não encontrado                        |
|      5 | Limite de requisições atingido (Rate limited) |
|      6 | Conflito de estado do recurso                 |

Scripts devem ramificar a lógica com base no código de saída ou no `error.code` estruturado, e não no texto da mensagem de erro.

## Tentativas (Retries)

As tentativas de reenvio são automáticas, mas apenas onde é seguro fazê-lo. O erro `429` é repetido para todos os comandos, respeitando o `Retry-After` com backoff limitado. Erros `408` e `5xx` são repetidos apenas para requisições idempotentes (RFC 9110 §9.2.2) — leituras, `glossaries replace` e `glossaries delete`.

`glossaries create`, `glossaries add`, `glossaries remove`, `batches rename` e `batches archive` **não** são repetidos após um erro `5xx`, pois a gravação pode já ter sido processada e uma segunda tentativa a aplicaria duas vezes. Essas falhas são reportadas ao seu script com o código de saída `1`: leia o recurso novamente e decida se deve tentar de novo, em vez de repetir cegamente.

Use `--no-retry` quando o chamador for responsável pela política de tentativas, e `--timeout <segundos>` (padrão 60) para limitar uma única requisição. Comandos destrutivos nunca aguardam indefinidamente por um prompt interativo: o uso não interativo deve passar `--force`.

## Perfis

Use perfis nomeados para manter as credenciais de diferentes workspaces ou ambientes separadas:

```bash
aiglot --profile cliente-a auth login --key "$CLIENT_A_KEY"
aiglot --profile cliente-a account
export AIGLOT_PROFILE=cliente-a
```

## Variáveis de ambiente

| Variável             | Finalidade                                                                         |
| -------------------- | ---------------------------------------------------------------------------------- |
| `AIGLOT_API_KEY`     | Chave de API; substitui credenciais armazenadas                                    |
| `AIGLOT_PROFILE`     | Perfil de credencial nomeado                                                       |
| `AIGLOT_NO_TUI`      | Força a saída legível por máquina                                                  |
| `AIGLOT_NO_KEYCHAIN` | Ignora o keychain do sistema operacional                                           |
| `NO_COLOR`           | Padrão (no-color.org). Desativa apenas as cores; **não** altera o formato da saída |

> **Warning: Não imprima segredos**
>
> Evite o rastreamento de shell (shell tracing) em etapas de autenticação e nunca use echo com a `AIGLOT_API_KEY`. Remova cabeçalhos de autorização dos logs de CI e artefatos de falha.