# CLI COMMANDS REFERENCE

Complete reference for all elspais commands.

## Global Options

These options work with all commands:

  `-v, --verbose`    Verbose output with details
  `-q, --quiet`      Suppress non-error output
  `--config PATH`    Path to configuration file
  `--spec-dir PATH`  Override spec directory

## validate

Validate requirements format, links, hashes, and hierarchy.

  $ elspais validate                   # Check all rules
  $ elspais validate -j                # Output JSON for tooling
  $ elspais validate --mode core        # Exclude associated repo specs
  $ elspais validate --mode associate   # Local specs only, suppress cross-repo warnings

To auto-fix issues, use: `elspais fix`

**Options:**

  `-j, --json`          Output requirements as JSON
  `--export`            Export requirements as JSON dict keyed by ID
  `--mode {core,combined,associate}`  core: only local specs, associate: local specs with cross-repo warnings suppressed, combined: include associated repos

## fix

Auto-fix spec file issues (hashes, formatting).

  $ elspais fix                   # Fix all issues
  $ elspais fix --dry-run         # Preview fixes without applying
  $ elspais fix REQ-p00001        # Fix hash for a specific requirement

**Options:**

  `REQ_ID`        Specific requirement ID to fix (hash only)
  `--dry-run`     Show what would be fixed without making changes

## trace

Generate traceability matrix and reports.

  $ elspais trace --view          # Interactive HTML view
  $ elspais trace --format html   # Basic HTML matrix
  $ elspais trace --graph-json    # Export graph as JSON

**Options:**

  `--path DIR`             Path to repository root (default: auto-detect)
  `--format {markdown,html,csv,both}`  Output format (default: both)
  `--output PATH`          Output file path
  `--view`                 Interactive HTML traceability tree
  `--embed-content`        Embed full markdown in HTML for offline
  `--graph`                Use unified traceability graph
  `--graph-json`           Output graph structure as JSON
  `--report NAME`          Report preset (minimal, standard, full)
  `--depth LEVEL`          Max graph depth (0=roots, 1=children, ...)
  `--mode {core,sponsor,combined}`  Report scope
  `--sponsor NAME`         Sponsor name for filtered reports

**Depth Levels:**

  `0` or `requirements`    Show only requirements
  `1` or `assertions`      Include assertions
  `2` or `implementation`  Include code references
  `full`                   Unlimited depth

**Planned Options (not yet implemented):**

  `--edit-mode`    In-browser editing of implements/status
  `--review-mode`  Collaborative review with comments
  `--server`       Start review server
  `--port PORT`    Port for review server

## pdf

Compile spec files into a PDF document.

  $ elspais pdf                              # Generate spec-output.pdf
  $ elspais pdf --output review.pdf          # Custom output path
  $ elspais pdf --title "My Project Specs"   # Custom title
  $ elspais pdf --overview                   # PRD-only stakeholder overview
  $ elspais pdf --overview --max-depth 2     # Overview with depth limit

**Options:**

  `--output PATH`       Output PDF file path (default: spec-output.pdf)
  `--engine ENGINE`     PDF engine: xelatex (default), lualatex, pdflatex
  `--template PATH`     Custom pandoc LaTeX template
  `--title TITLE`       Document title
  `--cover PATH`        Markdown file for custom cover page
  `--overview`          Generate stakeholder overview (PRD only, no OPS/DEV)
  `--max-depth N`       Max graph depth for core PRDs in overview mode

**Prerequisites:**

- pandoc: <https://pandoc.org/installing.html>
- xelatex: Install TeX Live, MiKTeX, or MacTeX

**Overview Mode:**

Generates a lighter document for stakeholders:
- Only PRD-level requirements from all repos
- No OPS or DEV requirements
- Default title: "Product Requirements Overview"
- `--max-depth` limits core PRD depth (associates always fully included)

## analyze

Analyze requirement hierarchy and coverage.

  $ elspais analyze hierarchy     # Tree view of requirements
  $ elspais analyze orphans       # Find parentless requirements
  $ elspais analyze coverage      # Implementation coverage report

**Subcommands:**

  `hierarchy`   Show requirement hierarchy tree
  `orphans`     Find requirements with no parent
  `coverage`    Implementation coverage report

## changed

Detect git changes to spec files.

  $ elspais changed               # Show all spec changes
  $ elspais changed -j            # Output as JSON
  $ elspais changed -a            # Include non-spec files

**Options:**

  `--base-branch BRANCH`  Base branch for comparison (default: main)
  `-j, --json`            Output as JSON
  `-a, --all`             Include all changed files, not just spec

**What's Detected:**

  Uncommitted changes (modified/new spec files)
  Changes vs main/master branch
  Moved requirements (relocated to different file)

## index

Manage INDEX.md file.

  $ elspais index validate       # Check accuracy
  $ elspais index regenerate     # Rebuild from scratch

**Subcommands:**

  `validate`     Validate INDEX.md matches actual requirements
  `regenerate`   Regenerate INDEX.md from current spec files

## edit

Edit requirements in-place.

  $ elspais edit --req-id REQ-d00001 --status Draft
  $ elspais edit --req-id REQ-d00001 --implements REQ-p00001,REQ-p00002
  $ elspais edit --req-id REQ-d00001 --move-to roadmap/future.md
  $ elspais edit --from-json edits.json

**Options:**

  `--req-id ID`         Requirement ID to edit
  `--implements REFS`   New Implements (comma-separated, "" to clear)
  `--status STATUS`     New Status value
  `--move-to FILE`      Move to file (relative to spec dir)
  `--from-json FILE`    Batch edit from JSON (- for stdin)
  `--dry-run`           Show changes without applying
  `--validate-refs`     Validate implements references exist

**Batch JSON Format:**

```json
[
  {"req_id": "REQ-d00001", "status": "Draft"},
  {"req_id": "REQ-d00002", "implements": ["REQ-p00001"]}
]
```

## config

View and modify configuration.

  $ elspais config show           # View all settings
  $ elspais config get patterns.prefix
  $ elspais config set project.name "MyApp"
  $ elspais config path           # Show config file location

**Subcommands:**

  `show [--section] [-j]`  Show current configuration
  `get KEY [-j]`           Get value (dot-notation: patterns.prefix)
  `set KEY VALUE`          Set value (auto-detects type)
  `unset KEY`              Remove a key
  `add KEY VALUE`          Add value to array
  `remove KEY VALUE`       Remove value from array
  `path`                   Show config file location

**Examples:**

  $ elspais config get rules.strict_mode
  $ elspais config set rules.strict_mode true
  $ elspais config add directories.code src/lib
  $ elspais config unset associated.prefix

## init

Create .elspais.toml configuration.

  $ elspais init                  # Create default config
  $ elspais init --template       # Also create example requirement

**Options:**

  `--type {core,associated}`   Repository type
  `--associated-prefix PREFIX` Prefix for associated repo
  `--force`                    Overwrite existing configuration
  `--template`                 Create example requirement in spec/

## example

Display requirement format examples.

  $ elspais example               # Quick format reference
  $ elspais example --full        # Full specification document
  $ elspais example journey       # User journey template

**Arguments:**

  `requirement`  Full requirement template (default)
  `journey`      User journey template
  `assertion`    Assertion rules and examples
  `ids`          Show ID patterns from current config

**Options:**

  `--full`   Display full requirements specification file

## rules

View and manage content rules.

  $ elspais rules list            # List configured rules
  $ elspais rules show myfile.md  # Show rule file content

**Subcommands:**

  `list`        List configured content rules
  `show FILE`   Show content of a rule file

## docs

Read the user guide.

  $ elspais docs                  # Quickstart guide
  $ elspais docs config           # Configuration reference
  $ elspais docs all              # Complete documentation

**Arguments:**

  `quickstart`     Getting started guide (default)
  `format`         Requirement file format
  `hierarchy`      PRD/OPS/DEV levels
  `assertions`     Writing testable assertions
  `traceability`   Linking to code and tests
  `validation`     Running validation
  `git`            Change detection
  `config`         Configuration reference
  `commands`       This CLI reference
  `mcp`            MCP server for AI integration
  `all`            All topics concatenated

**Options:**

  `--plain`      Plain text output (no ANSI colors)
  `--no-pager`   Disable paging (print to stdout)

## completion

Generate shell tab-completion scripts.

  $ elspais completion            # Instructions
  $ elspais completion --shell bash > ~/.elspais-complete.bash

**Options:**

  `--shell {bash,zsh,fish,tcsh}`  Generate for specific shell

**Setup:**

  $ elspais completion --install    # Auto-detect shell and install

## version

Show version information.

  $ elspais version               # Show current version
  $ elspais --version             # Alternative

## doctor

Diagnose your elspais environment and installation.

  $ elspais doctor              # Quick setup check
  $ elspais doctor -v           # Detailed output
  $ elspais doctor -j           # JSON output for CI

**What it checks:**

  Configuration file exists, syntax, required fields
  ID pattern placeholders and spec directory paths
  Git worktree detection and canonical root
  Associate paths and configurations
  Local configuration (.elspais.local.toml)

**Options:**

  `-j, --json`     Output results as JSON
  `-v, --verbose`  Show detailed information for each check

## health

Run health checks across configuration, spec files, code, and tests.

  $ elspais health              # Run all checks
  $ elspais health --config     # Configuration only
  $ elspais health --spec       # Spec file checks
  $ elspais health --code       # Code reference checks
  $ elspais health --tests      # Test mapping checks
  $ elspais health -j           # JSON output

**Options:**

  `--config`       Run configuration checks only
  `--spec`         Run spec file checks only
  `--code`         Run code reference checks only
  `--tests`        Run test mapping checks only
  `-j, --json`     Output as JSON
  `-v, --verbose`  Show additional details

## associate

Manage links to associated repositories.

  $ elspais associate /path/to/repo    # Link a specific associate
  $ elspais associate --all            # Auto-discover and link all
  $ elspais associate --list           # Show linked associates
  $ elspais associate --unlink NAME    # Remove a link

**Options:**

  `--all`            Auto-discover and link all associates
  `--list`           Show status of linked associates
  `--unlink NAME`    Remove a linked associate (matches name, path, or prefix code)

**Notes:**

  Links are stored in `.elspais.local.toml` (gitignored, not shared)
  Validates target has `project.type = "associated"` in its config
  Accepts a path or a name (searches sibling directories)
  Worktree-safe: resolves relative paths from canonical repo root

## mcp

MCP (Model Context Protocol) server commands.

  $ elspais mcp install --global --desktop   # One-time setup
  $ elspais mcp serve                        # Start MCP server

**Note:** Requires `elspais[mcp]` extra.

**Subcommands:**

  `serve`      Start MCP server
  `install`    Register with Claude Code and/or Claude Desktop
  `uninstall`  Remove registration

**Options for install/uninstall:**

  `--global`   Claude Code: user scope (all projects) instead of current project
  `--desktop`  Also write to Claude Desktop config

**Options for serve:**

  `--transport {stdio,sse,streamable-http}`  Transport type (default: stdio)
