--- url: /v6.2/en-us/cli-auth.md --- # 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. ```bash HBI_HOST="" 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: ```bash # Simplest way to remember a local default host hbi auth use --host "" ``` `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-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 CLI 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. ```bash HBI_HOST="" hbi auth login --device-login # Equivalent entrypoint when you already know you want device login HBI_HOST="" 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: ![](/images/cli-auth/device-login-approval.png) ### 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**: ![](/images/cli-auth/personal-access-token-panel.png) 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 ```bash HBI_HOST="" \ HBI_CLIENT_ID="" \ HBI_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: ```bash HBI_HOST="" hbi auth login --client-id "" --client-secret "" # Short-flag equivalent (they are value flags, not interactive shortcuts) HBI_HOST="" hbi auth login -i "" -s "" ``` 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 locally ```bash HBI_HOST="" hbi auth login --interactive ``` `--interactive` prompts for `client_id` / `client_secret` on **this machine** and stores them in the CLI local credential store (config-backed, not the OS keyring). 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: ```bash HBI_HOST="" HBI_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 ```bash # 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: ```bash HBI_HOST="" 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: ```bash HBI_HOST="" \ HBI_CLIENT_ID="" \ HBI_CLIENT_SECRET="" \ hbi auth login ``` This path does not depend on the OS keyring; CLI stores renewable sign-in state in its config-backed local credential store. ### Existing access token workflows Prefer: ```bash export HBI_TOKEN="" ``` For a one-off override, you can also use the global flag: ```bash hbi --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 Current CLI releases no longer integrate with the OS keyring. The default behavior and `--credential-store config` both use the CLI config-backed local credential store; `--credential-store keyring` remains only as a compatibility surface and fails explicitly. If you still see OS keyring prompts on macOS, in containers, on remote development boxes, or in partial desktop sessions, you are usually running an old or non-current official `hbi` binary. Install or update to the official release and log in again. For runtimes that must not keep client credentials locally, use a one-off `HBI_TOKEN` / `--token` instead. ## 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: ```bash 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: ```bash 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.