Authentication and workspaces

The CLI keeps one account per workspace. Credentials live in the operating system keychain (service hansa); they never appear in the context file, logs, or output.

Logging in

hansa chat login --workspace yourworkspace

This prompts for your email and password. If the workspace requires two-factor authentication, you are asked for a TOTP code or a recovery code.

For scripts, read credentials from stdin instead of flags or environment variables:

echo '{"email": "you@example.com", "password": "…"}' \
  | hansa chat login --workspace yourworkspace --credentials-stdin

The JSON may also contain "totp" or "recovery_code" when two-factor authentication is required.

A valid saved session makes a repeated login a no-op. Use --reauth to replace the stored session deliberately.

Sessions and refresh

Access tokens refresh automatically using a rotating refresh token, guarded by a per-workspace lock so parallel CLI processes never break each other's session. If the stored session becomes unusable, the CLI removes it and asks you to log in again.

Logging out revokes the session on the server and deletes the stored credentials. Running it twice is safe:

hansa chat logout --workspace yourworkspace

Contexts

A context is one saved workspace: its domain, optional API override, and whether credentials exist. Tokens are never shown.

hansa context list        # saved contexts, default marker
hansa context show        # details for the current workspace
hansa context use yourworkspace     # set the default workspace
hansa context remove yourworkspace  # log out remotely and delete everything

Workspace resolution order: the --workspace flag, then the HANSA_WORKSPACE environment variable, then the saved default.

Headless environments

Without a keychain (CI containers, cron jobs), provide tokens via the environment:

export HANSA_ACCESS_TOKEN="…"
export HANSA_REFRESH_TOKEN="…"   # optional, enables automatic refresh

Tokens are never written to disk in this mode, and login without a usable keychain fails explicitly instead of storing credentials in plain text.