CLI-Automatisierung und Ausgabe

Die CLI gibt in einem Terminal lesbare Tabellen aus und JSON, wenn die Ausgabe per Pipe weitergeleitet wird, sodass derselbe Befehl sowohl interaktiv als auch in der Automatisierung funktioniert.

aiglot batches list                    # Tabelle im Terminal
aiglot batches list | jq '.data[0].id' # JSON bei Pipe
aiglot batches list --output ndjson    # ein Objekt pro Zeile
aiglot account --json                  # explizites JSON

Fehler werden an den Standard-Error-Stream gesendet, ebenso wie Warnungen, die der Aufrufer sehen muss, wie etwa eine gekürzte Ergebnisseite. Der Standard-Output bleibt daher sicher für die Weiterleitung in ein anderes Programm.

Warten auf den Abschluss einer Übersetzung

Ein Skript, das eine Übersetzung startet, muss normalerweise auf deren Abschluss warten. Pollen Sie batches get und stoppen Sie bei einem terminalen Status:

id=$(aiglot batches create catalogue.csv --instruction "Translate into French" --json | jq -r '.data.id')
aiglot batches approve "$id" --json > /dev/null

until status=$(aiglot batches get "$id" --json | jq -r '.data.status'); [ "$status" = "completed" ] || [ "$status" = "failed" ]; do
  sleep 5
done

[ "$status" = "completed" ] && aiglot batches download "$id" --output result.csv

Dies sind alle Status, die eine Übersetzung melden kann, sowie die drei, die sie beenden. Jeder beantwortet dieselbe Frage: Wer wartet und worauf?

Pagination

batches list und glossaries list basieren auf Cursoren. Übergeben Sie den next_cursor aus der vorherigen Antwort unverändert mit --cursor zurück, oder lassen Sie --all dies für Sie übernehmen, bis has_more den Wert false hat (begrenzt auf 200 Seiten als Sicherheitsmaßnahme):

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

Bei --output ndjson gibt --all jede Zeile jeder Seite aus, sobald sie eintrifft. Im Modus table und json wird ein kombiniertes Ergebnis mit has_more: false, next_cursor: null und einer pages_fetched-Zählung anstelle der request_id ausgegeben, da kein einzelner Request benannt werden kann, wenn mehrere ausgeführt wurden.

CI-Authentifizierung

Erstellen Sie einen dedizierten API-Key mit minimalen Berechtigungen und speichern Sie diesen im Secret-Manager Ihres CI-Providers:

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

Die CLI prüft die Anmeldedaten in dieser Reihenfolge: AIGLOT_API_KEY, OS-Keychain, dann die geschützte Konfigurationsdatei.

Exit-Codes

Skripte sollten basierend auf dem Exit-Code oder dem strukturierten error.code verzweigen, nicht auf dem Text der Fehlermeldung.

Retries

Retries erfolgen automatisch, jedoch nur dort, wo ein Retry sicher ist. 429 wird für jeden Befehl unter Beachtung von Retry-After mit begrenztem Backoff wiederholt. 408 und 5xx werden nur für idempotente Anfragen wiederholt (RFC 9110 §9.2.2): Lesezugriffe, glossaries replace, glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename und batches archive werden nach einem 5xx nicht wiederholt, da der Schreibvorgang möglicherweise bereits erfolgreich war und ein zweiter Versuch ihn doppelt anwenden würde. Diese Fehler werden Ihrem Skript mit Exit-Code 1 gemeldet: Lesen Sie die Ressource erneut aus und entscheiden Sie selbst, ob Sie es erneut versuchen möchten, anstatt blind zu wiederholen.

Verwenden Sie --no-retry, wenn der Aufrufer die Retry-Strategie steuert, und --timeout <seconds> (Standard 60), um eine einzelne Anfrage zu begrenzen. Destruktive Befehle warten niemals endlos auf eine interaktive Eingabe: Bei nicht-interaktiver Nutzung muss --force übergeben werden.

Profile

Verwenden Sie benannte Profile, um Anmeldedaten für verschiedene Workspaces oder Umgebungen getrennt zu halten:

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

Umgebungsvariablen