CLI Reference - Smithers

bunx smithers-orchestrator <command> [options]

The CLI is the operational surface for Smithers. JSX defines the workflow. The CLI is how you launch it, inspect it, answer approvals, recover from interruption, and understand why it is blocked.

Start With These Commands

Goal	Command
Install the local workflow pack	`bunx smithers-orchestrator init`
Launch a workflow file	`bunx smithers-orchestrator up workflow.tsx --input '{"task":"..."}'`
Launch a discovered pack workflow	`bunx smithers-orchestrator workflow implement --prompt "..."`
List recent and active runs	`bunx smithers-orchestrator ps`
Inspect one run deeply	`bunx smithers-orchestrator inspect <runId>`
Read event logs	`bunx smithers-orchestrator logs <runId>`
Read agent prompts and replies	`bunx smithers-orchestrator chat <runId>`
Approve or deny a pause	`bunx smithers-orchestrator approve <runId>` / `bunx smithers-orchestrator deny <runId>`
Resume after interruption	`bunx smithers-orchestrator up workflow.tsx --run-id <runId> --resume true`

How the CLI Fits With JSX

JSX is the authoring model.
The CLI is the operations model.
Both talk to the same runtime and the same persisted run state.

If you are new to Smithers, read CLI Quickstart before using this page as a full reference.

Command Map

Command	Purpose
`init`	Install a local `.smithers/` workflow pack.
`up`	Start or resume a workflow execution.
`tui`	Open the interactive Smithers observability dashboard.
`ps`	List active, paused, and recently completed runs.
`logs`	Stream lifecycle events for a run.
`chat`	Show agent prompts, responses, and stderr.
`inspect`	Print structured run state, steps, approvals, and loop info.
`node`	Show enriched node details for debugging retries, tool calls, and output.
`events`	Query run event history with filters, grouping, and NDJSON output.
`why`	Explain why a run is currently blocked or paused.
`approve` / `deny`	Record a decision for a pending approval gate.
`signal`	Deliver external data to a waiting signal node.
`supervise`	Watch for stale runs and auto-resume them.
`cancel` / `down`	Stop one run or all active runs.
`hijack`	Hand off an agent session or conversation.
`alerts`	List, acknowledge, resolve, or silence durable alerts.
`graph`	Render a workflow tree without executing.
`revert`	Restore workspace to a previous task attempt snapshot.
`retry-task`	Retry a specific task within a run, then resume.
`timetravel`	Revert to a previous task state with filesystem + DB reset.
`replay`	Fork from a checkpoint and resume execution (time travel).
`diff`	Compare two time-travel snapshots.
`fork`	Create a branched run from a snapshot checkpoint.
`timeline`	View execution timeline for a run and its forks.
`scores`	View scorer results for a run.
`observability`	Start or stop the local Grafana/Prometheus/Tempo stack.
`ask`	Query an installed agent CLI via MCP.
`human`	List and resolve durable human requests from a `<HumanTask>` node.
`agents`	Inspect built-in CLI agent capability registries and validate metadata.
`memory`	View and query cross-run memory facts.
`rag`	Ingest documents and query the RAG knowledge base.
`openapi`	Preview AI SDK tools generated from an OpenAPI spec.
`workflow`	Discover, create, resolve, and run flat workflows in `.smithers/workflows`.
`cron`	Register and run background schedule triggers.
`completions`	Generate shell completion scripts.
`mcp add`	Register Smithers as an MCP server for an agent integration.
`skills`	Sync skill files to agent integrations.

Resolution Rules

Workflow paths and IDs

up, graph, and revert take explicit workflow file paths:

bunx smithers-orchestrator up workflow.tsx --input '{"topic":"Zig"}'
bunx smithers-orchestrator graph workflow.tsx
bunx smithers-orchestrator revert workflow.tsx --run-id run-123 --node-id analyze

A workflow file can be invoked directly without up:

bunx smithers-orchestrator workflow.tsx --input '{"topic":"Zig"}'

The workflow command family resolves IDs under .smithers/workflows/*.tsx:

bunx smithers-orchestrator workflow implement --prompt "Add input validation"
bunx smithers-orchestrator workflow run implement --prompt "Add input validation"

bunx smithers-orchestrator workflow run <name> is a real subcommand. bunx smithers-orchestrator workflow <name> is a shorthand that rewrites to it.

Finding persisted state

Commands that operate on existing runs locate the nearest smithers.db by walking upward from the working directory: ps, logs, events, chat, inspect, node, why, scores, approve, deny, signal, cancel, down, supervise, diff, timeline, workflow doctor, cron start, cron list, cron rm No database found: exit with error.

Boolean options

Boolean flags accept either bare form or explicit true / false. Use false to disable a default-on option:

bunx smithers-orchestrator logs run-123 --follow false
bunx smithers-orchestrator chat run-123 --stderr false
bunx smithers-orchestrator hijack run-123 --launch false
bunx smithers-orchestrator up workflow.tsx --log false
bunx smithers-orchestrator observability --down true

Commands

init

Install the local workflow pack into .smithers/.

bunx smithers-orchestrator init [options]

Option	Description
`--force <boolean>`	Overwrite existing scaffold files. Default: `false`. The help output shows this as a bare boolean flag.

Generated pack contents:

.smithers/workflows/ — seeded workflows (implement, review, plan, ticket, tickets, ralph, improve-test-coverage, test-first, debug)
.smithers/prompts/ — shared MDX prompt templates
.smithers/components/ — reusable workflow components
.smithers/agents.ts — agent configuration based on installed CLIs
.smithers/preload.ts, .smithers/bunfig.toml, package.json, tsconfig.json

bunx smithers-orchestrator init
bunx smithers-orchestrator workflow implement --prompt "Commit the new .smithers pack"

up

Start or resume a workflow execution.

bunx smithers-orchestrator up <workflow> [options]

Option	Description
`--detach`, `-d <boolean>`	Background mode; print `runId`/`pid`/`logFile` and exit. Default: `false`.
`--run-id`, `-r <string>`	Explicit run ID.
`--max-concurrency`, `-c <number>`	Maximum parallel tasks. Default: `4`.
`--root <string>`	Tool sandbox root. Default: workflow file’s parent directory.
`--log <boolean>`	NDJSON event log output. Default: `true`.
`--log-dir <string>`	NDJSON log directory.
`--allow-network <boolean>`	Allow `bash` tool network access. Does not affect CLI-backed agents.
`--max-output-bytes <number>`	Max bytes per tool call return.
`--tool-timeout-ms <number>`	Max wall-clock time per tool call.
`--hot <boolean>`	Hot reload for `.tsx` workflows. Default: `false`.
`--input`, `-i <string>`	Input JSON string.
`--resume <boolean>`	Resume existing run. Default: `false`.
`--force <boolean>`	Resume even if run is marked `running`. Default: `false`.
`--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>`	Start an HTTP server alongside the workflow. Default: `false`.
`--port <number>`	HTTP server port when `--serve true`. Default: `7331`.
`--host <string>`	HTTP bind address when `--serve true`. Default: `127.0.0.1`.
`--auth-token <string>`	Bearer token for HTTP auth. Can also be provided through `SMITHERS_API_KEY`.
`--metrics <boolean>`	Expose `/metrics` Prometheus endpoint when `--serve true`. Default: `true`.
`--supervise <boolean>`	Run the stale-run supervisor loop (with `--serve`). Default: `false`.
`--supervise-dry-run <boolean>`	With `--supervise`, detect stale runs without resuming. Default: `false`.
`--supervise-interval <string>`	With `--supervise`, poll interval (e.g. `10s`, `30s`). Default: `"10s"`.
`--supervise-stale-threshold <string>`	With `--supervise`, stale heartbeat threshold. Default: `"30s"`.
`--supervise-max-concurrent <number>`	With `--supervise`, max runs resumed per poll. Default: `3`.

bunx smithers-orchestrator up workflow.tsx --input '{"description":"Fix auth bug"}'
bunx smithers-orchestrator up workflow.tsx --run-id run-123 --resume true
bunx smithers-orchestrator up workflow.tsx --run-id run-123 --resume true --force true
bunx smithers-orchestrator up workflow.tsx --detach --input '{"description":"Deploy v2"}'
bunx smithers-orchestrator up workflow.tsx --serve --port 8080 --auth-token secret
bunx smithers-orchestrator workflow.tsx --input '{"description":"Direct file shorthand"}'

Detached mode redirects stdout/stderr to a log file regardless of NDJSON logging settings.
Exits with code 3 when the workflow pauses in waiting-approval.
Serve mode starts the HTTP app and keeps the process alive until interrupted.

tui

Open the interactive Smithers observability dashboard for the nearest smithers.db.

bunx smithers-orchestrator tui

There are no command-specific flags in the current help output. See the TUI guide for the current keyboard model and feature reference.

ps

List active, paused, and recent runs.

bunx smithers-orchestrator ps [options]

Option	Description
`--status`, `-s <string>`	Filter: `running`, `waiting-approval`, `waiting-event`, `waiting-timer`, `continued`, `finished`, `failed`, `cancelled`.
`--limit`, `-l <number>`	Max rows. Default: `20`.
`--all`, `-a <boolean>`	Include all statuses.
`--watch`, `-w <boolean>`	Watch mode: refresh output continuously. Default: `false`.
`--interval`, `-i <number>`	Watch refresh interval in seconds. Default: `2`.

bunx smithers-orchestrator ps
bunx smithers-orchestrator ps --status waiting-approval
bunx smithers-orchestrator ps --limit 50
bunx smithers-orchestrator ps --watch --interval 5

logs

Tail lifecycle events for a run.

bunx smithers-orchestrator logs <runId> [options]

Option	Description
`--follow`, `-f <boolean>`	Poll for new events while run is active. Default: `true`.
`--follow-ancestry <boolean>`	Include events from parent runs in the output, ordered root-to-current. Default: `false`.
`--since <number>`	Start from event sequence number.
`--tail`, `-n <number>`	Last `N` events. Default: `50`.

bunx smithers-orchestrator logs run-123
bunx smithers-orchestrator logs run-123 --follow false
bunx smithers-orchestrator logs run-123 --since 400
bunx smithers-orchestrator logs run-123 --tail 10
bunx smithers-orchestrator logs run-123 --follow-ancestry true

When --follow-ancestry is enabled, events from the full parent chain are merged into a single stream with each line prefixed by the originating run ID. Reads from the database, not detached-process stdout. See Events.

events

Query run event history with filters, grouping, and NDJSON output.

bunx smithers-orchestrator events <runId> [options]

Option	Description
`--node`, `-n <string>`	Filter events by node ID.
`--type`, `-t <string>`	Filter by event category: `agent`, `approval`, `frame`, `memory`, `node`, `openapi`, `output`, `rag`, `revert`, `run`, `sandbox`, `scorer`, `snapshot`, `supervisor`, `timer`, `token`, `tool-call`, `voice`, `workflow`.
`--since`, `-s <string>`	Filter to a recent duration window (e.g. `5m`, `2h`).
`--limit`, `-l <number>`	Maximum events to display. Default: `1000`. Max: `100000`.
`--json`, `-j <boolean>`	Output NDJSON for piping. Default: `false`.
`--group-by <string>`	Group output by `"node"` or `"attempt"`.
`--watch`, `-w <boolean>`	Watch mode: append new events as they arrive. Default: `false`.
`--interval`, `-i <number>`	Watch poll interval in seconds. Default: `2`.

bunx smithers-orchestrator events run-123
bunx smithers-orchestrator events run-123 --node analyze --type tool-call
bunx smithers-orchestrator events run-123 --since 5m --limit 500
bunx smithers-orchestrator events run-123 --json
bunx smithers-orchestrator events run-123 --watch --interval 5
bunx smithers-orchestrator events run-123 --group-by node

chat

Show agent transcripts for the latest or a specified run. Reconstructs chat from attempt metadata, NodeOutput events, and fallback responseText.

bunx smithers-orchestrator chat [runId] [options]

Option	Description
`--all`, `-a <boolean>`	Show every agent attempt. Default: `false`.
`--follow`, `-f <boolean>`	Watch for new output. Default: `false`.
`--tail`, `-n <number>`	Last `N` chat blocks.
`--stderr <boolean>`	Include agent stderr. Default: `true`.

bunx smithers-orchestrator chat
bunx smithers-orchestrator chat run-123
bunx smithers-orchestrator chat run-123 --all true
bunx smithers-orchestrator chat run-123 --tail 20
bunx smithers-orchestrator chat run-123 --follow true --stderr false

inspect

Print structured run state.

bunx smithers-orchestrator inspect <runId> [options]

Option	Description
`--watch`, `-w <boolean>`	Watch mode: refresh output continuously. Default: `false`.
`--interval`, `-i <number>`	Watch refresh interval in seconds. Default: `2`.

Output includes: run metadata, step states, pending approvals, loop state, parsed runtime config, and error details.

bunx smithers-orchestrator inspect run-123
bunx smithers-orchestrator inspect run-123 --watch --interval 5

node

Show enriched node details for debugging retries, tool calls, and output.

bunx smithers-orchestrator node <nodeId> [options]

Option	Description
`--run-id`, `-r <string>`	Run ID containing the node.
`--iteration`, `-i <number>`	Loop iteration number. Default: latest iteration.
`--attempts <boolean>`	Expand all attempts in human output. Default: `false`.
`--tools <boolean>`	Expand tool input/output payloads in human output. Default: `false`.
`--watch`, `-w <boolean>`	Watch mode: refresh output continuously. Default: `false`.
`--interval <number>`	Watch refresh interval in seconds. Default: `2`.

bunx smithers-orchestrator node analyze -r run-123
bunx smithers-orchestrator node analyze -r run-123 --attempts
bunx smithers-orchestrator node analyze -r run-123 --tools
bunx smithers-orchestrator node analyze -r run-123 --watch --interval 5
bunx smithers-orchestrator node analyze -r run-123 --iteration 2

why

Explain why a run is currently blocked or paused.

bunx smithers-orchestrator why <runId> [options]

Option	Description
`--json <boolean>`	Output structured JSON diagnosis. Default: `false`.

bunx smithers-orchestrator why run-123
bunx smithers-orchestrator why run-123 --json

scores

View scorer results for a specific run.

bunx smithers-orchestrator scores <runId> [options]

Option	Description
`--node <string>`	Filter scores to a specific node ID.

bunx smithers-orchestrator scores run-123
bunx smithers-orchestrator scores run-123 --node review

approve

Approve a pending approval gate.

bunx smithers-orchestrator approve <runId> [options]

Option	Description
`--node`, `-n <string>`	Node ID. Required when multiple gates are pending.
`--iteration <number>`	Loop iteration. Default: `0`.
`--note <string>`	Approval note.
`--by <string>`	Approver identifier.

bunx smithers-orchestrator approve run-123 --node deploy --note "Looks good" --by alice

Recording approval does not resume execution. Resume with:

bunx smithers-orchestrator up workflow.tsx --run-id run-123 --resume true

deny

Deny a pending approval gate. Same options as approve.

bunx smithers-orchestrator deny <runId> [options]

bunx smithers-orchestrator deny run-123 --node deploy --note "Rollback plan missing" --by bob

signal

Deliver a durable signal to a run waiting on <WaitForEvent>.

bunx smithers-orchestrator signal <runId> <signalName> [options]

Option	Description
`--data <string>`	Signal payload as JSON. Default: `{}`.
`--correlation <string>`	Correlation ID to match a specific waiter.
`--by <string>`	Name or identifier of the signal sender.

bunx smithers-orchestrator signal run-123 payment-received --data '{"amount":100}'
bunx smithers-orchestrator signal run-123 approval --correlation txn-456 --by alice

supervise

Watch for stale running runs and auto-resume them.

bunx smithers-orchestrator supervise [options]

Option	Description
`--dry-run`, `-n <boolean>`	Show which stale runs would be resumed, without acting. Default: `false`.
`--interval`, `-i <string>`	Poll interval (e.g. `10s`, `30s`, `1m`). Default: `"10s"`.
`--stale-threshold`, `-t <string>`	Heartbeat staleness threshold before resume. Default: `"30s"`.
`--max-concurrent`, `-c <number>`	Max runs resumed per poll. Default: `3`.

bunx smithers-orchestrator supervise
bunx smithers-orchestrator supervise --dry-run
bunx smithers-orchestrator supervise --interval 30s --stale-threshold 1m --max-concurrent 5

Supervisor behavior

Each poll cycle the supervisor:

Queries stale running runs whose heartbeat exceeds --stale-threshold.
Queries waiting-timer runs that have a timer past its fire time.
For each candidate, applies guards before resuming:
- Workflow existence: skips the run if the workflow .tsx file no longer exists on disk.
- PID liveness: skips the run if the runtime owner PID is still alive (the run is not actually stale).
- Claim acquisition: attempts to claim the run for resume; skips if another supervisor already claimed it.
Stale runs are processed first, up to --max-concurrent. Timer-due runs fill remaining concurrency slots.
Runs that exceed the concurrency cap are rate-limited and retried on the next poll.

cancel

Halt one active run. Marks in-progress attempts as cancelled.

bunx smithers-orchestrator cancel <runId>

bunx smithers-orchestrator cancel run-123

Exits with code 2 on success.

down

Cancel all active runs in the nearest smithers.db.

bunx smithers-orchestrator down [options]

Option	Description
`--force <boolean>`	Cancel stale runs too. Default: `false`.

bunx smithers-orchestrator down

hijack

Hand off the latest resumable agent session or conversation.

bunx smithers-orchestrator hijack <runId> [options]

Option	Description
`--target <string>`	Expected engine: `claude-code` or `codex`.
`--timeout-ms <number>`	Wait time for live handoff. Default: `30000`.
`--launch <boolean>`	Open session immediately. Default: `true`.

Two hijack styles: native session hijack (CLI agents with resumable session IDs) and conversation hijack (agents resuming from durable message history).

bunx smithers-orchestrator hijack run-123
bunx smithers-orchestrator hijack run-123 --target codex
bunx smithers-orchestrator hijack run-123 --launch false

Cross-engine hijack is not supported.
If a live hijack succeeds and the run has a workflow path, Smithers auto-resumes in detached mode.
If auto-resume fails, prints the equivalent bunx smithers-orchestrator up ... --resume true --run-id ... command.
Conversation hijack reconstructs agents from the original .tsx source.

graph

Render a workflow tree without executing. Uses renderFrame internally.

bunx smithers-orchestrator graph <workflow> [options]

Option	Description
`--run-id`, `-r <string>`	Run ID for persisted input/outputs. Default: `"graph"`.
`--input <string>`	Input JSON. Overrides persisted input.

bunx smithers-orchestrator graph workflow.tsx --input '{"description":"Preview"}'
bunx smithers-orchestrator graph workflow.tsx --run-id run-123

revert

Restore workspace to a previous task attempt snapshot. See Revert.

bunx smithers-orchestrator revert <workflow> [options]

Option	Description
`--run-id`, `-r <string>`	Run ID.
`--node-id`, `-n <string>`	Node ID.
`--attempt <number>`	Attempt number. Default: `1`.
`--iteration <number>`	Loop iteration. Default: `0`.

bunx smithers-orchestrator revert workflow.tsx --run-id run-123 --node-id analyze --attempt 2

retry-task

Retry a specific task within a run. Resets the target node (and optionally its dependents) to pending, clears their output rows, then resumes the workflow. Only the reset tasks re-execute; completed tasks use cached results.

bunx smithers-orchestrator retry-task <workflow> [options]

Option	Description
`--run-id`, `-r <string>`	Run ID containing the task.
`--node-id`, `-n <string>`	Task/node ID to retry.
`--iteration <number>`	Loop iteration. Default: `0`.
`--no-deps <boolean>`	Only reset this node, not dependents. Default: `false`.
`--force <boolean>`	Allow retry even if run is still marked `running`. Default: `false`.

bunx smithers-orchestrator retry-task workflow.tsx -r run-123 -n implement
bunx smithers-orchestrator retry-task workflow.tsx -r run-123 -n analyze --no-deps true
bunx smithers-orchestrator retry-task workflow.tsx -r run-123 -n stuck-task --force true

Resets the target node and all downstream dependents to pending by default.
Clears persisted output rows for reset nodes so the agent starts fresh.
Cancels any prior failed/waiting attempts so retry budgets don’t block re-execution.
After resetting, automatically resumes the workflow with resume: true.

timetravel

Time-travel to a previous task state: revert the filesystem via jj to an attempt’s snapshot, reset the DB state, and optionally resume. Combines revert + node reset into one atomic operation.

bunx smithers-orchestrator timetravel <workflow> [options]

Option	Description
`--run-id`, `-r <string>`	Run ID.
`--node-id`, `-n <string>`	Task/node ID to travel back to.
`--iteration <number>`	Loop iteration. Default: `0`.
`--attempt`, `-a <number>`	Attempt number. Default: latest.
`--no-vcs <boolean>`	Skip filesystem revert (DB only). Default: `false`.
`--no-deps <boolean>`	Only reset this node, not dependents. Default: `false`.
`--resume <boolean>`	Resume the workflow after time travel. Default: `false`.
`--force <boolean>`	Force even if run is still marked `running`. Default: `false`.

bunx smithers-orchestrator timetravel workflow.tsx -r run-123 -n implement --resume true
bunx smithers-orchestrator timetravel workflow.tsx -r run-123 -n analyze -a 1 --no-vcs true
bunx smithers-orchestrator timetravel workflow.tsx -r run-123 -n step-3 --no-deps true --resume true

Restores the filesystem to the attempt’s jjPointer snapshot (unless --no-vcs).
Deletes DB frames created after the target attempt.
Resets the target node and dependents to pending.
With --resume, immediately re-runs the workflow from the reverted state.

replay

Fork from a checkpoint and resume execution (time travel). Creates a new run branched from a specific frame of an existing run, optionally resetting a node and overriding input, then immediately resumes execution.

bunx smithers-orchestrator replay <workflow> [options]

Option	Description
`--run-id`, `-r <string>`	Source run ID to replay from.
`--frame`, `-f <number>`	Frame number to fork from.
`--node`, `-n <string>`	Node ID to reset to pending.
`--input`, `-i <string>`	Input overrides as JSON string.
`--label`, `-l <string>`	Branch label for the fork.
`--restore-vcs <boolean>`	Restore jj filesystem state to the source frame’s revision. Default: `false`.

bunx smithers-orchestrator replay workflow.tsx --run-id run-123 --frame 5
bunx smithers-orchestrator replay workflow.tsx -r run-123 -f 5 -n analyze --input '{"topic":"Rust"}'
bunx smithers-orchestrator replay workflow.tsx -r run-123 -f 5 --label experiment-1 --restore-vcs true

diff

Compare two time-travel snapshots.

bunx smithers-orchestrator diff <a> <b> [options]

Arguments are snapshot refs in the format run_id:frame_no or run_id (uses latest frame).

Option	Description
`--json <boolean>`	Output as JSON. Default: `false`.

bunx smithers-orchestrator diff run-123:5 run-123:10
bunx smithers-orchestrator diff run-123 run-456
bunx smithers-orchestrator diff run-123:5 run-456:3 --json

fork

Create a branched run from a snapshot checkpoint (time travel). Unlike replay, fork does not automatically resume execution unless --run true is passed.

bunx smithers-orchestrator fork <workflow> [options]

Option	Description
`--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 string.
`--label`, `-l <string>`	Branch label.
`--run <boolean>`	Immediately start the forked run. Default: `false`.

bunx smithers-orchestrator fork workflow.tsx --run-id run-123 --frame 5
bunx smithers-orchestrator fork workflow.tsx -r run-123 -f 5 -n analyze --label fix-branch
bunx smithers-orchestrator fork workflow.tsx -r run-123 -f 5 --run true

timeline

View execution timeline for a run and its forks (time travel).

bunx smithers-orchestrator timeline <runId> [options]

Option	Description
`--tree <boolean>`	Include all child forks recursively. Default: `false`.
`--json <boolean>`	Output as JSON. Default: `false`.

bunx smithers-orchestrator timeline run-123
bunx smithers-orchestrator timeline run-123 --tree
bunx smithers-orchestrator timeline run-123 --json

observability

Start or stop the local observability stack (Docker Compose).

bunx smithers-orchestrator observability [options]

Option	Description
`--detach`, `-d <boolean>`	Background containers. Default: `false`.
`--down <boolean>`	Stop and remove stack. Default: `false`.

bunx smithers-orchestrator observability
bunx smithers-orchestrator observability --detach
bunx smithers-orchestrator observability --down

Prints Grafana, Prometheus, and Tempo endpoints on success. See Monitoring & Logs.

ask

Query via the best available installed agent CLI.

bunx smithers-orchestrator ask "How do I resume an approval-gated run?"

Supported agents: Claude, Codex, Gemini, Kimi, and PI. The command bootstraps a temporary MCP config, exposes Smithers as a local MCP server (bunx smithers-orchestrator --mcp), and delegates the question. Exits with error if no supported agent is installed.

Option	Description
`--agent <string>`	Force a specific agent: `claude`, `codex`, `gemini`, `kimi`, or `pi`. Default: auto-select best available.
`--tool-surface <string>`	MCP tool surface to expose: `semantic` or `raw`. Default: `semantic`.
`--no-mcp <boolean>`	Disable MCP bootstrap; pass the question as a plain prompt. Default: `false`.
`--print-bootstrap <boolean>`	Print the bootstrap configuration (agent, mode, tool surface) instead of running. Default: `false`.
`--dump-prompt <boolean>`	Print the full system prompt that would be sent to the agent. Default: `false`.
`--list-agents <boolean>`	List all available agents with usability status and bootstrap mode. Default: `false`.

MCP bootstrap mode is selected automatically per agent: mcp-config-file for Claude Code and Kimi, mcp-config-inline for Codex, mcp-allow-list for Gemini, and prompt-only for PI. Use --no-mcp to disable MCP entirely.

bunx smithers-orchestrator ask "How do I resume an approval-gated run?"
bunx smithers-orchestrator ask --agent codex "Explain the workflow graph"
bunx smithers-orchestrator ask --tool-surface raw "List the raw Smithers MCP tools"
bunx smithers-orchestrator ask --list-agents
bunx smithers-orchestrator ask --print-bootstrap "test query"
bunx smithers-orchestrator ask --dump-prompt "test query"

agents

Inspect Smithers’ built-in CLI agent capability registries.

bunx smithers-orchestrator agents <subcommand> [options]

Subcommand	Purpose
`agents capabilities`	Print the full capability registry for all built-in CLI agents.
`agents doctor`	Validate capability metadata for drift or internal contradictions.

agents capabilities

Print a JSON report of all built-in CLI agent capability registries. Use this to understand which CLI-backed agents Smithers knows about and what features each one advertises.

bunx smithers-orchestrator agents capabilities

Output is always JSON.

agents doctor

Validate the built-in CLI agent capability registries for drift or contradictions. Exits with code 0 when the registry is internally consistent, 1 when problems are detected.

bunx smithers-orchestrator agents doctor [options]

Option	Description
`--json <boolean>`	Print the doctor report as JSON instead of human-readable output. Default: `false`.

bunx smithers-orchestrator agents doctor
bunx smithers-orchestrator agents doctor --json

Use agents doctor in CI to catch registry drift before deployment.

human

List and resolve durable human requests generated by <HumanTask> nodes.

bunx smithers-orchestrator human <action> [requestId] [options]

Subcommand	Purpose
`human inbox`	List all pending human requests across runs.
`human answer <requestId>`	Submit a JSON response to a pending request.
`human cancel <requestId>`	Cancel a pending request without answering it.

<HumanTask> nodes pause workflow execution and record a durable request in the database. This command is the operational surface for that inbox. It is more general than approve/deny: a human request can carry structured data of any shape, not just a binary gate decision.

human inbox

bunx smithers-orchestrator human inbox

Lists all pending human requests. Output includes: requestId, runId, workflowName, nodeId, kind, prompt, status, requestedAt, age, and timeoutAtMs. Pass --format json for structured output:

bunx smithers-orchestrator human inbox --format json

human answer

Submit a response to a pending human request. The workflow resumes after the answer is recorded.

bunx smithers-orchestrator human answer <requestId> [options]

Option	Description
`--value <string>`	Response as a JSON string. Required.
`--by <string>`	Name or identifier of the operator answering.

bunx smithers-orchestrator human answer req-abc123 --value '{"approved":true}' --by "alice"
bunx smithers-orchestrator human answer req-abc123 --value '{"choice":"option-a","notes":"Looks good"}' --by "alice"

If the <HumanTask> node has a corresponding approval gate, answer automatically bridges the approval as well — no separate bunx smithers-orchestrator approve call is needed. Exits with code 4 if the request is not found, not pending, or has already expired.

human cancel

Cancel a pending human request without providing an answer.

bunx smithers-orchestrator human cancel <requestId> [options]

Option	Description
`--by <string>`	Name or identifier of the operator cancelling.

bunx smithers-orchestrator human cancel req-abc123 --by "alice"

If a corresponding approval gate exists, it is automatically denied with the cancellation reason. The workflow will resume and handle the cancelled state according to its error handling logic.

alerts

List, acknowledge, resolve, or silence durable alert instances.

bunx smithers-orchestrator alerts <action> [alertId] [options]

Action	Purpose
`alerts list`	List active alerts from the nearest `smithers.db`.
`alerts ack <alertId>`	Mark an alert as acknowledged.
`alerts resolve <alertId>`	Mark an alert as resolved.
`alerts silence <alertId>`	Silence an alert without resolving it.

The current help output exposes no alert-specific flags. ack, resolve, and silence require an alert ID.

bunx smithers-orchestrator alerts list
bunx smithers-orchestrator alerts ack alert-123
bunx smithers-orchestrator alerts resolve alert-123
bunx smithers-orchestrator alerts silence alert-123

memory

Inspect cross-run memory facts and perform semantic recall.

bunx smithers-orchestrator memory <subcommand> [options]

Subcommand	Purpose
`memory list <namespace>`	List all stored facts in a namespace.
`memory recall <query>`	Search memory by semantic similarity.

Both subcommands require --workflow to locate the smithers.db for the target workflow.

memory list

List all facts stored in a namespace.

bunx smithers-orchestrator memory list <namespace> [options]

Arguments:

namespace: Namespace to inspect (e.g. workflow:my-flow, global:default).

Option	Description
`--workflow`, `-w <string>`	Path to a `.tsx` workflow file. Required to locate the database.

bunx smithers-orchestrator memory list workflow:implement -w .smithers/workflows/implement.tsx
bunx smithers-orchestrator memory list global:default -w .smithers/workflows/implement.tsx

memory recall

Search stored facts by semantic similarity using vector embeddings.

bunx smithers-orchestrator memory recall <query> [options]

Arguments:

query: Natural language search query.

Option	Description
`--workflow`, `-w <string>`	Path to a `.tsx` workflow file. Required to locate the database.
`--namespace`, `-n <string>`	Namespace to search within. Default: `global:default`.
`--top-k`, `-k <number>`	Number of results to return. Default: `5`.

bunx smithers-orchestrator memory recall "auth bug fixes" -w .smithers/workflows/implement.tsx
bunx smithers-orchestrator memory recall "database migrations" -w .smithers/workflows/implement.tsx --namespace workflow:implement --top-k 10

See Cross-Run Memory and Memory Quickstart for the runtime model.

openapi

Preview the AI SDK tools that Smithers would generate from an OpenAPI spec.

bunx smithers-orchestrator openapi <subcommand>

Subcommand	Purpose
`openapi list <specPath>`	List all operations parsed from a spec as named tools.

openapi list

Parse an OpenAPI spec and print the tool names and summaries that Smithers would generate from it.

bunx smithers-orchestrator openapi list <specPath>

Arguments:

specPath: File path or URL to an OpenAPI spec (JSON or YAML).

bunx smithers-orchestrator openapi list ./api/openapi.yaml
bunx smithers-orchestrator openapi list https://petstore3.swagger.io/api/v3/openapi.json

Output lists one tool per operation: operationId — summary (or method + path). The count of tools is printed at the end. Use this to audit a spec before wiring it into a workflow with openApiTools(). See OpenAPI Tools and OpenAPI Tools Quickstart for the authoring model.

rag

Ingest documents into the RAG store or query it for relevant chunks.

bunx smithers-orchestrator rag <subcommand> [options]

Subcommand	Purpose
`rag ingest <file>`	Chunk, embed, and store a document in the vector store.
`rag query <query>`	Retrieve the most relevant chunks for a search query.

Both subcommands require --workflow to locate the smithers.db for the target workflow.

rag ingest

Chunk and embed a document into the SQLite vector store.

bunx smithers-orchestrator rag ingest <file> [options]

Arguments:

file: Path to the file to ingest.

Option	Description
`--workflow`, `-w <string>`	Path to a `.tsx` workflow file. Required to locate the database.
`--namespace`, `-n <string>`	Vector namespace. Default: `default`.
`--strategy <string>`	Chunking strategy: `recursive`, `character`, `sentence`, `markdown`, `token`. Default: `recursive`.
`--size <number>`	Chunk size in tokens or characters. Default: `1000`.
`--overlap <number>`	Chunk overlap. Default: `200`.

bunx smithers-orchestrator rag ingest ./docs/api-reference.md -w .smithers/workflows/implement.tsx
bunx smithers-orchestrator rag ingest ./data/knowledge-base.txt -w .smithers/workflows/implement.tsx --namespace kb --strategy markdown
bunx smithers-orchestrator rag ingest ./src/README.md -w .smithers/workflows/implement.tsx --size 500 --overlap 100

rag query

Search the vector store for chunks most relevant to a query.

bunx smithers-orchestrator rag query <query> [options]

Arguments:

query: Natural language search query.

Option	Description
`--workflow`, `-w <string>`	Path to a `.tsx` workflow file. Required to locate the database.
`--namespace`, `-n <string>`	Vector namespace to search. Default: `default`.
`--top-k`, `-k <number>`	Number of results to return. Default: `5`.

bunx smithers-orchestrator rag query "how does authentication work" -w .smithers/workflows/implement.tsx
bunx smithers-orchestrator rag query "database connection pooling" -w .smithers/workflows/implement.tsx --namespace kb --top-k 10

See RAG and RAG Quickstart for the retrieval model.

workflow

Manage flat workflows in .smithers/workflows/*.tsx.

bunx smithers-orchestrator workflow <command>

Command	Purpose
`workflow run <name>`	Run a discovered workflow by ID.
`workflow`	List discovered workflows (no subcommand).
`workflow list`	List discovered workflows.
`workflow path <name>`	Resolve workflow ID to entry file.
`workflow create <name>`	Create a new workflow scaffold.
`workflow doctor [name]`	Report discovery, preload, bunfig, and detected agents.

Run shorthands:

bunx smithers-orchestrator workflow implement --prompt "Add input validation"
bunx smithers-orchestrator workflow run implement --prompt "Add input validation"

Shorthand resolution:

Resolve name from .smithers/workflows/<name>.tsx
Rewrite to bunx smithers-orchestrator workflow run <name>

bunx smithers-orchestrator workflow
bunx smithers-orchestrator workflow list
bunx smithers-orchestrator workflow run implement --prompt "Investigate flaky tests"
bunx smithers-orchestrator workflow path implement
bunx smithers-orchestrator workflow doctor implement
bunx smithers-orchestrator workflow create foo
bunx smithers-orchestrator workflow foo --prompt "Investigate flaky tests"

Names: lowercase letters, numbers, hyphens only.
workflow create writes only the workflow file. Run bunx smithers-orchestrator init first for .smithers/agents.ts and .smithers/components/.

Workflow metadata comments

Discovery extracts optional metadata from // comments in the first six lines of each workflow file:

// smithers-source: generated
// smithers-display-name: Code Review

Marker	Values	Purpose
`smithers-source`	`seeded`, `generated`, `user`	Origin classification shown in `workflow list` and `workflow doctor`.
`smithers-display-name`	Free text	Human-readable name for the workflow.

workflow create automatically inserts both markers.

workflow list

List all discovered workflows under .smithers/workflows/. Output includes each workflow’s ID, entry file path, and source type.

bunx smithers-orchestrator workflow list

bunx smithers-orchestrator workflow list
# implement  .smithers/workflows/implement.tsx  user
# sweep      .smithers/workflows/sweep.tsx      generated

workflow run

Run a discovered workflow by ID.

bunx smithers-orchestrator workflow run <name> [options]

Arguments:

name: workflow ID

workflow run accepts all of the same execution options as up, plus:

Option	Description
`--prompt`, `-p <string>`	Shorthand for setting `input.prompt` when `--input` is omitted.

Workflow-specific behavior:

resolves <name> to .smithers/workflows/<name>.tsx
defaults --root to . when not provided
preserves all other up semantics including --resume, --detach, --serve, and hot reload

workflow path

Resolve a workflow ID to its entry file path. Prints the absolute path, ID, and source type.

bunx smithers-orchestrator workflow path <name>

Arguments:

name: Workflow ID to resolve.

bunx smithers-orchestrator workflow path implement
# /home/user/project/.smithers/workflows/implement.tsx

workflow create

Create a new workflow scaffold file in .smithers/workflows/. The name must contain only lowercase letters, numbers, and hyphens. Exits with code 4 if the name is invalid or the file already exists.

bunx smithers-orchestrator workflow create <name>

Arguments:

name: ID for the new workflow.

bunx smithers-orchestrator workflow create my-new-flow
# Created .smithers/workflows/my-new-flow.tsx

Run bunx smithers-orchestrator init first to ensure .smithers/agents.ts and .smithers/components/ exist.

workflow doctor

Inspect workflow discovery health. Reports the workflow root, discovered workflows, preload file status, bunfig status, and detected CLI agents. When name is provided, scopes the report to that single workflow.

bunx smithers-orchestrator workflow doctor [name]

Arguments:

name (optional): Workflow ID to inspect. Omit to inspect all discovered workflows.

bunx smithers-orchestrator workflow doctor
bunx smithers-orchestrator workflow doctor implement

cron

Background schedule triggers stored in the nearest smithers.db.

bunx smithers-orchestrator cron <command>

Command	Purpose
`cron start`	Start the scheduler loop.
`cron add <pattern> <workflowPath>`	Add a cron entry.
`cron list`	List registered entries.
`cron rm <cronId>`	Delete an entry.

bunx smithers-orchestrator cron add "0 * * * *" .smithers/workflows/implement.tsx
bunx smithers-orchestrator cron list
bunx smithers-orchestrator cron start
bunx smithers-orchestrator cron rm 0d3a8b0f-6f1c-4e2b-9f4d-0a7b7b95c2e1

Polls every 15 seconds.
Due jobs launch as detached bunx smithers-orchestrator up ... -d processes.
workflowPath is replayed through bunx smithers-orchestrator up; use an explicit file path.

cron start

Start the background scheduler loop in the current terminal. The loop polls every 15 seconds and launches due jobs as detached bunx smithers-orchestrator up ... -d processes. Runs until interrupted.

bunx smithers-orchestrator cron start

cron add

bunx smithers-orchestrator cron add <pattern> <workflowPath>

Arguments:

pattern: Cron expression (e.g. "0 * * * *" for hourly, "*/5 * * * *" for every 5 minutes).
workflowPath: Path or ID of the workflow to schedule.

bunx smithers-orchestrator cron add "0 9 * * *" .smithers/workflows/sweep.tsx
bunx smithers-orchestrator cron add "*/30 * * * *" .smithers/workflows/implement.tsx

cron list

List all registered background cron schedules from smithers.db. Output includes cronId, pattern, workflow path, enabled state, and last/next run timestamps.

bunx smithers-orchestrator cron list

cron rm

Delete an existing cron schedule by its ID.

bunx smithers-orchestrator cron rm <cronId>

Arguments:

cronId: UUID of the cron entry to remove (from cron list output).

bunx smithers-orchestrator cron rm 0d3a8b0f-6f1c-4e2b-9f4d-0a7b7b95c2e1

Framework-Provided Built-Ins

completions

bunx smithers-orchestrator completions bash
bunx smithers-orchestrator completions zsh
bunx smithers-orchestrator completions fish
bunx smithers-orchestrator completions nushell

Shell	Setup
`bash`	`eval "$(bunx smithers-orchestrator completions bash)"`
`zsh`	`eval "$(bunx smithers-orchestrator completions zsh)"`
`fish`	`bunx smithers-orchestrator completions fish \| source`
`nushell`	Add output of `bunx smithers-orchestrator completions nushell` to `config.nu`

mcp add

bunx smithers-orchestrator mcp add [options]

Option	Description
`--command`, `-c <cmd>`	Override the agent command.
`--no-global`	Project-local install.
`--agent <agent>`	Target agent (`claude-code`, `cursor`, etc.).

bunx smithers-orchestrator mcp add
bunx smithers-orchestrator mcp add --agent claude-code
bunx smithers-orchestrator mcp add --command "bunx smithers-orchestrator --mcp"

skills

Sync skill files to agent integrations.

bunx smithers-orchestrator skills <command>

Command	Description
`skills add [options]`	Sync skill files to agents.
`skills list`	List available skills.

skills also has the alias skill.

skills add

bunx smithers-orchestrator skills add [options]

Option	Description
`--depth <number>`	Grouping depth. Default: `1`.
`--no-global`	Project-local install.

bunx smithers-orchestrator skills add
bunx smithers-orchestrator skills add --depth 2
bunx smithers-orchestrator skills add --no-global

skills list

bunx smithers-orchestrator skills list

Global Options

Option	Description
`--format <json\|yaml\|md\|jsonl>`	Output format.
`--verbose`	Full output envelope.
`--filter-output <keys>`	Filter JSON by key path (e.g. `runs[0].id`).
`--schema`	Print JSON schema for the command.
`--llms`, `--llms-full`	Print LLM-readable manifest.
`--token-count`	Print token count instead of output.
`--token-limit <n>`	Limit output to `n` tokens.
`--token-offset <n>`	Skip first `n` output tokens.
`--help`	Command help.
`--version`	CLI version.
`--mcp`	Start as MCP stdio server. Used by `bunx smithers-orchestrator ask` and external tooling.

Operational Behavior

Progress reporting

During up execution, the CLI writes progress events to stderr with elapsed timestamps:

[00:00:02] → analyze (attempt 1, iteration 0)
[00:00:45] ✓ analyze (attempt 1)
[00:00:45] → implement (attempt 1, iteration 0)
[00:01:30] ✗ implement (attempt 1): tool timeout exceeded
[00:01:30] ↻ implement retrying (attempt 2)
[00:02:15] ✓ implement (attempt 2)
[00:02:15] ⏱ deploy waiting for timer (fires 2026-04-09T12:00:00Z)

Progress includes node lifecycle (→ ✓ ✗ ↻), timer events (⏱), hot-reload status, and run completion.

Signal handling

The CLI listens for SIGINT and SIGTERM. On receipt it:

Writes [smithers] received <signal>, cancelling run... to stderr.
Fires the abort controller to cancel in-flight operations.
Closes the SQLite database connection.
Exits with code 130 (SIGINT) or 143 (SIGTERM).

Signals are handled at most once; a second signal during shutdown force-kills the process.

SQLite cleanup

On process exit, SIGINT, or SIGTERM the CLI closes the SQLite connection via client.close(). This ensures WAL checkpointing and prevents database corruption from unclean shutdowns.

Event formatting

logs and events render each event line as:

[+MM:SS.mmm] <symbol> <summary>

Symbols are color-coded: ✓ green for success, ✗ red for failure, ⏸ for approvals, ⏱ for timers, 🔧 for tool calls, 📚 for RAG, 🧠 for memory. Payloads are truncated to 240 characters by default.

Exit Codes

Code	Meaning
`0`	Success.
`1`	Execution failure.
`2`	Run cancelled / `cancel` succeeded.
`3`	`up` completed in `waiting-approval`.
`4`	Invalid arguments or user-correctable input error.
`130`	Interrupted by SIGINT.
`143`	Terminated by SIGTERM.

runWorkflow — programmatic runtime API
Events — persisted lifecycle events
Revert — filesystem snapshot restoration
Hot Reload — up --hot true
Approvals — approve and deny
Time Travel — snapshots, forking, and replay

Getting Started

Build Workflows

Run and Operate

Core Concepts

Guides

Components

Integrations

Runtime API

Examples

Changelogs

Reference

​Start With These Commands

​How the CLI Fits With JSX

​Command Map

​Resolution Rules

​Workflow paths and IDs

​Finding persisted state

​Boolean options

​Commands

​init

​up

​tui

​ps

​logs

​events

​chat

​inspect

​node

​why

​scores

​approve

​deny

​signal

​supervise

​Supervisor behavior

​cancel

​down

​hijack

​graph

​revert

​retry-task

​timetravel

​replay

​diff

​fork

​timeline

​observability

​ask

​agents

​agents capabilities

​agents doctor

​human

​human inbox

​human answer

​human cancel

​alerts

​memory

​memory list

​memory recall

​openapi

​openapi list

​rag

​rag ingest

​rag query

​workflow

​Workflow metadata comments

​workflow list

​workflow run

​workflow path

​workflow create

​workflow doctor

​cron

​cron start

​cron add

​cron list

​cron rm

​Framework-Provided Built-Ins

​completions

​mcp add

​skills

Start With These Commands

How the CLI Fits With JSX

Command Map

Resolution Rules

Workflow paths and IDs

Finding persisted state

Boolean options

Commands

init

up

tui

ps

logs

events

chat

inspect

node

why

scores

approve

deny

signal

supervise

Supervisor behavior

cancel

down

hijack

graph

revert

retry-task

timetravel

replay

diff

fork

timeline

observability

ask

agents

agents capabilities

agents doctor

human

human inbox

human answer

human cancel

alerts

memory

memory list

memory recall

openapi

openapi list

rag

rag ingest

rag query

workflow

Workflow metadata comments

workflow list

workflow run

workflow path

workflow create

workflow doctor

cron

cron start

cron add

cron list

cron rm

Framework-Provided Built-Ins

completions

mcp add

skills

skills add

skills list

Global Options

Operational Behavior

Progress reporting

Signal handling

SQLite cleanup

Event formatting

Exit Codes

Related