JSON-kimenet és automatizálás

A CLI-t szkriptek és ügynökök általi olvasásra tervezték. Az alapértelmezett kimenet a JSON; a táblázatos és a soronkénti JSON-kimenet külön kérhető.

A kimeneti boríték

Minden sikeres parancs egy JSON-objektumot ír a stdout-ra:

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

A changed megmutatja, hogy a parancs ténylegesen módosított-e valamit — a false azt jelenti, hogy a kívánt állapot már létezett. A data tartalmazza az eredményt: csatornák vagy üzenetek listáit, egy üzenetet a tartalmával valódi beágyazott JSON-ként, parancsmegerősítéseket.

A hibák JSON-ként a stderr-re kerülnek, és sosem érintik a stdout-ot:

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

Kilépési kódok

Kód	Jelentés
0	Siker, a no-op is (`changed: false`)
1	Belső hiba
2	Használati vagy konfigurációs hiba
3	Hitelesítés szükséges vagy sikertelen
4	Hozzáférés megtagadva vagy előfeltétel teljesítetlen
5	Nem található vagy ütközés
6	Időtúllépés, nem elérhető vagy gyakoriságkorlát elérve

Egy robusztus szkriptminta:

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

Kimeneti formátumok

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

Hasznos globális kapcsolók

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

A HANSA_CONFIG környezeti változó áthelyezi a teljes kontextusfájlt, amellyel a párhuzamos feladatok elkülönített kontextusokat használhatnak. A headless tokenellátást és a kulcscsomó működését a hitelesítést ismertető útmutató írja le.

Biztonsági megjegyzések

A hitelesítési adatok csak az operációs rendszer kulcscsomójában vagy a folyamat környezetében léteznek — sosem a kimenetben, a naplókban vagy a kontextusfájlban.
A --verbose diagnosztika kiszűri az engedélyezési fejléceket, a hitelesítési bemenetet és a frissítési válaszokat.
Minden azonosító JSON-karakterláncként, az időbélyegek UTC RFC3339 formátumban kerülnek kiadásra; az üzenettartalom valódi beágyazott JSON-ként jelenik meg, nem idézett karakterláncként.