TL;DR

  • Prefer no-install: npx openspec@latest --version
  • Initialize at repo root: openspec init or openspec update
  • Essentials: openspec list, openspec list --specs, openspec validate <change-id> --strict

Prerequisites

  • macOS/Linux/Windows (WSL recommended)
  • Git 2.30+
  • Node.js LTS (>= 18) for npx/dlx

Installation Options

npx openspec@latest --version
npx openspec@latest list
pnpm dlx openspec@latest --version
yarn dlx openspec@latest --version

Note: assumes your team publishes the CLI to npm. Otherwise see below.

B) Global npm install

npm i -g openspec
openspec --version

C) Homebrew (if your team provides a tap)

brew tap your-org/tap
brew install openspec
openspec --version

D) Binary/internal distribution

  1. Download the binary for your OS from your internal registry.
  2. Put it on PATH (e.g., ~/bin, /usr/local/bin).
  3. chmod +x if needed.
  4. Verify: openspec --version.

E) Docker (optional)

docker run --rm -v "$(pwd)":/work -w /work your-registry/openspec:latest openspec --version

First-time initialization

openspec init   # or
openspec update

openspec list
openspec list --specs

See openspec/AGENTS.md and openspec/project.md for authoritative rules.

Quick validation

CHANGE=add-sample-feature
mkdir -p openspec/changes/$CHANGE/specs/demo
cat > openspec/changes/$CHANGE/specs/demo/spec.md << 'EOF'
## ADDED Requirements
### Requirement: Sample Feature
The system SHALL provide a sample capability for validation.

#### Scenario: Basic
- **WHEN** validation runs
- **THEN** the change passes minimal syntax checks
EOF

openspec validate $CHANGE --strict

Next steps

  • Read the practical SDD guide: /en/tutorials/openspec-sdd-intro/
  • Authoritative docs: openspec/AGENTS.md, openspec/project.md