---
url: /v6.2/cli.md
---
# HENGSHI CLI

## 概述

HENGSHI CLI 是 HENGSHI 官方命令行工具，也是面向人类与 AI Agent 的统一命令入口。它把原本分散在界面点击、后台 API、临时脚本里的操作，整理成稳定、可审查、可自动化的命令工作流。

CLI 当前覆盖的核心能力包括：

* 数据连接与数据集接入
* HQL / HE 查询与数据预览
* 仪表盘、报表与元素创建 / 配置
* 权限查询、授权与回收
* 系统配置、环境检查与运维动作
* 与官方 skills 配套的 Agent 执行工作流

> \[!NOTE]
> 从 **2.0.0** 开始，公开命令入口为 `hbi`，文档默认使用 `hbi` 与 `HBI_*`。为避免混淆，本页不展开旧命名空间的兼容细节；如你的环境仍在使用旧命令/变量，请以实际安装包与升级脚本输出为准。

## 作为 HENGSHI SENSE 与 Agent 之间的桥梁

HENGSHI CLI 的角色，不是替代 HENGSHI SENSE 页面，而是把 HENGSHI SENSE 的核心能力转成可稳定调用、审查和复用的命令入口。它既适合人工在终端直接使用，也适合被 OpenClaw 等 Agent、CI 流水线和自动化脚本调用。

在这条链路里，常见分工是：

| 层级 | 角色 | 典型职责 |
| --- | --- | --- |
| 人 | 任务提出者与审核者 | 提要求、确认边界、审结果 |
| Agent / 自动化流程 | 编排层 | 拆步骤、组织顺序、决定下一步调用哪条命令 |
| HENGSHI CLI + skills | 桥梁与执行层 | 把 HENGSHI SENSE 的业务能力转换成结构化命令、输出与 `--dry-run` 预演 |
| HENGSHI SENSE 服务端 | 业务能力层 | 真正完成连接、查询、建模、授权、发布等动作 |

如果你在为 OpenClaw 或其他 Agent 设计可复用工作流，CLI 通常就是这座桥本身：上接 Agent 的任务编排，下接 HENGSHI SENSE 的真实业务能力，而不是让 Agent 自己去猜页面路径或临时拼 API。

## CLI 适合解决什么问题

| 场景 | CLI 带来的价值 |
| --- | --- |
| 让 Agent 代做 BI 交付动作 | 统一命令与输出格式，避免“每个 Agent 猜一套 API” |
| 把高风险改动放进审批流 | `--dry-run` 先预演，再决定是否真正执行 |
| 把结果回传给人或其他系统 | `json` / `yaml` / `table` 输出更容易被读取、记录和二次处理 |
| 做批量化、可重复的运维任务 | 单命令、脚本、CI、Agent 都能复用同一条执行路径 |
| 让界面外产生的变更回到前端体验里 | 通过 SSE / Autopilot 指示器补上实时回显链路 |

## 命令面一览

HENGSHI CLI 不是单一功能命令，而是一整套面向 BI 交付主链路的命令树。

| 命令域 | 说明 | 示例 |
| --- | --- | --- |
| `app` | 应用、空间、门户、公共维度 | `hbi app list --area personal-area --root` |
| `dataset` | 数据集接入与列表查看 | `hbi dataset list --app 4812 --output json` |
| `data-model` | HQL / HE 查询与数据预览 | `hbi data-model query --app 4812 --dataset 3 "SUM({amount})"` |
| `dashboard` | 仪表盘、报表、主题 | `hbi dashboard create --app 4812 "区域销售驾驶舱"` |
| `element` | 图表、筛选器、容器、按钮、iframe 等元素，支持自定义标题与内容识别（链接/邮箱/图片）开关 | `hbi element chart create --dashboard 2048 --app 4812 --dataset 3 table --identify-link true --identify-email true --identify-image true` |
| `connection` | 数据源连接创建与管理 | `hbi connection list` |
| `authorize` | 统一授权 API | `hbi authorize grant app 42 --user 123:editor --dry-run` |
| `preferences` | 系统配置查看与变更预演 | `hbi preferences everest --output json` |

### HQL 表达式支持

CLI 的 `--dimension`、`--measure` 和 `--where` 参数接受 [HQL (HENGSHI Query Language)](https://api.hengshi.com/function_reference.html) 表达式，不限于简单字段名。

* **时间分组**：建议使用日历 HQL 函数（如 `day()`、`month()`、`trunc_month()`），避免 `substring` / `date_format` 等字符串截断
* **跨期函数**：HQL 还提供 `moy()`、`dom()`、`dow()`、`doy()`、`woy()`、`qoy()` 等跨期函数，实现月跨年、天跨月、季度跨年等连续时间聚合——这与前端 UI 的"月(跨年)"、"天(跨月)"选项在语义上完全等价
* **表达式验证**：使用 `hbi dataset expression-rewrite` 验证和重写表达式

详见 [`element chart create --dimension`](cli-reference-app.md#--dimension-时间函数说明) 的说明。

## 官方 skills 与 Agent 执行

CLI 会和官方 bundled skills 一起交付。官方 skills 通常按能力域分层；对外说明时，推荐同时保留 **skill 名称** 与 **职责描述**：

* `hbi-core`：认证、配置、输出与术语规则
* `hbi-data`、`hbi-data-modeling`、`hbi-pipeline`、`hbi-notebook`：数据连接、数据集、建模、执行与指标工作流
* `hbi-dashboard`、`hbi-dashboard-taste`、`hbi-app`：仪表盘规划、页面布局、元素配置与应用承载
* `hbi-permission`、`hbi-user-mgmt`：权限查询、授权回收与用户组织治理
* `hbi-workflow`：跨领域编排与顺序控制

这些 skills 的作用不是替代 CLI，而是把“什么时候调用哪条命令、应该先读什么、哪些动作必须先 `--dry-run`”这样的执行经验沉淀成可复用的标准流程。

## 阅读路径

如果你是第一次接触 HENGSHI CLI，建议按下面顺序阅读：

1. [安装与升级](cli-install.md)
2. [认证与连接](cli-auth.md)
3. [Agent 接入与 skills](cli-agent.md)
4. [常用工作流](cli-workflows.md)
5. [命令参考](cli-reference.md) — 已为高频命令域补充最小可用示例与典型输出，适合第一次上手
6. [实时回显与 Autopilot](cli-autopilot.md)
7. [排障与 FAQ](cli-faq.md)

> \[!TIP] 建议
> 如果你的目标是让 Agent 稳定执行动作，而不是人工逐条敲命令，优先看 [Agent 接入与 skills](cli-agent.md) 与 [常用工作流](cli-workflows.md)。如果你想快速上手某个命令域，直接进入 [命令参考](cli-reference.md)；高频命令域已经补充了最小可用示例和典型输出。