Commands

Forge exposes commands across two surfaces, and they are not the same set. The forge binary is a deterministic Go program with its own set of terminal commands — it is never in the LLM inference loop. Separately, Forge installs a family of /forge.* agent slash-commands (skills) into each configured agent. The two surfaces overlap for some commands, but many commands live on only one of them.

• Terminal forge <name> commands — the deterministic binary. Setup and lifecycle (install, init, sync, uninstall, restore, update, upgrade, doctor, config explain), analysis and status (analyze, health, drift, verify, archive, sdd-status, sdd-continue), the harness gates and runtime (budget, secscan, trace, docs, panel, review, hook, metrics, mcp serve, run), the brand/design seeds (brand, design), reporting (board, roadmap, wireframe), delivery (deliver, issues create), and the platform plumbing (import, migrate, memory, recall, skill-registry, skill-discover, extension, agent-build, learn, profile, provider, workspace, codegraph).
• /forge.* agent skills only — the SDD spine (explore, propose, specify, clarify, plan, tasks, implement), foundation authoring (constitution, security, infra), and most cross-cutting commands (reconcile, refine, pseudocode, checklist, levelup, discover, export, taskstoissues, brainstorm). There is no forge explore or forge reconcile terminal command — these run inside your agent.

Where each command runs

The Surface column in every table below names exactly where a command runs: CLI for a terminal forge <name> command, /forge.<name> for an agent skill, or both when a command is available on each surface. Every stateful terminal command reads and writes .forge/ in the target repo; point it elsewhere with --cwd <repo>.

Command map

Foundation sets the ground rules once. The spine drives each change from explore to archive. Cross-cutting and harness commands wrap the spine — safe to call at any point, or armed as gates around the implement → verify loop.

Entry commands (onboard, new, ff, continue, status) drop you onto the spine at the right phase for the change in hand.

Setup

Bootstrap Forge, configure agents, and manage the binary and snapshots.

Setup is terminal only apart from init: these commands install, upgrade, and roll back the binary and its managed config, so they run in your shell rather than inside an agent. /forge.init is the single slash-command in this group.

Command	Aliases	Surface	Description
install	—	CLI only	Detect the agents present on the machine and write the Forge command set into each one's native config (e.g. .claude/commands/). Backs up existing config first and is idempotent; scope with --scope workspace, preview with --dry-run.
init	—	CLI · /forge.init	Initialize this repo's .forge/config.yaml and the .forge/ tree — run once per repository. The wizard walks defaults; --yes accepts them headlessly for CI.
sync	—	CLI only	Re-apply agent configs and skills to the current binary version. Run it after upgrade to converge managed files without a full reinstall.
doctor	—	CLI only	Environment health check — agent detection, .forge/ presence and writability, embedded assets, and dependencies (Node, Engram, …) — the counterpart to install. Plain doctor is read-only; add --fix to attempt remediation of failed and warning dependency checks, then re-report. --selftest runs an in-process smoke test of the core commands instead, with no repository or dependency checks — the right one to run right after installing the binary, before a project exists.
update	—	CLI only	Report and fetch the latest available release. Does not touch .forge/ state.
upgrade	—	CLI only	Apply a binary-only self-update. Does not touch .forge/ state.
restore	—	CLI only	Roll back Forge-managed config to a previous snapshot — always recoverable to a known-good state. Forge snapshots automatically before every mutating operation, so there is no separate backup command to run first.
uninstall	—	CLI only	Remove Forge-managed files from this machine. A snapshot is captured automatically first, so restore can always roll it back.
config explain	—	CLI only	Print the fully resolved configuration and, for each value, the origin layer it came from (defaults, config.yaml, or the gitignored config.local.yaml).

Workflow spine

The canonical SDD phases, in the one order every change follows. A given change traverses a subset of the spine — adaptive depth picks the entry point, never a different ordering. See The Workflow for the full model.

The spine authoring phases (explore through implement) are /forge.* agent skills only — they have no terminal forge <name> form. verify and archive also exist as deterministic terminal commands.

Command	Aliases	Surface	Description
explore	—	/forge.explore	Investigate the codebase and compare approaches before committing to a direction; writes exploration.md and consults memory for prior decisions. Run first on substantial or hot-path changes.
propose	—	/forge.propose	Turn exploration into intent — draft proposal.md with the scope, approach, and rationale, before you pin down exact requirements.
specify	spec	/forge.specify	Write the delta spec under changes/<name>/specs/{domain}/spec.md using OpenSpec Given/When/Then scenarios and RFC-2119 language (MUST / SHOULD / MAY) — the testable contract the rest of the spine is measured against.
clarify	—	/forge.clarify	Resolve the open questions and ambiguities still in the spec before they leak into design and code.
plan	—	/forge.plan	Produce the technical design plan.md — architecture decisions, chosen approach, and trade-offs. Reads the spec and turns what into how. May also produce optional data-model.md and contracts/{interface-name}.md companions when the change introduces or modifies entities or external-facing interfaces.
tasks	—	/forge.tasks	Slice the design into an ordered, honest-status checklist tasks.md (backlog → in-progress → blocked → done); a task reaches done only when its acceptance scenarios pass under verify. Every task line carries a required 🟢/🟡/🟠/🔴 complexity tier and an optional [P] parallel marker, and the file closes with a machine-readable ## Execution Graph (waves, blockers, critical path, hour estimates) that estimate, roadmap, and swarm all read.
implement	apply, tdd	/forge.implement	Execute the tasks with strict TDD by default (tests before implementation), updating task status in tasks.md as it goes and driving the breaker-guarded verify loop.
swarm	—	/forge.swarm	Wave-parallel alternative to implement, driven by tasks.md's Execution Graph. Classifies non-critical-path tasks to a specialist type (interface/logic/data/test/infrastructure), previews the dispatch plan and waits for confirmation, dispatches up to 5 subagents per wave, runs a consensus checkpoint between waves, then executes critical-path tasks itself, sequentially, in the main thread. Its own engine — not an alias of implement.
verify	—	CLI · /forge.verify	Validate the implementation against the spec's acceptance scenarios plus configured tests and lint, writing verify-report.md. Read-only as a plain command; arms the circuit-breaker with --change (see Harness).
archive	—	CLI · /forge.archive	Promote a finished change — merge its delta spec into canonical .forge/specs/ and move it into the dated, immutable changes/archive/YYYY-MM-DD-<name>/ trail. Blocked until every task is done.

Archive is gated on honesty

archive is blocked while any task is blocked or not done. A successful archive is a real signal that the change is finished and verified — it cannot be run to paper over incomplete work.

Two ways onto the spine: direct, or through the entry commands

Every spine phase is directly callable by name (/forge.propose, /forge.specify, …), but propose, specify, plan, and tasks expect a change that already has prior context — a proposal to write specs against, a spec to design against, and so on. In practice most people never call those four directly. Instead:

• /forge.new <description> starts a change and gets you to a proposal.
• /forge.continue then walks the rest of the spine one phase at a time, resolving whichever phase comes next on its own.
• /forge.ff <name> blasts through all four planning phases back-to-back when the direction is already clear.

Call propose/specify/plan/tasks directly when you already know the change name and want to redo a single phase — explore, clarify, implement, verify, and archive are the ones you will type by name most often. See Entry commands below.

Entry commands

Get onto the spine at the right phase for the change in hand.

Command	Aliases	Surface	Description
onboard	—	/forge.onboard	Guided walkthrough of a complete SDD cycle on a real change in your codebase — the fastest way to learn the spine hands-on.
new	sdd-new	/forge.new	Create a fresh change directory under .forge/changes/<name>/ and triage its depth — runs explore (if warranted) then propose.
ff	sdd-ff	/forge.ff	Fast-forward all four planning phases back-to-back — propose → specify → plan → tasks — for a change whose direction is already clear. Interactive mode pauses for confirmation after each phase; auto mode runs straight through. Not to be confused with the trivial-depth auto-fast-forward in adaptive triage, which skips planning entirely and jumps straight to implement → verify.
continue	sdd-continue	/forge.continue · CLI forge sdd-continue	Resume an in-flight change from wherever it left off — runs the next dependency-ready phase, one at a time. State lives in state.yaml, so a change survives context compaction and agent restarts.
status	—	/forge.status · CLI forge sdd-status	Print the phase rollup — what is done, what is next, per-task counts — that orchestrators route on. Read-only.

Cross-cutting

Callable at any time and non-destructive, so you can run them freely without disturbing an in-flight change. See The Workflow.

analyze, health, drift, board, and wireframe are deterministic terminal commands; wireframe is the only one of those with no slash-command form. The rest of this group are /forge.* agent skills only — there is no forge reconcile or forge refine binary command.

drift is two different engines depending on the surface

forge drift (CLI) and /forge.drift (agent skill) share a command name but not an engine — the same "share a name, not an engine" split as forge roadmap vs. /forge.roadmap below. forge drift is a deterministic, static-analysis-only classifier limited to exactly three categories: Ghost (code, no spec), Phantom (spec, no code), Mutated (they disagree) — fixed print order, plain-text output, same inputs always produce the same result. /forge.drift detects those same three plus a fourth, Inverted — an architecture/NFR contradiction that requires LLM judgment, not something static analysis can determine — and renders its own emoji legend (👻 Ghost, 👁 Phantom, 🔀 Mutated, 🔄 Inverted) instead of the CLI's plain text. See Drift and reconcile for what Inverted means and why it cannot be deterministic.

roadmap is two different things depending on the surface

forge roadmap (CLI) and /forge.roadmap (agent skill) share a name but not an engine — the same "share a name, not an engine" split as forge.design vs. sdd-design. forge roadmap is a deprecated CLI alias for forge board's deterministic, portfolio-wide phase-status matrix. /forge.roadmap is an LLM-driven, per-change skill that sequences one change's task execution graph into a value-first delivery order of vertical slices — it does not touch the CLI matrix at all. See its row below for details.

"Tier" means exactly one thing in forge-kit

The word "tier" refers to exactly one concept: the 🟢/🟡/🟠/🔴 task-complexity marker on each tasks.md line (see the tasks row above). health's HIGH/MEDIUM/LOW/UNKNOWN risk classification (row below) and the dashboard's derived urgency ranking are related-sounding but unrelated concepts — neither is a "tier," and none of the three currently render on the same screen.

Command	Aliases	Surface	Description
analyze	—	CLI · /forge.analyze	Score spec quality on a reproducible 100-point scale — a single <spec-path> or the whole .forge/specs portfolio. Read-only unless --save; --json for machine output. Constitution conflicts cap the score.
health	—	CLI · /forge.health	Portfolio-wide risk dashboard: every active change's phase progress, verify state, and a HIGH/MEDIUM/LOW/UNKNOWN risk classification, plus a prioritized action list. Read-only unless --save. Its own engine — not a rollup of analyze.
estimate	—	CLI · /forge.estimate	Idempotent refresh of tasks.md's Execution Graph — recomputes waves, blockers, critical path, and hour estimates from the checklist's current tiers, and replaces only that JSON block. Never touches task descriptions or tiers; running it twice with no checklist changes is a no-op.
drift	—	CLI · /forge.drift	Detect code-vs-spec disagreement. The CLI deterministically classifies it into three categories — Ghost (code, no spec), Phantom (spec, no code), Mutated (they disagree); the skill additionally detects a fourth, judgment-based Inverted category. See the warning above for the split.
reqid check	—	CLI · /forge.reqid	Advisory scan of requirement IDs across .forge/specs and the active change: flags malformed IDs, duplicates, and IDs whose area prefix does not match the spec domain they live in. Reports only — it never rewrites an ID and never returns a blocking exit code.
reconcile	—	/forge.reconcile	The remedy for drift — bring code and specs back into agreement, walking each conflict interactively.
refine	—	/forge.refine	Improve an existing artifact in place — tighten a spec, design, or task list without starting a new change.
pseudocode	—	/forge.pseudocode	Draft pseudocode for a task before implementation.
checklist	—	/forge.checklist	Generate a review checklist for the current work.
tests	—	/forge.tests	Generate failing red-phase tests straight from the spec's Given/When/Then scenarios, mapped to their REQ-<AREA>-NNN requirement and classified contract/integration/unit. Never overwrites an existing test file — appends only new, non-duplicate tests — and writes test-coverage.md. Its own engine — not an alias of implement.
levelup	—	/forge.levelup	Suggest project-wide improvements.
discover	—	/forge.discover	Survey the codebase for existing capabilities.
export	—	/forge.export	Emit artifacts for use elsewhere.
taskstoissues	—	/forge.taskstoissues	Push tasks.md items into an external issue tracker.
brainstorm	—	/forge.brainstorm	Open-ended, unstructured ideation.
board	—	CLI	Derive the phase-status board from the active changes — one row per change, one column per SDD phase — and print it as markdown. Read-only; --write also saves .forge/board.md. The CLI forge roadmap alias is a deprecated name for this same command (prints a deprecation notice, defaults --write to the legacy .forge/roadmap.md path) — it is unrelated to the /forge.roadmap skill below.
roadmap	—	/forge.roadmap	Per-change value-first delivery sequencing, not the CLI matrix above. Reads the active change's tasks.md execution graph (waves/critical_path/blockers) and spec.md requirements, groups waves into vertical slices that each deliver one independently testable/usable capability, and sequences those slices by value/testability first, then context locality, always respecting blockers as a hard constraint. Writes .forge/changes/{change}/roadmap.md. Propose-and-confirm by default. Never presents dates, durations, or invented estimates.
wireframe	—	CLI only	Per-spec UI detection and deterministic wireframe scaffolding: reads <spec-path>, decides whether it describes a UI (keyword heuristic, overridable with --ui / --no-ui), and embeds a managed ## Wireframe section (ASCII + Mermaid) into the spec.

wireframe writes into the spec

Every other command in this group is read-only. wireframe is the exception — it injects a managed section into the target spec using the same replace-or-append-once mechanism Forge uses for all managed blocks, so re-running it is idempotent rather than additive.

Harness

Runtime guardrails around the implement → verify loop. The enforced gates return a non-zero exit to stop a runaway loop; a host hook or CI step reads that exit and halts. The four enforced controls are verify (circuit-breaker), budget (spend ceiling), secscan, and the review delivery gates. trace, docs, docsite, panel, metrics, and mcp serve are observe-only and never block. run drives the loop itself and obeys those gates rather than adding a new one. See the harness overview.

Command	Aliases	Surface	Description
verify --change <c>	—	CLI · /forge.verify	Verify a named change under the circuit-breaker: a single FAIL exits 0 but increments the breaker; N consecutive failures (--max-failures N, else workflow.breaker_threshold in config, else 3) return non-zero so the loop stops. State in changes/<c>/verify-attempts.yaml; clear with --reset-breaker. Add --isolated to run the configured tests, lint, and spec read against an ephemeral copy of the working tree, so a destructive test cannot damage uncommitted work — it isolates the filesystem working tree only, not processes, network, or $HOME, and it requires a git repository.
budget record|check|reset	—	CLI · /forge.budget	Enforce a per-change spend ceiling against changes/<c>/budget.yaml. record accumulates reported spend and returns non-zero the moment a ceiling — a --max-* flag, else the matching budget.* config key — is strictly crossed; check is the read-only verdict; reset clears it.
secscan scan|waive|reset	—	CLI · /forge.secscan	Enforced static gate: scan flags leaked secrets, PII, and prompt-injection strings and returns non-zero on any unwaived finding; waive accepts one by fingerprint; reset clears findings. Scope with --path, --min-severity.
trace record|show	—	CLI · /forge.trace	Per-change session event timeline in changes/<c>/session-log.jsonl. The breaker and budget gate emit into it automatically; record your own events, show the log. Observe-only — never a gate.
docs build|serve	—	CLI · /forge.docs	build renders the offline, read-only spec-viewer from .forge/ (--publish emits a Pages-ready public/). serve runs the embedded, interactive web control panel on 127.0.0.1:4321 — it can also run verify, archive, and clear gates.
docsite install|dev|build|publish	—	CLI only	Two families under one noun. install/dev/build work on the generator Forge installs into .forge/ itself: install scaffolds it, dev execs its dev server in the foreground, build runs its static build — one generated config, shared by both. publish renders forge's .forge/ state into a public documentation site you already own (VitePress, Docusaurus, Starlight, Mintlify, MkDocs) — distinct from docs, which renders forge's internal dashboard, and from install's own site. publish always derives fresh from .forge/specs|changes first, then writes the site with ownership tracking; --source-only stops after staging, before any render. See Documentation Site Generator.
panel	—	CLI only	Launch the observe-only lifecycle control panel as a TUI — it reads state and never mutates it.
hook post-tool-use	—	CLI only	The live-agent feeder: your coding host calls it after each tool use, passing the hook payload on stdin, so real activity lands in the timeline and budget. Best-effort and deliberately fast and silent — it never triggers detection or self-update. See Connect a live agent.
review start|finalize|validate	—	CLI only	Bounded review lifecycle producing a content-bound receipt: start opens against current scope, finalize records lens results and evidence, validate --gate <gate> checks the receipt against a delivery gate and returns non-zero when the tree no longer matches.
metrics	—	CLI · /forge.metrics	Roll up the harness state Forge already records — verify pass rate and breaker activity, budget spend, secscan waivers, and timeline volume — across every change, to answer whether the harness is actually working. Read-only; --json for machine output. See Harness Metrics.
mcp serve	—	CLI · /forge.mcp	Serve the read-oriented harness commands as MCP tools over a stdio JSON-RPC session, so an agent can query the gates directly. Queryable, not enforcing — a gate's refusal comes back as readable data; enforcement stays with the non-zero exits hooks and CI read. See Harness as MCP.
run	—	CLI only	The bounded autonomous loop: drive an executor across repeated iterations and stop the moment an enforced gate opens. Dry run is the default — the plan prints and nothing executes without --yes. Bounded by --max-iterations (default 5, hard cap 50). Forge supplies no model: you name the command that performs one iteration with --cmd. See Autonomous run.

Enforced gates block with a non-zero exit

verify --change, budget, secscan, and review validate are the controls that fail closed. When one returns non-zero, the loop must stop and escalate to a human — do not retry past it.

forge verify --change c1                 # FAIL exits 0, breaker 1/3
forge verify --reset-breaker --change c1 # clear after intervening
forge budget record --change checkout --tokens 600 --max-tokens 1000
forge secscan scan  --change checkout --path leak.txt
forge secscan waive --change checkout --fingerprint 0c9ab6bbabac
forge docs build --out public --publish
forge docsite install --target vitepress
forge docsite publish --target vitepress --out site
forge review validate --gate pre-commit
forge run --change checkout --cmd 'claude -p "implement the next open task"'
forge run --change checkout --cmd '...' --max-iterations 3 --yes

forge run executes nothing without --yes

The first form above prints the plan — iterations, executor, gates — and exits without running anything. That is the default and deliberate posture. --yes arms it, --max-iterations bounds it (default 5, never above 50), and any enforced gate opening stops the loop and returns non-zero for a human to pick up. Forge ships no model of its own: whatever you pass to --cmd is the thing that does the work.

Foundation

Standing project truth — run once. These phases set the ground rules the spine operates within, rather than describing a single change. See The Workflow.

constitution, security, and infra are authored entirely through their /forge.* agent skills — there is no forge constitution, forge security, or forge infra terminal command. Only brand and design have deterministic forge seed commands, which write a starter file for the agent to author into.

Command	Aliases	Surface	Description
constitution	—	/forge.constitution	Capture the project's non-negotiable principles and constraints. Load-bearing: conflicts against it cap your analyze score, so keep it current.
security	—	/forge.security	Define the security posture and requirements the spine validates against.
infra	—	/forge.infra	Define the infrastructure baseline that deployment artifacts derive from.
brand	—	CLI (seed) · /forge.brand	Define brand identity and voice; forge brand seeds .forge/design/brand.md, then /forge.brand authors it.
design	—	CLI (seed) · /forge.design	Define the design system and conventions; forge design seeds the files under .forge/design/, then /forge.design authors them.

Run these first, revisit rarely

Foundation phases establish standing truth. You run them once at project setup and update them only when the ground rules genuinely change — not per change.

Platform

Migration, memory, skills, repo and workspace detection, delivery, and review plumbing.

Command	Aliases	Surface	Description
import	—	CLI · /forge.import	Migrate an existing Spec-Kit (.specify) or OpenSpec (openspec) project into .forge/, non-destructively. Unmapped content lands losslessly in .forge/_imported/; site/ and scripts/ are skipped unless --include-generated.
migrate	—	CLI · /forge.migrate	Bring an existing .forge/changes/{name}/ folder created by an older forge-kit version up to date with the current artifact conventions (e.g. design.md → plan.md). Non-destructive, snapshotted, and idempotent — preview with --dry-run.
memory save|search|context|sync	—	CLI only	Manage project memory — the committable Engram team-sync export under .forge/memory/, so accumulated context travels with the repo and every teammate benefits.
recall	—	CLI · /forge.recall	Advisory reader over memory: surfaces prior specs and decisions relevant to a change's intent to inform explore and specify. Not a gate — never blocks.
skill-registry refresh	—	CLI only	Rebuild .forge/skill-registry.md (the resolved set of skills the engine can delegate to) with a cache-hit fast path; list prints it.
skill-discover	—	CLI · /forge.skill-discover	Two different tools sharing a name, not an engine. forge skill-discover (CLI) searches external sources (skills.sh, community git registries) and installs into .forge/skills/. /forge.skill-discover (agent skill) is local-only and never installs anything — it profiles the project's stack and the active change's spec.md/tasks.md, matches against Forge's own embedded skill catalog, and suggests what might help; enabling a suggestion is a separate, explicit step.
agent-build	—	CLI · /forge.agent-build	Author a new skill/agent Markdown file from a description, validate it (a missing ## Rules section is rejected), and install it across every configured agent adapter. The /forge.agent-build skill fronts the same CLI with a one-question-at-a-time interview and an explicit preview-then-confirm step before anything is written.
profile	—	CLI · /forge.profile	Read-only report of the repo-adaptivity profile Forge derives for this repo: detected stack, configured test/lint commands, git-hosting provider, size bucket, related repos, and which skills are relevant vs. skippable. Writes nothing.
provider	—	CLI · /forge.provider	Read-only report of the git-hosting provider Forge resolves for this repo (and any related repos), tying the provider adapters to the repo: section of .forge/config.yaml. It detects and reports — it never writes or calls a host API. Its one subcommand is show, which is also the default: forge provider and forge provider show are the same command.
deliver	—	CLI · /forge.deliver	Open a merge/pull request for a completed change provider-natively — the host resolved by provider supplies the argv, so the same command drives glab mr and gh pr. Refuses an incomplete change, mirroring archive, unless --allow-incomplete. Preview with --dry-run; --workspace delivers in every workspace repo carrying the change, each in isolation.
issues create	—	CLI only	Export the change's tasks.md to the resolved provider as one issue per not-yet-done task. --dry-run prints the exact commands without running them; --label tags them; --workspace runs the same export in every workspace repo carrying the change.
workspace	—	CLI · /forge.workspace	Read-only report of this repo plus every sibling under repo.related — each one's provider, location, and active changes — followed by the changes that span more than one repository. --change <c> instead reports which repos carry that change.
extension	—	CLI only	Manage third-party extensions against the embedded offline catalog: list, search, info, add, remove, update, enable, disable. add takes a catalog id, or a URL/path to install directly, bypassing the catalog.
codegraph init	—	CLI only	Initialize the codebase-graph provider for this project (--cwd <project-root>). A deliberately narrow, Forge-owned boundary used by generated agent guidance — it accepts no raw provider arguments.
learn extract|review|promote|reset	—	CLI · /forge.learn	The continuous-learning ledger: extract mines a change's session log and diff for recurring patterns, review lists the candidates, promote writes eligible ones into memory (human-gated — requires --approve), reset clears the ledger. Advisory, never a gate — it never returns a blocking exit code.

Next steps

• The Workflow — the phases these commands drive.
• The forge CLI — the terminal binary, real flags, and exit codes.
• Components — agents, skills, and personas the commands install.
• Configuration — tune command behavior.
• Project Structure — where commands write under .forge/.
• Harness overview — the runtime guardrails and enforced gates.