Authentication & Connection

Pick the target host first

Before CLI can perform any business action, it needs to know which HENGSHI SENSE host it is talking to.

HBI_HOST="<your-hengshi-sense-instance>" hbi auth login --device-login

HBI_HOST can be a bare host or include a subpath such as platform.hengshi.org/bi. When the scheme is omitted, CLI probes https:// first and falls back to http://.

If you want a local default host for interactive use, the simplest local-convenience path is:

# Simplest way to remember a local default host
hbi auth use --host "<your-hengshi-sense-instance>"

auth use fits “I already know the host and just want to make it the local default on this machine.” If you maintain a set of named aliases, you can still use instance add / instance use; but for scripts, agents, cron jobs, and multi-environment work, prefer explicit HBI_HOST=... hbi xxx over relying on local-default mechanisms.

Keep the public mental model as a simple decision table:

Scenario	Recommended	Notes
Human-operated terminal / someone can approve in a browser (including remote openclaw / SSH)	HBI_HOST=... hbi auth login --device-login	Requires browser approval; CLI stores a renewable sign-in state for the current host and reuses it
Automation / service accounts / CI	HBI_HOST=... HBI_CLIENT_ID=... HBI_CLIENT_SECRET=... hbi auth login	Uses client credentials and can keep obtaining/refreshing access tokens
You already have client_id / client_secret and want to pass values directly (no credential env injection, no prompts)	HBI_HOST=... hbi auth login --client-id "<client_id>" --client-secret "<client_secret>" (or short flags -i/-s)	Passes credential values directly. -i/-s are value flags for Client ID / Secret, not interactive shortcuts. Prefer controlled environments (avoid leaking into shell history)
You want to enter and store client credentials interactively	HBI_HOST=... hbi auth login --interactive	Still the client-credentials path: prompts on this machine and stores into the system keyring/local credential store; not a third auth model
You already have a token and only need a one-off override	HBI_TOKEN or --token	Temporary override only; does not create reusable login state and does not promise auto refresh

Note: “openclaw / SSH” here just means the CLI is running on a remote machine/container; the browser approval step can be completed on any device with a browser.

Public documentation uses HBI_* as the environment-variable namespace.

Option 1: Prefer browser device login

This is the recommended default path. It matches the mental model used by tools like gh auth login and glab auth login: pick the host explicitly, then log in.

HBI_HOST="<your-hengshi-sense-instance>" hbi auth login --device-login

# Equivalent entrypoint when you already know you want device login
HBI_HOST="<your-hengshi-sense-instance>" hbi auth device-login

hbi auth login --device-login and hbi auth device-login run the same browser-based device-login flow. The former fits the unified auth login mental model; the latter is a more direct entrypoint when device login is already the chosen path.

After a successful login, CLI stores the sign-in state for the current host locally and reuses it automatically.

This also works for remote terminals (openclaw / SSH / jump hosts / containers): as long as a human can open the approval page in any browser and confirm the request, device login works. The remote CLI only needs to show the device code / verification URL to the approver.

The browser side opens a dedicated approval page so you can confirm which instance, which device code, and which signed-in identity is approving the request:

Where do I find the personal client / PAT credentials after device login?

After the first successful device login, the system creates or reuses a personal client for the current user. You can inspect it in User Center > Personal Access Token:

Key points about this panel:

• It shows reusable Client ID / Client Secret
• The page does not display an access token; CLI stores and reuses it through the local credential cache
• If you later want to switch to the client credentials path, or provide renewable credentials to an agent runtime or CI job, copy the client credentials from this panel
• If you suspect the client_secret was leaked, you can delete the current PAT client from this panel; the old client becomes invalid, and the next device-login / PAT token flow will create a fresh personal credential
• For normal local desktop usage, hbi auth login --device-login is still the preferred path

Option 2: Log in with client credentials (direct credentials)

Use this path for service accounts, CI, agent runtimes, or any environment where you already have client_id / client_secret.

2.1 Non-interactive: provide credentials via environment variables

HBI_HOST="<your-hengshi-sense-instance>" \
HBI_CLIENT_ID="<client_id>" \
HBI_CLIENT_SECRET="<client_secret>" \
hbi auth login

CLI stores the resulting sign-in state locally. As long as valid client credentials remain available, later authenticated commands can continue to obtain or refresh access tokens automatically.

2.2 Non-interactive: pass credentials via CLI flags

If you do not want to pass client_id / client_secret via environment variables, you can pass them directly:

HBI_HOST="<your-hengshi-sense-instance>" hbi auth login --client-id "<client_id>" --client-secret "<client_secret>"

# Short-flag equivalent (they are value flags, not interactive shortcuts)
HBI_HOST="<your-hengshi-sense-instance>" hbi auth login -i "<client_id>" -s "<client_secret>"

Note: putting secrets on the command line can leak via shell history, process lists, or CI logs. For automation, prefer secrets + environment variables.

2.3 Interactive: enter and store credentials on this machine

HBI_HOST="<your-hengshi-sense-instance>" hbi auth login --interactive

--interactive prompts for client_id / client_secret on this machine and stores them in the system keyring (or local credential store). It is still the client credentials (direct credentials) path — just a different input UX, not a third auth model — and is best for human-operated desktop environments.

Option 3: Inject an access token directly

If you already have an access token, you can provide it directly:

HBI_HOST="<your-hengshi-sense-instance>" HBI_TOKEN="<token>" hbi auth status

For users, this should stay one concept: access token. HBI_TOKEN (environment variable) and --token (global flag) are just two ways to pass the same access token into the CLI. They override saved credentials, but they are not a separate auth system.

Note: token injection does not create reusable sign-in state and does not auto-refresh. Once it expires, you must inject a new token or switch back to the renewable paths above.

This path fits:

• Environments that already distribute short-lived tokens
• Temporary automation tasks
• Runtimes that should not keep client credentials locally
• Cases where token expiry is acceptable and no durable refresh guarantee is needed

Common auth commands

# Inspect current auth state
hbi auth status --output json

# Refresh the access token
hbi auth refresh

# Log out
hbi auth logout

# List supported auth methods
hbi auth methods

# Show the active auth method
hbi auth active

Public usage recommendations

Local desktop usage

Prefer:

HBI_HOST="<your-hengshi-sense-instance>" hbi auth login --device-login

If you already saved a default host on this machine, you can run hbi auth login --device-login (or hbi auth device-login) without repeating HBI_HOST. But for docs examples, scripts, and multi-environment work, still prefer explicit HBI_HOST=....

Agent runtimes / CI

Prefer:

HBI_HOST="<your-hengshi-sense-instance>" \
HBI_CLIENT_ID="<client_id>" \
HBI_CLIENT_SECRET="<client_secret>" \
hbi auth login

If the runtime should avoid the system keyring, environment variables plus the local credential cache are usually enough.

Existing access token workflows

Prefer:

export HBI_TOKEN="<token>"

For a one-off override, you can also use the global flag:

hbi --token "<token>" auth status

Credential-safety recommendations

• Do not hardcode access tokens or client secrets into scripts, docs, or repositories
• For automation, prefer secrets or environment-variable injection
• For local desktop usage, prefer browser device login
• Do not paste full auth status output into public channels

If a container or restricted runtime should avoid the system keyring entirely, you can explicitly set:

export HBI_DISABLE_KEYRING=true

If the current runtime keeps triggering OS keyring prompts — common in containers, remote development boxes, or partial desktop sessions — prefer explicit HBI_HOST + HBI_CLIENT_ID + HBI_CLIENT_SECRET injection (or a one-off HBI_TOKEN) and keep HBI_DISABLE_KEYRING=true so the CLI does not rely on system keyring integration.

Common connection issues

HBI_HOST or a local default host is not set

CLI does not know which host to target and will usually fail on the first request. Check:

echo "$HBI_HOST"
hbi instance current

If you do not want to rely on local defaults, pass HBI_HOST=... explicitly on the command line.

Login succeeded but the expected resources are missing

Check these first:

1. The CLI is pointing to the wrong host / instance
2. The current identity lacks access to the target app, dataset, connection, or space
3. The agent runtime inherited a different set of environment variables than your shell

Tokens expire or auth feels unstable

Start with:

hbi auth status --output json
hbi auth refresh

If you rely on client credentials, also confirm that HBI_CLIENT_ID and HBI_CLIENT_SECRET are still valid.