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, and agent scaffolding.

npm install -g @specforge/cli
# or run directly
npx @specforge/cli <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]

configure accepts exactly five flat keys (no dotted paths). Anything else is rejected with an “invalid key” error:

# View all config
specforge configure
 
# View a specific value
specforge configure defaultProjectId
 
# Set the local MCP output format (json or toon)
specforge configure mcpOutputFormat json
 
# Set the default project / specification
specforge configure projectId proj_abc123
specforge configure specificationId spec_xyz789

Modifies .specforge/config.json (project keys) or ~/.specforge/config.json (global keys) directly. Useful for scripting or making point changes without re-running init.

ℹ️ Agent Teams settings (agentTeams.*) and other structured sections are not configure keys — they live in the .specforge/config.json file and are set by specforge init or by hand-editing that file. See Configuration Schema.

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

Diagnostics & Debug

specforge debug

Low-level diagnostics for inspecting the MCP surface and connectivity. Useful when troubleshooting an agent integration.

specforge debug call <tool>    # Direct MCP tool dispatch
specforge debug tools          # List available MCP tools
specforge debug test           # Connection test
specforge debug whoami         # Identity and config info

ℹ️ The planning-review gate and per-ticket assay run inside the MCP tools (complete_planning_session, complete_work_session) — there is no standalone specforge review command. See MCP Tools.

Team Management

specforge members add

Invite a user to the current project.

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

Roles: editor, viewer. Default is editor. (The project creator is the owner; invites accept only editor or viewer.)

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

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 17 tools these commands configure access to
• Install CLI — First-time setup walkthrough