JSON-Ausgabe und Automatisierung

Die CLI ist zum Lesen durch Skripte und Agenten gebaut. JSON ist die Standardausgabe; Tabellen und zeilenweises JSON sind optional.

Der Umschlag

Jeder erfolgreiche Befehl gibt genau ein JSON-Objekt auf stdout aus:

{
  "ok": true,
  "schema_version": "1",
  "workspace": "yourworkspace",
  "domain": "yourworkspace.hansa.chat",
  "changed": false,
  "data": { }
}

changed sagt, ob der Befehl tatsächlich etwas geändert hat — false bedeutet, dass der Zielzustand bereits bestand. data enthält das Ergebnis: Kanal- oder Nachrichtenlisten, eine Nachricht mit ihrem Inhalt als echtes verschachteltes JSON, Befehlsbestätigungen.

Fehler gehen als JSON an stderr und berühren stdout nie:

{
  "ok": false,
  "schema_version": "1",
  "error": { "code": "unauthenticated", "message": "…", "retryable": false }
}

Exit-Codes

Code	Bedeutung
0	Erfolg, einschließlich No-Op (`changed: false`)
1	Interner Fehler
2	Nutzungs- oder Konfigurationsfehler
3	Authentifizierung nötig oder fehlgeschlagen
4	Zugriff verweigert oder Vorbedingung fehlgeschlagen
5	Nicht gefunden oder Konflikt
6	Zeitüberschreitung, nicht verfügbar oder rate-limited

Ein robustes Skriptmuster:

if hansa chat channels ensure --name Deploy --type public >/dev/null 2>&1; then
  echo "Kanal bereit"
fi

Ausgabeformate

hansa chat channels list -o json    # Standard, ein Umschlag
hansa chat channels list -o jsonl   # ein JSON-Objekt pro Zeile
hansa chat channels list -o table   # ausgerichtete Textspalten für Menschen

Nützliche globale Flags

--workspace <alias-oder-domain> # Workspace für einen Befehl überschreiben
--timeout 30s                   # Netzwerk-Timeout
--config /pfad/config.json      # eigene Kontextdatei (Standard: OS-Konfigurationsordner)
--verbose                       # Diagnose auf stderr, Geheimnisse gefiltert

Die Umgebungsvariable HANSA_CONFIG verlagert die gesamte Kontextdatei, damit parallele Jobs isolierte Kontexte nutzen können. Token ohne Schlüsselbund und das Schlüsselbund-Verhalten sind unter Authentifizierung beschrieben.

Sicherheitshinweise

Anmeldedaten liegen nur im Betriebssystem-Schlüsselbund oder in der Prozess-Umgebung — nie in der Ausgabe, in Protokollen oder in der Kontextdatei.
--verbose-Diagnose filtert Authorization-Header, Anmeldeeingaben und Refresh-Antworten.
Alle Kennungen werden als JSON-Zeichenketten ausgegeben, Zeitstempel als UTC RFC3339; Nachrichteninhalt erscheint als echtes verschachteltes JSON, nicht als Zeichenkette in Anführungszeichen.