Skip to main content
Prerequisites: bun installed, and a project directory where you want to run Smithers.
This cheatsheet is for the agent operating Smithers. You, the agent, run every command on this page for the human; never hand them to the human. The human states outcomes and answers questions; you operate the CLI.
Set up 
bunx smithers-orchestrator init                                       # scaffold .smithers/
bunx smithers-orchestrator init --template idea-to-tickets            # scaffold with guided template next steps
bunx smithers-orchestrator starters                                   # browse template IDs
Verify the setup 
bunx smithers-orchestrator --version          # prints the version, e.g. 0.23.0
bunx smithers-orchestrator workflow doctor    # vcs + workflow pack health
bunx smithers-orchestrator workflow list      # workflows discovered in this repo
workflow doctor confirms a VCS resolved and the pack scaffolded (output trimmed): 
vcs:
  jj:
    path: jj
    source: path
  git:
    path: git
    source: path
  ok: true
workflowRoot: /your/repo/.smithers
packs[2]:
  - scope: local
    packDir: /your/repo/.smithers
    preload:
      path: /your/repo/.smithers/preload.ts
      exists: true
    bunfig:
      path: /your/repo/.smithers/bunfig.toml
      exists: true
  - scope: global
    ...
workflows[46]:
  - id: audit
  - id: implement
  - ...
ok: true under vcs means jj or git resolved; if it is false, install one (see Installation). A non-empty workflows[...] count means the pack is in place. workflow list prints the same workflow entries with full metadata. Run 
bunx smithers-orchestrator workflow run implement --prompt "…"        # launch a seeded workflow
bunx smithers-orchestrator up workflow.tsx --run-id RUN_ID --resume true   # resume a paused run
What success looks like workflow run and up stream the lifecycle event log and exit on a terminal line: 
[12:00:01] ▶ Run started
[12:00:01] ↺ Run status: running
[12:00:38] ✓ implement (attempt 1)
[12:00:40] ✓ Run finished
✓ Run finished means the run completed. ⏸ <node> waiting for approval means it paused for a human decision (relay the question to the human, then clear it with approve and resume). ✗ Run failed: … reports the error. The CLI prints the run id and suggested next commands (logs, inspect) after launch; pass that id to every command below. Observe & control 
bunx smithers-orchestrator ps                                         # list runs
bunx smithers-orchestrator inspect RUN_ID                           # structured run state
bunx smithers-orchestrator logs RUN_ID --tail 20 --follow           # stream events
bunx smithers-orchestrator why RUN_ID                               # why is it paused?
bunx smithers-orchestrator approve RUN_ID --node NODE_ID --by NAME   # approve a paused node
bunx smithers-orchestrator cancel RUN_ID                            # cancel a run
See Tour for a full worked example. See CLI overview for the complete flag reference.