HansaChat

Documentation

JSON výstup a automatizace

Obálka výstupu, návratové kódy, formáty a bezpečné vzory pro skripty.

Rozhraní CLI je navrženo tak, aby je četly skripty a agenti. Výchozím výstupem je JSON; tabulky a JSON oddělovaný řádky jsou volitelné.

Obálka výstupu

Každý úspěšný příkaz vypíše na stdout jeden objekt JSON:

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

Pole changed říká, zda příkaz skutečně něco změnil — hodnota false znamená, že požadovaný stav již existoval. Pole data obsahuje výsledek: seznamy kanálů nebo zpráv, zprávu s jejím obsahem jako skutečným vnořeným JSON, potvrzení příkazů.

Chyby směřují na stderr jako JSON a stdout se nikdy nedotknou:

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

Návratové kódy

Kód Význam
0 Úspěch, včetně operace bez změny (changed: false)
1 Interní chyba
2 Chyba použití nebo konfigurace
3 Vyžadována nebo selhala autentizace
4 Odepřeno oprávnění nebo nesplněna podmínka
5 Nenalezeno nebo konflikt
6 Časový limit, nedostupnost nebo omezení rychlosti

Robustní vzor pro skripty:

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

Výstupní formáty

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

Užitečné globální přepínače

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

Proměnná prostředí HANSA_CONFIG přesune celý soubor kontextů, což umožní paralelním úlohám používat izolované kontexty. Dodávání tokenů v headless režimu a chování klíčenky jsou popsány v článku Autentizace a workspacy.

Bezpečnostní poznámky

  • Přihlašovací údaje žijí pouze v klíčence operačního systému nebo v prostředí procesu — nikdy ve výstupu, protokolech ani v souboru kontextů.
  • Diagnostika --verbose filtruje autorizační hlavičky, zadané přihlašovací údaje a odpovědi na obnovení tokenu.
  • Všechny identifikátory se vypisují jako řetězce JSON, časová razítka jako UTC RFC3339; obsah zpráv se zobrazuje jako skutečný vnořený JSON, nikoli jako řetězec v uvozovkách.