CLI Overview

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

Installation

The CLI requires Node 22+.

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

After installing, wh is available everywhere. See the Quickstart for the full walkthrough.

Everyday Use

Use wh use to set the repo for a working directory, pass --repo org/name when a script should be explicit, and add --json when another tool needs structured output. Most commands accept a repo from the current .wh file, the active profile, or a flag.

Command Pattern

Most commands follow the wh <domain> <verb> pattern (a few are flat single commands that take no verb — wh prime, wh onboard, wh update, wh init):

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

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

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

The CLI reads WH_TOKEN (authentication), WARMHUB_REPO / WARMHUB_ORG (default repo target), WARMHUB_API_URL (backend URL), and WH_PROFILE (auth profile), plus a few behavior toggles. See Environment Variables for the full list, accepted values, and precedence rules.

Per-Command Override

wh thing list --repo myorg/other-repo

Output Formats

Default (Human-Readable)

Colored, formatted text output:

wh thing list

JSON

Structured output for scripts and agents:

wh thing list --json

Paginated list commands wrap their rows in a page envelope:

{
  "items": [ /* rows */ ],
  "page": { "limit": 50, "count": 50, "hasMore": true, "nextCursor": "<cursor>" }
}

count is the number of items in this page. When hasMore is true, pass nextCursor back as --cursor to fetch the next page, or use --all to auto-fetch every page.

Live (Reactive)

Live updates by polling — re-runs the query periodically and auto-refreshes as data changes:

wh thing list --live

--max-updates <n> auto-exits after N updates, and --live-timeout-ms <ms> auto-exits when no update arrives within that window — both useful for scripted, bounded live reads.

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. A handful of verbs accept an alias — for example, wh auth whoami resolves to wh auth status. There is no general show/get aliasing; use the canonical verb shown in the command reference. A mistyped verb returns a “did you mean?” suggestion rather than silently resolving.

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          # structured CLI spec as JSON
wh doctor                      # verify environment and connectivity

Next steps

Need	Page
Every domain, verb, flag, and alias	Command Reference
Build and submit a multi-operation write	commit submit deep dive
Install the CLI as part of first-run setup	Quickstart