Skip to main content
The smithers CLI ships with the smithers-orchestrator package. It provides commands to run workflows, resume paused runs, manage approvals, inspect state, and revert to previous snapshots. 
bunx smithers <command> [options]

​
Commands

​
run

Execute a workflow from a .tsx file. 
smithers run <workflow.tsx> [options]
OptionDescription
--input JSONInput data as a JSON string. Parsed and passed to runWorkflow.
--run-id IDProvide a specific run ID. Must not already exist (use resume for existing runs).
--max-concurrency NMaximum parallel tasks. Default: 4.
--root PATHRoot directory for the tool sandbox. Default: the workflow file’s directory.
--log-dir PATHDirectory for NDJSON event logs. Relative to root. Default: .smithers/executions/<runId>/logs.
--no-logDisable event log file output entirely.
--allow-networkAllow the built-in bash tool to make network requests. Note: This flag only applies to Smithers’ built-in tools. CLI agent wrappers (ClaudeCodeAgent, CodexAgent, GeminiAgent) manage their own sandboxing independently — use the agent’s own sandbox options (e.g. sandbox: "read-only" for CodexAgent) to control their network access.
--max-output-bytes NMaximum bytes a single tool call can return. Default: 200000.
--tool-timeout-ms NMaximum wall-clock time per tool call in milliseconds. Default: 60000.
Example: 
smithers run workflow.tsx --input '{"description": "Fix auth bug"}' --max-concurrency 2
The command prints the RunResult as JSON to stdout and exits with the appropriate exit code.

​
resume

Resume a paused or crashed run. Smithers reloads persisted state from SQLite and continues from the last checkpoint. 
smithers resume <workflow.tsx> --run-id ID [options]
Accepts the same options as run (except --input, which is loaded from the database). Example: 
smithers resume workflow.tsx --run-id abc123

​
approve

Grant approval for a task that has needsApproval set. The workflow must be in waiting-approval status. 
smithers approve <workflow.tsx> --run-id ID --node-id ID [options]
OptionDescription
--iteration NRalph iteration number. Default: 0.
--note TEXTOptional note to attach to the approval record.
--decided-by TEXTName or identifier of the person approving.
Example: 
smithers approve workflow.tsx --run-id abc123 --node-id deploy --note "Reviewed output" --decided-by alice
After approving, resume the workflow to continue execution: 
smithers resume workflow.tsx --run-id abc123

​
deny

Deny approval for a task. The task will be marked as failed (or skipped if continueOnFail is set on the task). 
smithers deny <workflow.tsx> --run-id ID --node-id ID [options]
OptionDescription
--iteration NRalph iteration number. Default: 0.
--note TEXTOptional note explaining the denial.
--decided-by TEXTName or identifier of the person denying.
Example: 
smithers deny workflow.tsx --run-id abc123 --node-id deploy --note "Output looks wrong" --decided-by bob

​
status

Print the current status of a run as JSON. 
smithers status <workflow.tsx> --run-id ID
Example: 
smithers status workflow.tsx --run-id abc123
Output: 
{
  "runId": "abc123",
  "workflowName": "bugfix",
  "status": "waiting-approval",
  "createdAtMs": 1707500000000,
  "startedAtMs": 1707500000100,
  "finishedAtMs": null
}

​
frames

List the render frames for a run. Frames capture the workflow tree’s state at each render cycle. 
smithers frames <workflow.tsx> --run-id ID [--tail N] [--compact]
OptionDescription
--tail NNumber of most recent frames to return. Default: 20.
--compactOmit the full XML tree and show only task states, frame number, and mounted task IDs. Much smaller output for large workflows.
Example: 
smithers frames workflow.tsx --run-id abc123 --tail 5

​
list

List all runs stored in the workflow’s database. 
smithers list <workflow.tsx> [--limit N] [--status STATUS]
OptionDescription
--limit NMaximum number of runs to return. Default: 50.
--status STATUSFilter by status: running, finished, failed, cancelled, waiting-approval.
Example: 
smithers list workflow.tsx --status failed --limit 10

​
graph

Render the workflow tree without executing, and print the GraphSnapshot as JSON. Uses renderFrame internally. 
smithers graph <workflow.tsx> [--run-id ID] [--input JSON]
OptionDescription
--run-id IDRun ID to use in the context. Default: "graph". If an existing run ID is provided, its persisted input and outputs are loaded.
--input JSONInput data as JSON. Overrides the persisted input if both are provided.
Example: 
smithers graph workflow.tsx --input '{"description": "Preview"}'
This is useful for understanding the workflow structure, debugging conditional branches, and building external tooling.

​
revert

Revert the workspace to a previous task attempt’s filesystem state using JJ (Jujutsu). See Revert for full details. 
smithers revert <workflow.tsx> --run-id ID --node-id ID [--attempt N] [--iteration N]
OptionDescription
--attempt NAttempt number to revert to. Default: 1.
--iteration NRalph iteration number. Default: 0.
Example: 
smithers revert workflow.tsx --run-id abc123 --node-id analyze --attempt 2
Exits with 0 on success, 1 on failure.

​
cancel

Cancel a running or waiting-approval workflow. Marks all in-progress attempts as cancelled and sets the run status to "cancelled". 
smithers cancel <workflow.tsx> --run-id ID
Example: 
smithers cancel workflow.tsx --run-id abc123
Output: 
{
  "runId": "abc123",
  "status": "cancelled",
  "cancelledAttempts": 2
}
Exits with code 2 (cancelled).

​
version

Print the package version and exit. 
smithers --version
smithers -v

​
help

Print usage information and exit. 
smithers --help
smithers -h

​
Global Options

These options apply to run and resume commands:
OptionDescriptionDefault
--root PATHRoot directory for the tool sandbox. All filesystem tools are confined to this directory.Workflow file’s parent directory
--log-dir PATHDirectory for NDJSON event log files. Relative paths are resolved from --root..smithers/executions/<runId>/logs
--no-logDisable writing event log files. Events are still persisted to the SQLite database.Logging enabled
--allow-networkAllow the built-in bash tool to make outbound network requests. Does not affect CLI agent wrappers — see CLI Agents for agent-specific sandbox settings.Disabled
--max-output-bytes NMaximum bytes returned from a single tool call.200000
--tool-timeout-ms NMaximum time in milliseconds for a single tool call.60000
--max-concurrency NMaximum number of tasks running in parallel.4
--input JSONInput data as a JSON string (for run only).{}
--run-id IDExplicit run identifier.Auto-generated
--version, -vPrint version and exit.—
--help, -hPrint help and exit.—

​
Exit Codes

CodeStatusDescription
0finishedThe workflow completed successfully.
1failedThe workflow failed (task failure or engine error).
2cancelledThe workflow was cancelled.
3waiting-approvalThe workflow is paused waiting for human approval.
4invalid inputInvalid arguments, missing required flags, malformed JSON, or unknown command.

​
Workflow File

Every command (except --version and --help) takes a <workflow.tsx> path as its first positional argument. This file must have a default export that is a SmithersWorkflow object, typically created by calling smithers(...). 
// workflow.tsx
export default smithers((ctx) => (
  <Workflow name="my-workflow">
    <Task id="step1" output="result" agent={myAgent}>
      {`Do something with: ${ctx.input.description}`}
    </Task>
  </Workflow>
));
The workflow file is dynamically imported at runtime, so it can use any TypeScript features supported by Bun.

​
Typical Workflow

A common pattern is to run a workflow, wait for approval, and then resume: 
# 1. Start the workflow
smithers run workflow.tsx --input '{"description": "Deploy v2.0"}'
# Exits with code 3 (waiting-approval)

# 2. Check status
smithers status workflow.tsx --run-id <id>

# 3. Review the graph
smithers graph workflow.tsx --run-id <id>

# 4. Approve the gated task
smithers approve workflow.tsx --run-id <id> --node-id deploy

# 5. Resume execution
smithers resume workflow.tsx --run-id <id>
# Exits with code 0 (finished)
  • runWorkflow — Programmatic API equivalent.
  • Events — Understanding the NDJSON event logs.
  • Revert — Detailed revert documentation.
  • Approvals — How the approval system works.