JSON output and automation

The CLI is built to be read by scripts and agents. JSON is the default output; tables and line-delimited JSON are opt-in.

The envelope

Every successful command prints one JSON object to stdout:

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

changed tells you whether the command actually modified anything — a false means the desired state already existed. data holds the result: lists of channels or messages, a message with its content as real nested JSON, command acknowledgements.

Errors go to stderr as JSON and never touch stdout:

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

Exit codes

Code	Meaning
0	Success, including a no-op (`changed: false`)
1	Internal error
2	Usage or configuration error
3	Authentication required or failed
4	Permission denied or precondition failed
5	Not found or conflict
6	Timeout, unavailable, or rate limited

A robust script pattern:

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

Output formats

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

Useful global flags

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

The HANSA_CONFIG environment variable relocates the whole context file, which lets parallel jobs use isolated contexts. Headless token supply and the keychain behavior are described in authentication.

Security notes

Credentials live only in the OS keychain or the process environment — never in output, logs, or the context file.
--verbose diagnostics filter authorization headers, credential input, and refresh responses.
All identifiers are emitted as JSON strings, timestamps as UTC RFC3339; message content appears as real nested JSON, not as a quoted string.