Skip to content

cli-reference.md

Latest commit

 

History

History
227 lines (157 loc) · 4.24 KB

cli-reference.md

File metadata and controls

227 lines (157 loc) · 4.24 KB

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 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

Output:

cli
validation
search

Feature Commands

speq feature list

Display all features in a tree view.

# All features
speq feature list

# Features in a specific domain
speq feature list <domain>

Output:

specs/
├── cli/
│   ├── validate/
│   └── record/
├── validation/
│   └── keyword-casing/
└── search/
    └── semantic/

speq feature get

Get full feature spec or a single scenario.

# Full feature spec
speq feature get <domain>/<feature>

# Single scenario (quote if name has spaces)
speq feature get "<domain>/<feature>/<scenario-name>"

Examples:

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

speq feature validate

Validate spec structure and syntax.

# Validate all specs
speq feature validate

# Validate a domain
speq feature validate <domain>

# Validate a single feature
speq feature validate <domain>/<feature>

Validation 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/.

speq plan list

Output:

add-auth
fix-validation

Plans are listed alphabetically, one per line. Prints "No active plans." if none exist.

speq plan validate

Validate a plan directory structure and contents.

speq plan validate <plan-name>

Validates:

  • Plan directory exists (specs/_plans/<plan-name>/)
  • plan.md is present
  • Delta markers 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 the permanent decision log at specs/decision-log.md.

speq decision-log validate

Validates:

  • File exists (exits non-zero with an error message if absent)
  • H1 is # Architecture Decision Records
  • ADR headings follow ## ADR-NNN: <Title> — sequential, no gaps, starting at ADR-001
  • Each ADR contains all required fields: **Date:**, **Plan:**, **Status:**, ### Context, ### Decision
  • **Status:** is one of: Accepted, Superseded by ADR-NNN, Deprecated

### Options Considered and ### Consequences are optional and do not trigger errors when absent.

See Decision Log for the full format reference.

Record Command

speq record

Merge approved plan deltas into permanent specs.

speq record <plan-name>

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 plan to specs/_recorded/YYYY-MM-DD-<plan-name>/

Search Commands

speq search index

Build or rebuild the semantic search index.

speq search index

The index is built automatically on first search. Use this command to manually rebuild after spec changes.

speq search query

Semantic search across all scenarios.

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

Examples:

speq search query "error handling"
speq search query "validation" --limit 5

Output includes:

  • Feature path
  • Scenario name
  • Relevance score
  • 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.