---
url: /v6.2/cli-reference-core.md
---
# 核心与运行时命令

这一页覆盖跨领域都会用到的核心命令，适合作为 CLI 的基础导航与索引。

## `instance`

**用途**：管理本地保存的 host 别名与默认 host。

**常见子命令**：

* `add` `use`
* `list` `current` `show`
* `remove`

如果你需要在本机保存一个默认 host，或查看当前本机默认 host，优先进入这条命令树。对脚本、Agent、多环境切换和 cron，更推荐显式使用 `HBI_HOST=... hbi xxx`。

## `auth`

**用途**：登录、切换认证方式、查看当前凭据状态。

**常见子命令**：

* `login` `logout` `device-login`
* `status` `refresh`
* `use`
* `methods` `active` `activate`
* `config` `verify`
* `generate`

适合在首次接入某个 host、切换认证方式、排查登录态或访问令牌状态时使用。默认推荐路径是：先显式设置 `HBI_HOST`，再执行 `auth login --device-login`（或等价的 `auth device-login`）。`HBI_HOST` / `auth use --host` 可以直接写裸 host，也支持 `platform.hengshi.org/bi` 这类带子路径写法；省略 scheme 时 CLI 会先探测 `https://`，失败后再试 `http://`。`auth use --host ...` / `instance use` 都只应作为本地交互式默认值便捷机制，不应成为脚本、Agent 或多环境执行的主路径。

## `search`

**用途**：跨目录搜索应用、仪表盘和数据集。

这个命令没有二级子命令，重点在参数组合：

* `--area`
* `--root` / `--folder`
* `--recursive`
* `--type`
* `--query`

当你不知道资源位于哪个目录、哪个应用时，优先从 `search` 这一层命令树开始。

**最小可用示例**：

```bash
hbi search --area personal-area --root --recursive --query "销售" --output json
```

**典型输出**：

```json
[
  {
    "type": "dataset",
    "id": 3,
    "title": "制造销售模拟数据",
    "appId": 131476
  },
  {
    "type": "dataset",
    "id": 5,
    "title": "coffee_16年销售数据",
    "appId": 137591
  }
]
```

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

* 找到资源后，用 `hbi app show <appId>` 查看应用详情
* 或用 `hbi dataset show <appId> <datasetId>` 查看数据集详情
* 需要更精确的类型过滤时，配合 `--type dataset` 或 `--type dashboard`

## `config`

**用途**：查看或编辑 CLI 本地配置。

这个命令没有二级子命令，最常见的是：

* `hbi config`
* `hbi config --edit`

适合检查当前 CLI 读到的本地配置，或进入交互式编辑。

**最小可用示例**：

```bash
hbi config
```

**典型输出**：

```json
{
  "api_url": "https://<your-hengshi-sense-instance>",
  "authenticated": false,
  "locale": "en-US",
  "output_format": "table"
}
```

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

* 修改配置：`hbi config --edit`
* 查看当前实例设置：`hbi instance current`

## `preferences`

**用途**：读取或更新系统级配置。

**常见子命令**：

* 通用查看：`get` `about` `instances`
* 日志级别：`log-levels` `update-log-levels`
* 配置族：`environment` `everest` `security` `smtp` `home`
* 页面与样式：`app-mart-tag` `list-sort` `skin` `css` `js`
* 其他设置：`gis` `open-dwinfo`
* 按 key 读写：`get-config` `set-config`

如果你要做系统设置巡检、环境核对或配置预演，优先看这组命令。

**最小可用示例**：

```bash
hbi preferences about --output json
```

**典型输出**：

```json
{
  "smtpEnable": true,
  "startTime": 1780386402378,
  "version": "6.x.y"
}
```

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

* 查看特定配置族：`hbi preferences environment --output json`
* 查看日志级别：`hbi preferences log-levels --output json`
* 按 key 查询单个配置：`hbi preferences get-config <key> --output json`

## `scheduler`

**用途**：管理已经存在的计划任务。

**常见子命令**：

* `list` `show`
* `update` `delete`
* `switch`
* `context`
* `logs`

适合统一查看 notebook / pipeline / dataset / data-alert / app-refresh 等调度任务的状态与执行上下文。

**最小可用示例**：

```bash
hbi scheduler list --entity-group dataset --output json
```

**支持的实体类型**：

* `pipeline` — Pipeline（数据集成）
* `notebook` — Notebook（数据科学）
* `dataset` — Dataset（数据刷新）
* `data-alert` — 数据预警
* `app-email` — 应用邮件
* `app-refresh` — 应用刷新
* `ai-create-example` — 数据集智能学习
* `ai-rag-embedding` — 数据集向量化

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

* 查看特定任务详情：`hbi scheduler show <schedule-id> --output json`
* 启用/禁用任务：`hbi scheduler switch <schedule-id> --enable true`
* 查看执行上下文：`hbi scheduler context <schedule-id> --output json`
* 查看执行日志：`hbi scheduler logs <schedule-id>`

## `logs`

**用途**：下载系统日志。

**常见子命令**：

* `download --log-type BACKEND --begin <时间> [--end <时间>] [--output-file <path>]`

`--log-type` 支持 `BACKEND` 和 `APM`。`BACKEND` 对应系统调试里的服务器端调试日志；需要下载 APM 指标、trace 等日志时使用 `APM`。

`--begin` 和 `--end` 支持 RFC3339 时间（例如 `2026-06-24T14:54:00+08:00`），也支持 `yyyy-MM-dd HH:mm:ss` 形式的时间。未指定 `--end` 时，后端按当前时间处理。

这组命令通常用于排障或让运维同事回收日志包。

## 继续下钻建议

| 场景 | 先进入哪层命令树 |
| --- | --- |
| 登录、切换认证方式、核对登录态或访问令牌状态 | `auth` |
| 跨目录找应用、仪表盘、数据集 | `search` |
| 查看或编辑 CLI 本地配置 | `config` |
| 巡检系统级配置 | `preferences` |
| 管理已存在的计划任务 | `scheduler` |
| 下载系统日志 | `logs` |

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