The Command Line

OpenSpec has two halves, and mixing them up is the most common early stumble. The openspec … commands on this page run in your terminal. The /opsx:… commands run in your AI assistant's chat and are covered in skills and slash commands.

There is no separate interactive mode to start. Two terminal commands set a project up; after that you live in the chat, and come back here to inspect, validate and archive.

FIGURE 10 — The whole command line, on one page. In daily use you type four of these; the rest are for setting up, checking, and getting unstuck.

3.1 Setting up

openspec init [path]
  --tools <tools>       all | none | comma-separated tool ids
  --profile <profile>   core | custom
  --force               clean up legacy files without prompting
  --no-animation        static welcome screen

openspec update [path]
  --force               update even when tools are already current

init is run once per project. It creates the openspec/ directory and writes the workflow into each AI assistant you select. update regenerates those instruction files after you upgrade the package or change your profile — it also checks the npm registry and offers an interactive self-upgrade.

Installation itself is one line, and needs Node.js 20.19 or later:

npm install -g @fission-ai/openspec@latest

3.2 Browsing what exists

openspec list                     active changes, most recent first
openspec list --specs             capabilities instead
  --sort <recent|name>
openspec view                     an interactive dashboard
openspec show <item>              one change or one spec
  --type <change|spec>
  --deltas-only                   change only
  --requirements                  spec only
  --requirement <id>              spec only, 1-based
  --no-scenarios
openspec spec list --long
openspec spec show <spec-id>
openspec spec validate [spec-id]  --strict

Every one of these takes --json.

Note — an older noun-first group still works — openspec change show, change list, change validate — but each prints a deprecation warning to stderr. Prefer the verb-first forms above. The spec group is not deprecated and remains the way to inspect a single capability.

3.3 Validating

openspec validate [item-name]
  --all                 changes and specs
  --changes             changes only
  --specs               specs only
  --strict              warnings become failures
  --concurrency <n>     default 6
  --json

--strict is the flag worth putting in continuous integration. Without it, five conditions are only warnings and the change passes anyway; with it, each one fails the run. Those five, and the errors that fail either way, are set out in specs, deltas and validation.

3.4 Finishing

openspec archive [change-name]
  -y, --yes             answer the confirmation prompt
  --skip-specs          do not merge the delta specs
  --no-validate         skip validation first
  --json

This is the command that folds a completed change back into openspec/specs/. What it does, in order, is set out in applying and archiving.

Avoid: running openspec archive from a script or a CI job without --yes. A non-interactive run cannot answer the confirmation prompt, so archive stops before touching anything, exits 1, and prints the command to rerun. That is the correct behaviour, but it looks like a failure if you were not expecting it.

3.5 The workflow engine

These are what the slash commands call underneath. You rarely type them by hand, and knowing they exist is what lets you script or debug the loop.

openspec status                   artifact completion for a change
  --change <id>
  --schema <name>
openspec instructions [artifact]  enriched instructions for one artifact
  --change <id>                   'apply' and 'archive' are reserved values
openspec templates                resolved template paths for a schema
openspec schemas                  available workflow schemas
openspec new change <name>        create the change directory
  --description <text>
  --goal <text>
  --schema <name>

openspec instructions <artifact> is the interesting one. It returns the schema's instruction for that artifact with your project's own context and rules already injected, which is how a generated proposal ends up respecting your stack without anybody pasting it into a prompt.

3.6 Configuring

Two groups. The first is global, per-machine; the second manages workflow schemas.

openspec config path | list | get <key> | set <key> <value>
openspec config unset <key> | reset --all | edit
openspec config profile [preset]      core, or the expanded set

openspec schema which [name] --all
openspec schema validate [name] --verbose
openspec schema fork <source> [name]
openspec schema init <name>
  --artifacts <list>  --default  --force

Global settings live in a config.json under the usual per-platform config directory. The fields that matter day to day are profile (core by default), delivery (both by default — skills, command files, or both), and the list of workflows to install.

openspec config profile and openspec update are the pair you run to move from the six core commands to the full twelve.

3.7 The beta surface

Labelled beta by OpenSpec itself, and treated as such here. Expect commands and state to evolve.

openspec store setup [id] | register [path] | unregister <id>
openspec store remove <id> | list | doctor [id]
openspec doctor
openspec context   --code-workspace <path>
openspec workset create [name] --member <path> --tool <id>
openspec workset list | open <name> | remove <name>

Stores are the answer to planning that spans repositories: a standalone repo whose whole job is planning, with the same openspec/ shape, shared by git push like anything else. A platform team can own specifications that product teams reference read-only. Most single-repo projects — including the worked example in this section — need none of this.

Commands that read or write specs and changes accept --store <id> to act on a registered store rather than the nearest local openspec/ root.

3.8 Utility, and the agent contract

openspec feedback <message> --body <text>
openspec completion generate | install | uninstall [shell]
openspec --version
openspec --help

Shell completion covers bash, zsh, fish and powershell.

Every command accepts --json, and the contract is specific: exactly one JSON document, containing a status array, even on failure. Exit codes are 0 for success, 1 for an error, and 130 if you interrupt an interactive prompt.

That contract is not decoration. It is what lets your AI assistant drive OpenSpec without a human reading terminal output — which is precisely what the slash commands in the next page do.

Telemetry collects command names and the version, nothing else: no arguments, no paths, no content. It is disabled automatically in CI, and opting out is OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1.