Automação e saída de CLI

A CLI imprime tabelas legíveis no terminal e JSON quando a saída é redirecionada, 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 o erro padrão (stderr), assim como avisos que o chamador ainda precisa ver, como uma página de resultados truncada. Portanto, a saída padrão permanece segura para ser redirecionada para outro programa.

Aguardando a conclusão de uma tradução

Um script que inicia uma tradução geralmente precisa aguardar a sua conclusão. Monitore batches get e pare em um status terminal:

id=$(aiglot batches create catalogue.csv --instruction "Translate into French" --json | jq -r '.data.id')
aiglot batches approve "$id" --json > /dev/null

until status=$(aiglot batches get "$id" --json | jq -r '.data.status'); [ "$status" = "completed" ] || [ "$status" = "failed" ]; do
  sleep 5
done

[ "$status" = "completed" ] && aiglot batches download "$id" --output result.csv

Estes são todos os status que uma tradução pode reportar, e os três que a encerram. Cada um responde à mesma pergunta: quem está esperando e o quê?

Paginação

batches list e glossaries list são baseados em cursor. Passe o next_cursor da resposta anterior literalmente com --cursor, ou deixe que --all faça isso por você 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

Em --output ndjson, --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 quando várias foram executadas.

Autenticação de CI

Crie uma chave de API dedicada com escopo mínimo e armazene-a no gerenciador de segredos do 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 com base no código de saída ou no error.code estruturado, não no texto da mensagem de erro.

Tentativas (Retries)

As tentativas são automáticas, mas apenas onde é seguro tentar novamente. O erro 429 é tentado em todos os comandos, respeitando o Retry-After com backoff limitado. Os erros 408 e 5xx são tentados 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 tentados após um 5xx, pois a gravação pode já ter sido efetuada e uma segunda tentativa a aplicaria duas vezes. Essas falhas chegam ao seu script com a saída 1: leia o recurso novamente e decida se deve tentar de novo, em vez de tentar cegamente.

Use --no-retry quando o chamador for responsável pela política de tentativas, e --timeout <seconds> (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 client-a auth login --key "$CLIENT_A_KEY"
aiglot --profile client-a account
export AIGLOT_PROFILE=client-a

Variáveis de ambiente