CLI Reference

Generated from fspec v0.2.1 --help output

This reference is auto-generated from the actual fspec --help output to ensure it never drifts from the actual command behavior.

Command Structure

All fspec commands follow this pattern:

fspec <command> [options] [arguments]

Every command supports --help for detailed documentation:

fspec <command> --help

Work Management Commands

`fspec create-work-unit`

Create a new work unit (story, bug, or task).

Usage:

fspec create-work-unit <PREFIX> <title> [options]

Options:

--type <type> - Work unit type: story, bug, or task (default: story)
--epic <epic-id> - Epic to associate with
--description <desc> - Detailed description

Example:

fspec create-work-unit AUTH "User login" --type story

`fspec list-work-units`

List all work units with filtering options.

Usage:

fspec list-work-units [options]

Options:

--status <status> - Filter by status (backlog, specifying, testing, implementing, validating, done, blocked)
--prefix <prefix> - Filter by prefix (e.g., AUTH, UI, API)
--epic <epic-id> - Filter by epic

Example:

fspec list-work-units --status=implementing

`fspec show-work-unit`

Show detailed information about a specific work unit.

Usage:

fspec show-work-unit <work-unit-id>

`fspec update-work-unit-status`

Update work unit status (move through Kanban workflow).

Usage:

fspec update-work-unit-status <work-unit-id> <new-status> [options]

Options:

--skip-temporal-validation - Skip timestamp validation (for reverse ACDD)

Valid statuses: backlog, specifying, testing, implementing, validating, done, blocked

`fspec board`

Display visual Kanban board showing all work units.

Usage:

fspec board

Specification Commands

`fspec create-feature`

Create a new Gherkin feature file.

Usage:

fspec create-feature <feature-name>

`fspec validate`

Validate Gherkin syntax using official Cucumber parser.

Usage:

fspec validate [feature-file]

`fspec format`

Format feature files using AST-based formatter.

Usage:

fspec format [feature-file]

`fspec add-scenario`

Add a scenario to an existing feature file.

Usage:

fspec add-scenario <feature-name> <scenario-name>

Discovery Commands (Example Mapping)

`fspec set-user-story`

Set the user story for a work unit.

Usage:

fspec set-user-story <work-unit-id> --role <role> --action <action> --benefit <benefit>

`fspec add-rule`

Add a business rule (blue card).

Usage:

fspec add-rule <work-unit-id> <rule-text>

`fspec add-example`

Add a concrete example (green card).

Usage:

fspec add-example <work-unit-id> <example-text>

`fspec add-question`

Add a clarifying question (red card).

Usage:

fspec add-question <work-unit-id> <question-text>

`fspec generate-scenarios`

Generate Gherkin scenarios from Example Mapping.

Usage:

fspec generate-scenarios <work-unit-id>

Coverage Tracking Commands

`fspec generate-coverage`

Generate empty coverage files for all features.

Usage:

fspec generate-coverage

`fspec link-coverage`

Link scenarios to test files and implementation code.

Usage:

fspec link-coverage <feature-name> --scenario "<scenario-name>" \
  --test-file <path> --test-lines <range> \
  [--impl-file <path>] [--impl-lines <lines>]

Options:

--skip-validation - Skip file existence validation (for planning)

`fspec show-coverage`

Show coverage report for a feature or all features.

Usage:

fspec show-coverage [feature-name]

Virtual Hooks Commands

`fspec add-virtual-hook`

Add a work unit-scoped quality gate.

Usage:

fspec add-virtual-hook <work-unit-id> <event> <command> [options]

Options:

--blocking - Make hook blocking (prevent progression on failure)
--git-context - Auto-generate script that passes changed files

Events: pre-testing, post-testing, pre-implementing, post-implementing, pre-validating, post-validating

`fspec list-virtual-hooks`

List all virtual hooks for a work unit.

Usage:

fspec list-virtual-hooks <work-unit-id>

Checkpoint Commands

`fspec checkpoint`

Create a manual checkpoint for experimentation.

Usage:

fspec checkpoint <work-unit-id> <checkpoint-name>

`fspec list-checkpoints`

List all checkpoints for a work unit.

Usage:

fspec list-checkpoints <work-unit-id>

`fspec restore-checkpoint`

Restore from a checkpoint.

Usage:

fspec restore-checkpoint <work-unit-id> <checkpoint-name>

Reverse ACDD Commands

`fspec reverse`

Interactive reverse ACDD strategy planner.

Usage:

fspec reverse [options]

Options:

--strategy <A|B|C|D> - Choose strategy directly
--resume - Resume previous session
--status - Check current status

Strategies:

A: Spec Gap (generate specs from tests)
B: Test Gap (generate tests from specs)
C: Coverage Gap (link tests to code)
D: Full Reverse ACDD (analyze code, generate everything)

Tag Management Commands

`fspec register-tag`

Usage:

fspec register-tag <@tag> <category> <description>

`fspec add-tag-to-feature`

Add a tag to a feature file.

Usage:

fspec add-tag-to-feature <feature-file> <@tag>

`fspec validate-tags`

Validate all tags against registry.

Usage:

fspec validate-tags

Epic Management Commands

`fspec create-epic`

Create a new epic.

Usage:

fspec create-epic <title> <prefix> <description>

Global Options

All commands support:

--help - Show detailed help for the command
--version - Show fspec version

Getting Help

For comprehensive help on any command:

fspec <command> --help

For command group help:

fspec help specs      # Specification commands
fspec help work       # Work management commands
fspec help discovery  # Example Mapping commands

Note: This documentation is automatically kept in sync with the actual CLI implementation through CI/CD processes.

Reverse ACDD CLI Reference