CLI Reference

Table of contents

1. Overview
2. Core Commands
   1. forge init
   2. forge new
   3. forge status
   4. forge complete
3. Phase Management Commands
   1. forge phase status
   2. forge phase next
   3. forge phase complete
4. Learning Commands
   1. forge learn
5. MCP Integration
   1. forge mcp list
   2. forge mcp suggest
   3. forge mcp add
6. Utility Commands
   1. forge document
   2. forge uninstall
7. Command Options
8. Workflow Examples
   1. Standard Flow
   2. With Overrides
   3. Team Mode
9. Phase Validation System
   1. Validation Rules
   2. Visual Progress Indicators
   3. Progress Bars
10. File Structure
11. Tips & Best Practices
12. Error Messages
13. Version Information

---

Overview

The FORGE CLI (v0.6.0) provides a minimal yet powerful interface for AI-driven development with built-in phase validation, progress tracking, and automatic Claude Code subagent configuration.

Core Commands

forge init

Initialize FORGE in your project directory.

forge init

Creates:

• forge.yaml configuration file
• .forge/ directory structure
• Initial project analysis prompt

Note: Claude Code subagents are configured during global installation, not init.

---

forge new

Start a new development cycle.

forge new <feature-name>
forge new "user authentication"

Behavior:

• Solo mode: Creates .forge/current.md
• Team mode: Creates .forge/current/<feature>.md
• Initializes 5-phase cycle template

---

forge status

Display cycle progress with visual indicators (v0.6.0 feature).

forge status              # Visual progress summary
forge phase               # Current phase details
forge phase status        # Detailed phase requirements
forge status --detailed   # Full cycle content

Features:

• Visual progress bars
• Completion percentages
• Current phase indicator
• Next tasks display

Example Output:

📋 Current Cycle: user authentication
──────────────────────────────────────────────────
✅ 🎯 Focus        [██████████] 100%
🔄 📝 Orchestrate  [████░░░░░░] 40%
⏳ 🔨 Refine       [░░░░░░░░░░] 0%

📍 Current Phase: Orchestrate
   Next tasks:
   • Plan dependencies
   • Assign priorities

---

forge complete

Archive completed cycle with validation.

forge complete           # With validation
forge complete --force   # Skip validation

Validation Features:

• Checks all phases for completion
• Identifies mandatory incomplete items
• Prevents premature archival
• Shows helpful guidance

Validation Output:

⚠️  Cycle has incomplete phases!

Incomplete phases: Focus, Orchestrate
Mandatory tasks not completed:
  🎯 Focus: Define test scenarios (MANDATORY)

💡 Options:
  1. Complete the remaining tasks
  2. Use "forge complete --force" to archive anyway

Phase Management Commands

forge phase status

Detailed phase progress overview.

forge phase status

Shows:

• All phases with progress bars
• Mandatory incomplete items
• Visual completion indicators
• Task-level details

---

forge phase next

Transition to next phase with validation.

forge phase next         # With validation
forge phase next --force # Skip validation

Features:

• Validates mandatory items
• Updates phase markers
• Activates next phase
• Shows blocking items

---

forge phase complete

Mark current phase as complete.

forge phase complete

Actions:

• Marks all items as done
• Updates phase status
• Enables bulk completion

Learning Commands

forge learn

Manage project knowledge base.

forge learn                # View learnings
forge learn retrospective  # Create retro template
forge learn pattern       # Document pattern
forge learn claude        # Generate CLAUDE.md

MCP Integration

forge mcp list

Show available MCP servers.

forge mcp list

forge mcp suggest

Get project-specific recommendations.

forge mcp suggest

forge mcp add

Add MCP server to configuration.

forge mcp add <server>
forge mcp add filesystem

Utility Commands

forge document

Start documentation session.

forge document

forge uninstall

Remove FORGE from project.

forge uninstall --confirm

Command Options

Option	Commands	Description
--force	complete, phase next	Skip validation checks
--detailed	status	Show full content
--confirm	uninstall	Confirm destructive action

Workflow Examples

Standard Flow

# Start feature
forge new "shopping cart"

# Track progress
forge status

# Move through phases
forge phase next

# Complete when done
forge complete

With Overrides

# Force completion
forge complete --force

# Skip phase validation
forge phase next --force

Team Mode

# Parallel features
forge new "feature-a"
forge new "feature-b"

# Check all cycles
forge status

# Complete specific
forge complete feature-a.md

Phase Validation System

FORGE enforces proper workflow progression:

Validation Rules

1. Mandatory Tasks: Must be completed before phase transitions
2. Phase Dependencies: Can’t skip phases
3. Completion Checks: All phases validated before archival
4. Override Options: --force flags for flexibility

Visual Progress Indicators

Symbol	Meaning
⏳	Phase pending
🔄	Phase in progress
✅	Phase complete
⚠️	Mandatory item incomplete

Progress Bars

[██████████] 100% - Complete
[████░░░░░░] 40%  - In progress
[░░░░░░░░░░] 0%   - Not started

File Structure

project/
├── forge.yaml           # Configuration
├── .forge/
│   ├── current.md      # Active cycle
│   ├── history/        # Archived cycles
│   ├── templates/      # Templates
│   └── agents/         # Agent definitions
└── .claude/
    └── agents/         # Subagents

Tips & Best Practices

1. Check Progress Often: Use forge status regularly
2. Complete Phases: Don’t skip ahead without finishing
3. Use Validation: Let FORGE guide proper workflow
4. Force When Needed: Override for special cases
5. Track Learnings: Document patterns and insights

Error Messages

Message	Meaning	Solution
“No active cycle”	No cycle started	Run forge new <feature>
“Incomplete phases”	Validation failed	Complete tasks or use --force
“Cannot move to next phase”	Mandatory items incomplete	Finish required items

Version Information

Current Version: 0.6.0

For updates: GitHub Repository