CLI Commands

Complete reference for all SpecForge CLI commands, flags, and usage examples.

The specforge CLI is distributed as the npm package @specforge/cli. It manages authentication, project configuration, team membership, review gates, and agent scaffolding.

npm install -g @specforge/cli
# or run directly
npx @specforge/cli@latest <command>

Authentication

specforge login

Authenticate with SpecForge.

specforge login

Opens a browser-based OAuth flow and stores credentials in ~/.specforge/config.json.

For headless environments (remote servers, CI):

specforge login --api-key sf_live_...

Credentials are stored in ~/.specforge/config.json:

{
  "apiKey": "sf_live_...",
  "userId": "user_abc123"
}

Project Setup

specforge init

Initialize SpecForge in the current directory. Creates configuration files, detects installed coding tools, and generates agent/skill files.

specforge init

What It Does

1. Fetches your projects from the SpecForge API and prompts for selection
2. Fetches specifications from the selected project and prompts for selection
3. Prompts for output format — json (structured MCP responses) or toon (human-readable)
4. Creates .specforge/config.json with project and specification IDs
5. Detects installed tools — Claude Code, Cursor, Gemini CLI, Codex CLI, OpenCode — and generates per-tool config files
6. Generates agent instruction files — CLAUDE.md, GEMINI.md, or AGENTS.md depending on detected tools
7. Optionally sets up Agent Teams — if CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set, generates skill files in .claude/skills/

Flags

# Non-interactive for CI
specforge init --project proj_abc123 --spec spec_xyz789 --format json --yes
 
# Update only the active specification
specforge init --spec-only
 
# Preview what would be generated
specforge init --show
 
# Reinitialize, overwriting existing files
specforge init --force

ℹ️ If config files already exist, specforge init prompts for confirmation before overwriting unless --force is passed.

specforge configure

View or set configuration values. Without arguments, shows the full resolved config. With a key, shows that value. With a key and value, sets it.

specforge configure [key] [value]

Supports nested paths with dot notation:

# View all config
specforge configure
 
# View a specific value
specforge configure defaultProjectId
 
# Set a value
specforge configure format json
 
# Set nested values
specforge configure agentTeams.enabled true
specforge configure agentTeams.strategy wave
specforge configure agentTeams.maxParallelEpics 3
 
# Set review config values
specforge configure reviewConfig.readinessThreshold 85
specforge configure reviewConfig.gates.git_evidence false
specforge configure reviewConfig.testEvidence verbose

Modifies .specforge/config.json directly. Useful for scripting or making point changes without re-running init.

specforge switch

Change the active project or specification context.

specforge switch <id>

The <id> can be a project ID or a specification ID. SpecForge detects the type automatically.

# Switch to a different project
specforge switch proj_abc123
 
# Switch to a different specification
specforge switch spec_xyz789
 
# Switch both at once
specforge switch proj_abc123 --spec spec_xyz789

Updates .specforge/config.json and regenerates agent instruction files to reflect the new context. The MCP server picks up the change on the next tool call.

Diagnostics

specforge doctor

Run diagnostics to verify your SpecForge configuration. Checks authentication, project config, MCP server connectivity, and agent setup.

specforge doctor

SpecForge Doctor
  API Key         ✓ authenticated as user@example.com
  MCP Server      ✓ registered in .mcp.json
  Project         ✓ proj_abc123 accessible
  Specification   ✓ spec_xyz789 loaded (3 epics, 14 tickets)
  Agent Config    ✓ CLAUDE.md present
  Git             ✓ clean working tree

All checks passed.

✅ Run specforge doctor after any configuration change to verify everything still works.

specforge status

Display the current work context: active project, specification, and ticket status summary.

specforge status

Planning & Review

specforge plan

Preview the implementation plan for the active specification. Shows ticket ordering, waves, and estimated effort without starting any work.

specforge plan

specforge plan --strategy parallel --json

specforge review-planning

Run the Planning Review gate for a specification. Evaluates readiness, completeness, and structural quality.

specforge review-planning [specId]

If no specId is provided, uses the active specification.

specforge review-implementation

Run the Implementation Review gate for a specification. Evaluates completed work against quality standards.

specforge review-implementation [specId]

Specification Management

specforge spec activate

Set a specification as the active context for the current project.

specforge spec activate <spec-id>

specforge spec deactivate

Clear the active specification context.

specforge spec deactivate

Team Management

specforge members add

Invite a user to the current project.

specforge members add <email> [--role <role>]

Roles: admin, member, viewer. Default is member.

specforge members add alice@example.com
specforge members add bob@example.com --role admin

specforge members role

Change a member’s role.

specforge members role <email> <role>

specforge members remove

Remove a member from the project.

specforge members remove <email>

⚠️ Removing a member revokes access immediately and cannot be undone — you must re-invite to restore access.

specforge invitations accept

Accept a project invitation.

specforge invitations accept <invitation-id>

specforge invitations decline

Decline a project invitation.

specforge invitations decline <invitation-id>

Agent Scaffolding

specforge scaffold

Generate or regenerate agent configuration files for detected coding tools. Use when adding a new tool to your environment or resetting a config you accidentally modified.

specforge scaffold

# Detect all tools and generate configs
specforge scaffold
 
# Target a specific tool
specforge scaffold --target claude-code
 
# Preview without writing
specforge scaffold --dry-run

Generated Files by Target

Feedback

specforge feedback

Submit feedback about SpecForge directly from the CLI.

specforge feedback

Opens an interactive prompt to categorize and describe your feedback.

File Summary

ℹ️ Add .specforge/ to your .gitignore if your config contains sensitive values. The .mcp.json file is safe to commit as long as you use environment variables for the API key instead of hardcoding it.

See Also

• Configuration Schema — Full schema for all configuration files
• MCP Tools — The 22 tools these commands configure access to
• Install CLI — First-time setup walkthrough