Automação e saída da CLI
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 novas tentativas limitadas.
A CLI exibe tabelas legíveis no terminal e JSON quando a saída é redirecionada, então o mesmo comando funciona tanto no uso interativo quanto na automação.
aiglot batches list # table on a terminal
aiglot batches list | jq '.data[0].id' # JSON when piped
aiglot batches list --output ndjson # one object per line
aiglot account --json # explicit JSONAs falhas e os avisos que o chamador precisa ver, como os que indicam uma página de resultados truncada, são enviados para a saída de erro padrão. Assim, a saída padrão continua segura para redirecionar para outro programa.
Aguardar a conclusão de uma tradução
Primeiro, prepare o plano e confira o escopo, as exclusões e o custo calculado.
A CLI retorna objetos individuais diretamente: leia .id, .status e .plan,
não .data.id nem .data.status. Os comandos de listagem ainda usam um array data.
set -euo pipefail
batch=$(aiglot batches create catalogue.csv --instruction "Translate into French" --json)
id=$(printf '%s' "$batch" | jq -er '.id')
printf '%s\n' "$batch" | jq '.plan'Execute o próximo bloco somente depois que o plano, a qualidade Standard selecionada e o custo calculado forem autorizados. Uma autorização existente é suficiente se cobrir esses itens. A espera é limitada a 60 consultas e termina quando o status for completed, failed ou cancelled. Se o processo for interrompido ou atingir o tempo limite, guarde o ID do lote e retome-o sem criar outra tradução.
aiglot batches approve "$id" --quality standard --yes --json
for ((attempt = 0; attempt < 60; attempt++)); do
status=$(aiglot batches get "$id" --timeout 15 --json | jq -er '.status')
case "$status" in
completed)
aiglot batches download "$id" --output result.csv
break
;;
failed|cancelled)
printf 'Batch %s ended with status %s.\n' "$id" "$status" >&2
exit 1
;;
awaiting_instructions|awaiting_approval)
printf 'Batch %s needs a decision; inspect its plan before continuing.\n' "$id" >&2
exit 2
;;
esac
if ((attempt == 59)); then
printf 'Wait limit reached. Resume batch %s; do not create a duplicate.\n' "$id" >&2
exit 1
fi
sleep 5
doneEstes são todos os status que uma tradução pode apresentar, incluindo os três que a encerram. Cada um responde à mesma pergunta: quem está aguardando e pelo quê?
| Status | Significado | Quem aguarda | Terminal |
|---|---|---|---|
analyzing | a estrutura do arquivo está sendo lida | nós, por alguns segundos | |
awaiting_instructions | o arquivo foi lido; ainda não foi solicitado nada | você | |
awaiting_approval | o plano está pronto e tem um preço definido | você | |
translating | em andamento; único estado que consome créditos | nós | |
completed | concluída, com um arquivo de resultado disponível | ninguém | ✓ |
failed | encerrada sem resultado; consulte error.code | você, para tentar de novo | ✓ |
cancelled | interrompida de propósito; cobrança apenas pelo trabalho executado | ninguém | ✓ |
Paginação
batches list e glossaries list usam cursores. Reenvie sem alterações o next_cursor da resposta anterior com --cursor ou deixe --all percorrer as páginas até has_more ser false (com limite de segurança de 200 páginas):
aiglot batches list --status completed --all
aiglot glossaries list --all --output ndjsonCom --output ndjson, --all exibe cada linha de todas as páginas à medida que chega. Nos modos table e json, exibe um único resultado combinado, com has_more: false, next_cursor: null e a contagem pages_fetched no lugar de request_id, pois não é possível atribuir um único nome à solicitação depois que várias foram feitas.
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 provedor de CI:
export AIGLOT_API_KEY="aig_live_…"
aiglot account --jsonA CLI verifica as credenciais nesta ordem: AIGLOT_API_KEY, chaveiro do sistema operacional e, por fim, arquivo de configuração protegido.
Códigos de saída
| Código | Significado |
|---|---|
| 0 | Sucesso |
| 1 | Erro de API ou do servidor |
| 2 | Comando ou argumentos inválidos |
| 3 | Falha de autenticação ou permissão |
| 4 | Recurso não encontrado |
| 5 | Limite de solicitações atingido |
| 6 | Conflito de estado do recurso |
Os scripts devem tomar decisões com base no código de saída ou em error.code estruturado, não no texto da mensagem de erro.
Novas tentativas
As novas tentativas são automáticas, mas apenas quando são seguras. 429 é repetido em todos os comandos, respeitando Retry-After e usando intervalos crescentes limitados. 408 e 5xx só são repetidos em solicitaçõ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 5xx, pois a alteração talvez já tenha sido aplicada e uma segunda tentativa a duplicaria. Essas falhas são informadas ao script com o código de saída 1: consulte novamente o recurso e decida por conta própria se deve tentar outra vez, em vez de repetir às cegas.
Use --no-retry quando o chamador controlar a política de novas tentativas e --timeout <seconds> (padrão: 60) para limitar uma solicitação. Comandos destrutivos nunca ficam aguardando indefinidamente uma confirmação interativa: no modo não interativo, é necessário passar --force.
Perfis
Use perfis nomeados para manter separadas as credenciais de diferentes espaços de trabalho ou ambientes:
aiglot --profile client-a auth login --key "$CLIENT_A_KEY"
aiglot --profile client-a account
export AIGLOT_PROFILE=client-aVariáveis de ambiente
| Variável | Finalidade |
|---|---|
AIGLOT_API_KEY | Chave de API; substitui as credenciais armazenadas |
AIGLOT_PROFILE | Perfil de credenciais nomeado |
AIGLOT_NO_TUI | Força a saída legível por máquina |
AIGLOT_NO_KEYCHAIN | Ignora o chaveiro do sistema operacional |
NO_COLOR | Padrão (no-color.org). Desativa apenas as cores; não altera o formato da saída |