Reference
CLI Reference

CLI Reference

Complete command-line reference for fspec.

Getting Help

Every command has comprehensive --help documentation:

fspec --help                    # Main help
fspec help specs                # Command group help
fspec validate --help           # Specific command help

All fspec commands include:

  • Description and purpose
  • Usage syntax with arguments/options
  • AI-optimized sections (WHEN TO USE, PREREQUISITES, TYPICAL WORKFLOW, COMMON ERRORS, COMMON PATTERNS)
  • Complete examples with expected output
  • Related commands
  • Notes and best practices

Command Groups

fspec commands are organized into five logical groups:

specs - Gherkin Specifications

Gherkin validation, feature/scenario/step CRUD, bulk operations, formatting, coverage tracking.

Use this when you need to:

  • Create new feature files with proper Gherkin structure
  • Add, edit, or delete scenarios and steps
  • Validate Gherkin syntax using official Cucumber parser
  • Format feature files for consistency
  • Link scenarios to tests and implementation

Key commands:

  • fspec create-feature <name> - Create new feature file
  • fspec add-scenario <feature> <title> - Add scenario
  • fspec add-step <feature> <scenario> <keyword> <text> - Add step
  • fspec validate - Validate Gherkin syntax
  • fspec format - Format feature files
  • fspec link-coverage <feature> - Link tests/implementation
  • fspec show-coverage [feature] - Show coverage report

View all specs commands →

work - Work Management

Work units, epics, Kanban workflow, dependencies, board visualization.

Use this when you need to:

  • Create and organize work units into a backlog
  • Move work through Kanban states (backlog → specifying → testing → implementing → validating → done)
  • Prioritize work in the backlog
  • Manage dependencies between work units
  • Display the Kanban board

Key commands:

  • fspec create-work-unit <prefix> <title> - Create work unit
  • fspec list-work-units - List all work units
  • fspec update-work-unit-status <id> <status> - Move through workflow
  • fspec add-dependency <id> <depends-on-id> - Add dependency
  • fspec board - Display Kanban board
  • fspec auto-advance - Auto-advance ready work units

View all work commands →

discovery - Example Mapping

Example mapping for collaborative discovery (questions, rules, examples, assumptions).

Use this when you need to:

  • Add concrete examples to explore behavior
  • Add questions that need answers before implementation
  • Add business rules that govern the feature
  • Answer questions collaboratively (AI asks, human answers)
  • Generate Gherkin scenarios from examples

Key commands:

  • fspec add-rule <id> <rule> - Add business rule
  • fspec add-example <id> <example> - Add concrete example
  • fspec add-question <id> <question> - Ask question
  • fspec answer-question <id> <index> - Answer question
  • fspec generate-scenarios <id> - Generate Gherkin from examples
  • fspec query-example-mapping-stats - Show coverage

View all discovery commands →

metrics - Progress Tracking

Progress tracking, estimation, reports, token/time recording.

Use this when you need to:

  • Record time spent, tokens used, iterations completed
  • Update and track work unit estimates
  • Query estimation accuracy (actual vs estimated)
  • Generate comprehensive summary reports
  • Export work units for external analysis

Key commands:

  • fspec record-metric <id> <name> <value> - Record metric
  • fspec record-tokens <id> <tokens> - Record tokens used
  • fspec query-metrics - Show all metrics
  • fspec query-estimate-accuracy - Show estimation accuracy
  • fspec generate-summary-report - Generate project report

Examples:

fspec record-metric AUTH-001 time-spent 120
fspec record-tokens AUTH-001 15000
fspec query-metrics --format=json
fspec generate-summary-report --format=markdown --output=report.md

setup - Configuration

Tag registry, foundation docs, Mermaid diagrams, prefixes, epics.

Use this when you need to:

  • Register tags in the centralized registry
  • Create and manage epics (high-level initiatives)
  • Create and manage prefixes (namespaces for work unit IDs)
  • Add and validate Mermaid architecture diagrams
  • Update foundation documentation

Key commands:

  • fspec register-tag <tag> <category> <description> - Register tag
  • fspec list-tags - List all tags
  • fspec create-epic <name> <title> - Create epic
  • fspec create-prefix <prefix> <description> - Create prefix
  • fspec add-diagram <section> <title> <content> - Add Mermaid diagram
  • fspec show-foundation - Show foundation documentation

Examples:

fspec register-tag @performance "Technical Tags" "Performance-critical features"
fspec create-epic user-management "User Management Features"
fspec create-prefix AUTH "Authentication features"
fspec add-diagram "Architecture" "System Overview" "graph TB\n  A-->B"

Common Workflows

Forward ACDD (New Features)

# 1. Create work unit and move to specifying
fspec create-work-unit AUTH "User login"
fspec update-work-unit-status AUTH-001 specifying
 
# 2. Set user story
fspec set-user-story AUTH-001 \
  --role "registered user" \
  --action "log in to my account" \
  --benefit "I can access my dashboard"
 
# 3. Example Mapping (discovery)
fspec add-rule AUTH-001 "Password must be 8+ characters"
fspec add-example AUTH-001 "User logs in with valid email and password"
fspec add-question AUTH-001 "Should we support OAuth?"
fspec answer-question AUTH-001 0 --answer "Yes, via Auth0" --add-to rule
 
# 4. Generate scenarios
fspec generate-scenarios AUTH-001
 
# 5. Move to testing and write tests
fspec update-work-unit-status AUTH-001 testing
# ... write FAILING tests
 
# 6. Link tests to scenarios
fspec link-coverage user-login --scenario "Login with valid credentials" \
  --test-file src/__tests__/auth.test.ts --test-lines 45-62
 
# 7. Move to implementing and write code
fspec update-work-unit-status AUTH-001 implementing
# ... write code to make tests pass
 
# 8. Link implementation
fspec link-coverage user-login --scenario "Login with valid credentials" \
  --test-file src/__tests__/auth.test.ts \
  --impl-file src/auth/login.ts --impl-lines 10-24
 
# 9. Validate and complete
fspec update-work-unit-status AUTH-001 validating
fspec update-work-unit-status AUTH-001 done

Reverse ACDD (Existing Code)

# Use fspec reverse command via Claude Code
fspec reverse
 
# Or manually:
# 1. Create work unit for existing feature
fspec create-work-unit AUTH "User login (existing)" --epic=authentication
fspec update-work-unit-status AUTH-001 specifying
 
# 2. Analyze code and create scenarios
fspec create-feature "User Login"
fspec add-scenario user-login "Login with valid credentials"
fspec add-step user-login "Login with valid credentials" given "I am on the login page"
 
# 3. Create test skeleton
# ... create skeleton test file
 
# 4. Link to existing code (use --skip-validation)
fspec link-coverage user-login --scenario "Login with valid credentials" \
  --test-file src/__tests__/auth.test.ts --test-lines 10-25 \
  --impl-file src/routes/auth.ts --impl-lines 45-67 \
  --skip-validation
 
# 5. Check coverage
fspec show-coverage user-login

Validation and Quality Checks

# Validate Gherkin syntax
fspec validate
 
# Format feature files
fspec format
 
# Validate tags are registered
fspec validate-tags
 
# Run all checks
fspec check --verbose
 
# Check coverage gaps
fspec show-coverage
fspec audit-coverage user-login --fix

Querying and Reporting

# List work units by status
fspec list-work-units --status=implementing
 
# Show Kanban board
fspec board
 
# Query scenarios by tag
fspec get-scenarios --tag=@phase1 --tag=@critical
 
# Show acceptance criteria
fspec show-acceptance-criteria --tag=@phase1 --format=markdown
 
# Export work units
fspec export-work-units --format=json --output=work.json
 
# Generate summary report
fspec generate-summary-report --output=report.md

Output Formats

Many commands support multiple output formats:

# Text output (human-readable, default)
fspec list-features
 
# JSON output (machine-readable)
fspec list-features --format=json
 
# Markdown output (documentation)
fspec show-acceptance-criteria --format=markdown
 
# CSV output (spreadsheet)
fspec export-work-units --format=csv
 
# Mermaid output (diagrams)
fspec export-dependencies --format=mermaid

Common Options

Filtering

# By status
fspec list-work-units --status=implementing
 
# By prefix
fspec list-work-units --prefix=AUTH
 
# By epic
fspec list-work-units --epic=user-management
 
# By tag (AND logic)
fspec get-scenarios --tag=@phase1 --tag=@critical

Output Control

# Write to file
fspec show-feature login --output=login.txt
 
# Format selection
fspec show-coverage --format=json
 
# Verbose output
fspec validate --verbose
fspec check --verbose

Dry Run

# Preview without making changes
fspec delete-features-by-tag --tag=@deprecated --dry-run
fspec auto-advance --dry-run
fspec generate-coverage --dry-run

Environment Variables

# Override fspec directory
export FSPEC_DIR=/path/to/spec
 
# Disable colors
export NO_COLOR=1

Exit Codes

  • 0 - Success
  • 1 - Error (validation failure, command error)
  • 2 - Invalid usage (missing arguments, unknown flags)

Tips and Best Practices

  1. Use --help extensively - Every command has comprehensive help with examples
  2. Check status before advancing - Run fspec board to see current state
  3. Validate early and often - Run fspec check before committing
  4. Link coverage immediately - Don't wait until the end to map scenarios
  5. Use dry-run for bulk operations - Preview changes with --dry-run
  6. Export for backups - Regularly export work units and dependencies
  7. Tag consistently - Use fspec validate-tags to catch mistakes

See Also

CLI ReferencePrivacy