> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI 参考

> HeavenBase 命令行接口参考。

`hb` 命令是 Python 所用相同 HeavenBase API 之上的浅层命令行层。它初始化全局配置、浏览已注册工作区、编辑配置，并调用已配置的 LLM 预设 (Preset)。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb --help
hb -v
hb setup
```

## Setup 与路径

`hb setup` 初始化全局 HeavenBase 配置存储并注册默认工作区。它不会创建本地 `.heavenbase/` 文件夹。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb setup
hb setup --reset
```

`hb pj` 解析 HeavenBase 路径别名，如包状态的 `%/` 与资源的 `&/`。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb pj %/config.db
hb pj '&/configs/default.yaml'
```

## 工作区 (Workspace)

`hb ws` 管理全局工作区注册表。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb ws list
hb ws get
hb ws set default --active
hb ws activate default
hb ws deactivate
hb ws open default
hb ws health default
hb ws presets list
hb ws presets show debug
hb ws unset scratch
```

帮助在命令表中显示命令别名，如 `list|ls`、`activate|act|use`、`deactivate|deact`、`set|add` 与 `unset|remove|rm|del|delete`。

工作区预设 (Preset) 镜像 Python API `hb.HeavenBase("name", preset="debug")`。无 Docker demo 用 `debug`，本地服务栈用 `local-lts`，托管部署用 `web-lts`。

## 配置

`hb config` 通过 `ConfigManager` 编辑 HeavenBase 配置。短别名是 `hb cfg`。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb config get heavenbase.llm.default_preset
hb config list heavenbase.llm.presets
hb config set heavenbase.llm.default_preset mock
hb config add heavenbase.llm.presets.custom.tags cli
hb config unset heavenbase.llm.default_preset
hb config copy heavenbase.llm --source default
hb config history --limit 5
hb config scope
hb config diff
hb config edit --scope heavenbase
hb config reset --scope heavenbase.scratch
hb config compact --scope heavenbase
```

用 `--scope` 定位配置层，`--version` 读取保留历史，`--json` 输出 JSON 或解析 JSON 值。

别名：`hb cfg ls` / `show`，`hb cfg rm` / `remove` / `del` / `delete`，`hb cfg cp`，`hb cfg hist`。

## LLM

`hb llm` 调用 LLM 配置系统。预设 (Preset)、提供商 (Provider)、模型与入口 (Gateway) 与 Python 中 `hb.LLM(...)` 相同方式解析。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb llm chat "Summarize HeavenBase in one sentence."
hb llm chat --preset mock --provider mock --gateway mock --no-stream --verbose "hello"
hb llm chat "Summarize HeavenBase in one sentence." --copy
hb llm chat --mcp quickstart.math-tools:-1 "What's 42 * 73?"
hb llm chat --mcp quickstart.math-tools:-1 --max-steps 20 "What's 42 * 73?"
hb llm embed "semantic text" --preview
hb llm embed "semantic text" --json --copy
hb llm session --preset chat
hb llm session --mcp quickstart.math-tools:-1
hb llm session --mcp http://127.0.0.1:7001/mcp
hb llm imagen "a simple product diagram" --output ./image.png
hb llm status --preset mock
hb llm verbose --preset chat-pro
hb llm list presets
hb llm ls providers
```

常用 LLM 选项为 `--preset` / `-p`、`--model` / `-m`、`--provider` / `-b`、`--gateway` / `-g`、`--cache` / `--no-cache`，调用命令上还有 `--verbose` / `-v`。`chat`、`embed` 与 `session` 也接受重复的 `--input` 文件。`chat` 与 `embed` 支持 `--copy` / `-cp` 显式复制到剪贴板。`embed --preview` 显示前 4 与后 2 个值（四舍五入到 6 位小数）；无它时 `embed` 打印完整原始数组，`embed --json` 打印完整响应对象。`chat` 与 `session` 接受重复的 `--mcp` 值，可为 MCP URL 或已注册工具集 (Toolkit) 引用如 `quickstart.math-tools:-1`。`chat --max-steps` 限制 MCP 工具循环，默认 20 个 assistant 步。

规范工具集 (Toolkit) 引用形式为 `namespace.toolkit:version`。负版本从新到旧选择：`-1` 为 latest，`-2` 为次 latest，依此类推。

`hb llm verbose` 显示解析后的非密钥 LLM 参数。`resolve` 仍为别名，帮助中显示为 `verbose|resolve`。`hb llm list|ls` 列出 `presets`、`providers`、`models`、`gateways` 或 `all`。

发出 `think` 内容的模型的推理 chunk 在正常答案文本前以灰色打印在 `<think>` 与 `</think>` 内。MCP 工具循环将每次 assistant 迭代打印为 `STEPS: 001 / 020`。

交互式 `hb llm session` 支持 `/help`、`/save`、`/load`、`/clear`、`/regen`、`/back`、`/tools`、`/mcp` 与 `/exit`，短形式如 `/s`、`/l`、`/r`、`/b`。

## 后端 (Backend)

默认 CLI 后端 (Backend) 为 Typer。HeavenBase 也将相同命令注册表编译为 Click 与 argparse，供嵌入或宿主应用使用。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.cli import create_cli

typer_app = create_cli("typer")
click_app = create_cli("click")
argparse_parser = create_cli("argparse")
```

<br />