Scaffold CLI Reference

Overview

This is a terse index of the whole scaffold command surface. It tells you which command does what and points to the deep guides where a subsystem earns its own page. For the full mental model of a subsystem, follow the links:

• Pipeline navigation (next, run, complete, rework, skip, reset, check) is the day-to-day loop — see the Pipeline guide.
• Observability (observe event｜progress｜harvest｜audit｜ack) is its own large surface — see the Build Observability guide.
• Operations (doctor, agent-ops, hooks, mq, tia, sched) is the opt-in parallel-agent kit — merge queue, test-impact analysis, scheduler, health checks. Documented below; the worktree side lives in the Multi-agent guide.

All 30 commands are registered on a single yargs root (src/cli/index.ts:116) and every command accepts the global options --format json, --auto, --verbose, --root <dir>, and --force (src/cli/index.ts:146).

All commands at a glance

Setup & adoption

Two entry points: init for a fresh project, adopt for an existing codebase.

• scaffold init (src/cli/commands/init.ts:151) — scaffold a new project: writes .scaffold/ state and config. --force backs up and reinitializes if .scaffold/ already exists.
• scaffold adopt (src/cli/commands/adopt.ts:168) — bring an existing project under scaffold. It writes nothing by default: it renders an Adoption Plan and stops. --dry-run is deprecated and does nothing, since plan mode is already the default.

scaffold init
scaffold adopt                              # render the plan, write nothing
scaffold adopt --apply --plan-key <sha256>  # execute the approved plan

Pipeline navigation

The core loop. next tells you what's eligible, run emits the assembled prompt, complete records work done outside the CLI, and rework/skip/reset adjust state. See the Pipeline guide for phase ordering and dependencies.

• scaffold next (src/cli/commands/next.ts:28) — show the next eligible step(s) given current state and dependencies.
• scaffold run <step> (src/cli/commands/run.ts:45) — assemble and emit a pipeline step's prompt. --depth, --instructions, and --service refine the run.
• scaffold complete <step> (src/cli/commands/complete.ts:28) — mark a step completed for work executed outside scaffold run (this is the hook that fires phase-boundary audits — see the Observability guide).
• scaffold rework (src/cli/commands/rework.ts:39) — re-run steps by phase for depth improvement or cleanup. --phases, --through N, --exclude.
• scaffold skip <step..> (src/cli/commands/skip.ts:35) — skip one or more steps; --reason records why.
• scaffold reset [step] (src/cli/commands/reset.ts:32) — reset one step, or the whole pipeline (guarded by --confirm-reset).
• scaffold check <step> (src/cli/commands/check.ts:115) — report whether a conditional step applies to this project type.

scaffold next                 # what can I run now?
scaffold run user-stories     # emit the prompt for a step
scaffold rework --through 3   # re-run phases 1 through 3

Status & dashboard

Read-only views of project and pipeline state.

• scaffold status (src/cli/commands/status.ts:80) — pipeline progress and per-step status.
• scaffold info [step] (src/cli/commands/info.ts:26) — project summary, or detail on a single step.
• scaffold list (src/cli/commands/list.ts:74) — available methodologies, platform adapters, and tools.
• scaffold decisions (src/cli/commands/decisions.ts:23) — recorded decisions for the project.
• scaffold dashboard (src/cli/commands/dashboard.ts:77) — generate and open the visual pipeline dashboard.

Observability — scaffold observe …

observe is the build-observability surface: a durable event ledger, a fused progress timeline, a multi-lens audit, and worktree-ledger harvesting. It demands a subcommand (src/cli/commands/observe.ts:398). This guide only lists the verbs — the Build Observability guide documents the event schemas, the nine audit lenses, verdicts, stall signals, and config.

scaffold observe progress --replay
scaffold observe audit --scope docs --profile full
scaffold observe ack 3a8c1f02 --status acknowledged --note "tracked in #412"
scaffold observe harvest --worktree ../wt-alice

Knowledge

Two distinct command trees: knowledge manages the entries themselves; knowledge-freshness audits them for staleness.

• scaffold knowledge <subcommand> (src/cli/commands/knowledge.ts:417) — list, show <name>, update <target> [instructions..], reset <name> for global entries and local overrides.
• scaffold knowledge-freshness <command> (src/cli/commands/knowledge-freshness.ts:12) — the freshness-audit family: audit-prefilter, audit-run-entry, audit-apply, link-check, lint-unsourced, anti-over-rewrite, deep-guidance-check, bump-version.

scaffold knowledge list
scaffold knowledge show react-state-management

Validation

• scaffold validate (src/cli/commands/validate.ts:19) — validate meta-prompt frontmatter and config (the make validate gate).
• scaffold validate-knowledge (src/cli/commands/validate-knowledge.ts:20) — validate frontmatter on all knowledge entries (volatility, last-reviewed, sources, version-pin).

Version & update

• scaffold version (src/cli/commands/version.ts:78) — show the installed version and check for a newer one.
• scaffold update (src/cli/commands/update.ts:93) — check for and display available CLI updates.

Platform & skills

• scaffold build (src/cli/commands/build.ts:40) — generate the platform adapter output files from pipeline content.
• scaffold skill <action> (src/cli/commands/skill.ts:31) — manage scaffold skills for Claude Code and shared agents.
• scaffold guides [topic] (src/cli/commands/guides.ts:57) — open, list, or build the reference guides. --list --format json for discovery, --markdown / --print-path for agents, --build to regenerate the HTML.

scaffold guides --list --format json   # discover guides (agents)
scaffold guides cli --markdown         # read this guide's source
scaffold guides --build                # regenerate index.html (maintainer/CI)

Operations — the parallel-agent kit

These six commands are orthogonal to the pipeline: they install and run the machinery that lets several agents work one repo at once. None of them touch pipeline state.

All six are registered on the root CLI, so they always appear in scaffold --help. What is opt-in is the machinery they drive: until you run scaffold agent-ops install, there are no queue scripts, no gate seeds, and no poller for them to operate on, and most will tell you so rather than do anything.

scaffold doctor

Ten checks across six sections — pipeline (completed steps actually produced their outputs), beads (binary, live database, backup, guard), hooks (registered scripts exist and are executable), gate (the check / check-affected make targets resolve), queue (daemon lock, not paused), and scheduler (the poller schedule is loaded) (src/doctor/checks.ts:419). Each check reports ok / warn / error / skip with its own remediation line.

Three checks can self-heal under --fix: the live-Beads check delegates to bd doctor --fix, hook registration re-runs the installer, and the scheduler check reloads the job. Everything else still only reports its fix.

scaffold agent-ops

Installs the project-owned script bundle that worktree and merge-queue workflows call. --component selects what lands:

--component takes exactly one value; it is not repeatable, so --component merge-queue --component ci fails with AGENT_OPS_INVALID_COMPONENT. Run the command once per component.

all deliberately does not include merge-queue, ci, or gate — each of those changes how the repo merges or what CI runs, so they stay explicit opt-ins.

Seeded files (gate) are generated once and never overwritten without --force. Every install writes .scaffold/agent-ops-manifest.json and .scaffold/agent-ops-version; scaffold agent-ops check compares the tree against that manifest and exits 1 on a stale version, a locally modified file, or a missing file (files the manifest doesn't know about are reported but never fail the check).

scaffold mq — the merge queue

A local batching merge queue: PRs are enqueued, gated in batches, and merged in order, so parallel agents don't each re-run the full suite against a moving main.

Queue state lives under .mq/ — an append-only journal.jsonl that the queue state is a reduction of, plus the gate cache, logs, and the daemon lock. Configuration is the merge_queue: block of .scaffold/agent-ops.yaml (src/merge-queue/types.ts:95); notable keys are gate_command (default make check-affected), full_gate_command (default make check), batch_cap (16), ready_label (mq:ready), overlap_zones, and overlap_zone_policy (solo | hold).

scaffold tia — test-impact analysis

Recording cadence is merge_queue.tia.record in .scaffold/agent-ops.yaml — scheduled (default; first green pass per UTC day), always, or off.

scaffold sched

install / uninstall / status / list for local scheduler jobs, using launchd on macOS and systemd user timers on Linux. One job ships today, post-merge-poller (src/sched/jobs.ts:38), which runs the merge queue's post-merge full gate; --interval <seconds> sets its period on install (default 600). It requires scripts/ops/post-merge-poller.sh, so run scaffold agent-ops install --component merge-queue first. sched status exits 1 when the job is not loaded, so it doubles as a liveness probe.

See also

• Pipeline guide — phase ordering and the navigation loop.
• Build Observability guide — the full observe subsystem.

Driving scaffold from an agent

Every command below is safe to run with no TTY. Pass --format json and read stdout; human-readable progress goes to stderr and can be discarded.

Exit codes

Source of truth: src/types/enums.ts. A bats gate asserts this table and the enum agree in both directions, so a code cannot change on one side only.

The output envelope

Success:

{"success": true, "data": {}, "errors": [], "warnings": [], "exit_code": 0}

Failure:

{
  "success": false,
  "data": null,
  "errors": [
    {
      "code": "INIT_AUTO_FLAG_REQUIRED",
      "message": "--cli-interactivity is required in auto mode for cli projects",
      "exitCode": 1,
      "recovery": "Pass --cli-interactivity <args-only|interactive|hybrid>"
    }
  ],
  "warnings": [],
  "exit_code": 1
}

Branch on success. Where the envelope is emitted, it carries at least one entry in errors, every entry carries a recovery string naming the flag or command that fixes it, and exit_code always matches the process exit status.

Coverage is CLI-wide as of v3.53.0, and a static test fails the build if a command reports a failure any other way.

Choosing init or adopt

Run scaffold adopt when the directory already contains source code or docs. Run scaffold init for an empty or brand-new directory.

adopt runs in two steps. Bare scaffold adopt writes nothing — it renders an Adoption Plan and stops. scaffold adopt --apply --plan-key <sha256> then executes it, and that step writes .scaffold/ and selects the brownfield methodology itself. So no separate scaffold init is needed either way — but nothing is written until you approve the plan.

Flags --auto cannot default

Nine project types need one flag chosen explicitly, because there is no defensible default. They are annotated [required with --auto] in scaffold init --help.

game, browser-extension, macos-native, data-science and web3 need none. A type-specific flag implies its project type, so scaffold init --auto --cli-interactivity args-only is sufficient on its own.

Any non-interactive mode implies --auto: a piped invocation, or --format json, will refuse to invent an answer rather than silently choosing one.

The driving loop

scaffold next --format json          # .data.eligible[].command is runnable as-is
scaffold run <slug>                  # prints the assembled meta-prompt on stdout
scaffold complete <slug> --format json

Repeat until .data.pipeline_complete is true.

Adoption plan keys

plan_key is content-addressed: it hashes the plan's dispositions and initialize payload, and deliberately excludes project_root and generated_at (src/project/adoption-plan.ts). Two repos whose plans are identical therefore share a key. Do not cache a key across repositories; always read the key from the plan you just rendered.