# CLI reference > Every wheems command, argument and flag in version 0.0.3, from its own help output, with examples and what each prints. Every `wheems` command, from its own `--help` output in version 0.0.3. Run `wheems --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 ` | 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`](#wheems-setup) | The setup menu: engines, Slack, workspaces, knowledge, the service, doctor | | [`wheems init`](#wheems-init) | Create a workspace with its chief of staff (and the install, if there is none) | | [`wheems doctor`](#wheems-doctor) | Check this machine, Herdr core and the install | | [`wheems validate`](#wheems-validate) | Validate config files or install folders | | [`wheems review`](#wheems-review) | Go through skill proposals and changes to `about-you.md` | | [`wheems kb search`](#wheems-kb-search) | Search a workspace's knowledge base | | [`wheems kb reindex`](#wheems-kb-reindex) | Rebuild search indexes | | [`wheems skill list`](#wheems-skill-list) | List the library and waiting proposals | | [`wheems skill show`](#wheems-skill-show) | Print a skill's `SKILL.md` | | [`wheems service …`](#wheems-service) | Look after the background service | | [`wheems slack manifest`](#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`](#wheems-reply) | Post a progress note to the conversation's thread | | [`wheems note`](#wheems-note) | Save a note to the workspace's knowledge inbox | | [`wheems skill propose`](#wheems-skill-propose) | Propose a skill for you to review | | [`wheems kb search`](#wheems-kb-search) | Search the agent's own workspace | --- ## wheems setup Set up Wheems: engines, channels, workspaces, knowledge and the service, from a menu. ```text title="Usage" wheems setup [--home ] ``` | Option | Meaning | | --- | --- | | `--home ` | 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](https://wheems.dev/docs/quick-start/). ## wheems init Create a workspace with its chief of staff (and the install, if there is none). ```text title="Usage" wheems init [options] ``` | Argument or option | Meaning | | --- | --- | | `` | The workspace id, such as `personal`. Lowercase letters, digits and dashes. | | `--name ` | Its display name. Default: from the id (`acme` → `Acme`). | | `--channel ` | Chat in this Slack channel instead of the bot's direct messages. | | `--engine ` | What the chief of staff runs in: `claude-code`, `codex` or `opencode`. Default: `claude-code`. | | `--model ` | The engine's model. Default: the engine's usual one. | | `--home ` | The install folder. | ```bash title="Terminal" wheems init personal wheems init acme --channel acme-chat --engine codex ``` ```text title="Output" 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 .` | 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. ```text title="Usage" wheems doctor [--quick] [--json] [--home ] ``` | Option | Meaning | | --- | --- | | `--quick` | Skip starting a test session in Herdr core. | | `--json` | Print the report as JSON. | | `--home ` | 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](https://wheems.dev/docs/troubleshooting/). ## wheems validate Validate config files, or a whole install folder with the links between its files. ```text title="Usage" wheems validate [paths...] [--home ] ``` | Argument or option | Meaning | | --- | --- | | `[paths...]` | Files or install folders. Default: the install folder. | | `--home ` | The install folder. | ```bash title="Terminal" wheems validate wheems validate workspaces/acme/workspace.yaml wheems validate ~/Projects/wheems/examples/install ``` ```text title="Output" 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](https://wheems.dev/docs/reference/configuration/). ## wheems review Review what waits for you: skills agents proposed, and changes to `about-you.md`. ```text title="Usage" wheems review [--list] [--home ] ``` | Option | Meaning | | --- | --- | | `--list` | Only list what is waiting. | | `--home ` | 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](https://wheems.dev/docs/skills/#reviewing-with-wheems-review). ```text title="Output" Nothing waits for review. ``` ## wheems kb search Search the knowledge base by keyword and by meaning. ```text title="Usage" wheems kb search [options] ``` | Argument or option | Meaning | | --- | --- | | `` | What to look for, in plain words. Quotes are optional. | | `--workspace ` | The workspace. Default: `$WHEEMS_WORKSPACE`, or the only one. | | `--limit ` | How many results. Default: `5`. | | `--json` | Print the results as JSON. | | `--home ` | The install folder. | ```bash title="Terminal" wheems kb search what did we decide about the boat name --workspace personal ``` ```text title="Output" 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. ```text title="Usage" wheems kb reindex [--workspace ] [--home ] ``` | Option | Meaning | | --- | --- | | `--workspace ` | Only this workspace. Default: every workspace. | | `--home ` | The install folder. | ```text title="Output" 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](https://wheems.dev/docs/knowledge-base/#the-index). ## wheems skill list List the skills in the library, and proposals waiting for review. ```text title="Usage" wheems skill list [--json] [--home ] ``` | Option | Meaning | | --- | --- | | `--json` | Print them as JSON. | | `--home ` | The install folder. | ## wheems skill show Print a skill's `SKILL.md`: the latest version, or the one asked for. ```text title="Usage" wheems skill show [version] [--home ] ``` | Argument or option | Meaning | | --- | --- | | `` | The skill. | | `[version]` | This version instead of the latest. | | `--home ` | The install folder. | ```bash title="Terminal" 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. ```text title="Usage" wheems skill propose [input] [--home ] ``` | Argument or option | Meaning | | --- | --- | | `` | The skill, in lowercase words joined by dashes. | | `[input]` | `-`: read the `SKILL.md` from standard input, which is also the default. | | `--home ` | 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](https://wheems.dev/docs/skills/#how-agents-propose-skills). ## wheems reply Reply to the person in the current conversation. Agents run this, for progress notes during long work. ```text title="Usage" wheems reply [text...] [--home ] ``` | Argument or option | Meaning | | --- | --- | | `[text...]` | The reply. `-` or nothing reads it from standard input. | | `--home ` | The install folder. | ```bash title="Terminal (in an agent's session)" wheems reply "On it: reading last week's invoices first." ``` ## wheems note Save a note to the workspace's knowledge inbox. Agents run this. ```text title="Usage" wheems note [text...] [--home ] ``` | Argument or option | Meaning | | --- | --- | | `[text...]` | The note, in Markdown. `-` or nothing reads it from standard input. | | `--home ` | The install folder. | At most 32 KB, and refused if it looks like it holds a password, token or key. See [Notes](https://wheems.dev/docs/knowledge-base/#notes). ## wheems service The always-running service that connects chat to agents. See [Running as a service](https://wheems.dev/docs/service/). | Command | Options | What it does | | --- | --- | --- | | `wheems service install` | `--home ` | Run the service under launchd, now and at every login. | | `wheems service status` | `--home ` | Show whether the service is running. Exits with `1` when it isn't answering. | | `wheems service logs` | `-n, --lines ` (default `50`), `--home ` | 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 ` | Run the service in the foreground (launchd runs this). | ```bash title="Terminal" wheems service status ``` ```text title="Output" launchd: running (pid 41230) control socket: answering ``` ## wheems slack manifest Print the Slack app manifest to create the app from. ```text title="Usage" wheems slack manifest ``` ```bash title="Terminal" wheems slack manifest | pbcopy ``` See [The manifest, line by line](https://wheems.dev/docs/slack/#the-manifest-line-by-line). ## wheems help ```text title="Usage" wheems help [command] ``` The same as `wheems [command] --help`.