CLI reference
This page lists every command of the smind binary, the daemon and command line of sMind by Spacing Mind, with the usage text the binary prints. It is for people who script or operate smind from a terminal.
sMind by Spacing Mind, version 0.17.0. This page describes the 0.17.0 release.
The smind binary is the daemon and the command line. Most commands talk to a running daemon (start one with smind serve). Set SMIND_HOME to use another home directory than ~/.smind.
Command summary
This block is generated from smind --help. Do not edit it by hand: run task docs:cli to refresh it.
sMind is the Spacing Mind daemon and CLI.
Usage:
smind serve start the daemon
smind stop ask the running daemon to shut down gracefully
smind status which daemon (address, home, config) the CLI talks to
smind config get [path] show server.port / listen / hostnames as stored
smind config set <path> <value> change one (comments kept; restart to apply)
smind config unset <path> restore its default
smind set-password [--password-stdin] set the password remote clients log in with
(bcrypt hash in config.yaml; needed to listen beyond localhost)
smind service install|uninstall|status|start|stop|restart [--system]
run the daemon under systemd (Linux) or launchd (macOS)
smind service install [--system] [--home <dir>] [--path <PATH>] [--no-start]
smind service logs [-f] [-n <lines>] tail the daemon's own log (daemon.log)
smind relay [--listen <addr>] [--data-dir <dir>] start the self-hostable E2EE relay
smind relay host new|ls|rm|rotate [<id>] manage relay hosts (secret printed once)
smind host add|ls|rm|invite|approve|reject|enable-reverse|disable-reverse|rename|test|route|audit pair and manage connected hosts (needs fleet.enabled)
smind workspace create <repoPath> <name> <policy> register a workspace
smind workspace ls list workspaces
smind workspace setup show|set|clear <workspaceId> worktree setup/teardown scripts
smind workspace readiness [workspaceId] [--json] check whether a repo is ready for agents
[--setup-file F|-] [--teardown-file F|-]
smind account add [--base-url <url>] <provider> <label> < credential
register an account (credential from stdin)
smind account ls list accounts
smind account login [--device] <provider> <label> browser OAuth login (anthropic, openai);
--device: device-code login (openai), prints a code
smind account rm <id> remove an account (cascades routing/quota/workspace links)
smind account test <provider> check whether a provider looks ready to run
smind account usage [--refresh] [--json] plan usage windows per account
smind space create <workspaceId> <title> create a space within a workspace
smind space ls <workspaceId> list a workspace's spaces
smind task new <workspaceId> <title> [--space <id>] create a task, optionally scoped to a space
[--budget <usd>] cap the reported cost of its task tree (root tasks only)
smind task budget <taskId> [<usd> | --clear] show, set or clear a root task's tree budget (humans only)
smind task ls <workspaceId> list a workspace's tasks
smind task tree <workspaceId> | --task <taskId> [--json] show the task hierarchy with run state, permissions and cost
smind task send <taskId> <provider> <prompt> start a run, stream it (Ctrl+C to detach)
[--chat <chatId>] [--mode <permissionMode>] [--auto-accept]
smind task runs <taskId> [--chat <chatId>] list a task's runs, optionally per chat
smind task chat ls <taskId> [--all] list a task's chats (ID, title, provider, archived)
smind task chat new <taskId> [title] create a chat
smind task chat rename <chatId> <title> rename a chat
smind task chat archive <chatId> archive a chat
smind task mode <runId> [--auto-accept on|off] [<mode>] change a live run's permission mode or auto-accept (humans only)
smind task attach <runId> stream a run (Ctrl+C to detach)
smind task logs <runId> [-f|--follow] [--tail N] show (or follow) a run's history
smind task stop <runId> stop a running run
smind task archive <taskId> [--delete-branch] [--force] archive a task (shows what it puts at risk first)
smind profile add <name> <provider> [--mode <permissionMode>] [--auto-accept]
[--thinking-level=<level>] [--model=<model>]
[--notes=<text>] create an agent profile
smind profile ls list agent profiles
smind profile rm <id> remove an agent profile
smind usage [--since <RFC3339>] [--until <RFC3339>] token usage per account, model, or day
[--by account|model|day]
smind scratch usage|clean [--json] scratch disk usage (task temp dirs), or delete closed tasks' scratch
smind plugin install <source> install a plugin DISABLED and show what it would run
(a directory, git+<url>@<40-hex sha>, or <archive>#sha256=<hash>)
smind plugin link <dir> use a directory in place (development; never copied or deleted)
smind plugin list|show|enable|disable|remove|update|reload|logs
manage plugins (humans only, local only; run "smind plugin" for flags)
smind automation list|show|create|enable|disable|resume|fire|audit|memory|delete
signal -> task rules (humans only, local only; run "smind automation" for flags)
smind validation contract submit|show, list|show write a validation contract before code; read validator verdicts
(run "smind validation" for flags; smind never merges)
smind skill ls [--target claude|agents|codex|all] bundled orchestration skills x targets (installed/modified/missing)
smind skill install [--target ...] [--force] [name...] install the bundled skills (explicit; no daemon needed)
smind skill uninstall [--target ...] [name...] remove only the files smind installed
smind learn status|ls|show|approve|reject|pin|unpin|disable|enable|archive|restore|delete|undo|reflect|curate|mode|forget
manage learned skills and proposals (humans only; run "smind learn" for flags)
smind policy init|show|test|audit permission policy engine: write the template, show rules, explain a command, list decisions
(humans only; the engine is off until steward.policy.enabled; run "smind policy" for flags)
smind steward review|list|show|cancel ask for a read-only review of a task's head commit; read reviews (humans only; run "smind steward" for flags)
smind push test [<device id prefix>] send a test notification to phones registered for push
smind cooldown ls list providers cooling down after a rate limit
smind cooldown clear <provider> I reset my quota: clear a provider cooldown, retry held runs now (humans only)
smind provider update <id> [--models a,b] [--add-models a,b] edit an instance in config.yaml: its model list, extra models, disallowed tools
[--disallow T,U] [--inherit-claude-config=true|false] (humans only; applied live; keys stay on the Providers settings)
smind update [--check] [--version <v>] [--force] update this binary to the latest release (SHA-256 verified)
[--dry-run] [--json] --check only reports; refuses while runs are active unless --force
Every subcommand except "serve", "skill", "config", "set-password" and "update" talks to a locally running daemon over its
WebSocket API, authenticating with the token the daemon itself wrote to
~/.smind/token (override the home directory with $SMIND_HOME).cooldown
After a rate limit the daemon holds a provider cooldown until the parsed reset time and keeps --on-rate-limit=wait retries waiting until then. smind cooldown ls shows which providers are still cooling down and when they reset. When you reset your quota by hand, smind cooldown clear <provider> clears the cooldown and retries the held runs now (humans only).
provider update
smind provider update <id> edits one custom instance in config.yaml: --models a,b replaces its model list, --add-models a,b adds models to the provider's own catalog, --disallow T,U names tools the instance may not call, and --inherit-claude-config=true|false shares ~/.claude instead of a private config directory. An explicitly empty value (--models "") removes the field; a flag left out leaves it alone (humans only; the daemon applies the change live, and keys are edited on the Providers settings page).
Relay
This block is generated from smind relay --help.
smind relay — self-hostable E2EE relay server
Usage:
smind relay [--listen <addr>] [--grpc-web-listen <addr>] [--data-dir <dir>] [--max-devices-per-host <n>]
[--tls-cert <pem> --tls-key <pem>] start the relay server (default 16 devices per relay host);
with --tls-cert/--tls-key it serves your CA certificate
(e.g. Let's Encrypt) instead of a self-signed one
smind relay host new <id> enroll a relay host (secret printed once)
smind relay host ls list enrolled relay hosts
smind relay host rm <id> remove a relay host
smind relay host rotate <id> issue a new secret (printed once; the old one stops admitting)
smind relay connect [--fingerprint <hex>] <address> <host-id> <secret>
configure this daemon to use a relay
smind relay offer [--window <duration>] [--max-devices <n>] [--qr] [--png <file> [--force]]
print a pairing link (and QR code) for a mobile device or the desktop app
and open a pairing window (default 10m, 1 new device)
smind relay devices ls [--pending] list paired devices (and those awaiting approval)
smind relay devices approve <id> approve a pending device
smind relay devices revoke <id> revoke a device (it is disconnected and cannot return)
smind relay devices rename <id> <label> change a device's label
Device ids accept any unique prefix. With the daemon running, "relay devices"
and "relay offer" go through it; otherwise they edit the device registry file
directly and the change applies when the daemon next starts.
Trusting the relay's certificate: "relay connect" first verifies it like a web
browser would (public CA, matching host name, not expired); if that works nothing
is pinned. Otherwise (a self-signed relay, the default) it shows the certificate
fingerprint and asks you to confirm it, or takes --fingerprint <hex>; it never
pins a certificate silently.
A relay host is one daemon's mailbox on a relay: a host id plus an admission
secret. ("smind relay workspace ..." is the deprecated name for "smind relay
host ...".) Host changes take effect when the relay restarts.
"smind relay offer" prints the pairing link on stdout; on a terminal, or with
--qr, it also draws a QR code on stderr, and --png writes one to a file. Treat
the link like a password: anyone with it can reach this daemon through the
relay; to revoke it, run "smind relay host rotate". Traffic is end-to-end
encrypted; the relay cannot read your code or messages.
The relay is a dumb pipe: it authenticates relay hosts (SCRAM-style
challenge-response) and forwards opaque ciphertext between the daemon and
paired mobile devices. It never sees plaintext. Data lives under
$SMIND_HOME/relay (default ~/.smind/relay): a self-signed TLS
certificate (pin its fingerprint, printed at startup, at pairing time)
and the relay host secret hashes.
"smind relay connect"/"smind relay offer" are the OTHER side: they make
this daemon a client of some relay (self-hosted or not), so "smind serve"
dials out to it in the background and a paired mobile device can reach
this daemon's workspaces through it.
Connecting registers this daemon once with the relay; every paired client sees all of this daemon's workspaces, spaces and tasks; nothing is created in smind.Commands the summary leaves out
These commands exist but are not in the summary above. The usage lines are the ones the binary prints when you run a command with the wrong arguments.
smind task wait <runId|item:ID> [--timeout <duration>]
smind task permissions <runId>
smind task approve <runId> [requestId] [optionId]
smind task deny <runId> [requestId]
smind task options <runId>
smind task set-option <runId> <configId> <value>
smind task queue ls --chat <chatId>
smind task queue cancel <itemId>
smind profile edit <id> [--name=..] [--provider=..] [every `profile add` flag]
smind profile seed roles
smind mcp serve
smind mcp add <name> <stdio|http|sse> [--command <cmd>] [--arg <value>]... [--url <url>] [--env <KEY=VALUE>]... [--header <KEY=VALUE>]...
smind mcp ls
smind mcp rm <id>
smind mcp enable <id>
smind mcp disable <id>
smind relay connect [--fingerprint <hex>] <relay-address> <host-id> <secret>
smind relay offer [--window <duration>] [--max-devices <n>] [--qr] [--png <file> [--force]]
smind relay devices ls [--pending]
smind relay devices approve <id>
smind relay devices revoke <id>
smind relay devices rename <id> <label>task wait
smind task wait <runId|item:ID> blocks until the run is terminal and reports the outcome in its exit code:
| Code | Meaning |
|---|---|
| 0 | The run finished. |
| 1 | Any other error. |
| 3 | The run was stopped. |
| 4 | The run finished at a cap and needs Continue. |
| 5 | --timeout expired; the run keeps going. |
| 6 | The run failed on a rate-limit class (plan_window_exhausted, transient_429, rate_limited). |
| 7 | The run failed with something a human must fix (auth_expired, model_not_in_plan). |
host
smind host add|ls|rm|invite|approve|reject|enable-reverse|disable-reverse|rename|test|route|audit pairs and manages connected hosts. Needs fleet.enabled: true and the daemon running. <host> is a host id or its alias. See Connected hosts.
scratch
smind scratch usage [--json] shows scratch disk usage (task temp dirs); smind scratch clean [--json] deletes closed tasks' scratch.
steward
smind steward review <taskId> [--sha <40 hex>] asks for a read-only review of the task's head commit; steward list, show and cancel read and stop reviews. A review is advice: smind never merges.
policy
smind policy init writes the commented policy template (never overwrites), show prints the engine switch and rules, test "<command>" explains what the engine would decide per segment, and audit lists recent decisions. The engine is off until steward.policy.enabled is true. Humans only.
push test
smind push test [<device id prefix>] sends a test notification to phones registered for push. It exits 0 only if every phone was sent to.
update
smind update [--check] [--version <v>] [--force] [--dry-run] [--json] updates the binary to the latest release (SHA-256 verified). --check only reports; it refuses while runs are active unless --force.