Automazione e output della CLI
Esegui la CLI di AI Glot in sicurezza negli script e in CI con JSON o NDJSON, credenziali d'ambiente, profili, codici di uscita e nuovi tentativi limitati.
La CLI mostra tabelle leggibili nel terminale e JSON quando l’output viene reindirizzato, così lo stesso comando funziona sia in modalità interattiva sia nelle automazioni.
aiglot batches list # tabella nel terminale
aiglot batches list | jq '.data[0].id' # JSON se reindirizzato
aiglot batches list --output ndjson # un oggetto per riga
aiglot account --json # JSON esplicitoGli errori vengono inviati allo standard error, insieme agli avvisi che il chiamante deve comunque vedere, per esempio quando una pagina dei risultati è stata troncata. Lo standard output resta quindi sicuro da reindirizzare a un altro programma.
Attendere il completamento di una traduzione
Per prima cosa prepara il piano e controllane l’ambito, le esclusioni e il costo calcolato.
La CLI restituisce direttamente gli oggetti singoli: leggi .id, .status e .plan,
non .data.id o .data.status. I comandi di elenco usano comunque un 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'Esegui il blocco successivo solo dopo aver autorizzato il piano, la qualità Standard selezionata e il costo calcolato. L’autorizzazione esistente è sufficiente se li comprende. L’attesa è limitata a 60 controlli e termina con completed, failed o cancelled. Se il processo viene interrotto o scade il tempo, conserva l’ID del batch e riprendilo senza creare un’altra traduzione.
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
doneQuesti sono tutti gli stati che una traduzione può segnalare, compresi i tre che la terminano. Ognuno risponde alla stessa domanda: chi è in attesa e di cosa?
| Stato | Significato | Chi attende | Terminale |
|---|---|---|---|
analyzing | si sta leggendo la struttura del file | noi, per alcuni secondi | |
awaiting_instructions | il file è stato letto; non è ancora stato richiesto nulla | tu | |
awaiting_approval | il piano è pronto e ha un costo | tu | |
translating | in corso; è l’unico stato che consuma crediti | noi | |
completed | terminata, il file dei risultati è disponibile | nessuno | ✓ |
failed | terminata senza risultati; leggi error.code | tu, per riprovare | ✓ |
cancelled | interrotta intenzionalmente; viene addebitato solo il lavoro svolto | nessuno | ✓ |
Paginazione
batches list e glossaries list usano cursori. Passa senza modifiche a --cursor il valore next_cursor della risposta precedente oppure lascia che --all lo segua fino a quando has_more non è false (con un limite di 200 pagine come misura di sicurezza):
aiglot batches list --status completed --all
aiglot glossaries list --all --output ndjsonCon --output ndjson, --all stampa ogni riga di ogni pagina man mano che arriva. In modalità table e json, stampa un unico risultato combinato con has_more: false, next_cursor: null e il conteggio pages_fetched al posto di request_id, perché dopo più richieste non è possibile indicarne una sola.
Autenticazione in CI
Crea una chiave API dedicata con l’ambito minimo necessario e conservala nel gestore dei segreti del provider CI:
export AIGLOT_API_KEY="aig_live_…"
aiglot account --jsonLa CLI controlla le credenziali in quest’ordine: AIGLOT_API_KEY, portachiavi del sistema operativo e infine il file di configurazione protetto.
Codici di uscita
| Codice | Significato |
|---|---|
| 0 | Operazione riuscita |
| 1 | Errore API o del server |
| 2 | Comando o argomenti non validi |
| 3 | Errore di autenticazione o autorizzazione |
| 4 | Risorsa non trovata |
| 5 | Limite di richieste raggiunto |
| 6 | Conflitto di stato della risorsa |
Negli script, usa il codice di uscita o error.code strutturato per decidere come procedere, non il testo del messaggio di errore.
Nuovi tentativi
I nuovi tentativi sono automatici, ma solo quando sono sicuri. 429 viene ripetuto per ogni comando, rispettando Retry-After e usando un backoff limitato. 408 e 5xx vengono ripetuti solo per le richieste idempotenti (RFC 9110 §9.2.2): letture, glossaries replace, glossaries delete.
Dopo un errore 5xx, glossaries create, glossaries add, glossaries remove, batches rename e batches archive non vengono ripetuti, perché la modifica potrebbe essere già stata applicata e un secondo tentativo la applicherebbe due volte. Questi errori vengono segnalati allo script con il codice di uscita 1: rileggi la risorsa e valuta se riprovare, invece di farlo alla cieca.
Usa --no-retry quando la gestione dei nuovi tentativi è a carico del chiamante e --timeout <seconds> (predefinito: 60) per impostare un limite alla durata di una singola richiesta. I comandi distruttivi non attendono all’infinito una risposta interattiva: in modalità non interattiva devi passare --force.
Profili
Usa profili con nome per tenere separate le credenziali di workspace o ambienti diversi:
aiglot --profile client-a auth login --key "$CLIENT_A_KEY"
aiglot --profile client-a account
export AIGLOT_PROFILE=client-aVariabili d’ambiente
| Variabile | Scopo |
|---|---|
AIGLOT_API_KEY | Chiave API; prevale sulle credenziali salvate |
AIGLOT_PROFILE | Profilo di credenziali con nome |
AIGLOT_NO_TUI | Forza l’output leggibile dalle macchine |
AIGLOT_NO_KEYCHAIN | Ignora il portachiavi del sistema operativo |
NO_COLOR | Standard (no-color.org). Disattiva solo i colori, non modifica il formato dell’output |