Skip to main content

CLI Commands

Complete reference for all LeanSpec CLI commands.

Global Options​

Available for all commands:

  • --help - Show help for a command
  • --version - Show LeanSpec version

Commands​

lean-spec init​

Initialize LeanSpec in your project.

lean-spec init

Interactive prompts:

  1. Choose setup path (quick start, choose template, or customize)
  2. Handle existing files (merge, backup, or skip)
  3. Configure initial settings

What it creates:

  • .lean-spec/config.json - Configuration file
  • .lean-spec/templates/ - Custom templates directory
  • specs/ - Specs directory
  • AGENTS.md - AI agent integration guidance (if not present)

Options:

  • None (fully interactive)

lean-spec create​

Create a new spec.

lean-spec create <name> [options]

Arguments:

  • <name> - Spec name (required)

Options:

  • --title <title> - Set custom title
  • --description <desc> - Set initial description
  • --tags <tags> - Comma-separated tags
  • --priority <priority> - Set priority (low, medium, high, critical)
  • --assignee <name> - Set assignee
  • --template <template> - Use a specific template
  • --field <name=value> - Set custom field (can be used multiple times)
  • --no-prefix - Skip date prefix even if configured

Examples:

# Basic spec
lean-spec create user-authentication

# Spec with metadata
lean-spec create user-auth --status=planned --priority=high --tags=security,api

# Spec with custom fields
lean-spec create user-auth --field epic=PROJ-123 --field sprint=42

Output:

✓ Created: specs/001-user-authentication/
  Edit: specs/001-user-authentication/README.md

Behavior:

  • Creates specs/NNN-name/ directory (flat structure with global numbering)
  • Generates README.md from template
  • Assigns sequential number (NNN) globally across all specs
  • Sets frontmatter with metadata

Note: Default is flat structure. For date-based grouping, configure pattern: "custom" in .lean-spec/config.json.

lean-spec list​

List all specs with optional filtering.

lean-spec list [options]

Options:

  • --archived - Include archived specs
  • --status <status> - Filter by status (planned, in-progress, complete, archived)
  • --priority <priority> - Filter by priority (low, medium, high, critical)
  • --tag <tag> - Filter by tag (use multiple --tag flags for multiple tags)
  • --assignee <name> - Filter by assignee
  • --field <name=value> - Filter by custom field (can specify multiple)
  • --sort <field> - Sort by field (id, created, name, status, priority) (default: id)
  • --order <order> - Sort order (asc, desc) (default: desc)

Examples:

# List all specs
lean-spec list

# Filter by status
lean-spec list --status=in-progress
lean-spec list --status=planned

# Filter by priority
lean-spec list --priority=high

# Filter by tag
lean-spec list --tag api

# Filter by multiple tags
lean-spec list --tag api --tag backend

# Combine filters
lean-spec list --status planned --priority high --tag api

# Filter by custom field
lean-spec list --field epic=PROJ-123

Output:

=== Specs ===

📅 specs/001-user-authentication
   Created: 2025-11-02 · Priority: high · Tags: security, api

⏳ specs/002-password-reset
   Created: 2025-11-02 · Priority: medium

Note: Output shows flat structure (default). With date-grouping configured, paths would be specs/YYYYMMDD/NNN-name/.

Status Icons:

  • 📅 Planned
  • ⏳ In progress
  • ✅ Complete
  • 📦 Archived

lean-spec update​

Update spec metadata.

lean-spec update <spec> [options]

Arguments:

  • <spec> - Spec identifier (required). Can be:
    • Spec number: 42 or 042
    • Spec name: unified-dashboard
    • Full folder: 045-unified-dashboard

Options:

  • --status <status> - Update status (planned, in-progress, complete, archived)
  • --priority <priority> - Update priority (low, medium, high, critical)
  • --tags <tags> - Update tags (comma-separated, replaces existing)
  • --assignee <name> - Set assignee
  • --field <name=value> - Update custom field (can be used multiple times)

Examples:

# Update status (using spec number)
lean-spec update 1 --status=in-progress

# Update priority (using spec name)
lean-spec update user-auth --priority=critical

# Update tags
lean-spec update 001-user-auth --tags=security,api,mvp

# Update custom fields
lean-spec update 1 --field epic=PROJ-123

# Update multiple fields
lean-spec update 1 --status=complete --priority=high

Output:

✓ Updated: specs/001-user-auth
  Fields: status, priority

Special Behavior:

  • Setting status to complete automatically adds completed timestamp
  • Visual badges in README.md are auto-updated
  • Both frontmatter and badges stay in sync

Full-text search across all specs.

lean-spec search <query> [options]

Arguments:

  • <query> - Search query (required)

Options:

  • --status <status> - Filter results by status
  • --priority <priority> - Filter results by priority
  • --tag <tag> - Filter results by tag
  • --assignee <name> - Filter results by assignee
  • --field <name=value> - Filter results by custom field (can specify multiple)

Examples:

# Basic search
lean-spec search "authentication"

# Search with filters
lean-spec search "JWT token" --status=in-progress
lean-spec search "API" --tag=security
lean-spec search "password" --field epic=PROJ-123

Output:

Found 2 specs matching "authentication":

📅 specs/001-user-authentication
   Created: 2025-11-02
   Matches in: Overview, Key Scenarios

⏳ specs/003-two-factor-auth
   Created: 2025-11-02
   Matches in: Technical Approach

Search Behavior:

  • Searches in spec content (README.md)
  • Case-insensitive
  • Searches title, overview, scenarios, criteria, etc.
  • Does not search frontmatter metadata

lean-spec archive​

Archive completed specs.

lean-spec archive <spec>

Arguments:

  • <spec> - Spec identifier (required). Can be:
    • Spec number: 42 or 042
    • Spec name: unified-dashboard
    • Full folder: 045-unified-dashboard

Examples:

# Archive by spec number
lean-spec archive 1

# Archive by name
lean-spec archive user-auth

Output:

✓ Archived: specs/001-user-auth
  Moved to: specs/archived/001-user-auth

Behavior:

  • Moves spec from specs/ to specs/archived/
  • Preserves directory structure
  • Keeps all metadata
  • Spec no longer appears in lean-spec list by default

Best Practice:

  • Update status to complete before archiving
  • Archive specs when work is fully done
  • Use to keep active workspace clean

lean-spec view​

View spec content.

lean-spec view <spec> [options]

Arguments:

  • <spec> - Spec identifier (required). Can be:
    • Spec number: 42 or 042
    • Spec name: unified-dashboard
    • Full folder: 045-unified-dashboard

Options:

  • --raw - Output raw markdown (for piping/scripting)
  • --json - Output as JSON
  • --no-color - Disable colors

Examples:

# View formatted spec
lean-spec view 001-user-authentication

# Get raw markdown (for scripting)
lean-spec view 001-user-auth --raw | grep "TODO"

# Get structured JSON
lean-spec view 001-user-auth --json | jq '.frontmatter.status'

Default Output (formatted):

━━━ 001-user-authentication ━━━

📅 Status: planned
🟡 Priority: high
📆 Created: 2025-11-02
🏷️  Tags: #security #api

────────────────────────────────────────────────────────────

# User Authentication

## Overview
...

Raw Output (--raw):

---
status: planned
priority: high
created: 2025-11-02
tags:
  - security
  - api
---

# User Authentication

## Overview
...

JSON Output (--json):

{
  "name": "001-user-authentication",
  "path": "specs/001-user-authentication",
  "frontmatter": {
    "status": "planned",
    "priority": "high",
    "created": "2025-11-02",
    "tags": ["security", "api"]
  },
  "content": "# User Authentication\n\n## Overview\n..."
}

Use Cases:

  • Default: Human-readable spec viewing
  • --raw: Piping to other tools, AI context, version control diffs
  • --json: Programmatic access, CI/CD, integrations

lean-spec open​

Open spec in editor.

lean-spec open <spec> [options]

Arguments:

  • <spec> - Spec identifier (required). Can be:
    • Spec number: 42 or 042
    • Spec name: unified-dashboard
    • Full folder: 045-unified-dashboard

Options:

  • --editor <editor> - Specify editor command

Examples:

# Open in default editor
lean-spec open 001-user-authentication

# Open in specific editor
lean-spec open 001-user-auth --editor=code
lean-spec open 001-user-auth --editor=vim

Editor Selection:

  1. --editor flag if provided
  2. $VISUAL environment variable
  3. $EDITOR environment variable
  4. System default (open on macOS, xdg-open on Linux, start on Windows)

Behavior:

  • Opens the spec's README.md file
  • GUI editors (VS Code, Atom) don't block terminal
  • Terminal editors (vim, nano) block until closed

lean-spec templates​

List available project templates.

lean-spec templates

Output:

=== Available Templates ===

minimal        Just folder structure, no extras
standard       Recommended - includes AGENTS.md (default)
enterprise     Governance with approvals and compliance

Use: lean-spec init
Then choose "Choose a template" option

lean-spec stats​

Show statistics about specs.

lean-spec stats

Output:

=== Spec Statistics ===

Total Specs: 15
  Planned: 5
  In Progress: 7
  Complete: 3

By Priority:
  Critical: 2
  High: 6
  Medium: 5
  Low: 2

By Tag:
  api: 8
  security: 5
  ui: 3

lean-spec board​

View specs organized by status (Kanban-style).

lean-spec board

Output:

╔═══════════════════════════════════════════════════════════╗
║                    LeanSpec Board                         ║
╠═══════════════════════════════════════════════════════════╣
║ PLANNED          IN PROGRESS         COMPLETE             ║
╠─────────────────┬────────────────────┬────────────────────╣
║ user-auth       │ api-gateway        │ login-ui           ║
║ rate-limiting   │ database-setup     │ password-hash      ║
║ oauth-provider  │ error-handling     │ session-mgmt       ║
║                 │                    │                    ║
║ 3 specs         │ 3 specs            │ 3 specs            ║
╚═════════════════╧════════════════════╧════════════════════╝

lean-spec deps​

Show dependencies for a spec (coming soon).

lean-spec deps <spec>

Arguments:

  • <spec> - Spec identifier. Can be:
    • Spec number: 42 or 042
    • Spec name: unified-dashboard
    • Full folder: 045-unified-dashboard

Note: This feature is planned but not yet implemented.

Spec Identifiers​

All commands that accept a <spec> argument support flexible formats:

# Spec number (with or without padding)
42
042

# Spec name
unified-dashboard

# Full folder name
045-unified-dashboard

# With old date-based structure (still supported)
specs/20251102/001-user-auth
20251102/001-user-auth
001-user-auth

LeanSpec will find the spec regardless of which format you use.

Configuration​

Commands respect settings in .lean-spec/config.json:

{
  "template": "spec-template.md",
  "specsDir": "specs",
  "structure": {
    "pattern": "flat",
    "sequenceDigits": 3,
    "defaultFile": "README.md"
  },
  "frontmatter": {
    "required": ["status", "created"],
    "optional": ["tags", "priority"],
    "custom": {
      "epic": "string",
      "sprint": "number"
    }
  }
}

See Configuration Reference for details.

Exit Codes​

  • 0 - Success
  • 1 - Error (invalid arguments, file not found, etc.)
  • 2 - User cancelled operation

Next: Explore Configuration or learn about Custom Fields.