跳转到主要内容
hb 命令是 Python 所用相同 HeavenBase API 之上的浅层命令行层。它初始化全局配置、浏览已注册工作区、编辑配置，并调用已配置的 LLM 预设 (Preset)。 
hb --help
hb -v
hb setup

​
Setup 与路径

hb setup 初始化全局 HeavenBase 配置存储并注册默认工作区。它不会创建本地 .heavenbase/ 文件夹。 
hb setup
hb setup --reset
hb pj 解析 HeavenBase 路径别名，如包状态的 %/ 与资源的 &/。 
hb pj %/config.db
hb pj '&/configs/default.yaml'

​
工作区 (Workspace)

hb ws 管理全局工作区注册表。 
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。 
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(...) 相同方式解析。 
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，供嵌入或宿主应用使用。 
from heavenbase.cli import create_cli

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