commands[114]:
- 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,g,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[39]{name,short,type,default,desc}:
detach,d,boolean,false,Background mode; preflight the graph, then print runId/pid/logFile once the run is admitted
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
steal-ownership,,boolean,false,Take over a run whose driver is still alive (live owner PID; heartbeating remote owner; or held resume claim). Two engines on one run split-brain its scheduling; --force does NOT grant this
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)
monitor,,boolean|string,true,Monitor workflow that watches this run as a sibling; auto-discovers .smithers/monitor/<workflowId>.tsx (no-op when absent). Pass a path to pick one; --no-monitor opts out
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[41]{name,short,type,default,desc}:
detach,d,boolean,false,Background mode; preflight the graph, then print runId/pid/logFile once the run is admitted
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
steal-ownership,,boolean,false,Take over a run whose driver is still alive (live owner PID; heartbeating remote owner; or held resume claim). Two engines on one run split-brain its scheduling; --force does NOT grant this
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)
monitor,,boolean|string,true,Monitor workflow that watches this run as a sibling; auto-discovers .smithers/monitor/<workflowId>.tsx (no-op when absent). Pass a path to pick one; --no-monitor opts out
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)
started-by-harness,,string,,Durable self-reported launch harness; environment may fill when omitted
started-by-session,,string,,Durable self-reported harness session; environment may fill when omitted
started-by-prompt,,string,,Explicit durable launch context; never inferred from workflow input
herdr,,boolean|string,,Mirror this run into a herdr terminal workspace (one pane per agent node); optionally =SESSION for a named session
- 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: supervisor
purpose: Workflow supervisor live outline of phases and agents; sources through the workspace gateway by default (start-or-attach with a silent fallback to direct smithers.db reads) and doubles as the herdr cockpit right pane. j/k select, Enter opens a detail tab in herdr, [ ] switch runs, f follow live, q quit
flags[5]{name,short,type,default,desc}:
db,,string,,Path to smithers.db (default: discover from cwd)
cwd,,string,,Project directory for DB discovery (default: process.cwd())
interval,i,number,0.5,Poll interval in seconds
gateway,g,string,,Source through a workspace gateway over RPC: a base URL to attach (hard-fails if unreachable) or auto to start-or-attach; default with no flag is auto with a silent fallback to direct-db
direct,,boolean,false,Force direct smithers.db reads and bypass the gateway (escape hatch for a broken gateway)
- name: top
purpose: Alias for smithers supervisor (workflow supervisor)
- 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[10]{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)
kill-runs,,boolean,false,With gateway stop cancel gateway-hosted runs instead of parking them for resume
apply-listeners,,boolean,false,Apply declared listener creates and updates on boot and registry changes (otherwise plan only)
delete-listeners,,boolean,false,Also delete owned hooks removed from the registry; requires --apply-listeners
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: listeners
purpose: Plan or explicitly apply the .smithers/listeners.json GitHub webhook declaration
args[1]{name,type,required,desc}:
action,enum,false,Plan by default; use apply to mutate GitHub
flags[1]{name,short,type,default,desc}:
delete,,boolean,false,With apply delete owned hooks removed from the registry
- name: monitor
purpose: Open the Smithers Monitor. A built-in oneshot opens its dedicated live transcript, honest steering delivery, restart, and attachment-scoped cheap narrator controls. Other runs use the all-runs workspace view. 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; built-in oneshots open their dedicated monitor
flags[6]{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
host,,string,,Gateway bind host when autostarting (or SMITHERS_GATEWAY_HOST); use 0.0.0.0 for Tailscale/LAN access; a bearer token is minted automatically for non-loopback binds
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,,Follow a live run to completion; default follows only when stdout is a TTY (pipes/redirects snapshot and exit); -f forces follow and --no-follow forces snapshot
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[9]{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 from the live cursor
interval,i,number,2,Watch poll seconds
history,,boolean,false,Replay existing history before tailing in watch mode
- name: tail
purpose: "Tail a run's output: verbatim node output with --node, or a concise run-level event overview"
args[1]{name,type,required,desc}:
runId,string,true,Run ID
flags[5]{name,short,type,default,desc}:
node,n,string,,Filter to a single node and print its output verbatim
follow,f,boolean,true,Poll for new events until the run reaches a terminal state
format,,enum,pretty,pretty|jsonl
linger,,boolean,false,After the run is terminal stay open until q/Enter or Ctrl-C (herdr panes pass this)
overview,,boolean,false,Run-level supervision board (per-node state + attempt, approve/steer CTAs, queue summary) above the event scroll
- 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[5]{name,short,type,default,desc}:
agent,,enum,,claude-code|codex|antigravity|pi|omp|kimi|amp
cwd,,string,.,Working directory for the chat session
started-by-harness,,string,,Durable self-reported launch harness
started-by-session,,string,,Durable self-reported harness session
started-by-prompt,,string,,Explicit durable launch context
- 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[15]{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
preflight,,enum,auto,Dirty-working-copy preflight (auto|warn|off)
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
started-by-harness,,string,,Durable self-reported launch harness
started-by-session,,string,,Durable self-reported harness session
started-by-prompt,,string,,Explicit durable launch context; never inferred from the goal
- 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: steer
purpose: "Steer a running workflow in one step: with a message, queue a durable steer for the target node's next agent step (the run never stops); with --takeover, hand off the live agent session (a run-wide hijack that warns before aborting in-flight siblings); bare steer auto-picks the single active run"
args[2]{name,type,required,desc}:
runId,string,false,Run ID; auto-picks the single active run (or prompts) if omitted
message,string,false,Steer message to queue for the target node's next agent step (prompts if omitted and not --takeover)
flags[5]{name,short,type,default,desc}:
node,n,string,,Node id to steer (default: the run's current in-flight agent node)
takeover,t,boolean,false,Hijack the live agent session instead of queuing a steer (run-wide; warns before aborting in-flight siblings)
yes,y,boolean,false,Skip the takeover confirmation prompt (answer yes)
timeout-ms,,number,30000,Wait time for live handoff (takeover)
session,,string,,herdr session hosting the mirror (auto-detected from the pane env by default)
- 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[5]{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
watch,,boolean,false,Interactively answer each approval gate and human request by keystroke as it appears then linger until the run ends (herdr gate panes)
- 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: gc
purpose: Report disk use and reclaim stale Smithers logs, sandboxes, worktrees, and campaign scratch
flags[4]{name,short,type,default,desc}:
older-than,,string,7d,Only reclaim artifacts unused for at least this long e.g. 24h
dry-run,,boolean,false,Report what would be removed without removing anything
include-unmanaged,,boolean,false,Also reclaim recognized legacy campaign worktrees and temp artifacts after safety checks
force,,boolean,false,Also remove owned worktrees holding uncommitted or unpushed work
- 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[6]{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
host,,string,,Gateway bind host when autostarting (or SMITHERS_GATEWAY_HOST); use 0.0.0.0 for Tailscale/LAN access; a bearer token is minted automatically for non-loopback binds
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[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
host,,string,,Gateway bind host when autostarting (or SMITHERS_GATEWAY_HOST); use 0.0.0.0 for Tailscale/LAN access; a bearer token is minted automatically for non-loopback binds
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[6]{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
force,,boolean,false,Cross unresolved effects and mark the run needs-attention
revert,,boolean,true,Run compensation handlers; use --no-revert to skip
- 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[7]{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
steal-ownership,,boolean,false,Retry and resume even though the run still has a live driver; --force does NOT grant this
accept-workflow-change,,boolean,false,Resume this run after its workflow source changed, re-blessing durability metadata in place; you own replay determinism
- 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[10]{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
steal-ownership,,boolean,false,Time-travel (and --resume) even though the run still has a live driver; --force does NOT grant this
revert,,boolean,true,Run compensation handlers; use --no-revert to skip
- name: replay
purpose: Fork from a checkpoint and resume execution
args[1]{name,type,required,desc}:
workflow,string,true,Workflow file path
flags[7]{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 (comma-separate ids; dependents are not reset for you)
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
force,,boolean,false,Cross unresolved effects and mark the parent needs-attention
- name: fork
purpose: Create a branched run from a snapshot checkpoint
args[1]{name,type,required,desc}:
workflow,string,true,Workflow file path
flags[7]{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 (comma-separate ids; dependents are not reset for you)
input,i,string,,Input overrides as JSON
label,l,string,,Branch label
run,,boolean,false,Immediately start the forked run
force,,boolean,false,Allow --run to cross unresolved external effects
- 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[4]{name,short,type,default,desc}:
yes,,boolean,false,Skip confirmation prompt
json,j,boolean,false,Emit JumpResult JSON
force,,boolean,false,Cross unresolved effects and mark the run needs-attention
revert,,boolean,true,Run compensation handlers; use --no-revert to skip
- name: snapshots
purpose: List durability snapshots (workspace checkpoints) for a run and its descendant child runs
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 and invalidate child work newer than it
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 owned worktrees and legacy worktrees registered under Smithers' hidden campaign directories
- name: worktree.prune
purpose: Remove the worktrees of runs that are over (finished, failed, or cancelled)
flags[5]{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
include-unmanaged,,boolean,false,Also remove stale hidden campaign worktrees without owner metadata when clean and published
- 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: claude-shell
purpose: Launch Claude Code with the registered account that has the most quota headroom
flags[2]{name,short,type,default,desc}:
label,,string,,Pin one registered Claude account
dry-run,,boolean,false,Print the selected account without launching Claude
- 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.reauth
purpose: Check and sequentially reauthenticate registered Claude accounts in the browser
flags[4]{name,short,type,default,desc}:
provider,,enum,claude-code,Account provider to reauthenticate
label,,string,,Only reauthenticate this account label
force,,boolean,false,Reauthenticate even when the current login is live
include-default,,boolean,false,Also check the ambient ~/.claude login
- 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[43]{name,short,type,default,desc}:
detach,d,boolean,false,Background mode; preflight the graph, then print runId/pid/logFile once the run is admitted
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
steal-ownership,,boolean,false,Take over a run whose driver is still alive (live owner PID; heartbeating remote owner; or held resume claim). Two engines on one run split-brain its scheduling; --force does NOT grant this
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)
monitor,,boolean|string,true,Monitor workflow that watches this run as a sibling; auto-discovers .smithers/monitor/<workflowId>.tsx (no-op when absent). Pass a path to pick one; --no-monitor opts out
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)
started-by-harness,,string,,Durable self-reported launch harness; environment may fill when omitted
started-by-session,,string,,Durable self-reported harness session; environment may fill when omitted
started-by-prompt,,string,,Explicit durable launch context; never inferred from workflow input
herdr,,boolean|string,,Mirror this run into a herdr terminal workspace (one pane per agent node); optionally =SESSION for a named session
- 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, node retry churn), plus a periodic run-progress digest whenever a followed run has been silent for a full window; --transitions all adds finished/cancelled/continued, --all-runs follows every run in the workspace; backs the plugin's background monitor
flags[7]{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
retry-alert-attempt,,number,3,Active-attempt number that flags a node as retry-churning (0 disables)
progress-every-ms,,number,1800000,Emit a run-progress digest after this long without any notification for a followed run (0 disables)
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
- name: herdr.status
purpose: Ping the herdr server and report its version, protocol, and client compatibility
flags[1]{name,short,type,default,desc}:
session,,string,,Target a named herdr session's socket
- name: herdr.attach
purpose: Mirror an existing run into a herdr workspace and follow its status until the run ends or Ctrl-C
args[1]{name,type,required,desc}:
runId,string,true,Run ID to mirror into herdr
flags[1]{name,short,type,default,desc}:
session,,string,,Target a named herdr session's socket
- name: herdr.open
purpose: "Open (or re-open) an on-demand herdr pane for a run: a node's lingering output tail, or the run-level overview when no node is given; adopts an existing pane instead of duplicating it"
args[2]{name,type,required,desc}:
runId,string,true,Run ID whose workspace to open a pane in
nodeId,string,false,Node ID to open a tail pane for (omit for the run-level overview pane)
flags[1]{name,short,type,default,desc}:
session,,string,,Target a named herdr session's socket
- name: herdr.clean
purpose: Close herdr workspaces that mirror a smithers run whose run is terminal in the DB; never touches workspaces that do not map to a known run, and leaves active runs open
flags[1]{name,short,type,default,desc}:
session,,string,,Target a named herdr session's socket
