Automazione CLI e output

La CLI stampa tabelle leggibili nel terminale e JSON quando l’output è inoltrato tramite pipe, così lo stesso comando funziona sia in modo interattivo che in automazione.

aiglot batches list                    # tabella nel terminale
aiglot batches list | jq '.data[0].id' # JSON quando inoltrato
aiglot batches list --output ndjson    # un oggetto per riga
aiglot account --json                  # JSON esplicito

Gli errori vengono inviati allo standard error, così come gli avvisi che l’utente deve comunque vedere, come una pagina di risultati troncata. Lo standard output rimane quindi sicuro per essere inoltrato a un altro programma.

Attendere il completamento di una traduzione

Uno script che avvia una traduzione solitamente deve attenderne la conclusione. Interroga batches get e fermati quando viene raggiunto uno stato terminale:

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

Questi sono tutti gli stati che una traduzione può riportare, e i tre che ne sanciscono la fine. Ognuno risponde alla stessa domanda: chi sta aspettando e cosa?

Paginazione

batches list e glossaries list si basano su cursori. Passa il next_cursor della risposta precedente esattamente com’è tramite --cursor, oppure lascia che --all lo faccia per te finché has_more non è false (con un limite di 200 pagine come sicurezza):

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

In --output ndjson, --all stampa ogni riga di ogni pagina man mano che arriva. Nelle modalità table e json, stampa un unico risultato combinato con has_more: false, next_cursor: null e un conteggio pages_fetched al posto di request_id, poiché non è possibile nominare una singola richiesta quando ne sono state eseguite diverse.

Autenticazione CI

Crea una chiave API dedicata con i permessi minimi e memorizzala nel gestore dei segreti del provider CI:

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

La CLI verifica le credenziali in questo ordine: AIGLOT_API_KEY, keychain del sistema operativo, infine il suo file di configurazione protetto.

Codici di uscita

Gli script dovrebbero basarsi sul codice di uscita o sull’error.code strutturato, non sul testo del messaggio di errore.

Tentativi di ripristino (Retries)

I tentativi sono automatici, ma solo dove è sicuro farlo. L’errore 429 viene riprovato per ogni comando, rispettando Retry-After con un backoff limitato. Gli errori 408 e 5xx vengono riprovati solo per le richieste idempotenti (RFC 9110 §9.2.2): letture, glossaries replace, glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename e batches archive non vengono riprovati dopo un 5xx, perché la scrittura potrebbe essere già andata a buon fine e un secondo tentativo la applicherebbe due volte. Tali fallimenti vengono riportati allo script con l’uscita 1: leggi nuovamente la risorsa e decidi autonomamente se riprovare invece di procedere alla cieca.

Usa --no-retry quando la politica di ripristino è gestita dal chiamante, e --timeout <seconds> (default 60) per limitare una singola richiesta. I comandi distruttivi non attendono mai all’infinito un prompt interattivo: l’uso non interattivo deve passare --force.

Profili

Usa profili nominativi per tenere separate le credenziali di diversi workspace o ambienti:

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

Variabili d’ambiente