130+commands
8phase verbs
14Blacksmith ops
17Anvil subcommands
3CLI tiers
78f-aliases
All three tiers execute identical code paths. Use whichever fits your workflow.
forge <cmd>
canonical
Full cross-platform form. Works in any shell, CI, or script. Always correct.
f <cmd>
kubectl-style short alias
Bash/zsh interactive shorthand. f open ulease, f audit, fbrief metal.
c<cmd> <slug>
legacy project tier
Preserved muscle-memory aliases. copen ulease, cclose ulease.
npm install -g @forge/cli
forge --version
echo 'source $(npm root -g)/@forge/cli/shell/forge-aliases.sh' >> ~/.zshrc
source ~/.zshrc
forge completion --shell bash
forge completion --shell zsh >> ~/.zshrc
mkdir -p ~/forge && cd ~/forge
forge init myproject
forge open myproject
Every Anvil moves through 8 metallurgy-named phases. These are the first-class lifecycle commands — they print a phase banner, record state to .forge-phase, and delegate to the underlying handler.
Phase 1
forge brief <slug>
fbrief
Charter, intent, persona, success criteria. Name the work before lighting the forge.
Phase 2
forge survey <slug>
fsurvey
Codebase brain scan + domain research. Map the terrain before you strike.
Phase 3
forge strike <slug>
fstrike
Walking skeleton — first cut. Get the iron hot.
Phase 4
forge shape <slug>
fshape
Architecture, ADRs, module layout. Form before fire.
Phase 5
forge temper <slug>
ftemper
Refactor + stabilize. Controlled cooling.
Phase 6
forge quench <slug>
fquench
Full 80+ dimension audit + 6-band check. Harden the steel.
Phase 7
forge stamp <slug>
fstamp
SemVer bump + changelog + git tag. Mark the maker.
Phase 8
forge ship <slug>
fship
Production deploy. Off the anvil.
| Command | Alias | Description |
|---|
| forge anvil |
fanvil |
List all anvils with current phase and last-touch timestamp. |
| forge phase <slug> [<verb>] |
fphase |
Show or set an anvil's phase without running the full handler. |
| Command | Description |
|---|
| forge open <slug> [--host <name>] |
Print project context briefing for paste into AI host. --host claude|cursor|codex|copilot|gemini pipes directly to that host's CLI. Short: copen |
| forge close <slug> |
End session — full close ritual (writes handoff, updates MEMORY.md). Short: cclose |
| forge refresh |
Re-register lifecycle aliases after a new project is initialised. |
| forge status [--json] |
List all projects with last-touched timestamp + missing-file warnings. --json for CI scripting. |
| forge ls [--json] |
List all projects that have a MEMORY.md. Subset of forge status. |
| forge version |
Show CLI version, protocol versions, and config root path. |
| Command | Description |
|---|
| forge story new <id> <title> |
Create story file + git branch + workflow state. ID format: US-001, F-042. |
| forge story status [id] |
Show workflow state for one story or all active stories. |
| forge story commit |
Auto-fill Implementation section from staged files + current git hash. |
| forge story gen-tests <id> |
Generate Playwright test skeleton from AC (Gherkin GIVEN/WHEN/THEN → test stubs). |
| Command | Description |
|---|
| forge adr new "<title>" |
Auto-numbered ADR-NNN with YAML frontmatter. Appended to ADR index. |
| forge adr supersede <old> <new> |
Mark old ADR as SUPERSEDED and create bi-directional link to new ADR. |
| forge adr graph |
Emit Mermaid dependency diagram of all ADRs and their supersession links. |
| forge adr list |
List all ADRs with status (PROPOSED / ACCEPTED / SUPERSEDED / DEPRECATED). |
| Command | Description |
|---|
| forge workflow start <kind> <id> |
Start a state machine for feature, hotfix, or release workflow. |
| forge workflow status [id] |
Show active workflows, current state, and next gate. |
| forge workflow gate <id> |
Run prerequisite checks: typecheck, lint, git-ahead validation. Must pass before advance. |
| forge workflow advance <id> |
Advance to next state — only runs if gate passed. Refuses otherwise with remediation hint. |
Forge has 17 canonical personas (analyst, pm, architect, dev, qa, sm, security, sre, dpo, and more) plus the Blacksmith apex. Roles enforce tool-level restrictions — not just prompt preambles.
| Command | Description |
|---|
| forge persona [name] |
List all 4 quick-select personas, or show pre-flight checklist + output contract for a named persona. |
| forge persona declare <name> |
Lock role for current session. Installs a transient deny-hook so restricted tools literally cannot be called. |
| forge persona current |
Show the locked persona for the current session. |
| forge role [name] |
Activate one of 20 extended BMAD-compatible personas (broader set including DPO, FinOps, SRE). |
Forge audits 80+ B-* dimensions and rolls up to 6 bands: HEAT · HARDNESS · FIT · WEAR · GRAIN · POLISH. Worst band = project verdict.
| Command | Options | Description |
|---|
| forge audit |
--fix -d N --json |
Run all 80+ B-* dimensions for the current project. --fix auto-repairs mechanical findings. -d N limits to N dimensions. --json for CI. |
| forge audit-claude <slug> |
--host |
Run headless audit via Claude Code (or Cursor / Codex / Copilot / Gemini when configured) using audit_protocol_v14. |
| forge audit-claude-all |
— |
Run audit-claude across every project. Portfolio verdict = worst active band. |
forge bands metal POLISH
forge bands metal HEAT --since 7d
forge bands metal WEAR --trend --json
| Command | Options | Description |
|---|
| forge coverage check [story-id] |
--json |
AC tag coverage check — 100% required for a story to reach Done. Checks GIVEN/WHEN/THEN tags in test files. |
| forge sla check |
--json |
KI SLA review across all projects. Flags items past due date. |
| forge sla install-cron |
— |
Install macOS launchd plist for daily SLA check at 9am. |
| forge phase-gate <slug> |
— |
Validate PRD → Architecture → Stories artifact sequence. Refuses to pass if any predecessor is missing. |
| Command | Options | Description |
|---|
| forge recon check <slug> |
— |
Dry-run validation — finds stale references. Never writes anything. |
| forge recon fix <slug> |
--dangerously |
Reconcile reference files. Prompts for each change unless --dangerously. |
| forge recon all |
— |
Run recon check across every project in the portfolio. |
| forge recon fix-all |
--dangerously |
Reconcile every project. Use --dangerously for unattended batch fix. |
Forge Anvil is the local NoSQL memory engine: confidence decay, contradiction detection, semantic search (TF-IDF, pure JS, 100% local, no cloud). All memories stored in ~/.forge/anvil/.
| Command | Description |
|---|
| forge anvil strike "<text>" |
Store a new ground-truth memory with full confidence (1.0). Detects contradictions against existing memories before writing. |
| forge anvil draw |
List active memories by type and project. Shows confidence scores and age. |
| forge anvil seek <query> |
Semantic search across all memories using TF-IDF ranking. Returns top-N matches with confidence scores. |
| forge anvil temper <dossier> "<note>" |
Reset confidence score to 1.0 for a memory. Use when you've verified stale information is still correct. |
| forge anvil fractures |
List all memories flagged for conflict resolution. Shows contradicting pairs side-by-side. |
| forge anvil assay |
Memory health dashboard: total count, stale memories (confidence <0.5), unresolved conflicts, telemetry. |
| forge anvil cast |
Dump all memories to markdown (offline portability). Exports to ~/forge/anvil-export-{date}.md. |
| forge anvil kindle |
Initialize Anvil for a project. Creates .forge/anvil/ and seeds from existing MEMORY.md. |
| forge anvil smelt |
Ingest existing docs / decisions into memories. Processes markdown files, extracts facts, writes memories with initial confidence. |
| forge anvil slag [days] |
Check freshness of dossiers. Flags memories not touched in N days (default: 30). |
| forge anvil cool |
Explicit tarball backup of Anvil state to ~/.forge/backups/. |
| forge anvil --consolidate |
Sleep-daily compression — merges redundant memories while preserving the lower confidence score. |
| forge anvil quench |
End session cleanly. Reads git state + open todos, writes a structured exit summary to SESSION_STATE.md — the next session resumes cold in under 60 seconds. |
| forge anvil where |
Print current SESSION_STATE.md — read-only. Shows where you stopped last session. |
| forge anvil seal |
Archive today's work — compiles decisions, session state, git activity, and dossier deltas into an immutable context.YYYYMMDD.txt file. Run after quench at end of day. |
| forge recall <target> |
Print a past daily context file. Targets: yesterday, last-week, 20260514, context.20260514.txt. Read-only. |
| forge apply <target> |
Inject a past context file into PRIOR_CONTEXT.md — read by the next AI session on cold-start alongside SESSION_STATE.md. Most common: forge apply yesterday. |
| Command | Options | Description |
|---|
| forge memory search <query> |
--json -n N |
TF-IDF ranked search over all projects' MEMORY.md files. -n N limits results (default 10). Cross-project. |
| forge memory promote |
--dry-run |
Save-to-master ritual — promotes memories scoring ≥8, marked Repeated, or flagged High to the master system prompt. --dry-run shows what would be promoted without writing. |
| Command | Description |
|---|
| forge catalog skills |
Regenerate skills_catalog.md from installed forge-skills. |
| forge catalog agents |
Regenerate agents_catalog.md from installed agent definitions. |
| forge catalog plugins |
Regenerate plugins_catalog.md from plugin registry. |
| forge catalog mcp |
Regenerate mcp_catalog.md from discovered MCP server configs. |
| forge catalog connector |
Regenerate connectors_catalog.md (Linear, Notion, GitHub, VS Code). |
| forge catalog all |
Regenerate ALL FIVE catalogs in one pass. |
| forge catalog grep [pattern] |
grep the skills catalog for a pattern. Faster than opening the file. |
Install, audit, and generate docs for Forge skills. Skills are reusable slash-command handlers. CORE_SKILLS is the always-on global set; per-host sets layer on top.
| Command | Options | Description |
|---|
| forge skills list [--global] |
--global |
List all installed skills. --global shows CORE_SKILLS (always-on set). |
| forge skills install --global |
--global |
Install CORE_SKILLS to every configured host. |
| forge skills certify [slug] |
— |
Audit a skill against B-SK10/11/12 criteria. P0/P1 = fail, P2 = warn. |
| forge gen-skill-docs --host <name> |
--host all |
Generate host-specific SKILL.md. --host all generates for all 5 hosts; --host claude for one. |
| forge hosts list |
— |
List 5 configured hosts with (base) / [preview] flags. |
Writs are protocol documents — named rules, policies, and decision records that companions reference. The companion graph links writs to the skills and dossiers that depend on them.
| Command | Options | Description |
|---|
| forge view writ |
— |
List all writs by category. |
| forge view writ <name> |
— |
Open named writ in less. Alias: forge view writ sys → arun_system_prompt. |
| forge view writ <name> --cat |
--cat |
Pipe writ to stdout (for scripting / injection). |
| forge view writ --category <cat> |
--category |
Filter writ list to a single category (e.g. forge, policy, persona). |
| forge writs verify [--json] |
--json |
Detect orphans, one-way refs, and dangling targets. --json for CI output. |
| forge writs list |
— |
List all writs indexed on disk. |
| forge writs show <name> |
— |
Show writ with its companion connections (skills + dossiers that depend on it). |
| forge writs matrix |
— |
Print companion graph from disk — the full writ-to-companion dependency map. |
Ground-Up Rebuild Unit — 3-zone living rebuild docs per project. Cold Iron drills validate your rebuild works before you need it. Lives at ~/claude/guru/[slug]-guru.md.
| Command | Options / Args | Description |
|---|
| forge guru status |
[slug] |
Show all GURU files — Cold Iron health, days since last drill, zone freshness. Omit slug for all projects. |
| forge guru diagnose |
slug |
Surface drift, staleness, missing zones, overdue drills. Read-only diagnostic. |
| forge guru sync |
--pr --decision --lifecycle |
Append event to Zone 3 RECORD. --pr: PR log. --decision: echo latest forge anvil strike. --lifecycle: phase transition. |
| forge guru consolidate |
slug |
Rewrite Zone 1 CANONICAL from Zone 3 history. Requires Blacksmith authority. Logs to Consolidation Log. |
| forge guru drill |
slug --dry-run --layer N |
Run Cold Iron test rebuild drill (blank round). Layers: 1=static, 2=env, 3=data, 4=migration. --dry-run checks preconditions only. |
| forge guru init |
slug |
Bootstrap 3-zone GURU file for a new project at ~/claude/guru/[slug]-guru.md. |
| forge guru retire |
slug |
Mark project RETIRED in Zone 2. Requires Blacksmith authority. Irreversible. Never auto-triggered. |
| forge guru config |
slug |
Show current Cold Iron config — frequency (days), schedule, enabled layers. |
| forge guru config set |
slug freq N |
Set drill frequency in days. Ratchet enforced — can only decrease interval (increase frequency), never loosen. |
Cold Iron Drill Layers
| Layer | Name | Validates |
|---|
| 1 | Static | Protocols, skill files, writ structure present and parseable |
| 2 | Environment | Secrets/variables load; env template matches current structure |
| 3 | Data | ~/claude/data/[slug]/ present; seed loads cleanly into isolated store |
| 4 | Migration | Schema migration dry-run against isolated data; Layer 4 halts if data dir absent |
Automated Triggers
Sunday 08:00
launchd cold-iron scan — queues overdue drills to ~/claude/guru/.drill-queue
1st of month
retirement scan — warns 14 days out, critical past flag date
post-merge hook
queues PR sync + arch-triggered drill on every git merge
| Command | Options | Description |
|---|
| forge deploy precheck |
— |
Run P-0001..P-0004 deployment-pattern checks. Validates env vars, migrations, health endpoints, rollback plan. |
| forge deploy verify |
— |
Curl health-check URLs from RUNBOOK.md. Non-zero exit on any failure — use in post-deploy CI step. |
| forge deploy-now [slug] |
--dangerously |
Multi-target deploy with abort checks. --dangerously skips band gate (requires Blacksmith authority). Logs to audit trail. |
| Command | Description |
|---|
| forge cd project <slug> |
Print project directory path (use with cd $(forge cd project ulease)). |
| forge cd prompts |
Print prompts directory path. |
| forge cd root |
Print Forge root path ($FORGE_ROOT, defaults to ~/forge). |
| forge backup project <slug> |
In-tree project snapshot. Writes timestamped tarball inside project directory. |
| forge backup all [dir] |
Full versioned tarball of all projects + state + memory. The KING command. 30-day rolling window. |
| forge backup restore-list [dir] |
List available tarballs newest-first with sizes and dates. |
| forge git init |
Initialize git repo with Forge-safe .gitignore (excludes secrets, anvil data, binary backups). |
| forge git status |
Show what would be committed. Annotated with Forge file categories. |
| forge git push [msg] |
Commit + push to GitHub with optional message. Runs lint + typecheck gate first. |
| forge archive [--quiet] |
Move stray .bak files and superseded protocols to archive/. --quiet suppresses progress output. |
All read-only. Opens the relevant reference file in your pager or $EDITOR. Use forge edit <type> <slug> to open for editing.
| Command | Reads |
|---|
| forge view handoff <slug> | Latest handoff document |
| forge view snap <slug> | project_snapshot.md |
| forge view todo <slug> | reference_todo_{slug}.md |
| forge view masterprompt <slug> | reference_masterprompt_{slug}.md |
| forge view arch <slug> | reference_architecture_{slug}.md |
| forge view releases <slug> | reference_releases_{slug}.md |
| forge view stories <slug> | reference_stories_{slug}.md |
| forge view test <slug> | reference_test_{slug}.md |
| forge view seo <slug> | reference_seo_{slug}.md |
| forge view security <slug> | reference_security_{slug}.md |
| forge view pr <slug> | reference_pullrequest_{slug}.md |
| forge view known <slug> | reference_known_issues_{slug}.md |
| forge view glossary <slug> | GLOSSARY.md |
| forge view runbook <slug> | RUNBOOK.md |
| forge view sprint <slug> | docs/sprint-current.md |
| forge view memory <slug> | MEMORY.md |
| forge view rules <slug> | PROJECT_RULES.md |
| forge view adr <slug> [id] | List all ADRs or show ADR-{id} |
| forge view workflow <slug> <type> | docs/workflows/{type}.md |
forge edit memory <slug> — open MEMORY.md in $EDITOR
forge edit file <slug> <file> — open arbitrary file
Off by default. No data leaves your machine unless you explicitly opt in. No args, paths, or project names ever tracked. EU PostHog endpoint. Self-hostable.
| Command | Description |
|---|
| forge telemetry on |
Opt in to anonymous usage stats. Shows a preview of exactly what will be sent before enabling. |
| forge telemetry off |
Opt out. Immediately stops all data collection. |
| forge telemetry status |
Show current opt-in state and configured endpoint. |
FORGE_TELEMETRY=on forge audit
FORGE_TELEMETRY_URL=https://posthog.yourco.com forge audit
| Command | Description |
|---|
| forge capture |
Append blank capture scaffold to inbox and open in $EDITOR. For logging decisions mid-session. |
| forge inbox |
Edit the chat-capture inbox file — a flat log of observations not yet promoted to memory. |
| forge stale [slug] |
Check for stale handoffs. Flags projects with no close in N days (default: 3). |
| forge search <pattern> |
Cross-project grep across all reference_*.md files. Faster than shell grep on large portfolios. |
| forge remind |
Show days-since-last memory promote per project. Nudges you to run the save-to-master ritual. |
| Command | Description |
|---|
| forge qa <slug> <minutes> |
Time-boxed QA briefing. Generates a scoped test plan for the given time window. Great for session planning. |
| forge correct-course [slug] [desc] |
STOP / LOG / DECIDE / RESUME — BMAD-style course correction. Pauses work, forces decision, documents rationale. |
| Command | Options | Description |
|---|
| forge glossary check |
--json |
Verify type↔glossary alignment — ensures every type exported by source matches a glossary entry. |
| forge docs lint |
--json |
Verify internal doc links + RUNBOOK last-verified field freshness. |
| forge run <section> |
--dry-run --no-confirm |
Execute a RUNBOOK ```sh exec``` block by section name. --dry-run prints commands without running. |
| Command | Description |
|---|
| forge gen tests <story-id> |
Convert AC (Gherkin GIVEN/WHEN/THEN) → Playwright test skeleton. Also available as forge story gen-tests <id>. |
| Command | Options | Description |
|---|
| forge migrate code-to-project |
--apply |
Rename code-* directories to project-*. Dry-run by default; --apply commits changes. |
| forge migrate refs |
--apply |
Rename old reference file convention to new naming scheme. Dry-run by default. |
| forge migrate orphans |
— |
Recover orphaned *-code_* files left from incomplete migrations. |
Root authority — never permanent. Granted via TTL'd god-mode session or one-shot FORGE_BLACKSMITH=1 env flag. Every action is logged to ~/.forge/blacksmith/audit.log (append-only, mode 0600). Every destructive op tarballs the workspace BEFORE acting (30-day restore window). Authority never propagates to sub-shells.
Session (3)
| Command | Alias | Description |
|---|
| forge blacksmith god-mode [--ttl SEC] |
fbsgo |
Enable root authority. Default TTL: 1800s (30 min). Max: 4hr. Auto-expires. Logged immediately. |
| forge blacksmith end-session |
fbsend |
End god-mode immediately, before TTL expires. |
| forge blacksmith status |
fbsstatus |
Show authority state + TTL remaining + last 5 audit log entries. |
Destructive (4) — auto-tarball + typed-confirm always required
| Command | Alias | Description |
|---|
| forge blacksmith nuke <slug> |
fbsnuke |
Tarball → delete anvil → remove from FORGE.md → log. 30-day restore window. Requires typing nuke <slug>. |
| forge blacksmith reset <slug> |
fbsreset |
Wipe phase / audit / band state. Workspace files kept. Also tarballed first. |
| forge blacksmith purge-buried |
fbspurge |
Bulk-delete all buried-phase anvils. Each is individually backed up before deletion. |
| forge blacksmith restore <slug> <id> |
fbsrestore |
Reverse a nuke using backup ID. No authority required — recovery is always easy. |
Override (3) — bypass guardrails, audited forever
| Command | Alias | Description |
|---|
| forge blacksmith ship <slug> --dangerously |
fbsship |
Deploy bypassing audit + band gates. Requires typing ship <slug>. Use only in true emergencies. |
| forge blacksmith override-band <slug> <BAND> [reason] |
fbsoverride |
Force a band GREEN with reason string permanently recorded in audit log. Reason is required and cannot be blank. |
| forge blacksmith bypass-gate <slug> |
fbsbypass |
Skip phase-gate checks for 24h. Auto-clears. Logged with timestamp and authority source. |
Impersonation (1)
| Command | Alias | Description |
|---|
| forge blacksmith as <persona> <command…> |
fbsas |
Run any forge command as any of the 17 personas. Logged as BOTH a persona event AND a Blacksmith impersonation event. |
Inspection (2)
| Command | Alias | Description |
|---|
| forge blacksmith backups |
fbsbackups |
List all tar backups newest-first with sizes, dates, and restore IDs. |
| forge blacksmith audit-log [N] |
fbsaudit |
Show last N audit-log events (default 50). Append-only — cannot be edited or cleared. |
CI / Automation two-key safety
FORGE_BLACKSMITH=1 FORGE_BLACKSMITH_YES=1 forge blacksmith purge-buried
Usage smells — warning signs
| Pattern | What it really means |
|---|
| fbsship --dangerously > 1×/month | Audit gates too strict OR your test suite is flaky |
| fbsoverride > 3×/quarter | Band thresholds are wrong — recalibrate them |
| god-mode session > 4hrs | Root being used as default workflow — that's a culture problem |
| FORGE_BLACKSMITH=1 baked into CI | Your automation has been pwned |
| nuke without ever using restore | Over-pruning the portfolio |
| Same anvil reset > 2× in 30 days | Should have been nuked instead |
--version
Print CLI version and exit.
--help
Print help text. Works on any subcommand: forge anvil --help.
--json
Machine-readable JSON output (where supported). Safe for CI pipelines.
| Variable | Default | Purpose |
|---|
| FORGE_ROOT |
~/.forge |
Project root. Auto-detects ~/claude for legacy installs. |
| FORGE_TELEMETRY |
off |
Override config telemetry: on or off. One-shot per invocation. |
| FORGE_TELEMETRY_URL |
PostHog EU |
Custom telemetry endpoint. Point at your own PostHog instance. |
| FORGE_BLACKSMITH |
— |
Set to 1 to provide one-shot Blacksmith authority. Never bake into CI. |
| FORGE_BLACKSMITH_YES |
— |
Set to 1 alongside FORGE_BLACKSMITH=1 to skip typed-confirm in automation. |
| FORGE_HOME |
auto |
Install root (set by shell aliases). Points at the @forge/cli npm root. |
Exit codes
2
Windows — not yet supported (use Git Bash or WSL)
No commands match your search. Try a different keyword.