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

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

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

Domains: org, repo, shape, graph, thing, assertion, commit, use, init, doctor, sub, auth, token, credential, component, prime, 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

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
WH_PROFILE	Named auth profile (same as --profile / -P)	staging
WARMHUB_CLI_HTTP_TIMEOUT_MS	HTTP client headers/body timeout in milliseconds for long-running requests (Node only; no-op under Bun). Default 5700000 (95 minutes). Set to 0 for unlimited.	3600000
WARMHUB_CLI_NO_UPDATE_CHECK	Disable the background CLI update check. Set to 1, true, or TRUE to enable the opt-out. Equivalent to passing --no-update-check.	1

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

Live (Reactive)

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

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