---
url: /v6.2/cli-reference-app.md
---
# 应用与仪表盘命令

这一页覆盖应用空间、仪表盘和页面控件相关命令,和 `hbi-app`、`hbi-dashboard` 这两类 skills 最接近。高频命令域提供最小可用示例与典型输出，方便第一次上手时直接照着跑。

## `app`

**用途**：管理应用本体，以及应用级配置与授权。

**常见子命令**：

* 生命周期：`list` `show` `create` `update` `move` `transfer` `delete` `duplicate` `export` `import`
* 内容替换：`dataapp-replace` `connection-replace`
* 授权与发布：`grant` `revoke` `permissions` `publish` `republish` `unpublish` `share`
* 应用能力：`param` `dimension` `rule` `subscribe` `portal` `locale` `refresh-schedule`
* 智能化：`vectorize-datasets`

**最小可用示例**：

```bash
hbi app list --area personal-area --root --limit 3 --output json
```

**典型输出**：

```json
[
  {
    "id": 4812,
    "title": "销售分析应用",
    "createdAt": "2025-03-15 10:00:00",
    "createdBy": 151,
    "updatedAt": "2026-05-20 14:30:00",
    "updatedBy": 151,
    "action": "read",
    "area": "PERSONAL_AREA",
    "type": "ANALYTIC_APP",
    "isPublish": false
  }
]
```

**下一步常见动作**：

* 查看应用详情：`hbi app show 4812 --output json`
* 列出应用内仪表盘：`hbi dashboard list --app 4812 --output json`
* 列出应用内数据集：`hbi dataset list --app 4812 --output json`
* 授权应用访问：`hbi app grant 4812 -u 123 -p edit --dry-run`

如果你需要继续深入某个应用能力，重点关注这些命令树：

* 参数与公共维度：`app param` `app dimension`
* 规则与订阅：`app rule` `app subscribe`
* 门户、本地化、刷新计划：`app portal` `app locale` `app refresh-schedule`

## `folder`

**用途**：管理文件夹树。

**常见子命令**：

* `list` `show`
* `create` `update` `delete`
* `move`
* `root`

适合在个人空间、团队空间、数据集市等目录体系里组织资源。

**最小可用示例**：

```bash
hbi folder root --area personal-area --output json
```

**典型输出**：

```json
{
  "id": 0,
  "title": "personal_area_root_folder",
  "area": "PERSONAL_AREA",
  "children": [
    {
      "id": 3674,
      "title": "Analytics Projects",
      "area": "PERSONAL_AREA",
      "children": []
    }
  ]
}
```

**下一步常见动作**：

* 查看特定文件夹：`hbi folder show 3674 --output json`
* 创建子文件夹：`hbi folder create --parent 3674 "Q1 Reports" --output json`
* 移动文件夹：`hbi folder move 3674 --target-parent 0 --dry-run`

## `dashboard`

**用途**：管理仪表盘、报表和主题。

**常见子命令**：

* `list` `show`
* `create` `copy` `delete` `update`
* `export-data` `export-file`
* `plan`
* `theme`

**最小可用示例**：

```bash
hbi dashboard create --app 4812 "销售驾驶舱" --output json
```

**典型输出**：

```json
{
  "id": 7650,
  "title": "销售驾驶舱",
  "appId": 4812,
  "dashboardType": "dashboard",
  "createdAt": "2026-06-02 15:30:00",
  "createdBy": 151
}
```

**下一步常见动作**：

* 查看仪表盘详情：`hbi dashboard show 7650 --app 4812 --output json`
* 在仪表盘中创建图表：`hbi element chart create --dashboard 7650 --app 4812 --dataset 3 --custom-title "销售趋势" --show-chart-title bar`
* 导出仪表盘数据：`hbi dashboard export-data 7650 --app 4812 --output json`

继续下钻时，最常用的是两条命令树：

* 按 YAML 批量创建或更新：`dashboard plan`
* 主题资源管理：`dashboard theme`

`plan` 适合按 YAML 批量创建或更新仪表盘；`theme` 用于管理系统内建或应用可见的自定义主题。

## `element`

**用途**：管理仪表盘里的图表和页面控件。

`element` 本身是一个二级命令入口，常见家族包括：

* `chart`
* `button`
* `filter`
* `container`
* `iframe`
* `image`
* `shape`
* `text`

**最小可用示例**：

```bash
# 创建柱状图
hbi element chart create --dashboard 7650 --app 4812 --dataset 3 --custom-title "销售趋势" --show-chart-title bar --output json

# 创建表格并启用内容识别（链接/邮箱/图片）
hbi element chart create --dashboard 7650 --app 4812 --dataset 3 table --identify-link true --identify-email true --identify-image true --output json
```

**典型输出**：

```json
{
  "id": 12450,
  "chartType": "line",
  "dashboardId": 7650,
  "appId": 4812,
  "datasetId": 3,
  "createdAt": "2026-06-02 15:45:00"
}
```

**下一步常见动作**：

* 查看图表详情：`hbi element chart show 12450 --dashboard 7650 --app 4812 --output json`
* 查询图表数据：`hbi element chart query 12450 --dashboard 7650 --app 4812 --output json`
* 更新图表配置：`hbi element chart patch 12450 --dashboard 7650 --app 4812 --config chart-config.json`

#### `--dimension` 时间函数说明

`chart create` 的 `--dimension` 参数接受任意 [HQL 表达式](https://api.hengshi.com/function_reference.html)，不限于简单字段名。时间分组建议使用日历 HQL 函数，避免 `substring` / `date_format` 等字符串截断方式。

**时间函数对照表：**

| 自然周期 | 跨期函数 | 说明 |
| --- | --- | --- |
| `day({field})` | `dom({field})` | 日 / 月中日（跨月对比用 `dom`） |
| `month({field})` | `moy({field})` | 月 / 年中月（月跨年对比用 `moy`） |
| `quarter({field})` | `qoy({field})` | 季度 / 年中季度（季度跨年对比用 `qoy`） |
| `week({field})` | `woy({field})` | 周 / 年中周（周跨年对比用 `woy`） |
| `year({field})` | `doy({field})` | 年 / 年中日 |
| `trunc_month({field})` | — | 截断到月，忽略日 |

跨期函数（`moy` / `dom` / `dow` / `doy` / `woy` / `qoy`）返回绝对序号，不随年/月边界重置，天然支持月跨年、天跨月、季度跨年等连续时间聚合。

**示例：**

```bash
# 月跨年：按月中月对比，跨越年边界
hbi element chart create --dashboard 11 --app 22 line \
  --dataset 33 \
  --dimension "moy({created_at})" \
  --dimension "year({created_at})" \
  --measure "SUM({amount})"

# 天跨月：按月中日对比，跨越月边界
hbi element chart create --dashboard 11 --app 22 line \
  --dataset 33 \
  --dimension "dom({created_at})" \
  --measure "SUM({amount})"
```

完整 HQL 函数参考：<https://api.hengshi.com/function_reference.html>

你也可以用 `hbi dataset expression-rewrite --app <ID> --dataset <ID> --expression "..."` 验证和重写表达式。

如果你要真正创建或更新控件，最常进入的是这些命令树：

* 图表：`element chart`
* 过滤器：`element filter`
* 容器：`element container`
* 文本：`element text`

创建应用参数过滤器时，`--app` 始终表示目标仪表盘所在的应用。如果参数属于另一个数据包，请同时传入 `--data-app <SOURCE_APP_ID>` 和 `--app-param <PARAM_ID>`。在 YAML/JSON spec 中，对应字段是 `dataAppId` 和 `appParamId`；只有参数属于目标应用时才可以省略 `--data-app` / `dataAppId`。

例如 `element chart` 下面常见的子命令包括：

* `create` `update`
* `list` `show`
* `query`
* `export-data` `export-file`
* `patch`
* `delete`

## 继续下钻建议

| 场景 | 先进入哪层命令树 |
| --- | --- |
| 应用生命周期、导入导出、移动与转移 | `app` |
| 应用参数、公共维度、规则、订阅、门户 | `app param` `app dimension` `app rule` `app subscribe` `app portal` |
| 文件夹树管理 | `folder` |
| 仪表盘 / 报表本体 | `dashboard` |
| 仪表盘 plan 与主题 | `dashboard plan` `dashboard theme` |
| 图表与页面控件 | `element` / `element chart` / `element filter` / `element container` / `element text` |

需要具体参数和示例时，再在终端查看对应层级的 `--help`。