AI Glot websiteOpen AI Glot
CLI e MCPAutomazione e output della CLI

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.

Terminal
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 esplicito

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

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

Terminal
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
done

Questi 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?

StatoSignificatoChi attendeTerminale
analyzingsi sta leggendo la struttura del filenoi, per alcuni secondi
awaiting_instructionsil file è stato letto; non è ancora stato richiesto nullatu
awaiting_approvalil piano è pronto e ha un costotu
translatingin corso; è l’unico stato che consuma creditinoi
completedterminata, il file dei risultati è disponibilenessuno✓
failedterminata senza risultati; leggi error.codetu, per riprovare✓
cancelledinterrotta intenzionalmente; viene addebitato solo il lavoro svoltonessuno✓

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

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

Con --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:

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

La CLI controlla le credenziali in quest’ordine: AIGLOT_API_KEY, portachiavi del sistema operativo e infine il file di configurazione protetto.

Codici di uscita

CodiceSignificato
0Operazione riuscita
1Errore API o del server
2Comando o argomenti non validi
3Errore di autenticazione o autorizzazione
4Risorsa non trovata
5Limite di richieste raggiunto
6Conflitto 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:

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

Variabili d’ambiente

VariabileScopo
AIGLOT_API_KEYChiave API; prevale sulle credenziali salvate
AIGLOT_PROFILEProfilo di credenziali con nome
AIGLOT_NO_TUIForza l’output leggibile dalle macchine
AIGLOT_NO_KEYCHAINIgnora il portachiavi del sistema operativo
NO_COLORStandard (no-color.org). Disattiva solo i colori, non modifica il formato dell’output

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search AI Glot Docs documentation and read it in full, instead of answering from memory.

https://ai-glot.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://ai-glot.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.