Quickstart: CLI

This guide walks you through installing the wh CLI, creating a repository, and writing your first data — all from the terminal.

Prerequisites: You’ll need a WarmHub account. The CLI will prompt you to sign in on first use — see Getting Access for details.

Install the CLI

The CLI is currently published to GitHub (requires Node 22+):

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, the wh command is available everywhere.

1. Log In

Writing data requires authentication. Log in with a single command:

wh auth login

This opens your browser — sign in with email, Google, or GitHub. After you confirm, the CLI saves your credentials and auto-refreshes them in the background.

Verify it worked:

wh auth status

For CI/CD or headless environments, see Getting Access for non-interactive options including personal access tokens.

2. Create an Organization

Organizations are the top-level namespace. Create one to hold your repositories:

wh org create myorg

3. Create a Repository

A repo is where all your data lives — shapes, things, assertions, and commits:

wh repo create myorg/world -d "My first repo"

4. Set Your Target Repository

Most wh commands operate on a specific org/repo. Set it once with wh use so you don’t need --repo on every command:

wh use myorg/world

This writes a .wh file in the current directory. All subsequent commands in this directory will target myorg/world automatically.

You can also specify a repo per-command with the --repo flag, or set the WARMHUB_REPO environment variable. The CLI resolves the target repo using this priority: --repo flag > WARMHUB_REPO env > .wh file.

5. Create a Shape

Shapes define the structure of your data. Create a Location shape with three fields:

wh shape create Location --fields '{"x":"number","y":"number","label":"string"}'

6. Add a Thing via Commit

All data writes go through commits. Add a thing named cave under the Location shape:

wh commit create --add cave --shape Location --data '{"x":3,"y":7,"label":"Dark Cave"}' -m "Add first location"

This creates an atomic commit containing a single add operation. The thing’s wref (WarmHub reference) is Location/cave.

7. View HEAD

See all active things in the repository:

wh thing head

This returns the current snapshot of active repo data at the latest version.

WarmHub hides system-managed component infrastructure records by default.

Component-seeded data things under your own shapes are still included. Add --exclude-components to hide all component-owned data things too.

8. View a Specific Thing

Retrieve a single thing by its wref:

wh thing view Location/cave

9. Add an Assertion

Assertions are claims about another thing. Create a Belief shape, then assert something about the cave:

wh shape create Belief --fields '{"safe":"boolean","confidence":"number"}'

wh assertion create --shape Belief --about Location/cave --data '{"safe":true,"confidence":0.8}'

The assertion is linked to Location/cave via its about reference. This relationship is immutable — once set, it cannot be changed.

10. Query Assertions

List all assertions about a specific thing:

wh assertion list Location/cave

11. View the Commit Log

See recent commits to understand the history of changes:

wh commit list --last 5

Every mutation in WarmHub is recorded as a commit with an author, message, timestamp, and stable commit ID.

Tips

JSON output. Add --json to any command for machine-readable output:

wh thing head --json

Reactive mode. Use --live to watch for real-time changes:

wh thing head --live

Agent context. The wh prime command outputs a complete context dump — shapes, sample wrefs, commit history, and write examples — in a single call. This is designed for AI agents that need to bootstrap their understanding of a repo:

wh prime
wh prime --json    # structured version

Next Steps

• Core Concepts — if you haven’t already, review the mental model behind orgs, repos, shapes, things, assertions, and commits
• MCP Quickstart — connect an AI agent to WarmHub via the Model Context Protocol
• Data Modeling — learn about wrefs, shapes, things, and assertions in detail
• CLI Reference — full command reference for all wh commands