specscore-cli

specscore-cli

CLI for SpecScore — lint, query, and scaffold SpecScore specifications.

Our approach to development

We build with our own tooling:

• SpecScore — specify requirements as SpecScore.md artifacts
• SpecStudio — author & manage specs across their lifecycle
• inGitDB — store structured data in Git where applicable
• DALgo — data access layer for Go
• cover100.dev — drive toward 100% test coverage
• DataTug — query & explore data

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.

Code exploration & spec ↔ code linkage

We use Codegrapher for efficient code exploration and bidirectional linkage between specifications and source code. You can browse this repository's code graph online — the directory tree and quick file search are served from the committed snapshot in codegrapher/. Codegrapher indexes the codebase into a queryable knowledge graph of symbols and their relationships, letting AI agents navigate and trace code quickly instead of grepping — and connect SpecScore specs to the code that implements them, and back.

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.

Releasing

[!IMPORTANT] Do not bump the version manually. There is no version string to edit in source — the version is derived from the git tag at build time. Cut releases only through the Release workflow:

• Actions → Release → Run workflow, then pick auto (next version from conventional commits since the last tag), patch / minor / major, or an explicit vX.Y.Z; or
• push a vX.Y.Z tag.

Or from the CLI: gh workflow run release.yml -f release_tag=auto. The workflow tags, builds, and publishes the GitHub release; afterwards run specscore self-update to pull the new binary locally.

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