CLI-Automatisierung und Ausgabe

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

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

Fehler sowie Warnungen, die für den Aufrufer relevant sind (z. B. eine gekürzte Ergebnisseite), werden an den Standard-Error-Stream (stderr) geschrieben. Der Standard-Output (stdout) bleibt somit sicher für die Weiterleitung in andere Programme.

Pagination

batches list und glossaries list sind cursor-basiert. Übergeben Sie den next_cursor aus der vorherigen Antwort unverändert mit --cursor oder nutzen Sie --all, um automatisch fortzufahren, bis has_more den Wert false erreicht (begrenzt auf maximal 200 Seiten als Sicherheitsstopp):

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

Im Modus --output ndjson gibt --all jede Zeile jeder Seite sofort bei Erhalt aus. Im Tabellen- und JSON-Modus wird ein kombiniertes Ergebnis mit has_more: false, next_cursor: null und einer pages_fetched-Zählung anstelle der request_id ausgegeben, da bei mehreren aufeinanderfolgenden Anfragen keine einzelne Request-ID mehr sinnvoll ist.

CI-Authentifizierung

Erstellen Sie einen dedizierten API-Schlüssel 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 und schließlich die geschützte Konfigurationsdatei.

Exit-Codes

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

Retries (Wiederholungsversuche)

Retries erfolgen automatisch, sofern dies sicher ist. Ein 429-Fehler wird für jeden Befehl unter Beachtung von Retry-After mit einem begrenzten Backoff wiederholt. 408- und 5xx-Fehler werden nur bei idempotenten Anfragen (RFC 9110 §9.2.2) wiederholt – also bei Lesezugriffen, glossaries replace und glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename und batches archive werden nach einem 5xx-Fehler nicht wiederholt, da der Schreibvorgang bereits erfolgt sein könnte und ein zweiter Versuch zu Duplikaten führen würde. Diese Fehler werden an Ihr Skript mit dem Exit-Code 1 zurückgegeben: Lesen Sie die Ressource erneut aus und entscheiden Sie selbst, ob ein erneuter Versuch sinnvoll ist, anstatt blind zu wiederholen.

Verwenden Sie --no-retry, wenn das aufrufende Programm die Retry-Policy steuert, und --timeout <sekunden> (Standard: 60), um eine einzelne Anfrage zu begrenzen. Destruktive Befehle warten niemals auf eine interaktive Bestätigung: Für die nicht-interaktive Nutzung muss --force übergeben werden.

Profile

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

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

Umgebungsvariablen