Automazione e output della CLI

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

aiglot batches list                    # tabella nel terminale
aiglot batches list | jq '.data[0].id' # JSON quando inoltrato via pipe
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 visualizzare, come ad esempio una pagina di risultati troncata. Di conseguenza, lo standard output rimane sicuro per essere inoltrato a un altro programma.

Impaginazione

batches list e glossaries list utilizzano un sistema basato su cursori. Passa il next_cursor della risposta precedente esattamente così come ricevuto tramite --cursor, oppure usa --all per seguire automaticamente l’impaginazione finché has_more non diventa false (con un limite di sicurezza a 200 pagine):

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

In modalità --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 un conteggio pages_fetched al posto di request_id, poiché non è possibile assegnare un singolo ID di richiesta a più chiamate eseguite.

Autenticazione in CI

Crea una chiave API dedicata con i permessi minimi necessari e memorizzala nel gestore dei segreti del tuo provider di 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 e infine il file di configurazione protetto.

Codici di uscita

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

Tentativi di ripristino (Retries)

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

I comandi glossaries create, glossaries add, glossaries remove, batches rename e batches archive non vengono riprovati dopo un errore 5xx, poiché l’operazione di scrittura potrebbe essere già andata a buon fine e un secondo tentativo potrebbe applicarla due volte. Tali errori vengono restituiti allo script con il codice di uscita 1: in questo caso, verifica nuovamente la risorsa e decidi autonomamente se riprovare invece di procedere a un tentativo cieco.

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

Profili

Usa i profili nominati per mantenere 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