CLI Commands

<TrackedFiles paths="crates/supersigil-cli/src/commands/*.rs" />

Global Options

These options apply to all commands:

Flag	Description
--color <when>	Color output: auto (default), always, never

Individual commands add their own flags as documented below.

supersigil init

Create a supersigil.toml config and optionally install agent skills.

supersigil init
supersigil init -y
supersigil init --no-skills
supersigil init --skills-path .agents/skills

In a terminal, init prompts whether to install agent skills (default: yes) and where to put them (default: .agents/skills/). In non-interactive environments (piped stdin, CI, or -y), it installs skills to the default path automatically.

Flag	Description
-y	Accept all defaults without prompting
--skills	Install skills (skip the yes/no prompt, still prompts for path in TTY)
--no-skills	Skip skills installation entirely
--skills-path <dir>	Install skills to a custom directory (implies --skills)

When a non-default skills path is used, init adds a [skills] section to the generated config:

paths = ["specs/**/*.md"]

[skills]
path = "custom/skills"

Does not overwrite an existing supersigil.toml.

supersigil new <type> <id>

Scaffold a new spec document.

supersigil new requirements auth
supersigil new design auth
supersigil new tasks auth
supersigil new --project backend requirements auth

The type argument is a document type: one of the four built-in types (requirements, design, tasks, adr) or any custom type defined in config. The id argument is the feature name used to derive the document ID and file path.

Convention:

• Document ID: {id}/{type_short} (e.g. auth/req, auth/design)
• File path: {spec_dir}{id}/{id}.{type_short}.md

In single-project mode, {spec_dir} is specs/. In multi-project mode, {spec_dir} is derived from the selected project’s glob pattern (e.g. backend/specs/ for a project with paths = ["backend/specs/**/*.md"]).

The requirements type is shortened to req in IDs and filenames. All other types use their full name.

The generated file includes a type-appropriate template with placeholder sections and components.

Flag	Description
--project <name>, -p	Target project (required in multi-project mode, invalid in single-project mode)

supersigil verify

Whole-graph verification. This is the CI command.

supersigil verify
supersigil verify --since main --committed-only
supersigil verify --project backend --format json

Builds the full document graph and runs structural checks, plugin evidence discovery, and coverage analysis.

Flag	Description
--since <ref>	Git ref for staleness checks
--committed-only	Only consider committed changes
--merge-base	Use merge-base for git diff
--project <name>, -p	Filter to a project (multi-project mode)
--format <fmt>	Output format: terminal (default), json, markdown
--detail <compact|full>	Detail level: in terminal mode, full disables finding collapse to show every finding; in JSON mode, compact omits evidence records on clean runs (default: compact)

Exit codes:

Code	Meaning
0	All checks pass
1	One or more errors found
2	Warnings only (no errors)

supersigil ls

List all discovered documents.

supersigil ls
supersigil ls --type requirements --status draft
supersigil ls --project frontend --format json

Flag	Description
--type <type>	Filter by document type
--status <status>	Filter by status
--project <name>, -p	Filter by project (multi-project mode)
--format <fmt>	Output format: terminal (default), json

supersigil context <id>

Structured view of a document’s relationships, criteria, and coverage.

supersigil context auth/req
supersigil context auth/req --format json

Returns the document’s metadata, criteria, coverage, implementing designs, tracked files, and dependency relationships.

Flag	Description
--format <fmt>	Output format: terminal (default), json
--detail <compact|full>	JSON detail level: compact omits raw components, full includes everything (default: compact)

supersigil status [id]

Coverage summary. Without an ID, shows project-wide totals. With an ID, shows detail for that document.

supersigil status
supersigil status auth/req
supersigil status --format json

Reports total criteria vs covered, broken down by document type and status.

Flag	Description
--format <fmt>	Output format: terminal (default), json

supersigil plan [id|prefix]

Outstanding work: unverified criteria, pending tasks with topological ordering.

supersigil plan                    # All outstanding work
supersigil plan auth               # Filter by prefix
supersigil plan auth/tasks         # Specific document
supersigil plan --full

Lists tasks in dependency order. Shows which criteria still need coverage and which tasks are blocked.

Flag	Description
--full	Show all criteria and full task details including completed items
--format <fmt>	Output format: terminal (default), json

supersigil refs [prefix]

List criterion refs in canonical doc-id#criterion-id form.

supersigil refs                    # All refs
supersigil refs auth               # Refs matching prefix
supersigil refs --all

Flag	Description
--all	Show all criterion refs (no context scoping)
--format <fmt>	Output format: terminal (default), json
--width <n>	Maximum body text width in terminal mode (default: 72, 0 = no truncation)

supersigil affected

List documents affected by file changes since a git ref.

supersigil affected --since main
supersigil affected --since HEAD~5 --committed-only
supersigil affected --since main --merge-base

Uses <TrackedFiles> globs to determine which spec documents are affected by the changed files.

Flag	Description
--since <ref>	Git ref to diff against (required)
--committed-only	Only consider committed changes
--merge-base	Use merge-base for git diff
--format <fmt>	Output format: terminal (default), json

supersigil graph

Output the document dependency graph.

supersigil graph                   # Mermaid format (default)
supersigil graph --format dot      # Graphviz DOT format
supersigil graph --format json     # Structured JSON for tooling

The JSON format outputs a structured representation of the graph with documents (including their components) and edges arrays. This is the format consumed by the graph explorer and can be used by custom tooling.

Flag	Description
--format <fmt>	Graph format: mermaid (default), dot, json

supersigil explore

Open an interactive graph explorer in your browser.

supersigil explore                 # Open in browser
supersigil explore --output graph.html  # Write to file instead

Generates a self-contained HTML file with an interactive D3.js visualization of the spec graph. The same visualization is available on the docs site at /explore/.

The explorer provides:

• Clustered force-directed layout with document nodes grouped by prefix
• Click to inspect document details (type, status, edges, components)
• Double-click to drill into a document’s internal components
• Filter by document type and status
• Impact trace to highlight everything downstream of a selected document
• Search with fuzzy matching on document ID and title
• URL deep-linking for shareable views

Flag	Description
--output <path>	Write HTML to this path instead of opening in browser

supersigil export

Export component trees with verification data for all documents.

supersigil export --format json

Outputs the parsed component hierarchy for every spec document, enriched with verification status and evidence entries. Each document produces a JSON object containing its fences (source-ordered supersigil-xml blocks with their component trees) and outgoing graph edges.

This is the data source for editor Markdown previews and the documentation site spec browser. Editor extensions call the equivalent LSP endpoint (supersigil/documentComponents) rather than shelling out to this command.

Flag	Description
--format <fmt>	Output format: json (default and only option)

supersigil schema

Display component and document type schema. Shows all built-in and configured components with their attributes, plus document type definitions with valid statuses.

supersigil schema                  # YAML format (default)
supersigil schema --format json

Flag	Description
--format <fmt>	Schema format: yaml (default), json

supersigil import --from kiro

Import Kiro format specs into Supersigil Markdown.

supersigil import --from kiro
supersigil import --from kiro --dry-run
supersigil import --from kiro --source-dir ./kiro-specs --output-dir ./specs --prefix myapp

Flag	Description
--from <format>	Source format (currently only kiro)
--dry-run	Preview import without writing files
--source-dir <path>	Source directory (default: .kiro/specs)
--output-dir <path>	Output directory (default: specs)
--prefix <prefix>	Prefix for generated document IDs
--force	Overwrite existing files

Note

Imported files may contain TODO(supersigil-import) comments where manual review is needed. Run supersigil verify after importing to validate the results.

supersigil skills install

Install or update the embedded agent skills.

supersigil skills install
supersigil skills install --path custom/skills

Writes the six bundled agent skills to disk: ss-feature-specification, ss-feature-development, ss-retroactive-specification, ss-spec-driven-development, ss-refactoring, and ss-ci-review. If skills already exist at the target path, they are overwritten with the version embedded in the current binary.

Use this after upgrading Supersigil to get the latest skill versions.

Flag	Description
--path <dir>	Target directory (default: .agents/skills/, or skills.path from supersigil.toml)

Path resolution order: --path flag, then skills.path from supersigil.toml, then .agents/skills/. Does not require supersigil.toml to exist.

supersigil completions <shell>

Generate shell completion scripts for tab completion.

# Bash
mkdir -p ~/.local/share/bash-completion/completions
supersigil completions bash > ~/.local/share/bash-completion/completions/supersigil

# Zsh (ensure ~/.zfunc is in your fpath)
mkdir -p ~/.zfunc
supersigil completions zsh > ~/.zfunc/_supersigil

# Fish
mkdir -p ~/.config/fish/completions
supersigil completions fish > ~/.config/fish/completions/supersigil.fish

Prints a completion script to stdout for the specified shell. Supported shells: bash, zsh, fish, elvish, powershell.

Does not require supersigil.toml to exist.