Skip to content

cli-reference.md

Latest commit

 

History

History
269 lines (192 loc) · 5.59 KB

cli-reference.md

File metadata and controls

269 lines (192 loc) · 5.59 KB
Raw

speq-skill / Docs / CLI Reference

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:

  1. Reads delta specs from specs/_plans/<plan-name>/
  2. Merges deltas into permanent specs in specs/<domain>/<feature>/
  3. Strips DELTA markers
  4. 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.