Output JSON e automazione | HansaChat Docs

La CLI è costruita per essere letta da script e agenti. JSON è l’output predefinito; le tabelle e il JSON delimitato per riga sono opzionali.

La busta

Ogni comando riuscito stampa un oggetto JSON su stdout:

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

changed dice se il comando ha effettivamente modificato qualcosa — un valore false significa che lo stato desiderato esisteva già. data contiene il risultato: elenchi di canali o messaggi, un messaggio con il suo contenuto come JSON realmente annidato, conferme dei comandi.

Gli errori vanno su stderr come JSON e non toccano mai stdout:

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

Codici di uscita

Codice	Significato
0	Riuscito, incluso un no-op (`changed: false`)
1	Errore interno
2	Errore di uso o di configurazione
3	Autenticazione richiesta o non riuscita
4	Permesso negato o precondizione non soddisfatta
5	Non trovato o conflitto
6	Timeout, non disponibile o limite di frequenza raggiunto

Uno schema di script robusto:

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

Formati di output

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

Flag globali utili

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

La variabile d’ambiente HANSA_CONFIG sposta l’intero file dei contesti, il che permette ai job paralleli di usare contesti isolati. La fornitura di token headless e il comportamento del portachiavi sono descritti in autenticazione.

Note di sicurezza

Le credenziali risiedono solo nel portachiavi del sistema operativo o nell’ambiente del processo — mai nell’output, nei log o nel file dei contesti.
La diagnostica di --verbose filtra le intestazioni di autorizzazione, l’input delle credenziali e le risposte di refresh.
Tutti gli identificatori vengono emessi come stringhe JSON, i timestamp come UTC RFC3339; il contenuto dei messaggi compare come JSON realmente annidato, non come stringa tra virgolette.