Automação e saída da CLI

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

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 JSON

Falhas são enviadas para a saída de erro padrão, assim como avisos que o chamador ainda precisa ver, por exemplo, quando uma página de resultados foi truncada. Assim, a saída padrão continua segura para ser redirecionada 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 estimado. A CLI retorna objetos individuais diretamente: leia .id, .status e .plan, não .data.id nem .data.status. Os comandos de listagem continuam usando 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 de autorizar o plano, a qualidade Standard selecionada e o custo estimado. 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 exceder o tempo limite, guarde o ID do lote e retome-o sem criar outra tradução.

aiglot batches approve "$id" --quality standard --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
done

Estes são todos os status que uma tradução pode apresentar, incluindo os três que encerram o processo. Cada um responde à mesma pergunta: quem está aguardando e pelo quê?

Paginação

batches list e glossaries list usam cursores. Passe o next_cursor da resposta anterior sem alterações usando --cursor ou deixe que --all percorra as páginas até has_more ser false (com limite de 200 páginas como proteção):

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

Com --output ndjson, --all imprime cada linha de cada página assim que ela chega. Nos modos table e json, imprime um único resultado combinado com has_more: false, next_cursor: null e uma contagem pages_fetched no lugar de request_id, pois não é possível indicar uma única solicitação quando várias foram executadas.

Autenticação em CI

Crie uma chave de API dedicada, com o mínimo de permissões necessárias, 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, chaveiro do sistema operacional e, por fim, arquivo de configuração protegido.

Códigos de saída

Os scripts devem tomar decisões com base no código de saída ou em error.code estruturado, e não no texto da mensagem de erro.

Novas tentativas

As novas tentativas são automáticas, mas apenas quando são seguras. O status 429 é repetido em todos os comandos, respeitando Retry-After e usando um intervalo crescente limitado. Os status 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 gravação pode já ter sido concluída e uma segunda tentativa a aplicaria novamente. Essas falhas são informadas ao script com o código de saída 1: leia novamente o recurso e decida se deve tentar de novo, em vez de repetir às cegas.

Use --no-retry quando o chamador controlar a política de novas tentativas e --timeout <seconds> (60 por padrão) para limitar a duração de uma única solicitação. Comandos destrutivos nunca ficam aguardando indefinidamente uma confirmação interativa: em uso 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-a

Variáveis de ambiente