Chapter 7
CLI Reference
Every command, every flag, every example. The chapter you bookmark.
Overview
The pforge CLI is a convenience wrapper — two scripts, no dependencies beyond Git and your shell. Every command shows the equivalent manual steps, so non-CLI users can follow along.
| Platform | File | Usage |
|---|---|---|
| Windows / PowerShell | pforge.ps1 | .\pforge.ps1 <command> |
| macOS / Linux / Bash | pforge.sh | ./pforge.sh <command> |
Not there? Both scripts are copied to your project root during
setup.ps1 / setup.sh. If they're missing, copy them manually from the Plan Forge repo.
analyze vs diagnose — which do I use?
One tells you if your blueprint is solid. The other finds out why the bridge collapsed.
Use analyze after hardening a plan. Use diagnose when a slice fails.
pforge analyze scores a plan's quality (traceability, coverage, gates — 0 to 100).pforge diagnose investigates a bug in code (root cause, fix recommendations).One tells you if your blueprint is solid. The other finds out why the bridge collapsed.
Use analyze after hardening a plan. Use diagnose when a slice fails.
Commands
pforge init
Bootstrap a project with the Plan Forge Pipeline. Delegates to
setup.ps1 / setup.sh.| Flag | Type | Description |
|---|---|---|
-Preset | string | Tech preset: dotnet, typescript, python, java, go, swift, rust, php, azure-iac. Comma-separated for multi-preset. |
-ProjectPath | path | Target project directory (default: current dir) |
-Agent | string | Agent adapter: copilot, claude, cursor, codex, gemini, windsurf, generic, all |
Bootstrap a project
.\pforge.ps1 init -Preset dotnet
.\pforge.ps1 init -Preset typescript -ProjectPath ./my-app
.\pforge.ps1 init -Preset dotnet -Agent allBash equivalent
./pforge.sh init --preset dotnet
./pforge.sh init --preset typescript --path ./my-app
./pforge.sh init --preset dotnet --agent allEquivalent manual steps
- Run
.\setup.ps1/./setup.shwith your preferred parameters - Follow the interactive wizard
pforge check
Validate that setup completed correctly. Delegates to
validate-setup.ps1 / validate-setup.sh.PowerShell / Bash
pforge checkEquivalent manual steps
- Run
.\validate-setup.ps1 - Review the output for any missing files
pforge status
Show all phases from
DEPLOYMENT-ROADMAP.md with their current status.PowerShell / Bash
pforge statusExample output
Phase Status (from DEPLOYMENT-ROADMAP.md):
─────────────────────────────────────────────
Phase 1: User Authentication 📋 Planned
Phase 2: Dashboard Widgets 🚧 In Progresspforge new-phase <name>
Create a new phase plan file and add an entry to the deployment roadmap.
| Arg / Flag | Type | Description |
|---|---|---|
name | string (required) | Phase name, e.g. user-auth |
--dry-run | boolean | Preview without creating |
PowerShell
.\pforge.ps1 new-phase user-auth --dry-run
.\pforge.ps1 new-phase user-authWhat it does
- Finds the next phase number (e.g., Phase 3)
- Creates
docs/plans/Phase-3-USER-AUTH-PLAN.mdfrom template - Adds a Phase 3 entry to
DEPLOYMENT-ROADMAP.md
pforge branch <plan-file>
Create a Git branch matching the plan's declared Branch Strategy.
| Arg / Flag | Type | Description |
|---|---|---|
plan | path (required) | Path to plan file |
--dry-run | boolean | Preview without creating |
PowerShell
.\pforge.ps1 branch docs/plans/Phase-3-USER-AUTH-PLAN.md --dry-run
.\pforge.ps1 branch docs/plans/Phase-3-USER-AUTH-PLAN.md
CLI-only — not available as MCP tool. Use via terminal.
pforge commit <plan-file> <slice-number>
Stage all changes and commit with a conventional commit message derived from the slice's goal.
| Arg / Flag | Type | Description |
|---|---|---|
plan | path (required) | Path to plan file |
slice | number (required) | Slice number |
--dry-run | boolean | Preview commit message without committing |
PowerShell
.\pforge.ps1 commit docs/plans/Phase-3.md 2 --dry-run
.\pforge.ps1 commit docs/plans/Phase-3.md 2
CLI-only — not available as MCP tool.
pforge phase-status <plan-file> <status>
Update a phase's status in the deployment roadmap.
| Arg | Type | Description |
|---|---|---|
plan | path (required) | Path to plan file |
status | enum (required) | planned · in-progress · complete · paused |
PowerShell
.\pforge.ps1 phase-status docs/plans/Phase-3.md in-progress
.\pforge.ps1 phase-status docs/plans/Phase-3.md complete
CLI-only — not available as MCP tool.
pforge sweep
Scan all code files for deferred-work markers: TODO, FIXME, HACK, stub, placeholder, mock data.
PowerShell / Bash
pforge sweepExample output
Completeness Sweep — scanning for deferred-work markers:
─────────────────────────────────────────────────────────
src/Services/UserService.cs:42: // TODO: Wire to real email service
src/Controllers/AuthController.cs:18: // FIXME: Add rate limiting
FOUND 2 deferred-work marker(s). Resolve before Step 5 (Review Gate).Also available as: forge_sweep MCP tool
pforge diff <plan-file>
Compare changed files against the plan's Scope Contract. Flags forbidden files, unplanned files, and confirms in-scope changes.
PowerShell
.\pforge.ps1 diff docs/plans/Phase-3-USER-AUTH-PLAN.mdExample output
Scope Drift Check — 4 changed file(s) vs plan:
──────────────────────────────────────────────────
✅ IN SCOPE src/Services/UserService.cs
✅ IN SCOPE src/Repositories/UserRepository.cs
🟡 UNPLANNED src/Config/AppSettings.cs
🔴 FORBIDDEN tests/Legacy/OldTests.cs
DRIFT DETECTED — 1 forbidden file(s) touched.Also available as: forge_diff MCP tool
pforge analyze <plan-file>
Cross-artifact consistency scoring — validates traceability, scope coverage, test coverage, and gate definitions. Scores 0–100.
| Flag | Type | Description |
|---|---|---|
--quorum | boolean | Multi-model consensus analysis |
--mode | plan | file | Explicit analysis mode (auto-detected if omitted) |
--models | string | Comma-separated model override |
Analyze plan consistency
# Single-model analysis
.\pforge.ps1 analyze docs/plans/Phase-1-AUTH-PLAN.md
# Multi-model quorum
.\pforge.ps1 analyze docs/plans/Phase-1-AUTH-PLAN.md --quorum
# Analyze a code file directly
.\pforge.ps1 analyze src/services/billing.ts --mode fileScoring Dimensions
| Dimension | Points | What It Checks |
|---|---|---|
| Traceability | 25 | MUST/SHOULD criteria exist, slices defined, criteria mapped to slices |
| Coverage | 25 | Changed files within Scope Contract, no forbidden edits |
| Test Coverage | 25 | MUST criteria matched against test files via keyword fuzzy matching |
| Gates | 25 | Validation gates referenced in slices, no deferred-work markers |
Exit codes: 0 = pass (≥60), 1 = fail (<60). Also available as: forge_analyze MCP tool.
pforge diagnose <file>
Multi-model bug investigation — dispatches file analysis to multiple AI models independently, then synthesizes root cause analysis with fix recommendations.
| Flag | Type | Description |
|---|---|---|
--models | string | Comma-separated model override |
Investigate a bug
.\pforge.ps1 diagnose src/services/billing.ts
.\pforge.ps1 diagnose src/auth/token-validator.ts --models grok-3-mini,grok-4Each model analyzes independently for: root cause, failure modes, reproduction steps, impact assessment, fix recommendations, regression risk.
Output saved to: .forge/analysis/diagnose-*. Also available as: forge_diagnose MCP tool.
pforge run-plan <plan-file>
Execute a hardened plan — spawn CLI workers for each slice, validate at every boundary, track tokens and cost.
| Flag | Type | Default | Description |
|---|---|---|---|
--estimate | boolean | — | Cost prediction only, no execution |
--assisted | boolean | — | Human codes, orchestrator validates gates |
--model | string | — | Model override (e.g., claude-sonnet-4.6) |
--resume-from | number | — | Skip completed slices, resume from N |
--dry-run | boolean | — | Parse and validate without executing |
--quorum | boolean | auto | — | Force quorum on all slices, or auto for threshold-based |
--quorum-threshold | number | 6 | Complexity threshold for auto quorum (1–10) |
Execute a plan (5 modes)
# Estimate cost without executing
.\pforge.ps1 run-plan docs/plans/Phase-7.md --estimate
# Full auto execution
.\pforge.ps1 run-plan docs/plans/Phase-7.md
# Assisted mode
.\pforge.ps1 run-plan docs/plans/Phase-7.md --assisted
# Resume from slice 3 after fixing a failure
.\pforge.ps1 run-plan docs/plans/Phase-7.md --resume-from 3
# Quorum mode with custom threshold
.\pforge.ps1 run-plan docs/plans/Phase-7.md --quorum=auto --quorum-threshold 8Execution Modes
| Mode | Flag | What Happens |
|---|---|---|
| Full Auto | (default) | gh copilot CLI executes each slice with full project context |
| Assisted | --assisted | You code in VS Code; orchestrator prompts and validates gates |
| Estimate | --estimate | Shows slice count, token estimate, and cost — without executing |
Results written to: .forge/runs/<timestamp>/. Also available as: forge_run_plan MCP tool.
pforge smith
Inspect your forge — diagnose environment, VS Code config, setup health, version currency, and common problems. Every issue includes a
FIX: suggestion.PowerShell / Bash
pforge smithWhat The Smith Checks
| Category | Checks |
|---|---|
| Environment | git, VS Code CLI, PowerShell/bash version, GitHub CLI |
| VS Code Config | chat.agent.enabled, chat.useCustomizationsInParentRepositories, chat.promptFiles |
| Setup Health | .forge.json valid, copilot-instructions.md exists, file counts match preset |
| Version Currency | Installed templateVersion vs source VERSION |
| Common Problems | Duplicate instructions, orphaned agents, missing applyTo, unresolved placeholders |
Also available as: forge_smith MCP tool.
pforge ext <subcommand>
Extension management — browse, install, remove, and publish guardrail extensions.
| Subcommand | Description |
|---|---|
ext search [query] | Browse the community catalog. Omit query for all extensions. |
ext add <name> | Download and install from catalog in one step. |
ext info <name> | Show detailed info before installing. |
ext install <path> | Install from a local directory path. |
ext list | List all installed extensions. |
ext remove <name> | Remove an installed extension. |
ext publish <path> | Generate a catalog entry for submission via PR. |
Manage extensions
.\pforge.ps1 ext search saas
.\pforge.ps1 ext add saas-multi-tenancy
.\pforge.ps1 ext info plan-forge-memory
.\pforge.ps1 ext list
.\pforge.ps1 ext remove healthcare-compliance
.\pforge.ps1 ext publish .forge/extensions/my-extensionAlso available as: forge_ext_search, forge_ext_info MCP tools.
pforge update [source-path]
Update framework files from a Plan Forge source without re-running the full setup wizard. Preserves all user-customized files.
| Flag | Type | Description |
|---|---|---|
source | path (optional) | Plan Forge source path (auto-detects ../plan-forge) |
--dry-run | boolean | Preview changes without applying |
--force | boolean | Skip confirmation prompt |
Update framework files
.\pforge.ps1 update
.\pforge.ps1 update C:\path\to\plan-forge --dry-run
.\pforge.ps1 update --forceWhat Gets Updated vs Protected
| Updated (safe to replace) | Never Touched (your files) |
|---|---|
| Pipeline prompts, agents, shared instructions, runbook, lifecycle hooks, new preset files | copilot-instructions.md, project-profile, project-principles, DEPLOYMENT-ROADMAP.md, .forge.json, plan files, existing preset files |
Bootstrapping from older versions: If your
pforge.ps1 doesn't have the update command yet (pre-v1.2.1), download the latest script first, then run pforge update.
pforge help
Show help — list all available commands with one-line descriptions.
PowerShell / Bash
pforge helpMCP Server Commands
The MCP server is started directly with Node.js, not through the pforge CLI:
node pforge-mcp/server.mjs
Start the full stack: MCP (stdio) + Express (HTTP on 3100) + WebSocket (3101). Use with
.vscode/mcp.json for auto-start.Terminal
# Full MCP server (normal usage — started by VS Code via mcp.json)
node pforge-mcp/server.mjs
# Dashboard + REST API only (no MCP stdio)
node pforge-mcp/server.mjs --dashboard-only
# Custom project path
node pforge-mcp/server.mjs --project /path/to/projectFull Reference
This chapter covers the happy path for each command. For exhaustive edge-case documentation, see the full source: CLI-GUIDE.md