CLI Overview

The wh CLI is the primary human interface for interacting with WarmHub. It covers all operations — creating repos, committing data, querying state, and bootstrapping agent context.

Installation

The CLI is currently published to GitHub:

echo "@warmhub:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> ~/.npmrc

npm install -g @warmhub/cli@next
wh --version

After installing, wh is available everywhere.

Architecture

The CLI has two layers:

• Command engine — command handlers, parsing, formatting, and typed errors.
• Executable entry point — stdio wiring, signal handling, and process exit behavior.

Command Pattern

All commands follow the wh <domain> <verb> pattern:

wh org create myorg
wh repo list myorg
wh thing head --shape Location
wh commit create --ops '[...]'

Domains: org, repo, shape, thing, assertion, commit, workspace, use, init, doctor, sub, auth, token, credential, component, prime, notifications

See the full command reference for every domain, verb, flag, and alias.

Configuration

Default Repo (.wh file)

The easiest way to set a default repo is wh use, which writes a .wh file in the current directory:

wh use myorg/world
wh thing head              # targets myorg/world

The CLI resolves the target repo using this priority:

1. --repo flag (per-command override)
2. WARMHUB_REPO environment variable
3. .wh file in the current directory

Environment Variables

Variable	Description	Example
WARMHUB_REPO	Default org/repo for all commands	myorg/myrepo
WARMHUB_ORG	Default org	myorg
WARMHUB_API_URL	Backend URL	https://api.warmhub.ai

Per-Command Override

wh thing head --repo myorg/other-repo

Output Formats

Default (Human-Readable)

Colored, formatted text output:

wh thing head

JSON

Structured output for scripts and agents:

wh thing head --json

Live (Reactive)

Real-time WebSocket updates — auto-refreshes as data changes:

wh thing head --live

Ergonomics

Prefix expansion. Flag prefixes expand to the full name if unambiguous:

wh repo create myorg/repo --desc "My repo"
# expands to --description

Fuzzy matching. Typos in domains, verbs, and flags get “did you mean?” suggestions.

Verb aliases. Many verbs have short aliases:

wh commit log     # alias for: wh commit list
wh thing show     # alias for: wh thing view
wh repo init      # alias for: wh repo create

Getting Help

wh help                        # full help overview
wh <domain>                    # list verbs for a domain
wh <domain> <verb> --help      # verb details with flags and examples
wh help --format json          # full CLI spec as JSON
wh doctor                      # verify environment and connectivity