Automazione e output della CLI

Nel terminale, la CLI mostra tabelle di facile lettura; se l’output viene reindirizzato, produce JSON. Lo stesso comando funziona quindi sia in modalità interattiva sia nei processi automatizzati.

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

Gli errori e gli avvisi che il chiamante deve comunque vedere, per esempio quando una pagina di risultati è stata troncata, vengono inviati allo standard error. Lo standard output resta quindi sicuro da reindirizzare a un altro programma.

Attendere il completamento di una traduzione

Prepara prima il piano e controllane l’ambito, le esclusioni e il costo stimato. La CLI restituisce direttamente i singoli oggetti: leggi .id, .status e .plan, non .data.id o .data.status. I comandi di elenco continuano invece a usare 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 seguente solo dopo aver autorizzato il piano, la qualità Standard selezionata e il costo stimato. Un’autorizzazione esistente è sufficiente se li copre. L’attesa è limitata a 60 controlli e termina con gli stati 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 --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

Questi sono tutti gli stati che può restituire una traduzione, compresi i tre che la terminano. Rispondono tutti alla stessa domanda: chi sta aspettando e che cosa?

Paginazione

batches list e glossaries list usano cursori. Passa il valore next_cursor della risposta precedente così com’è, usando --cursor, oppure lascia che --all segua i cursori fino a quando has_more è false (con un limite di sicurezza di 200 pagine):

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

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

Autenticazione nei flussi CI

Crea una chiave API dedicata con le autorizzazioni minime necessarie e conservala nel gestore dei segreti del provider CI:

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

La CLI cerca le credenziali in quest’ordine: AIGLOT_API_KEY, portachiavi del sistema operativo, quindi file di configurazione protetto.

Codici di uscita

Negli script, usa il codice di uscita o il valore strutturato error.code per gestire gli errori, non il testo del messaggio.

Nuovi tentativi

I nuovi tentativi sono automatici, ma solo quando riprovare è sicuro. Per ogni comando, le risposte 429 vengono ritentate rispettando Retry-After e usando un backoff limitato. Le risposte 408 e 5xx vengono ritentate solo per le richieste idempotenti (RFC 9110 §9.2.2): letture, glossaries replace e glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename e batches archive non vengono ritentati dopo una risposta 5xx, perché la modifica potrebbe essere già stata applicata e un secondo tentativo la eseguirebbe di nuovo. Questi errori vengono restituiti allo script con il codice di uscita 1: rileggi la risorsa e decidi se riprovare, invece di ripetere il comando alla cieca.

Usa --no-retry quando la gestione dei tentativi è affidata al chiamante e --timeout <seconds> (60 per impostazione predefinita) per limitare la durata di una singola richiesta. I comandi distruttivi non restano in attesa all’infinito di una conferma interattiva: per usarli in modalità non interattiva, specifica --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-a

Variabili di ambiente