CLI reference - HeavenBase

The hb command is the shallow command-line layer over the same HeavenBase APIs used from Python. It initializes global config, browses registered workspaces, edits config, and calls configured LLM presets.

hb --help
hb -v
hb setup

Setup and paths

hb setup initializes the global HeavenBase config store and registers the default workspace. It does not create a local .heavenbase/ folder.

hb setup
hb setup --reset

hb pj resolves HeavenBase path aliases such as %/ for package state and &/ for resources.

hb pj %/config.db
hb pj '&/configs/default.yaml'

Workspaces

hb ws manages the global workspace registry.

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

Config

hb config edits HeavenBase config through ConfigManager. The short alias is 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

Use --scope to target a config layer, --version for retained history reads, and --json for JSON output or JSON value parsing. Aliases: hb cfg ls / show, hb cfg rm / remove / del / delete, hb cfg cp, and hb cfg hist.

LLM

hb llm calls the LLM config system. Presets, providers, models, and gateways resolve the same way as hb.LLM(...) in Python.

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

Common LLM options are --preset / -p, --model / -m, --provider / -b, --gateway / -g, --cache / --no-cache, and --verbose / -v on call commands. chat, embed, and session also accept repeated --input files. chat and embed support --copy / -cp for explicit clipboard copying. embed --preview shows the first 4 and last 2 values rounded to 6 decimals; without it, embed prints the full raw array and embed --json prints the full response object. chat and session accept repeated --mcp values for MCP URLs or registered Toolkit refs such as quickstart.math-tools:-1. chat --max-steps caps MCP tool loops and defaults to 20 assistant steps. The canonical Toolkit ref form is namespace.toolkit:version. Negative versions select from newest to oldest: -1 is latest, -2 is second-most latest, etc. hb llm verbose shows the resolved non-secret LLM args. resolve remains an alias and appears in help as verbose|resolve. hb llm list|ls lists presets, providers, models, gateways, or all. Reasoning chunks from models that emit think content are printed in grey inside <think> and </think> before normal answer text. MCP tool loops print each assistant iteration as STEPS: 001 / 020. Interactive hb llm session supports /help, /save, /load, /clear, /regen, /back, /tools, /mcp, and /exit with short forms such as /s, /l, /r, and /b.

Backends

The default CLI backend is Typer. HeavenBase also compiles the same command registry to Click and argparse for embedding or host applications.

from heavenbase.cli import create_cli

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

​Setup and paths

​Workspaces

​Config

​LLM

​Backends

Setup and paths

Workspaces

Config

LLM

Backends