CLI Reference

Install

SpecKeep is distributed as a single binary via GitHub Releases.

Linux:

VERSION=v0.5.1
curl -fsSL "https://raw.githubusercontent.com/bzdvdn/speckeep/${VERSION}/scripts/install.sh" | bash -s -- --version "${VERSION}"

Windows (PowerShell):

$version="v0.5.1"
$env:SPECKEEP_VERSION=$version
powershell -ExecutionPolicy Bypass -c "iwr -useb https://raw.githubusercontent.com/bzdvdn/speckeep/$version/scripts/install.ps1 | iex"

To also add the install directory to PATH:

• Linux: add --add-to-path or set SPECKEEP_ADD_TO_PATH=1
• Windows: set $env:SPECKEEP_ADD_TO_PATH=1 or run the script with -AddToPath

Commands

speckeep init [path]

Initializes a SpecKeep workspace in the target project.

Examples:

speckeep init
speckeep init my-project --lang en --shell sh
speckeep init my-project --lang en --shell sh --specs-dir .speckeep/specifications --archive-dir .speckeep/artifacts/archive --constitution-file docs/constitution.md
speckeep init my-project --docs-lang ru --agent-lang en --comments-lang en --shell powershell --agents claude --agents cursor

Important flags:

• --git initializes a Git repository when true; default is enabled
• --lang sets the base language; default is en
• --shell selects the generated workflow script family; required: sh or powershell
• --specs-dir overrides the specs directory (advanced)
• --archive-dir overrides the archive directory (advanced)
• --constitution-file overrides the constitution file path (advanced)
• --docs-lang sets the generated documentation language
• --agent-lang sets the generated prompt and agent guidance language
• --comments-lang records the preferred code comment language
• --agents generates project-local agent command files

speckeep refresh [path]

Refreshes only SpecKeep-managed generated artifacts in an existing project.

This command updates:

• .speckeep/spk-yaml
• .speckeep/templates/**
• .speckeep/scripts/**
• project-local agent skill packs
• the managed SpecKeep guidance block inside AGENTS.md

This command does not update:

• the constitution file (project.constitution_file, default: CONSTITUTION.md)
• contents under specs_dir/** (but it can safely move the directory with --specs-dir)
• contents under specs_dir/<slug>/plan/**
• contents under archive_dir/** (but it can safely move the directory with --archive-dir)

Lean artifact layout is now the default for generated guidance and readiness checks. Existing feature packages may still contain legacy summary.md, spec.digest.md, or plan.digest.md, but refresh no longer requires them and new workspaces do not depend on them.

Examples:

speckeep refresh my-project
speckeep refresh my-project --shell powershell --agents claude --dry-run
speckeep refresh my-project --agent-lang ru --json

Important flags:

• --lang, --docs-lang, --agent-lang, --comments-lang override the existing configured languages
• --shell overrides the generated workflow script family
• --constitution-file overrides the configured constitution file path (and safely moves the existing file when possible)
• --specs-dir overrides paths.specs_dir (and safely moves the existing specs directory when possible)
• --archive-dir overrides paths.archive_dir (and safely moves the existing archive directory when possible)
• --agents overrides enabled project-local agent targets
• --dry-run reports pending managed changes without writing them
• --json outputs the refresh result as JSON

speckeep add-agent [path]

Adds one or more agent targets to an existing SpecKeep project.

speckeep add-agent my-project --agents claude --agents codex

speckeep list-agents [path]

Lists enabled agent targets from .speckeep/spk-yaml.

speckeep remove-agent [path]

Disables one or more agent targets and removes their generated files.

speckeep cleanup-agents [path]

Removes orphaned agent artifacts that no longer match enabled targets in config.

Migrating Existing Feature Packages

If your active feature folders still contain summary.md, spec.digest.md, or plan.digest.md:

• you can keep them temporarily; current prompts and checks ignore them by default
• treat tasks.md as the main operational entrypoint for implement and verify
• move the important recap material into tasks.md ## Implementation Context
• keep .speckeep/constitution.summary.md as the compact policy layer
• run speckeep refresh . --dry-run first to preview managed guidance changes before normalizing older feature packages

speckeep doctor [path]

Checks workspace health.

doctor reports:

• error for missing required files or invalid config values
• warning for orphaned agent artifacts still present on disk
• warning for non-standard Git branch names
• ok when the workspace is healthy

Use --json for machine-readable output in automation and CI.

speckeep dashboard [path]

Displays a visual dashboard of all active features in the project.

The dashboard includes:

• Feature slug
• Current workflow phase
• Implementation progress percentage
• Status (READY/BLOCKED)
• Current Git branch (with !! warning if there is a mismatch with the feature slug)

speckeep dashboard

speckeep feature <slug> [path]

Shows a detailed workflow view for one feature.

The text view includes:

• current phase and ready_for
• inspect and verify status when reports exist
• task progress when tasks.md exists
• grouped workflow findings
• a short focus hint for the next likely action

Use --json to return structured state plus feature-local findings.

speckeep feature repair <slug> [path]

Repairs safe feature-local SpecKeep issues.

Current repair scope includes:

• migrating flat spec artifacts (specs/<slug>.md) to the canonical directory layout (specs/active/<slug>/spec.md)
• migrating plan artifacts from the old plans/<slug>/ layout to specs/active/<slug>/

Use --dry-run to preview changes and --json for structured output.

speckeep features [path]

Lists workflow status across all discovered features.

The text view summarizes:

• phase and ready_for
• inspect and verify verdicts
• task progress
• grouped issue counts
• artifact presence

Use --json for machine-readable output.

speckeep migrate [path]

Runs safe project-wide SpecKeep migrations.

Current migration scope focuses on canonicalizing legacy inspect report paths across the project.

speckeep list-specs [path]

Lists spec slugs from specs_dir/ (default: specs/active/).

speckeep show-spec <name> [path]

Prints one spec file by slug.

speckeep check <slug> [path]

Shows feature readiness and the exact next action for one feature.

Output includes artifact presence, inspect and verify verdict, task progress, the exact next slash command, and a compact structured-check summary when phase-specific readiness checks produce categorized findings.

Use --all to check every feature in one table. Exits with code 1 when any feature is blocked. Use --json for machine-readable output suitable for CI, including check_summary and check_findings when available.

speckeep check export-report
speckeep check export-report my-project --json
speckeep check my-project --all
speckeep check my-project --all --json

speckeep trace [slug] [path]

Parses Proof: entries from tasks.md to map completed tasks to implementation evidence. It does not scan source code.

The Proof: line directly under each completed [x] task follows the format:

• Proof: <kind> <path> [<anchor>], where kind is code|test|docs|chore, path is a repo-root-relative path, and anchor is the owning function/test/type name (optional but recommended).
• examples: Proof: code src/handlers/export.go ExportHandler, Proof: test src/tests/export_test.go TestExportFlow, Proof: docs docs/export.md.

This command reports orphaned/duplicate/missing proof, missing files, and warns on missing anchors.

Use slug to filter findings for a specific feature. Use --tests to show only test-kind proof entries. Use --json for machine-readable output.

speckeep trace
speckeep trace export-report
speckeep trace export-report --tests
speckeep trace export-report my-project --json

speckeep converge <slug> [path]

The cheap closing loop for "almost done" features: confirms every completed task carries a valid Proof: entry (existing file, resolvable anchor), every touched surface exists, and AC-* coverage holds.

It is lighter than verify — no report file is produced. When gaps remain it lists them as structured findings and exits with code 1; the agent appends follow-up tasks (## Converge Follow-ups in tasks.md) and re-runs until converged, with a hard stop after 2 fix rounds.

Use --json for machine-readable output. Exits with code 1 when the feature is not converged.

speckeep converge export-report
speckeep converge export-report my-project --json

speckeep guard [path]

The deterministic CI gate for closing features: fails (exit 1) when at least one active feature is not archive-ready — open tasks, missing Proof:, blocked inspect/verify state, or a branch mismatch.

Pass --slug <slug> to limit the check to one feature. Use --json for CI logs.

speckeep guard my-project
speckeep guard my-project --slug export-report
speckeep guard my-project --json

speckeep import <openspec|speckit> [path]

Migrates feature packages from another spec system into the current speckeep workspace.

• openspec: reads openspec/changes/<slug>/ and rebuilds spec.md (RQ-*/AC-* from ### Requirement: and #### Scenario: blocks), plan.md from design.md, and copies tasks.md best-effort (with a note to regenerate via /spk-tasks).
• speckit: reads specs/<slug>/ and copies spec.md / plan.md / tasks.md.

Existing speckeep feature directories are never overwritten — they are reported as skipped. Use --json for machine-readable output.

speckeep import openspec ./
speckeep import speckit ./spec-kit-project
speckeep import openspec . --json

speckeep self check / speckeep self upgrade

Manages the installed binary.

• speckeep self check: reports the installed version vs the latest GitHub release (--json for machine output). Read-only — exits 0.
• speckeep self upgrade: downloads the latest release archive, verifies its sha256 checksum against sha256sum.txt, and replaces the running binary in place. On Windows or when the install directory is not writable it prints a manual-install hint instead of failing silently.

speckeep self check
speckeep self check --json
speckeep self upgrade

speckeep demo [path]

Creates a demo workspace at the given path (default: ./speckeep-demo).

The workspace is pre-populated with an example feature (export-report) at the implement phase — spec, inspect report, plan, tasks, and data model are all present. Suggests /spk-scope, /spk-challenge, and /spk-handoff to try immediately.

speckeep demo
speckeep demo ./my-demo --agents claude

speckeep export <slug> [path]

Bundles all artifacts for one feature into a single markdown document.

Reads and concatenates: spec, inspect report, plan, tasks, data model, research, challenge report, and verify report (skips missing files). Useful for sharing full feature context with a reviewer or a new agent session.

Use --output <file> to write to a file instead of stdout.

speckeep export export-report
speckeep export export-report my-project --output export-report-bundle.md

speckeep list-archive [path]

Lists archived features from archive_dir/ (default: specs/archived/).

Shows one entry per slug (most recent snapshot) with status, archived date, and reason. Entries are sorted by date descending. Status values are color-coded: completed in green, deferred in yellow, abandoned and rejected in red.

Flags:

• --status — filter by archive status: completed, superseded, abandoned, rejected, deferred
• --since <YYYY-MM-DD> — filter to archives on or after this date
• --json — output as JSON for automation and CI

speckeep list-archive
speckeep list-archive my-project --status deferred
speckeep list-archive my-project --since 2026-01-01
speckeep list-archive my-project --json