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.

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

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.

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:

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

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:

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

Variáveis de ambiente