CLI reference | Wheems docs

Every wheems command, from its own --help output in version 0.0.3. Run wheems <command> --help for the same on your machine.

Global options

Option	Meaning
`-v`, `--version`	Print the version number.
`-h`, `--help`	Show help for any command.
`--home <dir>`	The install folder. Default: `$WHEEMS_HOME`, then `~/wheems`. Accepted by most commands; not by `slack manifest`, `service restart` or `service uninstall`.

Commands exit with 0 on success and 1 on failure, with the reason on standard error, such as Error: Workspace acme already exists at /Users/you/wheems/workspaces/acme

Commands for you

Command	What it does
`wheems`	The welcome screen: the cloud, then how the install is doing (workspaces and agents, the service, search, review). The cloud winks once, and is left out when the output isn’t a terminal or the terminal is narrower than 53 columns.
`wheems setup`	The setup menu: engines, Slack, workspaces, knowledge, the service, doctor
`wheems init`	Create a workspace with its chief of staff (and the install, if there is none)
`wheems doctor`	Check this machine, Herdr core and the install
`wheems validate`	Validate config files or install folders
`wheems review`	Go through skill proposals and changes to `about-you.md`
`wheems kb search`	Search a workspace’s knowledge base
`wheems kb reindex`	Rebuild search indexes
`wheems skill list`	List the library and waiting proposals
`wheems skill show`	Print a skill’s `SKILL.md`
`wheems service …`	Look after the background service
`wheems slack manifest`	Print the Slack app manifest

Commands for agents

These work only inside a conversation Wheems started, where WHEEMS_CONVERSATION is set. Anywhere else they fail with, for example, wheems reply works inside a conversation started by Wheems (WHEEMS_CONVERSATION is not set).

Command	What it does
`wheems reply`	Post a progress note to the conversation’s thread
`wheems note`	Save a note to the workspace’s knowledge inbox
`wheems skill propose`	Propose a skill for you to review
`wheems kb search`	Search the agent’s own workspace

wheems setup

Set up Wheems: engines, channels, workspaces, knowledge and the service, from a menu.

wheems setup [--home <dir>]

Option	Meaning
`--home <dir>`	The install folder (default: `$WHEEMS_HOME` or `~/wheems`).

Creates the install folder, as a git folder, if there is none. Then offers Engines, Channels, Workspaces, Knowledge, Service, Check everything and Done. Arrow keys and Enter pick; Esc or Ctrl+C backs out of a step without saving it. Run it again any time. See the Quick start.

wheems init

Create a workspace with its chief of staff (and the install, if there is none).

wheems init [options] <workspace>

Argument or option	Meaning
`<workspace>`	The workspace id, such as `personal`. Lowercase letters, digits and dashes.
`--name <name>`	Its display name. Default: from the id (`acme` → `Acme`).
`--channel <channel>`	Chat in this Slack channel instead of the bot’s direct messages.
`--engine <engine>`	What the chief of staff runs in: `claude-code`, `codex` or `opencode`. Default: `claude-code`.
`--model <model>`	The engine’s model. Default: the engine’s usual one.
`--home <dir>`	The install folder.

wheems init personal
wheems init acme --channel acme-chat --engine codex

Created /Users/you/wheems/workspaces/acme, with its chief of staff on Codex

Codex asks once whether to trust a new folder, and nobody can answer it from Slack.
Answer it now: run the two lines below, say yes, then quit it.

  cd /Users/you/wheems/workspaces/acme
  codex --no-daemon

Then invite the bot to #acme-chat and restart the service: wheems service restart

On a machine with no install yet, it first creates the install folder, as wheems setup does, and prints Created the install at /Users/you/wheems (a git folder). Connecting Slack still needs wheems setup.

It writes workspace.yaml, skills.yaml, agents/chief-of-staff.md (with permissions: auto) and the knowledge/ folders, and adds the engine’s account to install.yaml if it’s missing.

Error	Why
`Workspace acme already exists at …`	Pick another id.
`Workspace personal already chats in the bot's direct messages. Give this one a channel with --channel <name>.`	Only one workspace can have direct messages.
`"Acme" is not a workspace name: use lowercase letters, digits and dashes`	Use an id such as `acme`.
`No engine "…". Choose one of: …`	`--engine` must be one of the listed engines.

wheems doctor

Check that this machine, Herdr core and the install are healthy.

wheems doctor [--quick] [--json] [--home <dir>]

Option	Meaning
`--quick`	Skip starting a test session in Herdr core.
`--json`	Print the report as JSON.
`--home <dir>`	The install folder.

Checks, in sections: System, Herdr core, Config, Agents, Channels, Knowledge, Review and Service. Each check is ✓ pass, ! warning, ✗ failure or - skipped, with a hint on the next line. It ends with Doctor passed., or Doctor failed: 1 check failed. and exit code 1. What each check means is in Troubleshooting.

wheems validate

Validate config files, or a whole install folder with the links between its files.

wheems validate [paths...] [--home <dir>]

Argument or option	Meaning
`[paths...]`	Files or install folders. Default: the install folder.
`--home <dir>`	The install folder.

wheems validate
wheems validate workspaces/acme/workspace.yaml
wheems validate ~/Projects/wheems/examples/install

workspaces/acme/workspace.yaml:3: error Unrecognized key: "chanels"
1 error

A file it doesn’t recognise by name fails with Not a config file Wheems knows: expected install.yaml, workspace.yaml, skills.yaml, agents/*.md or workflows/*.yaml. See the Configuration reference.

wheems review

Review what waits for you: skills agents proposed, and changes to about-you.md.

wheems review [--list] [--home <dir>]

Option	Meaning
`--list`	Only list what is waiting.
`--home <dir>`	The install folder.

For each item: Approve, Edit, then approve (in $VISUAL or $EDITOR), Turn it down (deletes it), Leave it for later, or Stop reviewing. Outside a terminal it only lists. See Skills.

Nothing waits for review.

wheems kb search

Search the knowledge base by keyword and by meaning.

wheems kb search [options] <query...>

Argument or option	Meaning
`<query...>`	What to look for, in plain words. Quotes are optional.
`--workspace <id>`	The workspace. Default: `$WHEEMS_WORKSPACE`, or the only one.
`--limit <n>`	How many results. Default: `5`.
`--json`	Print the results as JSON.
`--home <dir>`	The install folder.

wheems kb search what did we decide about the boat name --workspace personal

Boat name
  /Users/you/wheems/workspaces/personal/knowledge/pages/boat-name.md (page, updated 2026-11-11)
  The boat is called Halcyon, chosen over Kestrel because it's calmer.

With --json, each result has path, file, kind (page or note; inbox notes count as notes), title, snippet, score, matched (keyword, meaning), origin (person or automated) and updated, and the report says its mode.

Error	Why
`Say which workspace with --workspace: acme, personal`	There’s more than one workspace.
`The acme workspace has no search index yet. …`	Start the service, or run `wheems kb reindex`.

wheems kb reindex

Rebuild the search index from the files, and swap it in when it’s done.

wheems kb reindex [--workspace <id>] [--home <dir>]

Option	Meaning
`--workspace <id>`	Only this workspace. Default: every workspace.
`--home <dir>`	The install folder.

acme: indexed 12 files with nomic-embed-text
personal: indexed 3 files, keyword search only

When the service is running, it does the rebuild. See Knowledge base and search.

wheems skill list

List the skills in the library, and proposals waiting for review.

wheems skill list [--json] [--home <dir>]

Option	Meaning
`--json`	Print them as JSON.
`--home <dir>`	The install folder.

wheems skill show

Print a skill’s SKILL.md: the latest version, or the one asked for.

wheems skill show <name> [version] [--home <dir>]

Argument or option	Meaning
`<name>`	The skill.
`[version]`	This version instead of the latest.
`--home <dir>`	The install folder.

wheems skill show weekly-report 1

wheems skill propose

Propose a new skill, or a change to one, for the person to review. Agents run this.

wheems skill propose <name> [input] [--home <dir>]

Argument or option	Meaning
`<name>`	The skill, in lowercase words joined by dashes.
`[input]`	`-`: read the `SKILL.md` from standard input, which is also the default.
`--home <dir>`	The install folder.

The proposal needs front matter with name and description, instructions after it, at most 64 KB, and nothing that looks like a credential. See Skills.

wheems reply

Reply to the person in the current conversation. Agents run this, for progress notes during long work.

wheems reply [text...] [--home <dir>]

Argument or option	Meaning
`[text...]`	The reply. `-` or nothing reads it from standard input.
`--home <dir>`	The install folder.

wheems reply "On it: reading last week's invoices first."

wheems note

Save a note to the workspace’s knowledge inbox. Agents run this.

wheems note [text...] [--home <dir>]

Argument or option	Meaning
`[text...]`	The note, in Markdown. `-` or nothing reads it from standard input.
`--home <dir>`	The install folder.

At most 32 KB, and refused if it looks like it holds a password, token or key. See Notes.

wheems service

The always-running service that connects chat to agents. See Running as a service.

Command	Options	What it does
`wheems service install`	`--home <dir>`	Run the service under launchd, now and at every login.
`wheems service status`	`--home <dir>`	Show whether the service is running. Exits with `1` when it isn’t answering.
`wheems service logs`	`-n, --lines <n>` (default `50`), `--home <dir>`	Print the end of the service’s log.
`wheems service restart`		Restart the service, for example after changing config.
`wheems service uninstall`		Stop the service and remove it from launchd.
`wheems service run`	`--home <dir>`	Run the service in the foreground (launchd runs this).

wheems service status

launchd: running (pid 41230)
control socket: answering

wheems slack manifest

Print the Slack app manifest to create the app from.

wheems slack manifest

wheems slack manifest | pbcopy

See The manifest, line by line.

wheems help

wheems help [command]

The same as wheems [command] --help.