Troubleshooting & FAQ

Who is HENGSHI CLI mainly for?

Strictly speaking, CLI can be used by both humans and agents. In many real scenarios, it also works especially well as a stable command entrypoint for agents and automation flows.

Are skills required?

For agents, the practical answer is yes.

• If you want agents such as OpenClaw to reuse HENGSHI CLI workflows reliably, the official skills matter a lot
• They capture execution order, --dry-run strategy, and output conventions as reusable standard workflows

For humans typing commands directly in a terminal, the CLI itself can still work without them, so they are not a hard prerequisite in that case.

How should I choose an authentication path?

In most cases:

1. Local desktop usage: prefer hbi auth login --device-login
2. Agent runtimes / CI: prefer HBI_HOST + HBI_CLIENT_ID + HBI_CLIENT_SECRET
3. Existing access-token workflows: only then use HBI_HOST + HBI_TOKEN or a one-off --token

If you need the clearest one-shot login entry, prefer:

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

HBI_HOST does not need to be a full URL; a bare host or a subpath form such as platform.hengshi.org/bi both work. When the scheme is omitted, CLI probes https:// first and falls back to http://.

How do I confirm the CLI itself is installed correctly?

Run:

hbi --version
hbi --help
hbi auth status

If the first two commands work and the third only says that you are not logged in yet, the CLI binary is already fine.

Will CLI reuse the sign-in state automatically after login?

Yes.

Yes. In the common login paths, CLI stores the local sign-in state for reuse. If valid client credentials remain available in the environment, later authenticated commands can also obtain or refresh access tokens automatically.

Why does the system keyring keep popping up, or how do I avoid it in a container / remote runtime?

If the current runtime should not use the OS keyring — for example in containers, remote development boxes, CI, or partial desktop sessions — disable keyring integration explicitly:

export HBI_DISABLE_KEYRING=true

Then prefer explicit HBI_HOST + HBI_CLIENT_ID + HBI_CLIENT_SECRET injection (or a one-off HBI_TOKEN) instead of interactive local credential storage.

Where can I find the personal client created by device login?

Go to User Center > Personal Access Token.

After the first successful device login, the system creates or reuses a personal client for the current user. This panel shows the Client ID and Client Secret, but it does not display an access token; access tokens are still cached and renewed locally by CLI.

Why can I log in but still not see the expected resources?

Check these first:

1. Whether HBI_HOST or the saved local default host points to the correct target
2. Whether the current identity really has access to the app, dataset, or connection
3. Whether the agent runtime inherited the same environment variables as your shell

Why is --dry-run recommended before risky actions?

Because permission changes, configuration updates, and similar side-effecting operations fit naturally into a review flow. The value of --dry-run is not “one more step”; it is that the agent can explain what it plans to change, where, and with what impact before the real write happens.

Why don’t I see the Autopilot indicator on the page?

Common reasons:

1. An administrator has disabled GENERAL_CONFIG_ENABLE_SSE, so the instance no longer exposes the Autopilot / SSE feedback UI (the frontend system-preferences field then appears as enableSse=false)
2. The current page is outside the pages that support live sync
3. The current page is mobile or does not expose a top status indicator
4. The current session does not have an active SSE connection
5. The current user is not in the realtime path for this page

For the current page boundary, see the “Current page boundary” section in Realtime Sync & Autopilot.

Why did CLI or an agent change a resource, but the page did not refresh?

That usually does not mean the CLI failed. More common explanations are:

1. An administrator has disabled GENERAL_CONFIG_ENABLE_SSE for the instance
2. The current page is outside the realtime-sync coverage
3. The changed resource does not belong to the current detail page or active list
4. The current action is really an execution / execution-record / DAG flow that mainly relies on synchronous waiting or polling
5. The current connection is down and the Autopilot indicator is disconnected
6. A reverse proxy or gateway cut /api/sse/subscribe too early or buffered the SSE response
7. The page has unsaved local edits and should not be overwritten directly

What information should I include when troubleshooting?

At minimum:

• CLI version
• Installation method (static installer / release asset)
• Operating system
• HBI_HOST (and, if you rely on one, the saved local default host / instance alias)
• Authentication method (device login / client credentials / temporary access-token injection)
• The executed command
• Whether --dry-run was used
• Preferably one --output json result
• If UI sync is involved, also include the page path, Autopilot state, and whether the surface is mobile

Recommended troubleshooting order

1. Confirm the CLI binary works
2. Confirm the target instance and authentication
3. Confirm the current instance, target resource, and permissions
4. Only then check whether UI realtime sync is expected on the current page

This is usually much faster than starting from the browser alone.