README
¶
specscore-cli
CLI for SpecScore — lint, query, and scaffold SpecScore specifications.
Install
macOS / Linux — curl
curl -fsSL https://specscore.md/install/get-cli | sh
Windows — PowerShell
powershell -c "irm https://specscore.md/install/get-cli.ps1 | iex"
macOS — Homebrew
brew install specscore/tap/specscore
Windows — Scoop / WinGet
scoop bucket add specscore https://github.com/specscore/scoop-bucket
scoop install specscore
# or
winget install SpecScore.CLI
See installation docs for options (version pinning, custom install dir).
Usage
specscore spec lint # lint the current spec tree
specscore feature list # list features
specscore feature show <slug> # inspect a feature
specscore task list # show the task board
specscore version # full build identity
specscore --version # bare semver
Full command reference: see spec/features/cli/.
Updating
Bring an existing install to the latest release:
specscore self-update # or: specscore update
specscore self-update --check # report whether a newer release is available; change nothing
specscore self-update --yes # skip the confirmation prompt (non-interactive / CI)
self-update detects how specscore was installed. Package-managed installs (Homebrew, Scoop, WinGet) are never overwritten — it prints the right manager command to run instead (e.g. brew upgrade specscore). Manual installs (release-archive download, go install) are replaced in place after the downloaded asset's checksums.txt entry is verified.
Install a specific release instead of the latest:
specscore self-update --version v0.6.0 # leading "v" optional
specscore self-update --version 0.4.0 --allow-downgrade # an older target requires --allow-downgrade
--check exit codes: 0 up to date, 10 update available, other non-zero on error — convenient for CI staleness gates. Full contract: spec/features/cli/self-update/.
Configure your AI agents
Teach the AI coding agents working in this repo about its SpecScore conventions in one command. specscore agent setup writes each agent's instruction file (and, where the agent supports a skills directory, copies the SpecScore skill bundles into it).
Pass agents as a comma-separated list (space-separated and --all also work):
specscore agent setup claude,codex,copilot,cursor,antigravity.google,pi.dev,opencode
Supported agents: claude, codex, copilot, cursor, antigravity.google, pi.dev, opencode. The command is idempotent (existing files are skipped unless --force) and reports every path it adds, modifies, or skips. Full contract: spec/features/cli/agent/setup/.
AI skills
If you drive specscore from inside Claude Code (or any agent host that loads Claude Code plugins), install the ai-plugin-specscore plugin. It ships agent skills that wrap each CLI resource group — they teach the agent when to call which command, which flags to pass, and how to interpret exit codes, all grounded in the feature specs in this repo.
/plugin marketplace add specscore/ai-marketplace
/plugin install specscore@specscore
Then bootstrap the CLI itself with /specscore:install, or install manually with the one-liner above.
Test coverage
specscore-cli maintains 100% statement coverage across all packages. This is enforced automatically — the CI pipeline and the local pre-push hook both reject any change that drops below 100%.
All contributions are required to maintain 100% coverage. If your change adds or modifies code, include tests that cover every new branch.
License
Apache License 2.0 — see LICENSE.
Related
- specscore/specscore — the SpecScore format and documentation
- specscore/ai-plugin-specscore — agent skills that wrap this CLI
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
specscore
command
|
|
|
internal
|
|
|
selfupdate
Package selfupdate resolves the latest stable release of the specscore CLI from GitHub and compares it against the running build's version.
|
Package selfupdate resolves the latest stable release of the specscore CLI from GitHub and compares it against the running build's version. |
|
telemetry
Package telemetry is the single audit surface for all telemetry transmission from the specscore CLI.
|
Package telemetry is the single audit surface for all telemetry transmission from the specscore CLI. |
|
pkg
|
|
|
config
Package config resolves SpecScore configuration from layered sources.
|
Package config resolves SpecScore configuration from layered sources. |
|
consilium
Package consilium owns the deterministic consilium engine for the `specscore` CLI: the vote-schema types and validator, the roster resolver and validator, the gate-knob and roster config loaders for the `consilium:` block in specscore.yaml, and the gate-rule arbiter that turns a panel's votes into a deterministic verdict.
|
Package consilium owns the deterministic consilium engine for the `specscore` CLI: the vote-schema types and validator, the roster resolver and validator, the gate-knob and roster config loaders for the `consilium:` block in specscore.yaml, and the gate-rule arbiter that turns a panel's votes into a deterministic verdict. |
|
entity
Package entity parses and represents SpecScore entity artifacts (`*.entity.md` files under `spec/features/**`).
|
Package entity parses and represents SpecScore entity artifacts (`*.entity.md` files under `spec/features/**`). |
|
event
Package event owns the shared event-dispatch plumbing for the `specscore` CLI: the Subscriber extension point, the Event envelope type, the envelope validator, the fan-out dispatcher, the built-in subscriber implementations (JsonlWriter, NoOp, Exec), and the events: config block loader.
|
Package event owns the shared event-dispatch plumbing for the `specscore` CLI: the Subscriber extension point, the Event envelope type, the envelope validator, the fan-out dispatcher, the built-in subscriber implementations (JsonlWriter, NoOp, Exec), and the events: config block loader. |
|
exitcode
Package exitcode defines the shared exit code constants and error type used by all SpecScore CLI commands and library consumers.
|
Package exitcode defines the shared exit code constants and error type used by all SpecScore CLI commands and library consumers. |
|
feature
Package feature provides feature discovery, traversal, metadata, dependency resolution, and scaffolding.
|
Package feature provides feature discovery, traversal, metadata, dependency resolution, and scaffolding. |
|
gitremote
Package gitremote parses git remote URLs into their owner / repo / host components.
|
Package gitremote parses git remote URLs into their owner / repo / host components. |
|
idea
Package idea parses and represents SpecScore Idea artifacts.
|
Package idea parses and represents SpecScore Idea artifacts. |
|
ideapromote
Package ideapromote implements `specscore idea promote <slug>` — turning a sidekick seed (spec/ideas/seeds/<slug>.md) into a lint-clean Idea (spec/ideas/<slug>.md).
|
Package ideapromote implements `specscore idea promote <slug>` — turning a sidekick seed (spec/ideas/seeds/<slug>.md) into a lint-clean Idea (spec/ideas/<slug>.md). |
|
idearelocate
Package idearelocate implements cross-repo relocation of Idea and sidekick-seed artifacts per spec/features/cli/idea/relocate/README.md.
|
Package idearelocate implements cross-repo relocation of Idea and sidekick-seed artifacts per spec/features/cli/idea/relocate/README.md. |
|
issue
Package issue — lifecycle transition orchestration for the Issue kind.
|
Package issue — lifecycle transition orchestration for the Issue kind. |
|
journal
Package journal implements the SpecScore activity journal: an append-only, date-sharded event store plus on-demand day/week/month summary rollups.
|
Package journal implements the SpecScore activity journal: an append-only, date-sharded event store plus on-demand day/week/month summary rollups. |
|
lifecycle
Package lifecycle hosts a kind-parameterized state machine for SpecScore artifact Status transitions.
|
Package lifecycle hosts a kind-parameterized state machine for SpecScore artifact Status transitions. |
|
lint
specscore:feature/cli/spec/lint
|
specscore:feature/cli/spec/lint |
|
plan
Package plan parses single-file Plan artifacts at spec/plans/<slug>.md per the SpecStudio plan-Feature contract (https://github.com/specscore/specstudio-skills/blob/main/spec/features/skills/plan/README.md).
|
Package plan parses single-file Plan artifacts at spec/plans/<slug>.md per the SpecStudio plan-Feature contract (https://github.com/specscore/specstudio-skills/blob/main/spec/features/skills/plan/README.md). |
|
projectdef
Package projectdef provides the specscore.yaml schema and read/write operations defined by the SpecScore Repo Config feature (https://specscore.md/repo-config).
|
Package projectdef provides the specscore.yaml schema and read/write operations defined by the SpecScore Repo Config feature (https://specscore.md/repo-config). |
|
property
Package property parses and represents SpecScore Property artifacts.
|
Package property parses and represents SpecScore Property artifacts. |
|
publication
Package publication implements durable publication policy config helpers.
|
Package publication implements durable publication policy config helpers. |
|
sidekick
Package sidekick scaffolds lint-clean sidekick-seed artifacts — the scaled-down Idea one-pagers parked under spec/ideas/seeds/.
|
Package sidekick scaffolds lint-clean sidekick-seed artifacts — the scaled-down Idea one-pagers parked under spec/ideas/seeds/. |
|
slug
Package slug provides shared slug-derivation helpers used across the SpecScore CLI.
|
Package slug provides shared slug-derivation helpers used across the SpecScore CLI. |
|
task
Package task defines the canonical task types, status enum, and related structures used by all SpecScore-based coordination tools.
|
Package task defines the canonical task types, status enum, and related structures used by all SpecScore-based coordination tools. |