---
title: "Automazione e output della CLI"
description: "Esegui in sicurezza la CLI di AI Glot in script e CI utilizzando JSON o NDJSON, credenziali d'ambiente, profili, codici di uscita e tentativi di ripristino limitati."
canonical: "https://ai-glot.com/docs/it/cli/automation"
updated: "2026-08-12"
---

# 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.

```bash
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):

```bash
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.

> **Warning: Una pagina troncata genera un avviso nello standard error**
>
> Senza `--all`, ogni volta che una pagina ha `has_more: true`, la CLI scrive nello standard error un avviso che indica il `next_cursor`, indipendentemente dalla modalità di output. Questo è fondamentale per `ndjson`, il cui standard output contiene solo le righe pure: l'avviso è l'unico segnale che una pagina parziale non rappresenta l'elenco completo.

## Autenticazione in CI

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

```bash
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

| Codice | Significato                                 |
| -----: | ------------------------------------------- |
|      0 | Successo                                    |
|      1 | Errore API o del server                     |
|      2 | Comando o argomenti non validi              |
|      3 | Errore di autenticazione o permessi         |
|      4 | Risorsa non trovata                         |
|      5 | Limite di frequenza superato (Rate limited) |
|      6 | Conflitto di stato della risorsa            |

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:

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

## Variabili d'ambiente

| Variabile            | Scopo                                                                                      |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `AIGLOT_API_KEY`     | Chiave API; sovrascrive le credenziali memorizzate                                         |
| `AIGLOT_PROFILE`     | Nome del profilo delle credenziali                                                         |
| `AIGLOT_NO_TUI`      | Forza l'output leggibile da macchina                                                       |
| `AIGLOT_NO_KEYCHAIN` | Salta il keychain del sistema operativo                                                    |
| `NO_COLOR`           | Standard (no-color.org). Disabilita solo i colori; **non** modifica il formato dell'output |

> **Warning: Non stampare i segreti**
>
> Evita il tracing della shell durante l'autenticazione e non eseguire mai l'echo di `AIGLOT_API_KEY`. Rimuovi gli header di autorizzazione dai log della CI e dagli artefatti di errore.