CLI reference

July 12, 2026 · View on GitHub

CLI reference

The speq CLI provides spec discovery, semantic search, and validation for spec-driven development.

Overview

speq <command> [subcommand] [options]

Command	Purpose
`domain`	List and explore spec domains
`feature`	List, get, and validate feature specs
`plan`	List and validate implementation plans
`decision-log`	Validate and show the permanent decision log
`record`	Merge plan deltas into permanent specs
`search`	Semantic search across scenarios

Domain commands

`speq domain list`

List all domains in the spec library.

speq domain list

Example

$ speq domain list
cli
validation
search

Feature commands

`speq feature list`

Display all features in a tree view.

speq feature list [domain]

Example

$ speq feature list
specs/
├── cli/
│   ├── validate/
│   └── record/
├── validation/
│   └── keyword-casing/
└── search/
    └── semantic/

`speq feature get`

Print a full feature spec, or a single scenario if a scenario name is appended to the path. Quote the path if the scenario name contains spaces.

speq feature get <domain>/<feature>
speq feature get "<domain>/<feature>/<scenario-name>"

Example

$ speq feature get cli/validate
$ speq feature get "cli/validate/Validation fails on missing field"

`speq feature validate`

Validate spec structure and syntax. Omit the target to validate every spec, or narrow it to a domain or a single feature.

speq feature validate [domain]
speq feature validate [domain/feature]

Example

$ speq feature validate validation
✓ validation/keyword-casing (0 errors, 0 warnings)

Checks:

Required sections (Feature, Background, Scenarios)
RFC 2119 keyword usage
Scenario step formatting
DELTA marker syntax

Plan commands

`speq plan list`

List all active plans in specs/_plans/, alphabetically, one per line.

speq plan list

Example

$ speq plan list
add-auth
fix-validation

Prints No active plans. if none exist.

`speq plan validate`

Validate a plan directory's structure and contents.

speq plan validate <plan-name>

Example

$ speq plan validate add-auth
✓ add-auth (0 errors, 0 warnings)

Checks:

Plan directory exists (specs/_plans/<plan-name>/)
plan.md is present
Delta markers are properly formatted
Spec syntax is valid
decision-log.md structure, if the file is present (absence is not an error)

Decision log commands

`speq decision-log validate`

Validate every fragment under specs/_decision/.

speq decision-log validate

Example

$ speq decision-log validate
Permanent decision log validation passed.

Checks:

Each fragment's H1 is # Decisions: <plan-name>
ADR headings follow ## ADR: <Title>
Each ADR contains all required fields: **ID:**, **Plan:**, **Status:**, ### Context, ### Decision
**ID:** is a kebab-case slug, unique across every fragment
**Status:** is one of: Accepted, Deprecated, Superseded by <slug>
Every **Supersedes:** and Superseded by <slug> reference resolves to a slug defined somewhere in specs/_decision/
### Options Considered and ### Consequences are optional; their absence does not trigger errors
An absent or empty specs/_decision/ directory passes

`speq decision-log show`

Assemble every fragment under specs/_decision/ into one # Architecture Decision Records view and print it to stdout. Writes nothing to disk.

speq decision-log show

Example

$ speq decision-log show
# Architecture Decision Records

## ADR: Adopt pure-Rust inference to remove the ONNX Runtime dependency

**ID:** pure-rust-inference
**Plan:** refactor-search-pure-rust-inference
**Status:** Accepted
...

Orders fragments by their numeric NNN- prefix, breaking ties by filename; ADRs within a fragment print in authoring order.

See Decision Log for the full format reference.

Record command

`speq record`

Merge approved plan deltas into permanent specs.

speq record <plan-name>

Example

$ speq record add-auth
Recorded plan 'add-auth' to specs/_recorded/

This command:

Reads delta specs from specs/_plans/<plan-name>/
Merges deltas into permanent specs in specs/<domain>/<feature>/
Strips DELTA markers
Archives the plan to specs/_recorded/NNN-<plan-name>/, where NNN is a record-time sequence number

Search commands

`speq search index`

Build or rebuild the semantic search index. The index is built automatically on first search; run this command to rebuild it manually after spec changes.

speq search index

Example

$ speq search index
Building search index...
Indexed 42 scenarios.

`speq search query`

Semantic search across all scenarios.

speq search query "<query>" [--limit <n>]

Example

$ speq search query "validation" --limit 3
cli/feature-validate/Validate single feature (score: 0.856)
  Validate single feature

cli/feature-validate/Summary at end (score: 0.853)
  Summary at end

Each result includes the feature path, scenario name, relevance score, and matching context.

Spec format and library structure

See Spec Library for the full spec format reference, including BDD/Gherkin structure, RFC 2119 keywords, and step formatting rules.