OpenSpec Tutorial: Install the CLI and Run Your First Change

Install OpenSpec on Windows, macOS, or Linux

Updated October 26, 2026. The published npm latest is 1.15.0. The standalone program needs no Node.js; the npm package needs Node.js 20.19.0+. Choose one installation method. The official installation guide covers the supported platforms.

For Windows PowerShell, the official standalone installer is:

irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex

For macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh

These commands execute the official installer from main. It selects a release binary and checks its SHA256SUMS; it does not compile main. To pin the binary, set OPENSPEC_VERSION=v1.15.0 in that shell first. The Windows destination is %LOCALAPPDATA%\Programs\openspec; macOS and Linux use ~/.local/bin. Windows adds the directory to the user PATH. Open a new terminal after installation.

If you already use Node.js and pnpm, install the published package instead:

node --version
pnpm add -g @fission-ai/[email protected]
openspec --version

The last command should print 1.15.0 for this pin. Without a global installation, use pnpm dlx @fission-ai/[email protected] --version. A successful dlx call does not make the bare openspec command available.

Fix a missing command or an unexpected version

On Windows, check every matching executable, then try the standalone file directly:

Get-Command openspec -All
where.exe openspec
& "$env:LOCALAPPDATA\Programs\openspec\openspec.exe" --version

If the direct path works but the bare command does not, reopen the terminal and check the user PATH. If the bare command prints an older version, an earlier PATH entry or shell alias is selecting another copy. For pnpm, pnpm bin -g identifies its global executable directory. A missing global-bin error concerns pnpm setup; use dlx for the exercise while resolving that setup.

On macOS or Linux:

command -v openspec
which -a openspec
"$HOME/.local/bin/openspec" --version

If necessary, add the actual installation directory to your shell’s PATH. With nvm or fnm, check the active Node version before reinstalling a global package. A version-manager shim may need refreshing. Do not remove an executable until you know which installation owns it.

Upgrade or uninstall the installation you chose

openspec version --check reports update availability. Upgrade a pnpm installation with pnpm add -g @fission-ai/openspec@latest, then run openspec update inside each project to refresh its generated integrations. Review the resulting diff. update is not the same operation as choosing a new package version.

For standalone installations, rerun the installer. openspec install explicitly switches an existing package-manager installation to standalone and prints removal guidance for the old copy. Verify the selected executable in a new terminal afterward.

To uninstall a pnpm copy, use pnpm remove -g @fission-ai/openspec. For standalone, remove only the executable at the verified installation path and its PATH entry. There is no openspec uninstall command. Keep openspec/specs/ and openspec/changes/archive/ if you need their history; removing the CLI does not require deleting project documents.

Find the CLI command for your task

These are terminal commands for 1.15.0. Run them in the intended project; replace the bare openspec prefix with pnpm dlx @fission-ai/[email protected] if you did not install globally.

/opsx:propose and /opsx:apply belong in an assistant chat, not PowerShell or Bash. Invocation spelling depends on the integration; Codex uses skills such as $openspec-propose. Use the files generated for your tool rather than assuming every host accepts the same slash command. See the 1.15.0 CLI reference.

For shared specifications across code repositories, use the Stores and multi-repo workflow. Stores ship in 1.15.0 but remain Beta. The npm beta tag is a separate distribution tag, not a requirement for using Stores.

OpenSpec Quick Start

The following exercise deliberately keeps its 1.13.2 pin. It gives existing readers a reproducible workflow without silently changing their commands. The same proposal, delta, design, and task snippets are also checked against 1.15.0. The downloadable CLI check script exercises local file operations without an AI model; installation scripts and agent implementation are separate steps.

This tutorial covers the OpenSpec CLI workflow: initialize a repository, create a change, write its proposal and specifications, then validate and archive the completed work. The examples use the published 1.13.2 package, Node.js 20.19.0+, and pnpm. Validation was checked with Node.js 26.7.0 and pnpm 10.28.2 in an empty directory, without model calls. Start in a new practice directory outside your application:

pnpm dlx @fission-ai/[email protected] --help
pnpm dlx @fission-ai/[email protected] init . --tools none

The first command runs help without a global installation; the second creates the OpenSpec structure without assistant integrations. Use an existing project only after reviewing what initialization will add. For definitions and suitability, read the independent OpenSpec workflow and files guide; this tutorial focuses on executing the first change.

What is OpenSpec?

OpenSpec is an AI-native system for spec-driven development. In practice, it gives your AI coding workflow a durable structure: instead of asking an agent to “just implement this feature,” you describe the intended change as a proposal, validate the spec, let the agent implement against that spec, and then archive the completed change back into your main source of truth.

That makes OpenSpec especially useful for brownfield projects: existing codebases where most work is not a greenfield rewrite, but a steady stream of bug fixes, features, refactors, and product changes.

If you are comparing the broader landscape, I also wrote a longer SDD comparison: BMAD vs spec-kit vs OpenSpec vs PromptX. This tutorial focuses only on using OpenSpec day to day.

When should you use OpenSpec?

Use OpenSpec when you want AI coding agents to operate with more determinism and less prompt drift.

Good fits:

• You already have a working codebase and want safer AI-assisted changes.
• You need a lightweight spec workflow without adopting a heavy enterprise process.
• You want a clear record of what changed, why it changed, and which requirements were updated.
• You work with multiple AI tools and want shared project instructions.
• You want reviewers to evaluate the intent and acceptance criteria before code is generated.

OpenSpec is less necessary for a one-off throwaway prototype. It becomes valuable when a repository must keep accumulating reliable decisions.

Install or run the OpenSpec CLI

The npm package is:

@fission-ai/openspec

Run the pinned package with pnpm:

pnpm dlx @fission-ai/[email protected] --help

The CLI entrypoint is openspec. Bare commands below, including the cheat sheet and optional AGENTS.md example, assume a separately installed CLI of the same version; otherwise use the pnpm dlx @fission-ai/[email protected] prefix:

openspec --help

The top-level help includes commands such as:

init            Initialize OpenSpec in your project
update          Update OpenSpec instruction files
list            List changes or specs
view            Display an interactive dashboard
new change      Create a new change directory
validate        Validate changes and specs
show            Show a change or spec
archive         Archive a completed change and update main specs
status          Display artifact completion status
instructions    Output enriched artifact/task instructions

Initialize OpenSpec in a project

For an interactive installation, run this from the intended project root. This is an alternative to the practice directory’s --tools none, not another required initialization:

pnpm dlx @fission-ai/[email protected] init .

If you want to configure AI tools non-interactively, use --tools:

pnpm dlx @fission-ai/[email protected] init . --tools claude,codex,cursor,gemini,github-copilot

You can also use:

pnpm dlx @fission-ai/[email protected] init . --tools all
pnpm dlx @fission-ai/[email protected] init . --tools none

The CLI help currently lists many supported tools, including claude, codex, cursor, gemini, github-copilot, kilocode, qwen, windsurf, cline, continue, opencode, roocode, trae, and others.

The core OpenSpec workflow

A simple OpenSpec loop looks like this:

1. Initialize OpenSpec in the repository.
2. Create a change for one feature, bug fix, or refactor.
3. Write the proposal and spec deltas before implementation.
4. Validate the change.
5. Ask your AI agent to implement against the approved change.
6. Review and test the code.
7. Archive the completed change so the main specs stay current.

This tutorial uses spec review before implementation as a project policy. OpenSpec’s artifact workflow is iterative: if implementation changes your assumptions, update the proposal, delta, design, and tasks, then validate again. The CLI does not enforce an irreversible sequence.

Create a new OpenSpec change

Use openspec new change <name>:

pnpm dlx @fission-ai/[email protected] new change add-user-login

You can include a description:

pnpm dlx @fission-ai/[email protected] new change add-user-login \
  --description "Add email/password login with session persistence"

The published 1.13.2 new change --help includes:

--goal <text>         Optional goal metadata to store with the change
--schema <name>       Workflow schema to use, default: spec-driven
--json                Output as JSON

Do not copy the old --areas or --initiative workspace options into this version’s commands. --goal remains available; it is optional metadata, not a mandatory workspace configuration. Check the installed version rather than mixing npm behavior with the main branch.

A good change name should be specific and action-oriented:

add-user-login
fix-billing-retry-idempotency
refactor-search-indexing
improve-onboarding-empty-state

Avoid vague names:

updates
misc-fixes
new-stuff
ai-work

Example: a brownfield feature change

Suppose you maintain a SaaS app and want to add magic-link login.

Create the change:

pnpm dlx @fission-ai/[email protected] new change add-magic-link-login --description "Allow users to sign in with one-time email magic links"

Then define the intent before coding. A strong proposal answers:

• What user problem does this solve?
• Which existing flows are affected?
• What must remain backward compatible?
• What are the acceptance criteria?
• What should the AI agent not change?

Save the following as openspec/changes/add-magic-link-login/proposal.md. The command above creates metadata and a README from the description; it does not create a complete proposal or delta:

# Change: add-magic-link-login

## Why
Users forget passwords and support receives frequent reset requests. Magic-link login should reduce friction while preserving existing password login.

## What Changes
- Add a magic-link request form.
- Send a single-use email token.
- Validate the token and create a session.
- Keep existing email/password login unchanged.

## Capabilities
### New Capabilities
- `auth`: Single-use magic-link login alongside password login.
### Modified Capabilities
- None. This practice project has no existing auth spec.

## Impact
Authentication routes, token storage, email delivery, and login tests.

## Non-goals
- Do not remove password login.
- Do not redesign the entire auth page.
- Do not change billing or account settings.

## Acceptance criteria
- A valid link signs the user in once.
- Expired or reused links fail safely.
- Existing password login tests still pass.

In a real application with an existing auth spec, review that spec first: an existing requirement may need MODIFIED, not another ADDED entry. This exercise deliberately starts without a main auth specification.

Write the actual spec delta

Create the directory openspec/changes/add-magic-link-login/specs/auth/, then save this complete file as openspec/changes/add-magic-link-login/specs/auth/spec.md:

## Purpose
Allow existing users to sign in with a single-use email link while preserving the existing password sign-in flow.

## ADDED Requirements

### Requirement: Single-use magic-link sign-in
The system SHALL allow an existing user to sign in with a valid, unexpired, unused email link, consume it atomically, and reject expired or reused links without creating a session.

#### Scenario: Valid link
- **WHEN** an existing user submits a valid, unexpired, unused link
- **THEN** the system creates a session and marks the link as used

#### Scenario: Expired link
- **WHEN** a user submits an expired link
- **THEN** the system rejects it without creating a session

#### Scenario: Reused link
- **WHEN** a user submits a previously used link
- **THEN** the system rejects it without creating a session

### Requirement: Preserve password sign-in
The system SHALL retain the existing email and password sign-in behavior.

#### Scenario: Existing password login
- **WHEN** an existing user submits correct email and password credentials
- **THEN** the system signs the user in through the existing flow

## ADDED Requirements, ### Requirement:, and #### Scenario: are parser-facing structure. Keep those headings and normative SHALL wording. The proposal’s acceptance list is not a substitute for this file. Validation checks structure, not whether token consumption is actually atomic.

Add design and implementation tasks

Save openspec/changes/add-magic-link-login/design.md:

## Context
Add magic-link login without removing password login.

## Goals / Non-Goals
Support existing users only. Registration, billing, and page redesign are out of scope.

## Decisions
Store a hash of each random token with a user ID, expiry, and used status.
Consume an unexpired token atomically before creating a session.
Keep the existing password flow and use a local email test double.

## Risks / Trade-offs
Concurrent requests could replay a token unless consumption is atomic.
Expired, reused, and concurrent requests need application tests.

## Migration Plan
Add token storage behind a feature flag; disabling it preserves password login.

Save openspec/changes/add-magic-link-login/tasks.md:

## 1. Implementation
- [ ] 1.1 Add token storage and a request endpoint with a local email test double.
- [ ] 1.2 Implement atomic token consumption and session creation.

## 2. Verification
- [ ] 2.1 Test valid, expired, reused, and concurrent token submissions.
- [ ] 2.2 Run existing password-login regression tests and review the diff.

These documents make the change ready to discuss, not ready to ship. Check tasks only after implementation and tests produce evidence. To inspect the schema’s artifact state, run:

pnpm dlx @fission-ai/[email protected] status --change add-magic-link-login --json

Validate changes and specs

Before implementation, run validation:

pnpm dlx @fission-ai/[email protected] validate add-magic-link-login

For stricter checks:

pnpm dlx @fission-ai/[email protected] validate add-magic-link-login --strict --json --no-interactive

Validate everything:

pnpm dlx @fission-ai/[email protected] validate --all

Useful validation flags:

--all              Validate all changes and specs
--changes          Validate all changes
--specs            Validate all specs
--type <type>      Specify change or spec when ambiguous
--strict           Enable strict validation mode
--json             Output validation results as JSON
--no-interactive   Disable interactive prompts

For CI, --json and --no-interactive are especially useful:

pnpm dlx @fission-ai/[email protected] validate --all --strict --json --no-interactive

List and inspect OpenSpec items

List active changes:

pnpm dlx @fission-ai/[email protected] list

List specs instead:

pnpm dlx @fission-ai/[email protected] list --specs

Get machine-readable output:

pnpm dlx @fission-ai/[email protected] list --json

Show a change or spec:

pnpm dlx @fission-ai/[email protected] show add-magic-link-login

Show JSON:

pnpm dlx @fission-ai/[email protected] show add-magic-link-login --json

If a name is ambiguous, specify the type:

pnpm dlx @fission-ai/[email protected] show add-magic-link-login --type change

For change review automation, --deltas-only can be helpful:

pnpm dlx @fission-ai/[email protected] show add-magic-link-login --json --deltas-only

How AGENTS.md fits into OpenSpec

Many AI coding tools read repository instruction files. AGENTS.md has become a common convention for telling agents how to behave inside a codebase.

OpenSpec generates tool-specific skills and command files. For example, a separate 1.13.2 initialization with --tools claude creates .claude/skills/openspec-propose/SKILL.md and .claude/commands/opsx/propose.md. It does not require a generated openspec/AGENTS.md. The following rules are optional, handwritten project policy:

• Do not implement before reading the change proposal.
• Keep implementation scoped to the approved change.
• Update tests and docs when required by the spec.
• Run validation before claiming the task is done.
• Archive only after implementation and review are complete.

A practical AGENTS.md section for OpenSpec might look like this:

## OpenSpec workflow

- Before coding, check active OpenSpec changes with `openspec list`.
- For a new feature or behavior change, create or use a change under `openspec/changes/`.
- Do not implement broad unrelated refactors inside a feature change.
- Run `openspec validate <change-name> --strict` before implementation handoff.
- After code and tests pass, archive with `openspec archive <change-name>`.

The value of AGENTS.md is not that it magically makes AI perfect. The value is that every compatible assistant starts from the same operational contract.

Implement with your AI coding agent

Once the change is written and validated, give the agent a focused instruction:

Implement the OpenSpec change `add-magic-link-login`.
Read the proposal and spec deltas first.
Keep the implementation scoped to this change.
Run relevant tests and report any deviations from the spec.

This prompt is much better than:

Add magic link login.

The OpenSpec version gives the agent a durable source of truth, a boundary, and a review target.

Archive a completed change

After implementation, review, and tests, archive the change:

pnpm dlx @fission-ai/[email protected] archive add-magic-link-login

To skip confirmation prompts:

pnpm dlx @fission-ai/[email protected] archive add-magic-link-login --yes

Check that the active change has moved to openspec/changes/archive/YYYY-MM-DD-add-magic-link-login/ and that openspec/specs/auth/spec.md contains both requirements. Then validate the main spec:

pnpm dlx @fission-ai/[email protected] validate auth --type spec --strict --json --no-interactive

The isolated CLI check for this article exercised init, new, strict validation, and archive using the files above. It did not implement authentication or send email. In the dry run, unchecked application tasks were retained as a warning; archive success is not evidence that those tasks were completed. In a real project, finish implementation, run the tests, and update the task list before archiving. Do not bypass validation to make this example pass.

The delta’s ## Purpose supplies the purpose when this new capability is created. Without it, archive can generate a placeholder that fails strict main-spec validation; an existing main spec’s placeholder must be edited there directly. --skip-specs is only for changes that genuinely need no spec update; this login example needs its delta merged.

OpenSpec command cheat sheet

Best practices for OpenSpec

1. Keep each change small

OpenSpec works best when a change maps to one coherent feature, bug fix, or refactor. If a proposal includes authentication, pricing, onboarding, and a redesign, split it.

2. Write non-goals explicitly

AI agents can overreach. A Non-goals section makes scope expansion easier to identify; it is not a filesystem permission boundary.

3. Validate before implementation

Validation catches structural problems before the AI writes code. That is cheaper than debugging generated code based on a weak spec.

4. Use JSON output for automation

Commands such as openspec list --json, openspec show --json, and openspec validate --json are useful in scripts and CI checks.

5. Archive consistently

If completed changes are never archived, your repository accumulates stale proposals. The archive step is what keeps the main specs aligned with reality.

Common mistakes

Mistake: using OpenSpec as a documentation dump

OpenSpec is not just a place to store random docs. It is a workflow for controlled change.

Mistake: creating one huge change

Large changes make AI implementation harder to review. Prefer multiple small changes with clear acceptance criteria.

Mistake: skipping validation

If the spec is invalid, the generated code is likely to drift. Validate early.

Mistake: asking the agent to infer everything

Do not make the agent guess the product intent. Write the proposal, define non-goals, and specify acceptance criteria.

OpenSpec vs spec-kit vs BMAD: quick positioning

• OpenSpec: best for lightweight, brownfield, change-centric workflows.
• GitHub spec-kit: stronger for structured greenfield or enterprise-style gated flows.
• BMAD: useful when you want a role-based AI planning team before development.
• PromptX: more of a context/persona platform than a strict spec workflow.

If your team is asking “how do we safely use AI agents in an existing repo?”, OpenSpec is one of the most practical starting points.

Versioned References

• OpenSpec 1.13.2 README
• 1.13.2 CLI reference
• 1.13.2 OPSX workflow

Final takeaway

OpenSpec is valuable because it turns AI coding from a chat-only activity into a reviewable change-management loop:

proposal -> spec delta -> validation -> implementation -> review -> archive

That loop is simple, but it solves a real problem: AI agents need durable context and boundaries. OpenSpec gives them both.