---
url: /v6.2/en-us/cli-agent.md
---
# 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](cli-install.md) 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:

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

### 2. Pin the instance and authentication

```bash
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](cli-auth.md) 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:

```bash
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:

```bash
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:

```bash
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](https://api.hengshi.com/function_reference.html) 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.