Wyniki JSON i automatyzacja

CLI zostało zaprojektowane tak, by odczytywały je skrypty i agenty. Domyślnym wyjściem jest JSON; tabele i JSON rozdzielany wierszami są dostępne na życzenie.

Struktura odpowiedzi

Każde udane polecenie wypisuje jeden obiekt JSON na standardowe wyjście (stdout):

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

Wartość changed informuje, czy polecenie rzeczywiście coś zmieniło — false oznacza, że żądany stan już istniał. data zawiera wynik: listy kanałów lub wiadomości, wiadomość z treścią jako prawdziwy zagnieżdżony JSON, potwierdzenia wykonania poleceń.

Błędy trafiają na standardowe wyjście błędów (stderr) jako JSON i nigdy nie pojawiają się na stdout:

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

Kody wyjścia

Kod	Znaczenie
0	Sukces, w tym operacja pusta (`changed: false`)
1	Błąd wewnętrzny
2	Błąd użycia lub konfiguracji
3	Wymagane uwierzytelnienie lub uwierzytelnienie nie powiodło się
4	Brak uprawnień lub niespełniony warunek wstępny
5	Nie znaleziono lub konflikt
6	Przekroczono limit czasu, usługa niedostępna lub ograniczenie częstotliwości żądań

Odporny wzorzec dla skryptów:

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

Formaty wyjścia

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

Przydatne flagi globalne

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

Zmienna środowiskowa HANSA_CONFIG przenosi cały plik kontekstu, dzięki czemu równoległe zadania mogą używać izolowanych kontekstów. Dostarczanie tokenów w trybie headless i zachowanie kluczyka są opisane w rozdziale Uwierzytelnianie i przestrzenie robocze.

Uwagi o bezpieczeństwie

Dane uwierzytelniające są przechowywane wyłącznie w kluczyku systemowym lub środowisku procesu — nigdy w wynikach, logach ani pliku kontekstu.
Diagnostyka --verbose filtruje nagłówki autoryzacji, dane uwierzytelniające podane na wejściu i odpowiedzi odświeżania.
Wszystkie identyfikatory są wypisywane jako ciągi JSON, a znaczniki czasu jako UTC RFC3339; treść wiadomości pojawia się jako prawdziwy zagnieżdżony JSON, a nie ciąg w cudzysłowie.