CLI Reference - HeavenBase

The CLI is a front door, not a second building with suspiciously similar furniture.

1. Motivation

hb exposes common setup, workspace, configuration, LLM, Toolkit, Prompt, and dashboard workflows without inventing separate runtime authorities.

hb --help
hb --version
hb setup

Use --help on any command for the exact options installed in your environment.

2. Setup and Paths

hb setup initializes the default Context Registry and ensures the default workspace definition. It does not create a project-local .heavenbase/ directory.

hb setup
hb setup --reset
hb pj %/system.db
hb pj '&/configs/default.yaml'

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

3. Workspaces

hb ws list
hb ws create demo --preset debug
hb ws get demo
hb ws open demo
hb ws health demo
hb ws activate demo
hb ws deactivate
hb ws manifest demo > workspace.yaml
hb ws import workspace.yaml
hb ws unset demo

Creation and import register a durable definition without activating it. Selection is always the separate hb ws activate <id> action. hb ws presets list and hb ws presets show debug inspect packaged presets. Use debug for local no-service examples, local-lts for a local service stack, and web-lts for managed deployments.

4. Configuration

hb config and its hb cfg alias edit values through ConfigManager.

hb cfg get heavenbase.llm.default_preset
hb cfg list heavenbase.llm.presets
hb cfg set heavenbase.llm.default_preset mock
hb cfg unset heavenbase.llm.default_preset
hb cfg history --limit 5
hb cfg scope
hb cfg diff
hb cfg edit --scope heavenbase
hb cfg reset --scope heavenbase.scratch
hb cfg compact --scope heavenbase

Use --scope to target a layer, --version for retained history reads, and --json for JSON output or value parsing.

5. Dashboard

hb dashboard
hb dashboard --no-open
hb dashboard --app
hb dashboard --browser
hb dashboard --install-app
hb dashboard --host 127.0.0.1 --port 42777

The default host prefers the macOS system WebView and falls back to the system browser. --app explicitly requests Chromium --app; --install-app creates ~/Applications/HeavenBase.app for Finder and Dock launch. The dashboard refuses non-loopback binds unless --allow-network is explicit. That option exposes an unauthenticated configuration API, so use it only on a network you trust.

6. LLM

hb llm chat --preset mock --no-stream "hello"
hb llm embed "semantic text" --preview
hb llm session --preset chat
hb llm imagen "a simple product diagram" --output ./image.png
hb llm status --preset mock
hb llm verbose --preset chat-pro
hb llm list all

Call commands share --preset, --model, --provider, --gateway, cache, and verbose controls. Chat and sessions accept repeated --mcp values for URLs or Toolkit refs such as quickstart.math-tools:-1. The canonical Toolkit ref is namespace.toolkit:version. Negative versions count from newest to oldest, so -1 selects the latest.

7. MCP Toolkits

hb mcp setup --workspace demo
hb mcp list --workspace demo
hb mcp show quickstart.math-tools:-1 --workspace demo
hb mcp tools quickstart.math-tools:-1 --workspace demo
hb mcp call quickstart.math-tools:-1 add --args '{"left": 2, "right": 3}' --workspace demo
hb mcp mcp-json quickstart.math-tools:-1 --workspace demo
hb mcp serve quickstart.math-tools:-1 --workspace demo

Toolkit rows and referenced Capsule rows belong to the selected application workspace. Use hb mcp --help to inspect stdio, HTTP, removal, and Capsule-listing commands.

8. Prompts and Translations

hb prompt list
hb prompt show welcome
hb prompt create welcome --template "Hello, {name}!"
hb prompt render welcome --args '{"name": "Ada"}'
hb prompt tr-list

Prompt commands manage template rows and translation dictionaries through the packaged Prompt extension. Use hb prompt --help for translation bind, unbind, set, and remove operations.

9. Alternate CLI Compilers

Typer is the packaged CLI frontend. Host applications may compile the same command Registry to Click or argparse:

from heavenbase.cli import create_cli

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

The compiler changes presentation, not command ownership.

Summary

hb is a shallow adapter over public HeavenBase domains.
Workspace creation, import, and activation remain separate.
LLM, Toolkit, and Prompt commands reuse their Python authorities.
Command help is the exact reference for the installed build.

Further Exploration

Related resources:

Workspace — Durable identity and activation
Dashboard — Local visual workbench
LLM Overview — Presets and route resolution
MCP Toolkit Reference — Toolkit persistence and serving

​1. Motivation

​2. Setup and Paths

​3. Workspaces

​4. Configuration

​5. Dashboard

​6. LLM

​7. MCP Toolkits

​8. Prompts and Translations

​9. Alternate CLI Compilers

​Summary

​Further Exploration

1. Motivation

2. Setup and Paths

3. Workspaces

4. Configuration

5. Dashboard

6. LLM

7. MCP Toolkits

8. Prompts and Translations

9. Alternate CLI Compilers

Summary

Further Exploration