commands[102]:
- name: add
purpose: Install a workflow pack from GitHub, npm, or a local file
args[1]{name,type,required,desc}:
spec,string,true,GitHub npm or file pack spec
flags[2]{name,short,type,default,desc}:
global,,boolean,false,Install in ~/.smithers/packs instead of the local project
yes,,boolean,false,Skip trust confirmation
- name: init
purpose: Install the local Smithers workflow pack into .smithers/. In an interactive terminal init asks one question (your preferred coding agent), installs the pack with defaults plus that agent's plugin (or skill if no plugin), then opens a hijacked tutorial session hosted by that agent; piped/agent/CI runs (or --yes) install defaults. Pass an optional prompt to also launch the create-workflow builder after init.
args[1]{name,type,required,desc}:
prompt,string,false,Optional plain-English task: after init, launch the create-workflow builder with this prompt pre-filled
flags[12]{name,short,type,default,desc}:
agent,,string,,Preferred coding agent id (e.g. claude, codex, pi); skips the interactive agent question
tutorial,,boolean,true,After install, open a hijacked tutorial session hosted by your preferred agent (interactive init only); --no-tutorial skips
force,,boolean,false,Overwrite existing scaffold files
agents-only,,boolean,false,Only create .smithers/agents/ and leave workflow pack untouched
install,,boolean,true,Run bun install inside the pack after scaffolding
add-agents,,boolean,false,Launch the account registration wizard after scaffolding
skill,,boolean,true,Install the curated smithers skill into detected coding agents and append workflow guidance to existing CLAUDE.md/AGENTS.md files
global,,boolean,false,Scaffold the global pack in ~/.smithers (honors SMITHERS_HOME) instead of ./.smithers
update-prompt,,boolean,true,In an interactive terminal, ask which drifted shipped pack files to update (warns on shared components); --no-update-prompt skips
template,,string,,Show next steps for a canonical starter template ID after init
yes,,boolean,false,Non-interactive: skip prompts and use defaults; alias for --non-interactive
non-interactive,,boolean,false,Non-interactive: skip prompts and use defaults; alias for --yes
- name: make-workflow
purpose: Build a new Smithers workflow from a plain-English description. Dispatches to the create-workflow builder.
args[1]{name,type,required,desc}:
task,string,false,Plain-English description of the workflow to build (forwarded as the builder prompt)
flags[37]{name,short,type,default,desc}:
detach,d,boolean,false,Background mode; print runId/pid/logFile and exit
run-id,r,string,,Explicit run ID
max-concurrency,c,number,4,Maximum parallel tasks
root,,string,,Tool sandbox root directory
log,,boolean,true,Enable NDJSON event log file output
log-dir,,string,,NDJSON event logs directory
allow-network,,boolean,false,Allow bash tool network requests
max-output-bytes,,number,,Max bytes a single tool call can return
tool-timeout-ms,,number,,Max wall-clock time per tool call in ms
hot,,boolean,false,Hot reload for .tsx workflows
input,i,string,,Input data as JSON string or '-' to read JSON from stdin
annotations,,string,,Run annotations as flat JSON string/number/boolean object or '-' to read JSON from stdin
resume,,boolean|string,false,Resume an existing run; may be true or a run ID
force,,boolean,false,Resume even if still marked running
parent-run-id,,string,,Existing run ID to record as this run's parent (persisted lineage, surfaced by inspect/ps and the MCP run tools)
accept-workflow-change,,boolean,false,Resume this run after its workflow source changed, re-blessing durability metadata in place; you own replay determinism
resume-claim-owner,,string,,Internal durable resume claim owner
resume-claim-heartbeat,,number,,Internal durable resume claim heartbeat
resume-restore-owner,,string,,Internal durable resume restore owner
resume-restore-heartbeat,,number,,Internal durable resume restore heartbeat
serve,,boolean,false,Start an HTTP server alongside the workflow
supervise,,boolean,false,Run stale-run supervisor loop with --serve
supervise-dry-run,,boolean,false,With --supervise; detect without resuming
supervise-interval,,string,10s,Supervisor poll interval
supervise-stale-threshold,,string,30s,Heartbeat staleness threshold
supervise-max-concurrent,,number,3,Max runs resumed per poll
port,,number,7331,HTTP server port when --serve
host,,string,127.0.0.1,HTTP bind address when --serve
auth-token,,string,,Bearer token for HTTP auth or SMITHERS_API_KEY env
insecure,,boolean,false,Allow unauthenticated non-loopback HTTP binding; dangerous
metrics,,boolean,true,Expose /metrics endpoint when --serve
backend,,enum,,Bootstrap storage selection for a workflow owner or workspace Gateway; not a run-discovery/control flag (sqlite|pglite|postgres)
post-failure,,boolean,true,Auto-launch the post-failure autopsy workflow when this run fails (disable with --no-post-failure or SMITHERS_POST_FAILURE=0)
verbose,,boolean,false,Show engine info logs (run lifecycle, agent sessions) on interactive runs
report,,boolean,true,Narrate the result with a cheap agent and open an HTML summary on interactive runs (disable with --no-report or SMITHERS_NO_REPORT=1)
prompt,p,string,,Prompt text mapped to input.prompt when --input is omitted
interactive,,boolean,false,Pick inputs through interactive terminal prompts and live-render the run
- name: starters
purpose: Show plain-English starter workflows with copy-paste commands
args[1]{name,type,required,desc}:
id,string,false,Starter ID or alias
flags[4]{name,short,type,default,desc}:
audience,,string,,Filter by audience such as product, support, or founder
goal,,string,,Filter by goal such as plan, build, debug, or quality
workflow,,string,,Filter by seeded workflow ID
tag,,string,,Filter by starter tag
- name: hermes
purpose: Add Smithers to a local Hermes agent (register the MCP server and install the native Hermes plugin); alias for mcp add --agent hermes
- name: up
purpose: Start or resume a workflow execution from a discovered workflow ID or a .tsx workflow file path
args[1]{name,type,required,desc}:
workflow,string,false,Workflow ID or file path (omit with --interactive to pick one)
flags[36]{name,short,type,default,desc}:
detach,d,boolean,false,Background mode; print runId/pid/logFile and exit
run-id,r,string,,Explicit run ID
max-concurrency,c,number,4,Maximum parallel tasks
root,,string,,Tool sandbox root directory
log,,boolean,true,Enable NDJSON event log file output
log-dir,,string,,NDJSON event logs directory
allow-network,,boolean,false,Allow bash tool network requests
max-output-bytes,,number,,Max bytes a single tool call can return
tool-timeout-ms,,number,,Max wall-clock time per tool call in ms
hot,,boolean,false,Hot reload for .tsx workflows
input,i,string,,Input data as JSON string or '-' to read JSON from stdin
annotations,,string,,Run annotations as flat JSON string/number/boolean object or '-' to read JSON from stdin
resume,,boolean|string,false,Resume an existing run; may be true or a run ID
force,,boolean,false,Resume even if still marked running
parent-run-id,,string,,Existing run ID to record as this run's parent (persisted lineage, surfaced by inspect/ps and the MCP run tools)
accept-workflow-change,,boolean,false,Resume this run after its workflow source changed, re-blessing durability metadata in place; you own replay determinism
resume-claim-owner,,string,,Internal durable resume claim owner
resume-claim-heartbeat,,number,,Internal durable resume claim heartbeat
resume-restore-owner,,string,,Internal durable resume restore owner
resume-restore-heartbeat,,number,,Internal durable resume restore heartbeat
serve,,boolean,false,Start an HTTP server alongside the workflow
supervise,,boolean,false,Run stale-run supervisor loop with --serve
supervise-dry-run,,boolean,false,With --supervise; detect without resuming
supervise-interval,,string,10s,Supervisor poll interval
supervise-stale-threshold,,string,30s,Heartbeat staleness threshold
supervise-max-concurrent,,number,3,Max runs resumed per poll
port,,number,7331,HTTP server port when --serve
host,,string,127.0.0.1,HTTP bind address when --serve
auth-token,,string,,Bearer token for HTTP auth or SMITHERS_API_KEY env
insecure,,boolean,false,Allow binding a non-loopback --host with NO auth (exposes unauthenticated approve/deny/cancel control of the run; dangerous)
metrics,,boolean,true,Expose /metrics Prometheus endpoint when --serve
interactive,,boolean,false,Pick a workflow and inputs interactively then open the full-screen run monitor (no silent fallback: fails with TUI_MONITOR_UNAVAILABLE if the tui package is missing, leaving the detached run running)
backend,,enum,,Bootstrap storage selection for a workflow owner or workspace Gateway; not a run-discovery/control flag (sqlite|pglite|postgres)
post-failure,,boolean,true,Auto-launch the post-failure autopsy workflow when this run fails (disable with --no-post-failure or SMITHERS_POST_FAILURE=0)
verbose,,boolean,false,Show engine info logs (run lifecycle, agent sessions) on interactive runs
report,,boolean,true,Narrate the result with a cheap agent and open an HTML summary on interactive runs (disable with --no-report or SMITHERS_NO_REPORT=1)
- name: migrate
purpose: Copy the legacy bun:sqlite smithers.db into PGlite or Postgres and write the migrated.json marker
flags[3]{name,short,type,default,desc}:
to,,enum,pglite,Target backend (pglite|postgres)
url,,string,,Postgres connection URL when --to postgres
keep-sqlite,,boolean,true,Keep the legacy SQLite database after a successful copy
- name: eval
purpose: Run a workflow over JSON/JSONL cases and write a regression report
args[1]{name,type,required,desc}:
workflow,string,true,Workflow file path or discovered workflow ID
flags[16]{name,short,type,default,desc}:
cases,c,string,,JSON array, { cases: [...] }, or JSONL case file
suite,s,string,,Stable suite ID used in run IDs and report paths
run-label,,string,current UTC timestamp + nonce,Label appended to eval run IDs
dry-run,n,boolean,false,Plan run IDs without launching workflows
concurrency,j,number,1,Number of eval cases to run at once
max-cases,,number,,Run only the first N cases
report,r,string,.smithers/evals/<suite>.json,Report path
force,,boolean,false,Overwrite an existing report
include-output,,boolean,true,Include workflow outputs in the report
max-concurrency,,number,,Per-workflow task concurrency
root,,string,,Tool sandbox root directory
log,,boolean,true,Enable NDJSON event log file output
log-dir,,string,,NDJSON event logs directory
allow-network,,boolean,false,Allow bash tool network requests
max-output-bytes,,number,,Max bytes a single tool call can return
tool-timeout-ms,,number,,Max wall-clock time per tool call in ms
optimization,,string,,Apply a Smithers optimization artifact while running the eval suite
- name: optimize
purpose: Run GEPA prompt optimization over a workflow eval suite and write an optimized prompt artifact
args[1]{name,type,required,desc}:
workflow,string,true,Workflow file path or discovered workflow ID
flags[16]{name,short,type,default,desc}:
cases,c,string,,JSON array, { cases: [...] }, or JSONL case file
suite,s,string,,Stable suite ID used in run IDs and report paths
provider,p,enum,openai-api,GEPA patch generator provider
model,m,string,,Optimizer model for provider-backed GEPA
artifact,a,string,,Write the optimized prompt artifact to this path
report-dir,,string,,Directory for baseline and optimized eval reports
min-improvement,,number,0.000001,Minimum required absolute score improvement
max-cases,,number,,Run only the first N cases
concurrency,j,number,1,Number of eval cases to run at once
max-concurrency,,number,,Per-workflow task concurrency
root,,string,,Tool sandbox root directory
log,,boolean,true,Enable NDJSON event log file output
log-dir,,string,,NDJSON event logs directory
allow-network,,boolean,false,Allow bash tool network requests
max-output-bytes,,number,,Max bytes a single tool call can return
tool-timeout-ms,,number,,Max wall-clock time per tool call in ms
- name: supervise
purpose: Watch explicitly named stale runs and auto-resume them; --all opts into a workspace-wide sweep
flags[6]{name,short,type,default,desc}:
run,r,string,,Only supervise these run IDs (comma-separated)
all,a,boolean,false,Explicitly supervise every eligible run in the workspace
dry-run,n,boolean,false,Detect stale runs without resuming
interval,i,string,10s,Poll interval
stale-threshold,t,string,30s,Heartbeat staleness threshold before resume
max-concurrent,c,number,3,Max runs resumed per poll
- name: gateway
purpose: Serve the multi-run Gateway RPC/WS control plane for workspace run state (one singleton per workspace; a second start refuses); unlike up --serve, this is not tied to one run
args[1]{name,type,required,desc}:
action,enum,false,Manage the running singleton instead of serving: status | stop
flags[7]{name,short,type,default,desc}:
host,H,string,127.0.0.1,Gateway bind address
port,p,number,7331,Preferred port (falls back to an ephemeral port when taken; clients discover the verified URL with gateway status)
backend,,enum,,Storage behind this workspace Gateway; a boot/deployment choice, not a client run-lookup flag (sqlite|pglite|postgres)
auth-token,,string,,Bearer token for HTTP/WS auth (or SMITHERS_API_KEY); required for a non-loopback host
mint-token,,boolean,false,Mint a random bearer; require it on every request and record it only in the 0600 runtime state file
insecure,,boolean,false,Allow a non-loopback host with NO auth (dangerous)
idle-timeout,,number,,Exit after this many ms with no clients, in-flight runs, or registered schedules (0 = stay up; autostarted daemons set this automatically); overridable via SMITHERS_GATEWAY_IDLE_MS
- name: monitor
purpose: Open the Smithers Monitor, the gateway's live web UI over every run in the workspace (served at /monitor, no .smithers pack required). Pure observation; launches no run, no workflow, no agents. Resolves the workspace's singleton gateway (--gateway probe, then runtime-state discovery, then legacy port probe, then autostart) and opens the browser
args[1]{name,type,required,desc}:
runId,string,false,Focus this run when the monitor opens (deep-linked as ?runId=)
flags[5]{name,short,type,default,desc}:
gateway,g,string,,Gateway base URL (default http://127.0.0.1:<port>)
port,,number,7331,Gateway port when --gateway is not set
open,,boolean,true,Open a browser; use --no-open to just print the URL
autostart,,boolean,true,Start a local Gateway automatically when no Gateway is reachable; --no-autostart fails fast instead
daemon,,boolean,true,Autostart the Gateway as a background daemon; --no-daemon (or SMITHERS_NO_DAEMON=1) disables daemonized autostart
- name: bug
purpose: File a smithers bug report to bug.smithers.sh; with --run it attaches the run's workflow, status, error, and last ~50 events with secrets scrubbed
flags[4]{name,short,type,default,desc}:
run,,string,,Attach this run's workflow name, status, error, and recent events to the report
title,,string,,Bug title (derived from the run's error when omitted)
body,,string,,Bug description body
endpoint,,string,https://bug.smithers.sh/api/bugs,Bug endpoint URL; the SMITHERS_BUG_ENDPOINT env var takes precedence
- name: review
purpose: Run code review plus story-form HTML walkthrough generation for a repo or PR
args[1]{name,type,required,desc}:
repo,string,false,Repository path; defaults to the current directory
flags[17]{name,short,type,default,desc}:
from,,string,,Base ref for a merge-base diff
to,,string,,Head ref for a merge-base diff
commit,,string,,Review one commit
pr,,string,,Review a GitHub PR and post the review onto it
background,,string,,Requirement background for review and narration
no-review,,boolean,false,Skip review agents
no-narrate,,boolean,false,Skip the narrator agent
no-verify,,boolean,false,Skip verification over findings
quiz,,enum,auto,off|auto|on
concurrency,,number,8,Parallel file reviews
timeout,,number,10,Per-agent-task timeout in minutes
out,,string,,Output HTML path
title,,string,,Walkthrough title (default: narrator headline)
db,,string,,Smithers db path
split,,boolean,false,Side-by-side diffs instead of unified
publish,,boolean,false,Upload to the share service and print the share URL
open,,boolean,false,Open the walkthrough in the default browser
- name: ps
purpose: List active, paused, and recently completed runs
flags[5]{name,short,type,default,desc}:
status,s,string,,"Filter: running|waiting-approval|waiting-event|waiting-timer|paused|continued|finished|failed|cancelled"
limit,l,number,20,Max rows
all,a,boolean,false,Include all statuses
watch,w,boolean,false,Refresh continuously
interval,i,number,2,Watch refresh seconds
- name: logs
purpose: Tail lifecycle events for a run
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[5]{name,short,type,default,desc}:
follow,f,boolean,true,Poll for new events while run is active
from-seq,,number,,Start from event sequence number (exclusive)
since,,number,,Deprecated alias of --from-seq (an event sequence number, not a duration)
tail,n,number,50,Last N events
follow-ancestry,,boolean,false,Include ancestor run events root-to-current
- name: events
purpose: Query run event history with filters, grouping, and NDJSON output
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[8]{name,short,type,default,desc}:
node,n,string,,Filter by node ID
type,t,string,,"Category: agent|approval|frame|memory|node|openapi|output|revert|run|sandbox|scorer|snapshot|supervisor|timer|token|tool-call|workflow"
since,s,string,,Recent duration window such as 5m or 2h
limit,l,number,1000,Max events; capped at 100000
json,j,boolean,false,Emit NDJSON
group-by,,string,,"node | attempt"
watch,w,boolean,false,Append new events as they arrive
interval,i,number,2,Watch poll seconds
- name: chat
purpose: Show agent chat output for the latest run or a specific run
args[1]{name,type,required,desc}:
runId,string,false,Run ID; latest run if omitted
flags[4]{name,short,type,default,desc}:
all,a,boolean,false,Show every agent attempt
follow,f,boolean,false,Watch for new output
tail,n,number,,Last N chat blocks
stderr,,boolean,true,Include agent stderr
- name: chat-create
purpose: Create and start a one-task auto-hijacked chat run
flags[2]{name,short,type,default,desc}:
agent,,enum,,claude-code|codex|antigravity|pi|kimi|amp
cwd,,string,.,Working directory for the chat session
- name: oneshot
purpose: Run one well-scoped goal with a strong agent in the background, with optional review and a live UI
args[1]{name,type,required,desc}:
goal,string,false,Goal to complete; required unless using --status or a preference setter
flags[11]{name,short,type,default,desc}:
goal-file,,string,,Read a long goal from a file
model,,string,auto,Model slot or canonical model id
agent,,enum,,codex|kimi|claude-code|opencode
review,,enum,stored,Review preference for this run (on|off)
set-review,,enum,,Persist the review preference (on|off)
set-trivial,,enum,,Persist trivial-task routing (direct|oneshot)
status,,boolean,false,Print usable agents model chain and stored preferences as JSON
cwd,,string,.,Working directory for the task
detach,d,boolean,true,Run in the background; --detach false runs in the foreground
interactive,,boolean,false,Open the full-screen TUI monitor
open,,boolean,true,Open the run UI after launch
- name: hijack
purpose: Hand off the latest resumable agent session or Smithers-managed conversation
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[3]{name,short,type,default,desc}:
target,,string,,"Expected engine such as claude-code or codex"
timeout-ms,,number,30000,Wait time for live handoff
launch,,boolean,true,Open session immediately
- name: inspect
purpose: Output detailed state of a run: steps, agents, approvals, timers, loops, outputs
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[2]{name,short,type,default,desc}:
watch,w,boolean,false,Refresh continuously
interval,i,number,2,Watch refresh seconds
- name: node
purpose: Show enriched node details for debugging retries, tool calls, and output
args[1]{name,type,required,desc}:
nodeId,string,true,Node ID
flags[6]{name,short,type,default,desc}:
run-id,r,string,,Run ID containing the node
iteration,i,number,,Loop iteration; latest if omitted
attempts,,boolean,false,Expand all attempts in human output
tools,,boolean,false,Expand tool input/output payloads
watch,w,boolean,false,Refresh continuously
interval,,number,2,Watch refresh seconds
- name: why
purpose: Explain why a run is currently blocked or paused
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[1]{name,short,type,default,desc}:
json,,boolean,false,Structured JSON diagnosis
- name: status
purpose: "Concise run health at a glance: verdict, node counts, agent/model mix, throughput, and the nodes gating progress."
args[1]{name,type,required,desc}:
runId,string,true,Run ID to summarize
flags[2]{name,short,type,default,desc}:
json,,boolean,false,Output the structured summary as JSON
window,,number,,Recent-activity window in minutes for the throughput/verdict checks (default 10)
- name: what
purpose: Summarize what happened in a run or node with a cheap fast agent (deterministic recap without one)
args[1]{name,type,required,desc}:
runId,string,false,Run ID (default: latest run)
flags[4]{name,short,type,default,desc}:
node,n,string,,Node ID: explain one node instead of the whole run
iteration,i,number,,Loop iteration number (default: latest)
json,,boolean,false,Structured JSON (summary, agentId, source, facts)
timeout,,number,,Narrator agent timeout in seconds (default 60)
- name: human
purpose: List, answer, or cancel durable human requests
args[2]{name,type,required,desc}:
action,string,true,inbox|answer|cancel
requestId,string,false,Human request ID for answer/cancel
flags[2]{name,short,type,default,desc}:
value,,string,,JSON response for answer
by,,string,,Human operator identifier
- name: ask-human
purpose: Raise a blocking human-approval request from inside a run and wait for the decision
args[1]{name,type,required,desc}:
prompt,string,true,The decision or question to put to a human
flags[7]{name,short,type,default,desc}:
context,,string,,Extra context appended to the prompt
choices,,string,,Comma-separated choices for a fixed-choice decision
run-id,r,string,,Run to attach to (SMITHERS_RUN_ID or single active run)
node,n,string,,Node id to attach to (SMITHERS_NODE_ID)
iteration,,number,0,Loop iteration (SMITHERS_ITERATION or 0)
timeout,,number,,Seconds before the request expires
poll,,number,3,Poll interval in seconds while blocking
- name: alerts
purpose: List and manage durable alert instances
args[2]{name,type,required,desc}:
action,string,true,list|ack|resolve|silence
alertId,string,false,Alert ID for ack/resolve/silence
- name: approve
purpose: Approve a paused approval gate; auto-detects the node if only one is pending
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[4]{name,short,type,default,desc}:
node,n,string,,Node ID required if multiple approvals are pending
iteration,,number,0,Loop iteration
note,,string,,Approval note
by,,string,,Approver identifier
- name: deny
purpose: Deny a paused approval gate
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[4]{name,short,type,default,desc}:
node,n,string,,Node ID required if multiple approvals are pending
iteration,,number,0,Loop iteration
note,,string,,Denial note
by,,string,,Denier identifier
- name: signal
purpose: Deliver a durable signal to a run waiting on Signal or WaitForEvent
args[2]{name,type,required,desc}:
runId,string,true,Run ID
signalName,string,true,Signal name
flags[3]{name,short,type,default,desc}:
data,,string,,Signal payload as JSON; defaults to {}
correlation,,string,,Correlation ID to match a specific waiter
by,,string,,Signal sender identifier
- name: cancel
purpose: Safely halt agents and terminate one active run
args[1]{name,type,required,desc}:
runId,string,true,Run ID
- name: pause
purpose: Gracefully pause a run; let in-flight tasks finish, then park it resumably
args[1]{name,type,required,desc}:
runId,string,true,Run ID
- name: down
purpose: Cancel all active runs in the current Smithers workspace
flags[1]{name,short,type,default,desc}:
force,,boolean,false,Cancel runs even if they still appear live; without this only stale runs are cancelled
- name: graph
purpose: Render the workflow graph without executing it
args[1]{name,type,required,desc}:
workflow,string,true,Workflow ID or file path
flags[3]{name,short,type,default,desc}:
run-id,r,string,graph,Run ID for context
input,,string,,Input JSON; overrides persisted input
root,,string,,Tool sandbox root directory (same anchor as up)
- name: gui
purpose: Open a directory as a workspace in Smithers UI
args[1]{name,type,required,desc}:
path,string,false,Directory path (defaults to current working directory)
flags[5]{name,short,type,default,desc}:
gateway,g,string,,Gateway base URL (default http://127.0.0.1:<port>)
port,,number,7331,Gateway port when --gateway is not set
workflow,w,string,,Open this workflow's UI directly skipping run lookup
open,,boolean,true,Open a browser; use --no-open to just print the URL
autostart,,boolean,true,Start a local Gateway automatically when no Gateway is reachable
- name: ui
purpose: Open the custom UI for a workflow run in your browser
args[1]{name,type,required,desc}:
runId,string,false,Run to open. Defaults to the most recent run.
flags[4]{name,short,type,default,desc}:
gateway,g,string,,Gateway base URL (default http://127.0.0.1:<port>)
port,,number,7331,Gateway port when --gateway is not set
workflow,w,string,,Open this workflow's UI directly skipping run lookup
open,,boolean,true,Open a browser; use --no-open to just print the URL
- name: revert
purpose: Revert the workspace to a previous task attempt's filesystem state
args[1]{name,type,required,desc}:
workflow,string,true,Workflow file path
flags[4]{name,short,type,default,desc}:
run-id,r,string,,Run ID
node-id,n,string,,Node ID
attempt,,number,1,Attempt number
iteration,,number,0,Loop iteration
- name: retry-task
purpose: Retry a specific task within a run, then resume the workflow
args[1]{name,type,required,desc}:
workflow,string,true,Workflow file path
flags[5]{name,short,type,default,desc}:
run-id,r,string,,Run ID
node-id,n,string,,Task/node ID to retry
iteration,,number,0,Loop iteration
no-deps,,boolean,false,Only reset this node; skip dependents
force,,boolean,false,Allow retry even if run is still running
- name: timetravel
purpose: Time-travel to a task state; revert filesystem, reset DB, optionally resume
args[1]{name,type,required,desc}:
workflow,string,true,Workflow file path
flags[8]{name,short,type,default,desc}:
run-id,r,string,,Run ID
node-id,n,string,,Task/node ID
iteration,,number,0,Loop iteration
attempt,a,number,,Attempt number; latest if omitted
no-vcs,,boolean,false,Skip filesystem revert; DB only
no-deps,,boolean,false,Only reset this node
resume,,boolean,false,Resume after time travel
force,,boolean,false,Force even if run is still running
- name: replay
purpose: Fork from a checkpoint and resume execution
args[1]{name,type,required,desc}:
workflow,string,true,Workflow file path
flags[6]{name,short,type,default,desc}:
run-id,r,string,,Source run ID
frame,f,number,,Frame number to fork from
node,n,string,,Node ID to reset to pending
input,i,string,,Input overrides as JSON
label,l,string,,Branch label for the fork
restore-vcs,,boolean,false,Restore jj filesystem state to source frame revision
- name: fork
purpose: Create a branched run from a snapshot checkpoint
args[1]{name,type,required,desc}:
workflow,string,true,Workflow file path
flags[6]{name,short,type,default,desc}:
run-id,r,string,,Source run ID
frame,f,number,,Frame number to fork from
reset-node,n,string,,Node ID to reset to pending
input,i,string,,Input overrides as JSON
label,l,string,,Branch label
run,,boolean,false,Immediately start the forked run
- name: timeline
purpose: View execution timeline for a run and its forks
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[2]{name,short,type,default,desc}:
tree,,boolean,false,Include all child forks recursively
json,j,boolean,false,Output as JSON
- name: tree
purpose: Print DevTools snapshot as an XML tree
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[6]{name,short,type,default,desc}:
frame,,number,,Historical frame number
watch,,boolean,false,Stream live DevTools events
json,j,boolean,false,Emit snapshot JSON
depth,,number,,Truncate depth
node,,string,,Scope to subtree
color,,enum,auto,auto|always|never
- name: diff
purpose: Print a node DiffBundle as unified diff
args[2]{name,type,required,desc}:
runId,string,true,Run ID containing the node
nodeId,string,true,Node ID to diff
flags[4]{name,short,type,default,desc}:
iteration,,number,,Loop iteration; latest if omitted
json,j,boolean,false,Emit raw DiffBundle
stat,,boolean,false,Show stat summary only
color,,enum,auto,auto|always|never
- name: output
purpose: Print a node output row
args[2]{name,type,required,desc}:
runId,string,true,Run ID containing the node
nodeId,string,true,Node ID to fetch output for
flags[3]{name,short,type,default,desc}:
iteration,,number,,Loop iteration; latest if omitted
json,j,boolean,true,Emit raw row as JSON
pretty,,boolean,false,Schema-ordered render
- name: packs
purpose: List and update installed workflow packs.
- name: packs.list
purpose: List local and global workflow packs.
- name: packs.update
purpose: Re-resolve installed packs from their locked specs (all packs when no name is given).
args[1]{name,type,required,desc}:
name,string,false,Pack name to update (default: every locked pack)
- name: remove
purpose: Remove an installed workflow pack.
args[1]{name,type,required,desc}:
name,string,true,Installed pack name
flags[1]{name,short,type,default,desc}:
global,,boolean,false,Remove from ~/.smithers/packs
- name: eject
purpose: Copy a pack workflow and its UI, prompts, and libraries into the local .smithers pack.
args[1]{name,type,required,desc}:
spec,string,true,Pack workflow in the form <pack>:<workflow>
- name: share
purpose: Add this project's workflow pack to awesome-smithers and open a pull request.
flags[2]{name,short,type,default,desc}:
repo,,string,,Override the awesome-smithers repository (owner/name)
dry-run,n,boolean,false,Print the registry entry and diff without pushing
- name: rewind
purpose: Rewind a run to a previous frame
args[2]{name,type,required,desc}:
runId,string,true,Run ID to rewind
frameNo,number,true,Target frame number
flags[2]{name,short,type,default,desc}:
yes,,boolean,false,Skip confirmation prompt
json,j,boolean,false,Emit JumpResult JSON
- name: snapshots
purpose: List durability snapshots (workspace checkpoints) for a run
args[1]{name,type,required,desc}:
runId,string,true,Run ID to list snapshots for
flags[1]{name,short,type,default,desc}:
json,j,boolean,false,Emit rows as JSON
- name: restore
purpose: Restore a worktree to a durability checkpoint (latest for the node, or --seq)
args[2]{name,type,required,desc}:
runId,string,true,Run ID containing the checkpoint
nodeId,string,true,Node ID whose worktree to restore
flags[2]{name,short,type,default,desc}:
iteration,,number,,Loop iteration
seq,,number,,Checkpoint seq; latest if omitted
- name: worktree.list
purpose: List every worktree Smithers created in this repository and the run that owns it
- name: worktree.prune
purpose: Remove the worktrees of runs that are over (finished, failed, or cancelled)
flags[4]{name,short,type,default,desc}:
run,,string,,Only prune worktrees owned by this run id
older-than,,string,,Only prune worktrees untouched for at least this long e.g. 24h
dry-run,,boolean,false,Report what would be removed without removing anything
force,,boolean,false,Also remove worktrees holding uncommitted or unpushed work
- name: snapshot-hook
purpose: "Internal: PostToolUse hook that requests a Tier 1 durability snapshot"
- name: observability
purpose: Start or stop the local Docker Compose observability stack
flags[2]{name,short,type,default,desc}:
detach,d,boolean,false,Run containers in the background
down,,boolean,false,Stop and remove the stack
- name: ask
purpose: Ask a question about Smithers using an installed agent and the Smithers MCP server
args[1]{name,type,required,desc}:
question,string,false,Question to ask
flags[6]{name,short,type,default,desc}:
agent,,enum,,claude|codex|antigravity|kimi|pi
list-agents,,boolean,false,List detected agents and exit
dump-prompt,,boolean,false,Print generated system prompt and exit
tool-surface,,enum,semantic,semantic|raw
no-mcp,,boolean,false,Disable MCP bootstrap and use prompt fallback
print-bootstrap,,boolean,false,Print selected bootstrap configuration and exit
- name: scores
purpose: View scorer results for a specific run
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[1]{name,short,type,default,desc}:
node,,string,,Filter scores to a specific node ID
- name: usage
purpose: Show how much rate limit or subscription quota each registered account has used
flags[3]{name,short,type,default,desc}:
account,,string,,Only report this account label
provider,,string,,Only report accounts for this provider
fresh,,boolean,false,Bypass the short usage cache while respecting provider rate-limit floors
- name: docs
purpose: Print llms.txt for this CLI version
flags[2]{name,short,type,default,desc}:
latest,,boolean,false,Fetch the latest docs from smithers.sh instead of docs for this CLI version
docs-version,,string,,Fetch docs for a specific Smithers version, e.g. 0.22.0 or v0.22.0
- name: docs-full
purpose: Print llms-full.txt for this CLI version
flags[2]{name,short,type,default,desc}:
latest,,boolean,false,Fetch the latest docs from smithers.sh instead of docs for this CLI version
docs-version,,string,,Fetch docs for a specific Smithers version, e.g. 0.22.0 or v0.22.0
- name: update
purpose: Check for a newer Smithers release and upgrade the install (or print how). Workflow packs update via `packs update`.
flags[2]{name,short,type,default,desc}:
check,,boolean,false,Only report current vs latest version; never upgrade
dry-run,,boolean,false,Print the upgrade command without running it
- name: upgrade
purpose: "Run the agent-assisted Smithers upgrade workflow: fetch changelogs, upgrade with a cheap agent, and escalate to a smart agent only when needed."
flags[8]{name,short,type,default,desc}:
interactive,,boolean,false,Force the full-screen interactive TUI monitor (TTY only).
detach,d,boolean,false,Launch the upgrade workflow in the background and print the run ID.
dry-run,,boolean,false,Fetch changelogs and plan the upgrade without changing the install.
run-id,,string,,Explicit run ID for the upgrade workflow.
root,,string,,Tool sandbox root directory.
log-dir,,string,,NDJSON event logs directory.
backend,,enum,,"sqlite|pglite|postgres"
auth-token,,string,,Bearer token passed to the interactive monitor gateway client.
- name: agents.capabilities
purpose: Print JSON capability registry for built-in CLI agents
- name: agents.doctor
purpose: Validate built-in CLI agent capability registries and command-surface contracts
flags[1]{name,short,type,default,desc}:
json,,boolean,false,Print doctor report as JSON
- name: agents.add
purpose: Register a Smithers agent account, interactively or with flags
flags[9]{name,short,type,default,desc}:
provider,,enum,,"claude-code|antigravity|codex|kimi|anthropic-api|openai-api|gemini-api"
label,,string,,Unique account label
config-dir,,string,,Per-account CLI config dir for subscription providers
api-key,,string,,API key for API-key providers
model,,string,,Default model for this account
skip-login,,boolean,false,Skip credential-directory check
force,,boolean,false,Register even if no credentials are present
replace,,boolean,false,Overwrite an existing account with the same label
loop,,boolean,false,Wizard mode; keep adding accounts until done
- name: agents.list
purpose: List registered Smithers agent accounts
- name: agents.remove
purpose: Remove a registered agent account by label
args[1]{name,type,required,desc}:
label,string,true,Account label
flags[1]{name,short,type,default,desc}:
silent,,boolean,false,Do not error if the label is not registered
- name: agents.test
purpose: Spawn an account's underlying CLI with --version
args[1]{name,type,required,desc}:
label,string,true,Account label
- name: workflow.list
purpose: List discovered workflows (local .smithers/workflows/ plus the global ~/.smithers/workflows/; each entry reports its scope, local shadows global)
- name: workflow.run
purpose: Run a discovered workflow by ID
args[1]{name,type,required,desc}:
name,string,false,Workflow ID (omit with --interactive to pick one)
flags[37]{name,short,type,default,desc}:
detach,d,boolean,false,Background mode; print runId/pid/logFile and exit
run-id,r,string,,Explicit run ID
max-concurrency,c,number,4,Maximum parallel tasks
root,,string,,Tool sandbox root directory
log,,boolean,true,Enable NDJSON event log file output
log-dir,,string,,NDJSON event logs directory
allow-network,,boolean,false,Allow bash tool network requests
max-output-bytes,,number,,Max bytes a single tool call can return
tool-timeout-ms,,number,,Max wall-clock time per tool call in ms
hot,,boolean,false,Hot reload for .tsx workflows
input,i,string,,Input data as JSON string or '-' to read JSON from stdin
annotations,,string,,Run annotations as flat JSON string/number/boolean object or '-' to read JSON from stdin
resume,,boolean|string,false,Resume an existing run; may be true or a run ID
force,,boolean,false,Resume even if still marked running
parent-run-id,,string,,Existing run ID to record as this run's parent (persisted lineage, surfaced by inspect/ps and the MCP run tools)
accept-workflow-change,,boolean,false,Resume this run after its workflow source changed, re-blessing durability metadata in place; you own replay determinism
resume-claim-owner,,string,,Internal durable resume claim owner
resume-claim-heartbeat,,number,,Internal durable resume claim heartbeat
resume-restore-owner,,string,,Internal durable resume restore owner
resume-restore-heartbeat,,number,,Internal durable resume restore heartbeat
serve,,boolean,false,Start an HTTP server alongside the workflow
supervise,,boolean,false,Run stale-run supervisor loop with --serve
supervise-dry-run,,boolean,false,With --supervise; detect without resuming
supervise-interval,,string,10s,Supervisor poll interval
supervise-stale-threshold,,string,30s,Heartbeat staleness threshold
supervise-max-concurrent,,number,3,Max runs resumed per poll
port,,number,7331,HTTP server port when --serve
host,,string,127.0.0.1,HTTP bind address when --serve
auth-token,,string,,Bearer token for HTTP auth or SMITHERS_API_KEY env
insecure,,boolean,false,Allow binding a non-loopback --host with NO auth (exposes unauthenticated approve/deny/cancel control of the run; dangerous)
metrics,,boolean,true,Expose /metrics Prometheus endpoint when --serve
backend,,enum,,Bootstrap storage selection for a workflow owner or workspace Gateway; not a run-discovery/control flag (sqlite|pglite|postgres)
post-failure,,boolean,true,Auto-launch the post-failure autopsy workflow when this run fails (disable with --no-post-failure or SMITHERS_POST_FAILURE=0)
verbose,,boolean,false,Show engine info logs on interactive runs; the default keeps progress + warnings only (non-TTY/structured output always gets full logs)
report,,boolean,true,Narrate an interactive run's result with a cheap/fast agent and open an HTML summary in the browser (disable with --no-report or SMITHERS_NO_REPORT=1)
prompt,p,string,,Shorthand for input.prompt when --input is omitted
interactive,,boolean,false,Pick a workflow and inputs interactively then open the full-screen run monitor (no silent fallback: fails with TUI_MONITOR_UNAVAILABLE if the tui package is missing, leaving the detached run running)
- name: workflow.path
purpose: Resolve a workflow ID to its entry file path
args[1]{name,type,required,desc}:
name,string,true,Workflow ID
- name: workflow.inspect
purpose: Show workflow metadata and an agent-facing skill preview
args[1]{name,type,required,desc}:
name,string,true,Workflow ID
- name: workflow.create
purpose: Create a new flat workflow scaffold in .smithers/workflows/ (or ~/.smithers with --global)
args[1]{name,type,required,desc}:
name,string,true,New workflow ID
flags[1]{name,short,type,default,desc}:
global,,boolean,false,Create in the global ~/.smithers pack (honors SMITHERS_HOME) instead of the local .smithers
- name: workflow.skills
purpose: Generate agent-facing skill docs for discovered workflows
args[1]{name,type,required,desc}:
name,string,false,Workflow ID; omit for all workflows
flags[3]{name,short,type,default,desc}:
output,,string,,Output file for one workflow, or output directory for all
force,,boolean,false,Overwrite existing skill files
global,,boolean,false,Write skills into the global ~/.smithers pack instead of the local .smithers
- name: workflow.doctor
purpose: Inspect workflow discovery, preload files, bunfig, and detected agents
args[1]{name,type,required,desc}:
name,string,false,Workflow ID; omit for all
- name: claude.tick
purpose: One /workflows mirror frame for a run (Claude Code plugin protocol, contract v1); --wait blocks until a mirror-relevant event lands after --after-seq; also subscribes the session's claude monitor to the run
args[1]{name,type,required,desc}:
runId,string,true,Run ID to mirror
flags[6]{name,short,type,default,desc}:
after-seq,,number,0,Event-log cursor from the previous tick's seq
wait,,boolean,false,Block until a mirror-relevant event lands after --after-seq (or timeout)
timeout-ms,,number,420000,Max wait in ms before returning timedOut true
interval-ms,,number,750,Wait poll interval in ms
max-output-chars,,number,2000,Truncate node outputs to this many chars
collapse-phases,,boolean,false,Collapse the phase plan to a single phase
- name: claude.node-wait
purpose: Block until one node reaches a terminal state, then print its final state and output (returns timedOut true on expiry; re-invoke to keep waiting)
args[1]{name,type,required,desc}:
nodeId,string,true,Node ID to wait on
flags[5]{name,short,type,default,desc}:
run-id,,string,,Run ID that owns the node
iteration,i,number,,Loop iteration (default latest)
timeout-ms,,number,480000,Max wait in ms before returning timedOut true
interval-ms,,number,1000,Poll interval in ms
max-output-chars,,number,2000,Truncate the node output to this many chars
- name: claude.monitor
purpose: Follow the runs this session subscribed to (claude tick / claude subscribe) and print one NDJSON line per actionable transition (approval pending, human request, failed, stalled); --transitions all adds finished/cancelled/continued, --all-runs follows every run in the workspace; backs the plugin's background monitor
flags[5]{name,short,type,default,desc}:
interval-ms,,number,2000,Poll interval in ms
stalled-after-ms,,number,120000,Heartbeat age that flags a running run as stalled
ticks,,number,,Stop after N polls (default run until killed)
transitions,,string,actionable,Which transitions stream: actionable or all
all-runs,,boolean,false,Follow every run in the workspace instead of only this session's subscriptions
- name: claude.subscribe
purpose: Subscribe this session's background monitor to a run (done automatically by claude tick and Claude-launched runs); the monitor only notifies about subscribed runs
args[1]{name,type,required,desc}:
runId,string,true,Run ID the session's monitor should follow
- name: claude.unsubscribe
purpose: Stop this session's background monitor from following a run (outside a Claude Code session it drops the run for every session)
args[1]{name,type,required,desc}:
runId,string,true,Run ID the session's monitor should stop following
- name: cron.start
purpose: Start the background scheduler loop in the current terminal
- name: cron.add
purpose: Register a new workflow cron schedule
args[2]{name,type,required,desc}:
pattern,string,true,Cron expression
workflowPath,string,true,Path or ID of workflow to schedule
- name: cron.list
purpose: List registered background cron schedules
- name: cron.rm
purpose: Delete a cron schedule by ID
args[1]{name,type,required,desc}:
cronId,string,true,Cron ID
- name: memory.list
purpose: List all memory facts in a namespace
args[1]{name,type,required,desc}:
namespace,string,true,Namespace such as workflow:my-flow
flags[1]{name,short,type,default,desc}:
workflow,w,string,,Path to workflow file that locates the DB
- name: memory.get
purpose: Get a single memory fact by namespace and key
args[2]{name,type,required,desc}:
namespace,string,true,Namespace such as workflow:my-flow
key,string,true,Fact key
flags[1]{name,short,type,default,desc}:
workflow,w,string,,Path to workflow file that locates the DB
- name: memory.set
purpose: Set a memory fact (value stored verbatim as the fact's JSON value)
args[3]{name,type,required,desc}:
namespace,string,true,Namespace such as workflow:my-flow
key,string,true,Fact key
value,string,true,Fact value stored as-is
flags[2]{name,short,type,default,desc}:
workflow,w,string,,Path to workflow file that locates the DB
ttl,,number,,Time-to-live in milliseconds
- name: memory.rm
purpose: Delete a memory fact by namespace and key
args[2]{name,type,required,desc}:
namespace,string,true,Namespace such as workflow:my-flow
key,string,true,Fact key
flags[1]{name,short,type,default,desc}:
workflow,w,string,,Path to workflow file that locates the DB
- name: openapi.list
purpose: Preview tools generated from an OpenAPI spec
args[1]{name,type,required,desc}:
specPath,string,true,File path or URL to OpenAPI spec
- name: openapi.generate
purpose: Generate an AI SDK tools module from an OpenAPI spec
args[2]{name,type,required,desc}:
specPath,string,true,File path to OpenAPI spec
outputPath,string,true,Output JavaScript file for generated tools
- name: token.issue
purpose: Issue a local short-lived Gateway bearer token grant
flags[6]{name,short,type,default,desc}:
scopes,,string,run:read,Comma or space separated Gateway scopes
role,,string,operator,Role recorded on the token grant
user-id,,string,,User ID recorded on the token grant
ttl,,string,1h,Token lifetime such as 15m or 1h
action-id,,string,gateway,Action id allowed to resolve the brokered action token
reveal-token,,boolean,false,Include the raw bearer token in CLI output
- name: token.exec
purpose: Resolve an action token locally and inject the bearer into a child process environment
flags[5]{name,short,type,default,desc}:
handle,,string,,Brokered action token handle
action-id,,string,gateway,Action id expected by the brokered token
scopes,,string,,Comma or space separated scopes required for this action
env,,string,SMITHERS_API_KEY,Environment variable that receives the bearer token
command,,string,,Shell command to run with the injected token
- name: token.revoke
purpose: Revoke a locally issued Gateway bearer token
args[1]{name,type,required,desc}:
token,string,true,Bearer token to revoke
- name: completions
purpose: Generate shell completion scripts
args[1]{name,type,required,desc}:
shell,string,true,bash|fish|nushell|zsh
- name: mcp.add
purpose: Register Smithers as an MCP server for an agent integration
flags[3]{name,short,type,default,desc}:
agent,,string,,Target agent such as claude-code or cursor
command,c,string,,Override the command agents will run
no-global,,boolean,false,Install to project instead of globally
- name: skills.add
purpose: Sync skill files to agent integrations
flags[2]{name,short,type,default,desc}:
depth,,number,1,Grouping depth for skill files
no-global,,boolean,false,Install to project instead of globally
- name: skills.list
purpose: List available skills
