Hacker's terminal screen with glowing amber command glyphs and forge-spark effects on a slate-black background

Chapter 8

CLI Reference

Every command, every flag, every example. The chapter you bookmark.

📖 Reference Section
You've built your first feature. Chapters 7–14 are reference material, you don't need to read them in order. Jump to whichever chapter answers your current question, then return to building.

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?
pforge analyze scores a plan's quality (traceability, coverage, gates, 0 to 100).
pforge diagnose (or the forge_diagnose MCP tool) 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.

I'm Trying To…

Most people don't need every command. Find your use case, run the matching command:

Goal	Command	When
Setup & daily housekeeping
Set up a new project	`pforge init`	First time on this repo
Check setup is healthy	`pforge smith`	Before reporting a bug; after upgrading
Validate file counts and templates	`pforge check`	Before committing setup changes
Update framework files	`pforge update`	After a new Plan Forge release
Planning & authoring
Start a new feature plan	`pforge new-phase <name>`	You have a feature in mind
Score a plan's quality before running it	`pforge analyze <plan>`	Right after hardening
See what files changed vs the plan's scope	`pforge diff <plan>`	Mid-execution; before commit
Find leftover TODO/FIXME/HACK markers	`pforge sweep`	Before declaring a slice done
Execution
Estimate cost before running	`pforge run-plan <plan> --estimate`	You want to know what this will cost first
Run a plan end-to-end (cheapest)	`pforge run-plan <plan>`	Plan is hardened and you trust it
Run with multi-model consensus	`pforge run-plan <plan> --quorum=auto`	High-stakes feature; complex slices
Resume after a failed slice	`pforge run-plan <plan> --resume-from N`	You fixed slice N−1's failure
Co-pilot mode (you code, gates check)	`pforge run-plan <plan> --assisted`	You want to write the code yourself
Troubleshooting
Investigate a failing slice	`pforge diagnose <file>`	Slice failed and you don't know why
Run closed-loop drain	`pforge audit-loop`	Mass content audit (opt-in feature)
See chronological event history	`pforge timeline`	Forensic / "what happened on Tuesday?"
Post-deploy (LiveGuard)
Score code drift since baseline	`pforge drift`	After every deploy
Scan for high-entropy secrets	`pforge secret-scan`	Before every deploy (blocking)
Scan dependencies for CVEs	`pforge dep-watch`	Daily / before deploy
Compute health score 0–100	`pforge health-trend`	Weekly / on alert

Full command reference below, organized alphabetically. Each entry has the equivalent manual steps for non-CLI users.

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 all

Bash equivalent

./pforge.sh init --preset dotnet
./pforge.sh init --preset typescript --path ./my-app
./pforge.sh init --preset dotnet --agent all

Equivalent manual steps

Run .\setup.ps1 / ./setup.sh with 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 check

Equivalent 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 status

Example output

Phase Status (from DEPLOYMENT-ROADMAP.md):
─────────────────────────────────────────────
  Phase 1: User Authentication  📋 Planned
  Phase 2: Dashboard Widgets    🚧 In Progress

pforge 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-auth

What it does

Finds the next phase number (e.g., Phase 3)
Creates docs/plans/Phase-3-USER-AUTH-PLAN.md from 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 sweep

Example 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.md

Example 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. With --quorum or --models, runs a multi-model review instead, of a plan or a source file.

Flag	Type	Description
`--quorum[=<preset>]`	boolean \| preset	Multi-model consensus review instead of the score; the preset is `power`, `speed` or `power-gov`. Spends tokens; the report is saved to `.forge/analysis/`
`--mode`	plan \| file	Analysis mode. Defaults to `plan` for `.md`/`.markdown` files and `file` otherwise; `file` needs `--quorum`
`--models`	string	Comma-separated model override; implies `--quorum`

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

# Multi-model code review of a source file
.\pforge.ps1 analyze src/services/billing.ts --quorum=power

Scoring 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); with --quorum, 0 when the review completes. 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. Also available as the forge_diagnose MCP tool for Copilot Chat or any MCP client.

Flag / parameter	Type	Description
`--quorum=<preset>` (CLI)	preset	`power`, `speed` or `power-gov` (default: quorum config)
`file` (required)	string	Path to the source file to investigate (e.g., `src/services/billing.ts`)
`models`	string	Comma-separated model override (default: quorum config models)
`path`	string	Project directory (default: current)

Investigate a file

.\pforge.ps1 diagnose src/services/billing.ts
.\pforge.ps1 diagnose src/auth/token-validator.ts --models grok-4.20-0309-non-reasoning,grok-4.7

# From Copilot Chat
forge_diagnose({ file: "src/services/billing.ts" })
forge_diagnose({ file: "src/auth/token-validator.ts", models: "grok-4.20-0309-non-reasoning,grok-4.7" })

Each model analyzes independently for: root cause, failure modes, reproduction steps, impact assessment, fix recommendations, regression risk. The CLI saves the report to .forge/analysis/diagnose-*; the MCP tool returns it inline to the calling agent.

Reference: pforge-mcp/tools.json » forge_diagnose. Adjacent CLI command: pforge analyze for plan quality.

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. Always backed by `forge_estimate_quorum`, never hand-computed.
`--assisted`	boolean	—	Human codes, orchestrator validates gates
`--model`	string	—	Model override (e.g., `gpt-6-sol`)
`--resume-from`	number	—	Skip completed slices, resume from N
`--dry-run`	boolean	—	Parse and validate without executing
`--quorum`	auto \| power \| speed \| false	`auto`	Quorum preset. `auto`: threshold-based escalation. `power`: flagship models, threshold 5 (premium tier). `speed`: fast models, threshold 7. `false`: disable.
`--quorum-threshold`	number	6	Override the complexity threshold for auto-quorum (1–10). Implied by `--quorum=power\|speed`.

Execute a plan (5 modes)

# Estimate cost without executing (always tool-backed via forge_estimate_quorum)
.\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 presets (v2.82)
.\pforge.ps1 run-plan docs/plans/Phase-7.md --quorum=power     # flagship models, threshold 5
.\pforge.ps1 run-plan docs/plans/Phase-7.md --quorum=speed     # fast models, threshold 7
.\pforge.ps1 run-plan docs/plans/Phase-7.md --quorum=auto --quorum-threshold 8

Execution Modes

Mode	Flag	What Happens
Full Auto	(default)	`gh copilot` CLI executes each slice with full project context. Routing honors a host-aware preference so non-Copilot hosts (Claude Code, Cursor, Windsurf, Zed) prefer direct API to honor your subscription.
Assisted	`--assisted`	You code in VS Code; orchestrator prompts and validates gates
Estimate	`--estimate`	Shows slice count, token estimate, and cost, without executing. Returns the same numbers as the `forge_estimate_quorum` tool.

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 smith

What 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-extension

Also 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. Guidance files you have edited are kept.

Flag	Type	Description
`source`	path (optional)	Plan Forge source path (auto-detects `../plan-forge`)
`--dry-run`	boolean	Preview changes without applying
`--yes`, `-y`	boolean	v3.31.2+ — Skip the confirmation prompt (for unattended runs)
`--force`	boolean	Skip the confirmation prompt and apply the update even when the source is the version you already have
`--overwrite-customized`	boolean	v3.28.0+ — Also replace guidance files you edited. Each one is copied to `.forge/update-backups/<timestamp>/` first.

Update framework files

.\pforge.ps1 update
.\pforge.ps1 update C:\path\to\plan-forge --dry-run
.\pforge.ps1 update --force
.\pforge.ps1 update --overwrite-customized

What Gets Updated vs Protected

Updated (safe to replace)	Never Touched (your files)
Pipeline prompts, agents, shared instructions, runbook, lifecycle hooks, preset files. A stack preset's own copy of a shared instruction (for example `testing` or `security`) is used instead of the shared one.	`copilot-instructions.md`, project-profile, project-principles, `DEPLOYMENT-ROADMAP.md`, `.forge.json`, plan files

Guidance files you edited

Since v3.28.0, instruction, prompt, agent, skill, hook and runbook files are replaced only when your copy matches a version Plan Forge shipped. Setup's substitutions (project name, stack and setup date from .forge.json) are taken into account and filled in again on updated files, including files an older updater left with raw placeholders.

If you edited a file, update keeps your copy, lists it as KEEP, and writes the new version to .forge/update-pending/<path> so you can merge what you want. Run with --overwrite-customized to take the new versions anyway; each replaced file is backed up to .forge/update-backups/<timestamp>/<path> first.

Review the kept files with pforge pending, which pforge smith also reminds you about while any remain:

pforge pending lists them with their age.
pforge pending diff <path> compares your copy with the new version.
pforge pending apply <path> --yes takes the new version and backs your copy up to .forge/update-backups/.
pforge pending discard <path> --yes keeps your copy.

Use --all instead of a path to act on every file. Without --yes, apply and discard only show what they would do.

Files a release removed

Since v3.31.2, update also lists files in pforge-mcp/, pforge-master/ and pforge-sdk/ that the new release no longer ships as REMOVE, and moves them to .forge/update-backups/<timestamp>/ when it applies. Installed dependencies, .forge/, lockfiles, logs and .env files in those folders are never touched.

Updating to v3.28.0 from an older version: the update runs the script you already have, so this protection starts with the first update after v3.28.0. If you have edited guidance files, commit before updating so you can review and restore them with git, or replace pforge.ps1 / pforge.sh with the v3.28.0 copy first and then run the update.

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 self-update

Check GitHub for the latest Plan Forge release and install it. Composes with pforge update under the hood; refreshes the consumer .gitignore managed block (v3.15.1+) and invalidates the version-check cache so the next pforge smith doesn't show a stale "update available" banner.

Flag	Type	Description
`--yes`, `-y`	boolean	Skip the "Install vX.Y.Z now? [Y/n]" confirmation prompt. Before v3.31.2, the update it started still asked its own question and, with nobody to answer, cancelled; on those versions run `pforge self-update --yes --force` unattended
`--dry-run`	boolean	Print what would happen (target tag, downgrade detection) without writing anything
`--force`	boolean	Heal an already-current install — reinstalls the latest tagged release even when the local VERSION matches. Useful when a corrupt `-dev` tarball needs replacing
`--downgrade`	boolean	Required with `--force` when the latest release is OLDER than the local version (e.g. recovering from a manual VERSION edit). Without it, `self-update` refuses to silently downgrade.
`--verify`	boolean	v3.20.0+ — After a successful update, runs `pforge check` and `pforge smith` in subprocesses against the freshly-installed wrapper. Exits non-zero if either fails. Composes with every other flag.
`--overwrite-customized`	boolean	v3.28.0+ — Passed to `pforge update`: also replace guidance files you edited, backing each one up first.

Common combinations

pforge self-update                              # interactive — prompts before installing
pforge self-update --yes                        # unattended (CI, scripts)
pforge self-update --dry-run                    # preview only
pforge self-update --force                      # heal a corrupt install
pforge self-update --force --downgrade          # explicit roll-back (rare)
pforge self-update --verify                     # update + check + smith
pforge self-update --yes --verify               # unattended with verification
pforge self-update --force --verify             # heal + verify

Why --verify spawns subprocesses: When pforge.ps1 / pforge.sh are updated in-place, the running shell still has the OLD wrapper code loaded in memory (Issue #177). --verify shells out to pwsh -File pforge.ps1 check / bash pforge.sh check so the just-installed wrapper is the one that does the verification.

pforge help

Show help, list all available commands with one-line descriptions.

PowerShell / Bash

pforge help

pforge audit-loop v2.80+

Run a closed-loop audit drain (scan → triage → fix) until convergence. Off by default; opt in via .forge.json → audit.mode = "auto" | "always", or use --auto to respect the config.

Flag	Type	Default	Description
`--auto`	boolean	—	Respect `.forge.json#audit.mode`, skip cleanly if `off`
`--max`	number	5	Maximum drain rounds before terminating
`--dry-run`	boolean	—	Scan + triage but skip fix dispatch
`--env`	dev \| staging	dev	Environment name passed to content-audit scanner. Production is hard-blocked unless `allowProduction: true` in scanner opts.

PowerShell / Bash

# One-shot manual drain (3 rounds max, dry-run)
pforge audit-loop --max 3 --dry-run

# Respect .forge.json#audit config (most common in CI)
pforge audit-loop --auto

# Drain against staging
pforge audit-loop --auto --env staging

Findings route to three lanes: bug (registers in the bug registry), spec (submits to Crucible for re-smelting), or classifier (writes a local proposal artifact under .forge/audits/ for human review). The classifier-reviewer agent in .github/agents/ can audit the classifier's lane choices read-only.

Also available as: forge_tempering_drain MCP tool, POST /api/tempering/drain REST endpoint, and the /audit-loop slash-command skill in chat.

pforge timeline v2.82+

Offline chronological view of every event across the shop, runs, slices, incidents, bugs, deploys, Crucible interviews, Forge-Master turns, audit-loop rounds, memory captures. 9 sources, dedupe-safe across log rotation.

Flag	Type	Default	Description
`--window`	duration	24h	Lookback window (e.g., `1h`, `24h`, `7d`)
`--from` / `--to`	ISO datetime	—	Explicit range (overrides `--window`)
`--source`	string	all	Filter to one source: `run`, `incident`, `bug`, `deploy`, `crucible`, `fm-turn`, `memory`, `tempering`, `watch`
`--correlation`	string	—	Filter to one correlation id (run id, incident id, etc.)
`--group-by`	source \| hour \| day	—	Bucket events for a summary view
`--limit`	number	200	Max events returned
`--json`	boolean	—	Machine-readable JSON output

PowerShell / Bash

# Last 24h, all sources
pforge timeline

# Last hour, only Forge-Master turns
pforge timeline --window 1h --source fm-turn

# Everything tied to one run
pforge timeline --correlation run-2026-05-04T120000

# Daily summary for the past week, grouped by source
pforge timeline --window 7d --group-by source

# JSON for piping into jq / scripts
pforge timeline --window 24h --json | jq '.[] | select(.source == "incident")'

Also available as: forge_timeline MCP tool, GET /api/timeline REST endpoint, and the Timeline tab on the dashboard.

LiveGuard Commands (v2.27.0+)

Post-coding intelligence commands. All run locally, no network unless openclaw.endpoint is configured.

pforge drift

Score codebase against architecture guardrail rules. Tracks drift over time.

PowerShell / Bash

pforge drift
pforge drift --since HEAD~5

Also available as: forge_drift_report MCP tool.

pforge incident <desc>

Capture an incident with description, severity, affected files, and optional resolvedAt for MTTR tracking.

Flag	Type	Description
`--severity`	enum	`critical` · `high` · `medium` · `low`
`--files`	string	Comma-separated affected file paths, e.g. `src/api/handler.ts`

PowerShell / Bash

pforge incident "Auth token validation bypass" --severity critical --files src/auth/validator.ts
pforge incident "Slow query on dashboard load" --severity medium

pforge triage

Rank open alerts by priority (severity × recency).

Flag	Type	Description
`--min-severity`	enum	Filter by minimum severity: `critical` · `high` · `medium` · `low`
`--max`	number	Maximum number of results to display

PowerShell / Bash

pforge triage
pforge triage --min-severity medium --max 10

pforge deploy-log

Log a deployment with version, environment, and status.

Flag	Type	Description
`--version`	string	Deployment version, e.g. `v2.27.0`
`--env`	string	Target environment, e.g. `production`
`--status`	enum	`success` · `failure` · `rollback`

PowerShell / Bash

pforge deploy-log --version v2.27.0 --env production --status success
pforge deploy-log --version v2.27.0 --env staging --status failure

pforge regression-guard

Run validation gates from plans with command allowlist enforcement.

Flag	Type	Description
`--plan`	path	Path to plan file, e.g. `docs/plans/Phase-LiveGuard-v2.27.0-PLAN.md`

PowerShell / Bash

pforge regression-guard --plan docs/plans/Phase-LiveGuard-v2.27.0-PLAN.md

pforge runbook

Auto-generate an operational runbook from plan files and incident history.

Flag	Type	Description
`--plan`	path	Path to plan file

PowerShell / Bash

pforge runbook --plan docs/plans/Phase-7-DASHBOARD-PLAN.md

pforge hotspot

Git churn analysis to identify high-risk files. Results cached for 24 hours.

Flag	Type	Description
`--top`	number	Number of files to display (default: 10)
`--since`	string	Git log time range, e.g. `"3 months ago"`

PowerShell / Bash

pforge hotspot
pforge hotspot --top 15 --since "3 months ago"

pforge dep-watch

Scan dependencies for vulnerabilities and diff against the previous snapshot.

PowerShell / Bash

pforge dep-watch

pforge secret-scan

Scan recent commits for potential secrets via entropy analysis. Values are always redacted in output.

Flag	Type	Description
`--since`	string	Git ref range to scan, e.g. `HEAD~3`
`--threshold`	number	Entropy threshold for detection (default: 4.5), e.g. `4.0`

PowerShell / Bash

pforge secret-scan
pforge secret-scan --since HEAD~3 --threshold 4.0

Also available as: forge_secret_scan MCP tool.

pforge env-diff

Compare environment variable keys across .env files. Keys only, values are never read.

Flag	Type	Description
`--baseline`	path	Baseline env file, e.g. `.env`
`--files`	string	Comma-separated env files to compare, e.g. `.env.staging,.env.production`

PowerShell / Bash

pforge env-diff
pforge env-diff --baseline .env --files .env.staging,.env.production

Also available as: forge_env_diff MCP tool.

pforge health-trend

Aggregated health score over time.

Flag	Type	Description
`--days`	number	Number of days to include (default: 14), e.g. `30`

PowerShell / Bash

pforge health-trend
pforge health-trend --days 30

pforge fix-proposal

Generate a scoped 1-2 slice fix plan from a LiveGuard failure. Human reviews and runs the plan. Capped at one proposal per incident.

Flag	Type	Description
`--source`	enum (required)	`regression` · `drift` · `incident` · `secret`
`--incident-id`	string (optional)	Specific incident ID (used when `source=incident`)

PowerShell / Bash

pforge fix-proposal --source regression
pforge fix-proposal --source drift
pforge fix-proposal --source secret
pforge fix-proposal --source incident --incident-id INC-2026-04-001

Also available as: forge_fix_proposal MCP tool, POST /api/fix/propose REST endpoint (requires auth).

Review before running: Open docs/plans/auto/LIVEGUARD-FIX-*.md and fill in the TODO markers, then pforge run-plan --assisted <plan> on a branch.

pforge quorum-analyze

Assemble a structured quorum prompt from any LiveGuard data source. Returns the prompt text for you to run through your AI client's quorum mode. No model calls happen.

Flag	Type	Description
`--source`	enum (required)	`drift` · `triage` · `incident` · `runbook` · `fix-proposal`
`--goal`	enum (optional)	`root-cause` · `risk-assess` (default) · `fix-review` · `runbook-validate`
`--custom-question`	string (optional)	Freeform question that overrides `--goal` (max 500 chars)
`--quorum-size`	number (optional)	Model vote count requested in the prompt (default 3)

PowerShell / Bash

pforge quorum-analyze --source triage
pforge quorum-analyze --source drift --goal root-cause
pforge quorum-analyze --source incident --custom-question "Which fix should I prioritize given the sprint deadline?"

Also available as: forge_quorum_analyze MCP tool, POST /api/quorum/prompt REST endpoint (no auth required).

Third Edition Commands v3.x+

Six commands shipped between v2.99 and v3.5 that postdate the original CLI reference. Each is a thin wrapper over a v3.x MCP tool or subsystem, see the per-command "Also available as" link for the full MCP / REST mapping.

pforge sync-memories v2.99+

Generate .github/copilot-memory-hints.md from forge decisions, trajectories, auto-skills, OpenBrain entries. Hash-deduped and atomic; safe to run repeatedly. See Chapter 26 — Copilot Integration Trilogy.

Flag	Type	Description
`--since`	duration (optional)	Limit to trajectories in the last N (e.g. `14d`, `30d`). Default: 50 most recent.
`--explain`	flag (optional)	Verbose: show which entries were included/excluded and why
`--preview`	flag (optional)	Generate without writing, print the diff

PowerShell / Bash

pforge sync-memories
pforge sync-memories --since=14d
pforge sync-memories --preview --explain

Also available as: forge_sync_memories MCP tool.

pforge sync-instructions v3.0+

Generate .github/copilot-instructions.md by composing project profile + principles + extra instruction files + .forge.json commitments. Output is deterministic; same inputs produce identical files.

Flag	Type	Description
`--preview`	flag (optional)	Generate without writing, print the resulting content
`--force`	flag (optional)	Overwrite even if content hash matches (bypass dedup)

PowerShell / Bash

pforge sync-instructions
pforge sync-instructions --preview
pforge sync-instructions --force

Also available as: forge_sync_instructions MCP tool, POST /api/copilot-instructions/sync REST endpoint.

pforge sync-spaces v3.2+

Sync memory spaces across projects, pull shared knowledge from configured peer repositories into the local OpenBrain L3 store. Read-only on the local side until a confirmation flag is passed. Useful in fleet / multi-repo setups.

Flag	Type	Description
`--peer`	string (optional)	Limit sync to one configured peer name
`--apply`	flag (optional)	Write the merged records (default: dry-run)
`--since`	duration (optional)	Only consider records newer than N (default: `7d`)

PowerShell / Bash

pforge sync-spaces                       # dry-run, all peers
pforge sync-spaces --peer=billing-svc --apply
pforge sync-spaces --since=30d --apply

Configured under brain.federation.repos in .forge.json.

pforge plan-from-sarif <sarif-file> v3.1+

Generate a Plan Forge phase plan from a SARIF findings file (CodeQL, Semgrep, ESLint with SARIF reporter, etc.). Each finding becomes a slice in the resulting plan; severity drives priority ordering.

Flag	Type	Description
`--min-severity`	enum (optional)	`low` · `medium` · `high` · `critical` (default: `medium`)
`--max-slices`	number (optional)	Cap the number of slices (default: 10)
`--phase-name`	string (optional)	Override the auto-generated phase name

PowerShell / Bash

pforge plan-from-sarif codeql-results.sarif
pforge plan-from-sarif scan.sarif --min-severity=high --max-slices=5
pforge plan-from-sarif sec.sarif --phase-name="Phase-SEC-FIX"

Writes to docs/plans/Phase-N-PLAN.md. Plan still needs hardening via step2-harden-plan.prompt.md before execution.

pforge digest v3.3+

The "morning summary", compresses graph findings, pattern detectors, and event ledgers into a single human-readable digest. Categories: plans shipped, aging meta-bugs, stalled phases, probe-lane deltas, drift score changes, cost anomalies. See Chapter 28 — The Knowledge Graph.

Flag	Type	Description
`--since`	duration (optional)	Window (default: `24h`). Common: `7d` for weekly roll-up.
`--format`	enum (optional)	`markdown` (default) · `json`
`--post`	flag (optional)	Send via configured notification channel (Slack, Teams, etc.)
`--rebuild`	flag (optional)	Recompute from logs instead of reading cached `.forge/digests/YYYY-MM-DD.json`

PowerShell / Bash

pforge digest                       # today's, markdown
pforge digest --since=7d            # weekly
pforge digest --format=json | jq    # pipe-friendly
pforge digest --post                # broadcast to configured channel

Backs the Yesterday's Digest dashboard tile. Cron-friendly: pforge digest --post at 09:00 weekdays = free standup.

pforge hammer-fm v3.2+

Run the full Forge-Master tempering harness, false-marker scan across the entire codebase (TODO, FIXME, HACK, stub patterns, mock data, placeholder text). Wraps forge_sweep + forge_tempering_drain in a single tightened loop suitable for pre-release gates.

Flag	Type	Description
`--strict`	flag (optional)	Exit non-zero on any finding (default: report-only)
`--include`	glob (optional)	Limit scan to files matching a glob (default: all tracked)
`--max-rounds`	number (optional)	Cap convergence rounds (default: 3)

PowerShell / Bash

pforge hammer-fm
pforge hammer-fm --strict                # CI gate
pforge hammer-fm --include="src/**/*.ts"

Pairs well with forge_classifier_issue when findings are noise rather than bugs, see Chapter 27 — Team Coordination.

pforge fm-session [<goal>] v3.4+

Start (or resume) a Forge-Master reasoning session, interactive read-only conversation with the orchestrator. Use it for "why did Phase-X fail?", "what's the cheapest way to ship this plan?", and similar open-ended questions. Sessions persist to .forge/forge-master/sessions/.

Flag	Type	Description
`--resume`	string (optional)	Session ID to continue (omit to start new)
`--model`	string (optional)	Override the configured Forge-Master model
`--quiet`	flag (optional)	Suppress thought-trace output (final answer only)

PowerShell / Bash

pforge fm-session "Why did Phase-31 slice 4 fail?"
pforge fm-session --resume=fm-7f3a-...
pforge fm-session --quiet "What's the cheapest quorum for Phase-32?"

Also available as: forge_master_ask MCP tool (one-shot), POST /api/forge-master/ask REST endpoint.

pforge fm-recall <query> v3.4+

Search prior Forge-Master sessions for relevant answers. Useful when you remember asking something similar last week but don't remember the answer. Returns ranked session excerpts with session IDs you can fm-session --resume=... from.

Flag	Type	Description
`--limit`	number (optional)	Max results (default: 5)
`--since`	duration (optional)	Only sessions from last N (default: `90d`)
`--json`	flag (optional)	Machine-readable output

PowerShell / Bash

pforge fm-recall "gate timeout"
pforge fm-recall "snapshot pop strategy" --limit=10
pforge fm-recall "cost anomaly Phase-31" --since=30d --json

Backed by the L2 search index over .forge/forge-master/sessions/*.jsonl.

MCP 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/project

Full Reference

This chapter covers the happy path for each command. For exhaustive edge-case documentation, see the source: CLI-GUIDE.md on GitHub