CLI Overview
The wh CLI is the primary human interface for interacting with WarmHub. It covers all operations — creating graphs, writing data, querying state, and bootstrapping agent context.
Installation
Section titled “Installation”The CLI requires Node 22+.
npm install -g @warmhub/cliwh --versionAfter installing, wh is available everywhere. See the Quickstart for the full walkthrough.
Everyday Use
Section titled “Everyday Use”Use wh use to set the graph for a working directory, pass --graph org/name when a script should be explicit, and add --json when another tool needs structured output. Most commands accept a graph from the current .wh file or a flag.
Command Pattern
Section titled “Command Pattern”Most commands follow the wh <domain> <verb> pattern. A handful are flat single commands that take no verb — wh use, wh init, wh doctor, wh prime, wh onboard, wh update, wh notifications, and wh channel:
wh org create myorgwh graph list myorgwh thing list --shape Locationwh commit submit --ops '[...]'Domains: org, graph, shape, thing, assertion, commit, sub, auth, token, credential, component, collection, grant, view
The grant domain supports create, get, list, and revoke verbs. The view domain supports the evaluate verb. See the full command reference for every domain, verb, flag, and alias — including dedicated sections for grant and view. For a machine-readable summary of a domain, wh help <domain> --format json returns the complete spec for that domain.
Configuration
Section titled “Configuration”Default Graph (.wh file)
Section titled “Default Graph (.wh file)”The easiest way to set a default graph is wh use, which writes a .wh file in the current directory:
wh use myorg/worldwh thing list # targets myorg/worldThe CLI resolves the target graph using this priority:
--graphflag (per-command override)WARMHUB_GRAPHenvironment variable.whfile in the current directory
Environment Variables
Section titled “Environment Variables”The CLI reads WH_TOKEN (authentication), WARMHUB_GRAPH / WARMHUB_ORG (default graph 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
Section titled “Per-Command Override”wh thing list --graph myorg/other-graphOutput Formats
Section titled “Output Formats”Default (Human-Readable)
Section titled “Default (Human-Readable)”Colored, formatted text output:
wh thing listStructured output for scripts and agents:
wh thing list --jsonPaginated 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.
When you run wh thing list or wh thing query with --since-graph-seq and reach the last page (hasMore is false and nextCursor is null), the JSON output includes graphSeq at the top level:
{ "items": [ /* this page's rows */ ], "page": { "limit": 50, "count": 12, "hasMore": false, "nextCursor": null }, "graphSeq": 4821}graphSeq is your checkpoint: save it, and pass it as --since-graph-seq on the next run to read only what changed since. It appears only on the last page of the read, never on intermediate pages, and never on commands that did not pass --since-graph-seq.
As with ordinary pagination, items holds only the page you just fetched — the last page does not replay earlier ones. Accumulate rows yourself, or pass --all to have the CLI fetch and combine every page for you.
For the full incremental-read contract on list/HEAD reads — filtering, ordering, and error handling — see HEAD Queries. wh thing query refuses --since-graph-seq on four further forms, returning INCREMENTAL_READ_UNAVAILABLE: a glob --match filter, --resolve-collections, cross-graph --about targets, and --affirmed-about targets.
Failure output. When a command fails under --json, the CLI writes a structured error envelope to stderr:
{ "error": { "code": "CONFLICT", "errorCode": "thing_version_conflict", "backendCode": "thing_version_conflict", "message": "A newer version of this thing already exists.", "hint": "Re-fetch the thing and reapply your changes." }}error.code is a high-level bucket your script can branch on. Values are drawn from the ErrorCode enum: UNKNOWN, USER_INPUT, CONFIG, AUTH, BACKEND, CONFLICT, RATE_LIMITED, QUERY_TOO_EXPENSIVE, FIELD_INDEX_UNAVAILABLE, FIELD_NOT_INDEXABLE, and FIELD_TYPE_AMBIGUOUS. error.errorCode carries the service-specific error code when the API returns one; error.backendCode is also present for the same value and is retained for backwards compatibility. message is always present; hint, suggestions, and context are optional and included only when the CLI has additional detail to surface.
Partial output before failure. wh thing history --all does not behave as an all-or-nothing drain. If a later page refill is refused with QUERY_TOO_EXPENSIVE, the CLI writes every page it already fetched to stdout, prints a warning to stderr that history stopped early, and then rethrows the error. Scripts consuming wh thing history --all must handle the case where stdout contains valid, partial output even when the process exits with a non-zero status. Do not assume that a non-zero exit means stdout is empty or invalid.
Live (Reactive)
Section titled “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.
--all is not supported in live mode. The following paginated commands reject --all when --live is also present and exit with a usage error: wh shape history, wh assertion list, wh thing list, wh thing history, wh thing query, and wh thing about. Use --live without --all on these commands; pagination controls (--cursor, --limit) remain available.
Ergonomics
Section titled “Ergonomics”Exact flag names. Long flags and declared aliases must match exactly. Use the full --description name:
wh graph create myorg/my-graph --description "My graph"Unknown flags may receive a “did you mean?” suggestion, but are never expanded or executed. Typos in domains and verbs receive the same kind of recovery guidance.
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 never silently resolves: the error always lists the available verbs for that domain, and adds a “did you mean?” suggestion when a close match is found.
Getting Help
Section titled “Getting Help”wh help # full help overviewwh <domain> # list verbs for a domainwh <domain> <verb> --help # verb details with flags and exampleswh help --format json # full CLI spec as JSON (all domains)wh help <domain> --format json # spec for a single domain as JSONwh doctor # verify environment and connectivitywh help --format json returns the complete CLI spec as JSON: all domains, a compact verb matrix, and the authoritative global flags and controls tables. The payload includes a schemaVersion field — check it before parsing, as a version advance may indicate structural changes. Targeted JSON help (wh help <domain> --format json or wh <domain> <verb> --help --format json) returns only the spec for that domain or verb, without the aggregate tables.
Individual domain specs can carry a globalFlagOverrides map that modifies how inherited flags behave for that domain. For example, the channel domain carries { graph: { multiple: true } }, which signals that the --graph flag accepts multiple values for that domain. When consuming the JSON spec programmatically, apply any globalFlagOverrides entries on top of the top-level global flag definitions to get the effective flag contract for a given domain — entries in globalFlagOverrides take precedence over the inherited global flag definition for that domain only.
Next steps
Section titled “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 |