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.

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

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. --dry-run previews without writing.

scaffold init
scaffold adopt --dry-run    # preview what adoption would write

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)

See also

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