> ## 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 reference

> HeavenBase command-line interface reference.

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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

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

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

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

## Workspaces

`hb ws` manages the global workspace registry.

```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
```

Help displays command aliases in the command table, such as `list|ls`, `activate|act|use`, `deactivate|deact`, `set|add`, and `unset|remove|rm|del|delete`.

Workspace presets mirror the Python API `hb.HeavenBase("name", preset="debug")`. Use `debug` for no-Docker demos, `local-lts` for the local service stack, and `web-lts` for managed deployments.

## Config

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

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.

```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
```

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.

```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 />