CLI command reference

Every subcommand of the roscoe binary, with full flag tables and worked examples. Where source matters, apps/cli/src/commands/<name>.ts is the canonical definition.

The compiled binary (bun run compile → apps/cli/dist/roscoe) and the source-mode runner (bun apps/cli/src/index.ts) expose the same commands. Examples below assume the binary is on PATH.

roscoe init#

Scaffold the global data dir (~/.roscoe/) and (when inside a git repo) the project data dir (<repo>/.roscoe/). Runs DB migrations, writes a roscoe.yaml config + JSON Schema, wires .vscode/settings.json for YAML autocomplete, drops a self-contained .gitignore inside <repo>/.roscoe/ (create-only — --force does not overwrite it), and seeds the starter workflows into the global dir.

Whenever global init runs (anything but --repo-only), it also installs the global /roscoe slash command at ~/.claude/commands/roscoe.md so Claude Code / Cowork users can launch workflows with /roscoe <workflow-name>. The write is best-effort and idempotent (always overwritten) — a failure (e.g. a read-only home) is logged but never aborts init.

roscoe init [--global-only] [--repo-only] [--force] [--no-examples]

Example workflows seeded into ~/.roscoe/workflows/: demo-1-the-panel, demo-2-week-of-dinners, demo-3-name-tournament, demo-4-second-draft, demo-5-reality-check, demo-6-gift-shortlist, demo-7-fair-price, demo-8-smell-test, demo-9-check-one-claim. The repo workflow dir is left empty so a team can fill it with shared workflows.

Exit codes: 0 always (failures in individual steps are logged but never abort init — by design, you can re-run it any time).

# Default: scaffold both global and (if in a repo) project dirs
roscoe init

# I'm not in a repo and don't want the warning
roscoe init --global-only

# Refresh the roscoe.yaml schema and re-seed examples
roscoe init --force

roscoe serve#

Start the HTTP server with the embedded web UI on a single port. Available only from the compiled binary (the source-mode dev server is bun run dev, which runs API + Vite separately).

roscoe serve [-p <port>] [--no-open] [--no-register]

By default, roscoe serve registers the detected git root (making it the active project) and opens the URL in a browser. Auto-register failure is soft: it's logged and the server still starts.

Port resolution order (first match wins):

1. --port flag
2. ROSCOE_PORT env var
3. ports.serve in roscoe.yaml
4. Built-in fallback 7777

When the port comes from the fallback only, roscoe serve will auto-bump up to 9 ports forward to find a free one (so 7777, 7778, … 7786). Any explicitly set port is never silently bumped — if it's busy, roscoe serve exits with [roscoe] Port <N> is in use.

Exit codes: 0 on clean shutdown (SIGINT/SIGTERM), 1 on bind failure or invalid port.

roscoe serve                  # listens on 7777 (or next free port)
roscoe serve -p 8000          # listens on 8000 only; fails if busy
ROSCOE_PORT=9001 roscoe serve  # same effect via env var

roscoe stop#

Stop the running roscoe serve for the current ROSCOE_HOME, and wait for it to actually exit before returning. It triggers the server's own authenticated self-shutdown (POST /api/serve/restart, which SIGTERMs its own process), not a cross-process kill, so it's safe regardless of who started the server.

roscoe stop

No flags. Waits up to 10 seconds for the listener to disappear after requesting the stop.

The server aborts in-flight runs before it exits, so executor children of a running workflow are torn down rather than orphaned.

Exit codes: 0 if stopped (or nothing was running), 1 if a server is running but couldn't be stopped (missing auth token, or the request failed).

roscoe stop  # e.g. before roscoe update installs a new binary manually

roscoe locate#

Print where a running roscoe serve is for the current ROSCOE_HOME, without starting one. This is the attach-logic primitive the desktop shell uses to decide whether to reuse an existing server or spawn a new one; it's also useful from a shell to find the port and auth token of a server you started elsewhere.

roscoe locate [--json]

Exit codes: 0 if a server is found, 3 if none is running (the signal an attach caller uses to decide to spawn one), 1 on an unexpected error.

roscoe locate
roscoe locate --json | jq .baseUrl

roscoe mcp#

Start the MCP stdio server. Reads protocol messages on stdin, writes them on stdout — never use console.log from this command, or you'll corrupt the protocol stream. Diagnostic output goes to stderr.

roscoe mcp

No flags. Auto-loads .env.dev from the current repo if present (so a dev shell pointing at ~/.roscoe-dev keeps working without explicit env). Sets ROSCOE_SWEEP_TEST_RUNS=1 to enable cleanup of orphaned test_workflow rows.

Exit codes: 0 on SIGINT/SIGTERM. There is no explicit failure exit — a throw during tool registration or transport connect propagates and exits non-zero through Node's default handler (typically a corrupted DB — see Database recovery).

This is the entry point that Claude Code shells out to. Don't run it directly unless you're debugging the MCP layer; use roscoe install-mcp to register it with Claude Code instead.

roscoe run <workflow>#

Run a workflow by id (resolved from project or global sources) or by explicit YAML path. Routes through a running roscoe serve (or the dev API under bun run dev) — if neither is up, exits with a hint naming roscoe serve and ROSCOE_PORT. Running from source, the hint names the dev server too.

In a TTY, mounts a live Ink view with a node tree, status, and HITL prompt for human nodes. Press q to detach (the run keeps executing on the server), c to cancel, or o to open the run page in the browser.

With --json, the run is polled to completion (up to 120 s) and the result is printed as { runId, status, totalCostUsd, meteredCostUsd, subscriptionEquivCostUsd, billingMode, inputTokens, outputTokens }, plus stopReason when one is set. Outside a TTY without --json, no JSON is printed — just the run id and a monitor hint.

roscoe run [<workflow>] [-v key=value...] [-i name=value...] [-s global|repo]
          [--json] [--no-tty] [--attach <runId>] [--run-here]
          [--open cowork|claude_code] [--spending-cap <usd>]
          [--spending-cap-tokens <n>]

Workflow resolution — if the argument contains /, \, ends in .yaml / .yml, or names an existing file, it's treated as a path. Otherwise it's a workflow id. When the same id exists in both sources, repo wins; pass --source global to override. When repo shadows global, a # resolved from repo (shadows global) notice is printed. Path-based starts are realpath-checked server-side; non-existent or unreadable paths return 400.

Where the run executes. --run-here and --open are explicit overrides; absent either, the choice follows preferences.defaultRunLocation in roscoe.yaml (here, cowork, claude_code, or the default ask). ask prompts interactively in a TTY when Claude Desktop is installed, and falls back to here otherwise (so CI never hangs). See Running on your Claude subscription for what runs where, and roscoe.yaml for the preference.

Exit codes: 0 on successful start (or live-view detach), 1 on resolution / start / server-not-running failure.

roscoe run demo-1-the-panel
roscoe run demo-1-the-panel --source global
roscoe run examples/hello-world.workflow.yaml
roscoe run demo-4-second-draft --input goal="warm but firm"
roscoe run summarize --input document="my text" --input maxWords=50
roscoe run demo-1-the-panel --json                  # CI / agent
roscoe run --attach 01HXYZ...                       # reattach to a running run
roscoe run demo-1-the-panel --run-here              # skip the handoff prompt
roscoe run demo-1-the-panel --spending-cap 2.50     # cancel past $2.50

roscoe list#

List workflows from both project (<repo>/.roscoe/workflows/) and global (~/.roscoe/workflows/) sources. The project section is omitted entirely when there's no project source.

roscoe list

No flags. Shadowed entries (same id in both sources) are marked [shadowed by repo] in the global section.

Exit codes: 0 always.

roscoe resume <run-id> [transition]#

Resume a paused run. With a transition (positional or --transition), runs non-interactively (suitable for scripts and CI). In a TTY without one, mounts the same interactive Select picker roscoe run uses for HITL prompts. Like roscoe run, requires a running server.

roscoe resume <run-id> [transition] [--transition <name>] [--no-tty]

Exit codes: 0 on success, 1 if the run can't be resumed (not paused, unknown transition, run not found, server not running).

roscoe resume r-abc123 approve
roscoe resume r-abc123 reject
roscoe resume r-abc123 --transition approve
roscoe resume r-abc123                # interactive picker (TTY only)

roscoe monitor <run-id>#

Inspect a run. In a TTY, mounts the same live Ink view as roscoe run without starting a new run — useful for picking up an in-progress run from another shell. With --json or when piped, prints a one-shot snapshot (run + per-node trace) and exits without contacting the server.

roscoe monitor <run-id> [--json] [--no-tty]

Exit codes: 0 on success, 1 if the run isn't found or the live view can't reach the server.

roscoe history#

List recent runs for the current project, newest first.

roscoe history [-n <limit>] [--all]

When run outside a git repo, defaults to --all semantics with a notice. Output columns: STATUS · WORKFLOW · AGE · ID · DURATION. Paused rows print a roscoe resume <id> hint underneath.

Exit codes: 0 always.

roscoe validate <file>#

Validate a workflow YAML file against the Zod schema, the integrity checker, and the cross-workflow graph check. Prints schema errors first, then integrity errors, then graph errors, stopping at the first failing stage. Paths are resolved from the current working directory.

roscoe validate <file>

The graph check follows subworkflow nodes to their child workflow files and reports missing children, unknown child input/output names, reference cycles, and depth violations. It's a no-op for workflows with no subworkflow nodes.

Exit codes: 0 if valid, 1 if any of the three checks fails.

roscoe validate examples/my-workflow.workflow.yaml

When the workflow's version: field doesn't match the binary's supported schema version, the error tells you which way the mismatch goes and what to do — newer-than-binary asks you to run roscoe update, older-than-binary asks you to update the file or downgrade.

roscoe version#

Print the installed version and check the release manifest for a newer one.

roscoe version [--json] [--check] [--no-fetch]

# Human output
roscoe version

# Script-friendly
roscoe version --json | jq .updateAvailable

# CI gate — fail the build if the local binary is stale
roscoe version --check || echo "::warning::roscoe binary out of date"

The manifest URL defaults to https://roscoe.run/v/manifest.json; override with ROSCOE_MANIFEST_URL (used by tests and self-hosted mirrors).

roscoe update#

Download the latest release, verify its sha256 against the manifest, and swap it over the installed binary at ~/.roscoe/bin/roscoe (or wherever ROSCOE_INSTALL_DIR points). If a roscoe serve process is running on this machine the update token from ~/.roscoe/serve.lock is used to ask it to restart cleanly on the new version.

roscoe update [--check] [--force] [--rollback] [--no-restart]

# Standard upgrade path
roscoe update

# Will an update do anything? (handy in a Makefile)
roscoe update --check

# Revert the last update
roscoe update --rollback

roscoe serve also pre-downloads new releases in the background, so when you (or the Settings → Updates button) trigger an install the asset is already on disk and the swap is near-instant. The download path verifies sha256 before the rename, and on macOS the new binary is xattr-stripped and ad-hoc codesigned so Apple Silicon doesn't refuse to launch it. The previous binary stays on disk at ~/.roscoe/updates/previous/roscoe until the next update overwrites it.

roscoe update refuses to run when the active binary isn't at the canonical install location (e.g. you copied roscoe to /usr/local/bin/). In that case it prints the path it found and asks you to re-run install.sh or use your package manager's update command.

roscoe install-mcp#

Register the roscoe entry so a Claude MCP client launches the compiled binary as its MCP server. By default it targets Claude Code and writes the user-global ~/.claude.json (top-level mcpServers), so the install applies to every project; the machine-specific binary path stays out of any shared repo. Pass --client claude-desktop to target the Claude desktop app instead. Must be run from the compiled binary, not from source.

roscoe install-mcp [--client <name>] [--project] [--path <file>] [--command-path <path>]

With --client claude-desktop the entry is written to the desktop app's config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, ~/.config/Claude/claude_desktop_config.json on Linux, %APPDATA%\Claude\claude_desktop_config.json on Windows, or the Microsoft Store build's per-package path under %LOCALAPPDATA%\Packages\Claude_*\), creating the directory if needed. --project is not valid for Claude Desktop (it has no project-local config).

All target files use the same top-level mcpServers shape. Writes:

{
  "mcpServers": {
    "roscoe": {
      "command": "<path-to-roscoe-binary>",
      "args": ["mcp"]
    }
  }
}

Every other key in the file is preserved: ~/.claude.json's projects map and any other MCP servers stay put, only mcpServers.roscoe is replaced. The write is atomic (temp file + rename), so a populated ~/.claude.json is never truncated. A missing target file is created. Refuses to run from bun (source mode), since the resulting process.execPath would be the bun interpreter, not the roscoe command.

/roscoe slash command. The default user-global Claude Code install also writes ~/.claude/commands/roscoe.md (the same /roscoe command roscoe init installs) and prints its path. This is deliberately skipped for --project (a repo-local opt-in shouldn't create a machine-wide command file), for --client claude-desktop (the desktop app has no slash commands), and for --path targets. The write is best-effort — a failure is reported but never fails the MCP registration.

Exit codes: 0 on success, 1 if run from source or if the target config file exists but is malformed JSON (in which case it is left untouched).

roscoe register#

Register a project in the local project registry so it appears in the web UI's project switcher (the roscoe serve UI scopes itself to the active registered project). Registration does not move or copy any files; it only records the path.

roscoe register [path] [--activate] [--name <name>]

Entries are keyed on the resolved (realpath) git root, so registering the same repo twice is idempotent and sibling worktrees of one repo each get their own entry. Exits 1 when path isn't inside a git repo.

roscoe register                       # register the current repo
roscoe register ~/dev/projectA --activate
roscoe register . --name "Billing service"

roscoe unregister#

Remove a project from the registry — the inverse of roscoe register. This only unregisters the project from the UI project switcher; it deletes no files (workflows, roscoe.yaml, and run history all stay on disk).

roscoe unregister [path]

Removal is keyed on path, so it targets exactly one entry even when sibling worktrees of the same repo share a registry id. It resolves the same candidate paths registration uses (git root + realpath), so it still matches an entry for a path whose git root can no longer be resolved (e.g. a removed worktree). Exits 1 when no registered project matches the path.

roscoe unregister                     # unregister the current repo
roscoe unregister ~/dev/projectA

Environment variables#

For the dev server (bun run dev), .env.dev at the repo root sets ROSCOE_API_PORT (default 8080), ROSCOE_WEB_PORT (default 3000), and ROSCOE_HOME=~/.roscoe-dev so dev runs don't pollute the production DB.

Where to next#

• Running workflows from the CLI — the same commands as a walkthrough rather than a lookup table.
• MCP tools — what roscoe mcp exposes once an agent is connected to it.
• REST API — the HTTP surface roscoe serve puts these commands on top of.
• Environment variables — the full list, of which the table above covers only what the CLI reads.
• roscoe.yaml — the config file init writes and serve reads for its port.