De CLI is gebouwd om door scripts en agenten gelezen te worden. JSON is de standaarduitvoer; tabellen en regelgescheiden JSON zijn opt-in.
De envelope
Elke geslaagde opdracht print één JSON-object naar stdout:
{
"ok": true,
"schema_version": "1",
"workspace": "yourworkspace",
"domain": "yourworkspace.hansa.chat",
"changed": false,
"data": { }
}
changed geeft aan of de opdracht daadwerkelijk iets heeft gewijzigd — false betekent dat de gewenste toestand al bestond. data bevat het resultaat: lijsten met kanalen of berichten, een bericht met zijn inhoud als echte geneste JSON, bevestigingen van opdrachten.
Fouten gaan als JSON naar stderr en raken stdout nooit:
{
"ok": false,
"schema_version": "1",
"error": { "code": "unauthenticated", "message": "…", "retryable": false }
}
Exitcodes
| Code | Betekenis |
|---|---|
| 0 | Succes, inclusief een no-op (changed: false) |
| 1 | Interne fout |
| 2 | Gebruiks- of configuratiefout |
| 3 | Authenticatie vereist of mislukt |
| 4 | Toegang geweigerd of preconditie mislukt |
| 5 | Niet gevonden of conflict |
| 6 | Time-out, niet beschikbaar of snelheidsbeperkt |
Een robuust scriptpatroon:
if hansa chat channels ensure --name Deploy --type public >/dev/null 2>&1; then
echo "channel ready"
fi
Uitvoerformaten
hansa chat channels list -o json # default, one envelope
hansa chat channels list -o jsonl # one JSON object per line
hansa chat channels list -o table # aligned text columns for humans
Nuttige globale opties
--workspace <alias-or-domain> # override the workspace for one command
--timeout 30s # network timeout
--config /path/config.json # custom context file (default: OS config dir)
--verbose # diagnostics to stderr, secrets filtered
De omgevingsvariabele HANSA_CONFIG verplaatst het volledige contextbestand, zodat parallelle taken geïsoleerde contexten kunnen gebruiken. Headless-aanlevering van tokens en het gedrag van de sleutelketen worden beschreven in Authenticatie en workspaces.
Beveiligingsopmerkingen
- Inloggegevens staan uitsluitend in de sleutelketen van het besturingssysteem of in de procesomgeving — nooit in uitvoer, logs of het contextbestand.
--verbose-diagnostiek filtert autorisatieheaders, invoer van inloggegevens en refresh-antwoorden.- Alle identificatoren worden als JSON-strings uitgegeven, tijdstempels als UTC RFC3339; berichtinhoud verschijnt als echte geneste JSON, niet als quoted string.