Agent Integration & Skills

CLI does not replace the agent. It gives the agent a stable command entrypoint.

HENGSHI CLI works for direct human use as well as agent integration. This page focuses on the second case: how to make CLI execution more stable and reviewable when you integrate it into OpenClaw or another agent runtime.

The recommended mental model looks like this:

Layer	Purpose
Human	Provide intent, review results, confirm risk boundaries
Agent	Understand the request, break down steps, decide what capability to call
Skills	Encode domain knowledge into reusable standard workflows
HENGSHI CLI	Execute reads, previews, creates, updates, and authorization actions

Why agents should go through CLI

• Stable structured output: json / yaml works well for machine read/write paths
• Clear command boundaries: safer than letting the agent assemble private APIs
• Preview support: risky writes can go through --dry-run first
• Reusable everywhere: local terminals, CI, automation jobs, and agent runtimes share the same execution surface
• Auditable execution: the chain is easier to log, replay, and review

What official skills are for

HENGSHI CLI is delivered together with official bundled skills. The official skills typically cover these high-frequency capability domains. When describing them for readers, prefer writing both the skill names and the capabilities they cover:

• hbi-core: authentication, configuration, output, terminology rules
• hbi-data, hbi-data-modeling, hbi-pipeline, hbi-notebook: connections, datasets, modeling, execution, and metrics
• hbi-dashboard, hbi-dashboard-taste, hbi-app: planning, layout, element configuration, and app pages
• hbi-permission, hbi-user-mgmt: lookup, grant, revoke, and org governance
• hbi-workflow: cross-domain orchestration and sequencing

The main value of skills is to encode:

1. What to read before writing
2. Which actions must go through --dry-run
3. How results should be structured for humans or downstream systems

Recommended integration steps

1. Ensure the runtime is provisioned with the CLI

See Installation & Upgrade for the public install paths and post-install checks. For team or customer-facing agent runtimes, it is usually better to standardize on one CLI version and one install path instead of letting each runtime owner provision the environment ad hoc.

For example:

curl -fsSL https://download.hengshi.com/cli/install.sh | sh

2. Pin the instance and authentication

export HBI_HOST="<your-hengshi-sense-instance>"

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

See Authentication & Connection for the available auth paths. For agent runtimes, it is usually better to pin HBI_HOST + HBI_CLIENT_ID / HBI_CLIENT_SECRET; use HBI_TOKEN only as a temporary override.

3. Provision the bundled official skills

Official skills now ship together with the CLI, so the recommended path is to let the installer provision them instead of building a separate distribution flow.

If the CLI is already installed, prefer the built-in updater commands to sync the CLI or refresh the official skills:

hbi update --check
hbi update --with-skills

If the current install is not updater-managed yet, fall back to the installer path to install or refresh the official skills:

curl -fsSL https://download.hengshi.com/cli/install.sh | sh -s -- --with-skills

If you already know the target agent runtime, you can install directly into that runtime:

curl -fsSL https://download.hengshi.com/cli/install.sh | sh -s -- --with-skills --agent openclaw
curl -fsSL https://download.hengshi.com/cli/install.sh | sh -s -- --with-skills --agent github-copilot

If --agent is omitted, the installer auto-detects supported local agent config directories from the bundled supported-agents.tsv.

4. Constrain the agent’s default execution strategy

These rules should usually live in the agent prompt or runtime policy:

1. Read state before writing
2. Use --dry-run whenever possible
3. Prefer --output json or --output yaml
4. Do not assemble private HENGSHI APIs manually
5. For risky grants, deletes, or config changes, return the plan to a human before execution
6. Know HQL expressions: when constructing data-model query, metric, or measure arguments, HQL supports aggregation, time, and conditional functions — see HQL Function Reference for the full list

A typical agent execution pattern

For example, if an agent is asked to “create a sales dashboard and grant access to a teammate”, the recommended order is usually:

1. Read app and dataset context
2. Confirm whether the target dashboard already exists
3. Create the dashboard
4. Add charts or other elements
5. Preview the authorization with --dry-run
6. Execute the real grant after human confirmation

This is exactly the kind of sequencing that skills are good at capturing.

Recommended practice

If you plan to make CLI a formal part of an agent runtime, these practices usually help the most:

1. Pin the CLI version and the bundled-skill delivery path across environments
2. Prefer json or yaml output by default to reduce downstream parsing cost
3. Keep --dry-run in front of risky grants, deletes, and system configuration changes
4. Log HBI_HOST (or any saved local default host), the auth path, and the key command results for later review

What agents should return

When an agent uses CLI, ask it to summarize results in at least three buckets:

• What it did: which reads, previews, and writes were executed
• What it saw: what the important commands returned
• What is still missing: which steps did not continue because of permissions, missing context, or human confirmation

That gives teams something far more useful than a raw wall of terminal output.