The smith command line
Every smith command and flag in one line each, from the cobra definitions in internal/cli, with the desk's memory limit and the legacy task-tree commands.
One line per command or flag, read from the cobra definitions in internal/cli. The description is the flag's own help text where it has one. Environment variables a command reads are in environment variables. smith config check and its four flags are on config edits and are not repeated here.
01smith#
smith is the root: "Headless control plane for inspectable LLM task trees".
02desk#
smith desk [project] serves the smith desk: conversations, every run, and the conductor's MCP. This is what the desktop app starts as its core.
Under smith desk the core runs under a soft memory limit of a quarter of the machine's memory (MemTotal), at least 512 MiB and at most 2 GiB (deskMemoryLimit; 512 MiB when the total is unknown), skipped when GOMEMLIMIT is set and not empty.
| flag | what it does |
|---|---|
--listen |
loopback address for the desk, default 127.0.0.1:7333; port 0 picks a free one |
--patch-root |
the patch the desk's canvas api serves; default desk.json, else <project>/.smith/desk/patch |
--handoff-file |
where to write {"project"} before exiting 75 to be respawned on another project |
--exit-with-stdin |
exit when stdin closes, so the core dies with the app that started it |
--conductor-command |
the claude binary conductor sessions run; default desk.json, else claude on PATH |
--no-conductor |
serve the desk without a conductor; messages are kept unanswered |
--pprof-addr |
loopback-only address for a net/http/pprof listener on its own mux; off when empty; falls back to $SMITH_PPROF_ADDR, the flag wins; a non-loopback address is refused and the core fails to start |
--work-app-url |
browser URL for tickets_please, not its MCP endpoint |
--memory-app-url |
browser URL for the memory renderer, not its API endpoint |
--writable-root |
grant work-profile nodes a writable root, repeatable |
--harness-config |
operator-owned JSON harness configuration for prepare and start from a work ticket |
--project-root |
mount a local project path or name=path for authoring and history, repeatable; does not grant model writes |
--library-root |
directory for new local projects; default <patch>/.smith/library |
--template-root |
run template library root; operator templates are <root>/templates/<name>.yaml beside the shipped ones; default <patch>/.smith |
03tickets and serve#
smith tickets [subcommand]is the ticket tracker as its own MCP server: stdio MCP with no subcommand,serveover HTTP with the admin page. Subcommands: mcp (default), serve, check, init, migrate, import, grant-owner, list-users, list-memberships, commit-hook, embed. Flag parsing is disabled; everything goes to the tracker.smith serve [--addr :8765] [--data-root dir] [--remote-project-root dir]runs smith headless: the tracker's MCP at/mcp,/adminbehind tinyauth, and/healthz. It takes thesmith tickets serveflags, and flag parsing is disabled.
04mcp#
smith mcpruns the local Smith MCP control plane over stdio. See the MCP control plane.
05docs#
smith docs [topic[#anchor]]reads smith's built-in manual.smith docs --searchlists the pages and sections that mention these words.
06harness#
smith harness runs and recovers the canonical ticket harness.
smith harness run <patch>starts the canonical ticket harness and returns at its human gate.smith harness resume <patch>recovers an interrupted harness run and returns at its next gate or terminal.smith harness decide <patch>resolves a pending harness gate and continues the durable run.
Flags of harness run:
| flag | what it does |
|---|---|
--project |
tickets_please project slug |
--ticket |
ticket id or project shortcode |
--phase |
optional phase id or slug |
--work-runtime |
runtime for workspace work, claude or codex |
--intake-runtime, --plan-runtime, --review-runtime, --close-runtime |
runtime for that role, claude, codex or grok; default claude |
--intake-model, --plan-model, --work-model, --review-model, --close-model |
pin the model for that role; default picked from the model registry by tag; the review default differs from work |
--persona |
role=persona override, repeatable; role is plan, work, review, close or * |
--knowledge |
file from SMITH_KNOWLEDGE_DIR to give every role node, repeatable |
--research-route |
research route, direct or challenge; default direct |
--review-route |
review route, claude |
--memory-context |
memory context selector, repeatable or comma-separated |
--memory |
explicit memory name, repeatable or comma-separated |
--prove-recovery |
restart the Smith controller during work and deterministic checks |
Flags of harness resume and harness decide:
| flag | what it does |
|---|---|
--project |
tickets_please project slug (both) |
--run |
durable patch run id (both) |
--request |
pending gate request id (decide) |
--reason |
explicit human decision reason; required (decide) |
--approve |
approve the pending gate (decide) |
--reject |
reject the pending gate (decide) |
07asset#
smith asset tracks folders as versioned assets.
smith asset adopt <dir>starts tracking a folder as an asset and saves its first version. Flags--name(default the folder's name),--kind(what kind it is, like mock),--about(what it is and how to use it).smith asset save <id>saves the folder's current state as a new version.--noteis a note for the version.smith asset listlists the assets.
08init and lib#
smith initinitializes Smith libraries.--forceoverwrites user-modified library files.smith libmanages Smith libraries.smith lib updateupdates built-in libraries from embedded copies.--forceoverwrites user-modified files.
09config#
smith configconfigures Smith credentials. Itschecksubcommand is on config edits.
10runs#
smith runs <path> lists all runs for an app.
smith runs prune <path>removes old run directories.--keepretains N most recent runs,--older-thanremoves runs older than a duration (for example 7d, 24h, 30m),--drypreviews without deleting.smith runs index <path>indexes the written parts of past runs into the tracker's search.--endpointis the tickets MCP endpoint, default$SMITH_TICKETS_ENDPOINT;--tokenis the tickets bearer token, default$SMITH_TICKETS_TOKEN. Without an endpoint it fails with "a tickets endpoint is required".
11legacy task-tree commands#
These work on a task tree (an app) rather than on the desk. Details of the task-tree format are not covered here.
| command | what it does |
|---|---|
smith validate <path> |
validate a task tree against RFC 0001 rules |
smith plan <target-path> <goal> |
generate a proposal for a task tree from a goal. --model overrides the planner model, --max-cost-usd is the cost ceiling |
smith apply <proposal-path> |
apply a proposal to its target project. --dry shows what would be applied without writing, --force skips conflict detection |
smith run <path> |
execute a task tree |
smith status <path> |
report per-task status from the latest run manifest. --run shows a specific run ID |
smith set <path> [name=value ...] |
set persistent default inputs for an app |
smith unset <path> <name> [name ...] |
remove persistent default inputs from an app |
smith clean <path> |
remove generated content (runs, cache) from an app directory. --all removes the entire .smith/ directory including proposals, --dry previews |
Flags of smith run:
| flag | what it does |
|---|---|
--dry |
validate and report the execution plan without running |
--no-cache |
ignore cached outputs, force all tasks to execute |
--clear-cache |
delete all cached outputs before running |
--input |
pass a run input entry as name=value, repeatable |
--scope |
set a tool scope parameter as key=value, repeatable |
--writable-root |
grant an external work profile access to a root, repeatable |
--allow-uncontained-development |
deliberately authorize the named uncontained_development execution profile |