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 --interactive
2. Agent runtimes / CI: prefer HBI_CLIENT_ID + HBI_CLIENT_SECRET
3. Existing token workflows: use HBI_TOKEN directly

If you simply want to perform one explicit login first, you can also run:

hbi auth login --client-id <client_id> --client-secret <client_secret>

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 tokens automatically after login?

Yes.

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

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

Check these first:

1. Whether HBI_API_URL points to the correct instance
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_API_URL
• Authentication method (interactive login / client credentials / token)
• 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.