CLI Reference

The OpenSpec CLI (openspec) provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands (like /opsx:propose) documented in Commands.

Summary

Category	Commands	Purpose
Setup	`init`, `update`	Initialize and update OpenSpec in your project
Workspaces (beta)	`workspace setup`, `workspace list`, `workspace ls`, `workspace link`, `workspace relink`, `workspace doctor`, `workspace update`, `workspace open`	Set up local views over linked repos or folders
Shared context (beta)	`context-store setup`, `context-store register`, `context-store list`, `context-store doctor`, `initiative create`, `initiative show`, `initiative list`	Manage local context-store registrations and durable initiative context
Browsing	`list`, `view`, `show`	Explore changes and specs
Validation	`validate`	Check changes and specs for issues
Lifecycle	`archive`	Finalize completed changes
Workflow	`new change`, `set change`, `status`, `instructions`, `templates`, `schemas`	Artifact-driven workflow support
Schemas	`schema init`, `schema fork`, `schema validate`, `schema which`	Create and manage custom workflows
Config	`config`	View and modify settings
Utility	`feedback`, `completion`	Feedback and shell integration

Human vs Agent Commands

Most CLI commands are designed for human use in a terminal. Some commands also support agent/script use via JSON output.

Human-Only Commands

These commands are interactive and designed for terminal use:

Command	Purpose
`openspec init`	Initialize project (interactive prompts)
`openspec view`	Interactive dashboard
`openspec config edit`	Open config in editor
`openspec feedback`	Submit feedback via GitHub
`openspec completion install`	Install shell completions

Agent-Compatible Commands

These commands support --json output for programmatic use by AI agents and scripts:

Command	Human Use	Agent Use
`openspec list`	Browse changes/specs	`--json` for structured data
`openspec show <item>`	Read content	`--json` for parsing
`openspec validate`	Check for issues	`--all --json` for bulk validation
`openspec status`	See artifact progress	`--json` for structured status
`openspec instructions`	Get next steps	`--json` for agent instructions
`openspec templates`	Find template paths	`--json` for path resolution
`openspec schemas`	List available schemas	`--json` for schema discovery
`openspec workspace setup --no-interactive`	Create a workspace with explicit inputs	`--json` for structured setup output
`openspec workspace list`	Browse known workspaces	`--json` for typed workspace objects
`openspec workspace link`	Link a repo or folder	`--json` for structured link output
`openspec workspace relink`	Repair a linked path	`--json` for structured link output
`openspec workspace doctor`	Check one workspace	`--json` for structured status output
`openspec workspace update`	Refresh workspace-local guidance and agent skills	`--tools` selects agents; profile selects workflows
`openspec context-store list`	Browse registered context stores	`--json` for structured registrations
`openspec context-store doctor`	Check local store setup	`--json` for structured diagnostics
`openspec initiative list`	Browse shared initiatives	`--json` for structured initiative records
`openspec initiative show <id>`	Resolve an initiative	`--json` for canonical paths and metadata
`openspec new change <id>`	Create repo-local change scaffolding	`--json`, plus `--initiative` for shared coordination links
`openspec set change <id>`	Update checked-in change metadata	`--json`, plus `--initiative` for shared coordination links

Global Options

These options work with all commands:

Option	Description
`--version`, `-V`	Show version number
`--no-color`	Disable color output
`--help`, `-h`	Display help for command

Setup Commands

`openspec init`

Initialize OpenSpec in your project. Creates the folder structure and configures AI tool integrations.

Default behavior uses global config defaults: profile core, delivery both, workflows propose, explore, apply, sync, archive.

openspec init [path] [options]

Arguments:

Argument	Required	Description
`path`	No	Target directory (default: current directory)

Options:

Option	Description
`--tools <list>`	Configure AI tools non-interactively. Use `all`, `none`, or comma-separated list
`--force`	Auto-cleanup legacy files without prompting
`--profile <profile>`	Override global profile for this init run (`core` or `custom`)

--profile custom uses whatever workflows are currently selected in global config (openspec config profile).

Supported tool IDs (--tools): amazon-q, antigravity, auggie, bob, claude, cline, codex, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, junie, kilocode, kimi, kiro, opencode, pi, qoder, lingma, qwen, roocode, trae, windsurf

Examples:

# Interactive initialization
openspec init

# Initialize in a specific directory
openspec init ./my-project

# Non-interactive: configure for Claude and Cursor
openspec init --tools claude,cursor

# Configure for all supported tools
openspec init --tools all

# Override profile for this run
openspec init --profile core

# Skip prompts and auto-cleanup legacy files
openspec init --force

What it creates:

openspec/
├── specs/              # Your specifications (source of truth)
├── changes/            # Proposed changes
└── config.yaml         # Project configuration

.claude/skills/         # Claude Code skills (if claude selected)
.cursor/skills/         # Cursor skills (if cursor selected)
.cursor/commands/       # Cursor OPSX commands (if delivery includes commands)
... (other tool configs)

`openspec update`

Update OpenSpec instruction files after upgrading the CLI. Re-generates AI tool configuration files using your current global profile, selected workflows, and delivery mode.

openspec update [path] [options]

Arguments:

Argument	Required	Description
`path`	No	Target directory (default: current directory)

Options:

Option	Description
`--force`	Force update even when files are up to date

Example:

# Update instruction files after npm upgrade
npm update @fission-ai/openspec
openspec update

Workspace Commands

Workspace commands are in beta. The local-view model below is the current direction, but external automation, integrations, and long-lived workflows should still treat command behavior, state files, and JSON output as evolving.

Coordination workspaces are machine-local views over linked repos or folders. Workspace visibility is not change commitment: link the repos or folders OpenSpec should know about, then create changes when you are ready to plan specific work.

`openspec workspace setup`

Create a workspace in the standard OpenSpec workspace location and link at least one existing repo or folder.

openspec workspace setup [options]

Options:

Option	Description
`--name <name>`	Workspace name. Names must be kebab-case
`--link <path>`	Link an existing repo or folder and infer the link name from the folder name
`--link <name>=<path>`	Link an existing repo or folder with an explicit link name
`--opener <id>`	Store a preferred opener during non-interactive setup: `codex`, `claude`, `github-copilot`, or `editor`
`--tools <tools>`	Install workspace-local OpenSpec skills for agents. Use `all`, `none`, or comma-separated tool IDs
`--no-interactive`	Disable prompts; requires `--name` and at least one `--link`
`--json`	Output JSON; requires `--no-interactive`

Examples:

openspec workspace setup
openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex
openspec workspace setup --no-interactive --name platform --link /repos/api --tools codex,claude
openspec workspace setup --no-interactive --json --name checkout --link /repos/platform/apps/checkout

Interactive setup asks for a preferred opener and can install workspace-local OpenSpec skills for selected agents. Non-interactive setup stores a preferred opener only when --opener is provided; otherwise workspace open prompts later in interactive terminals when a supported opener is available, or asks scripts to pass --agent <tool> or --editor.

Workspace skill installation is skills-only in this beta slice: even if global delivery is commands or both, workspace setup writes agent skill folders in the workspace root and does not create slash command files. The active global profile chooses which workflow skills are installed; --tools chooses which agents receive them. If --tools is omitted in non-interactive setup, no skills are installed and workspace update --tools <ids> can add them later.

`openspec workspace list`

List known OpenSpec workspaces from the local registry.

openspec workspace list [--json]
openspec workspace ls [--json]

The list shows each workspace location and linked repos or folders. Stale registry records are reported but not changed.

`openspec workspace link`

Record an existing repo or folder for one workspace.

openspec workspace link [name] <path> [options]

Options:

Option	Description
`--workspace <name>`	Select a known workspace from the local registry
`--json`	Output JSON
`--no-interactive`	Disable workspace picker prompts

Examples:

openspec workspace link /repos/api
openspec workspace link api-service /repos/api
openspec workspace link --workspace platform /repos/platform/apps/checkout

The path must already exist. Relative paths are resolved against the command's current directory before OpenSpec stores the verified absolute path in machine-local workspace state. Linked paths can be full repos, packages, services, apps, or folders without repo-local openspec/ state.

`openspec workspace relink`

Repair or change the local path for an existing link.

openspec workspace relink <name> <path> [options]

The path must already exist. Relink updates only the machine-local path for the stable link name.

`openspec workspace doctor`

Check what one workspace can resolve on the current machine.

openspec workspace doctor [options]

Doctor shows the workspace location, planning path, linked repos or folders, missing paths, repo-local specs paths when present, and suggested fixes. It reports issues only; it does not repair them automatically.

Commands that need one workspace use the current workspace when run from inside a workspace folder or subdirectory. From elsewhere, pass --workspace <name>, select from the picker in an interactive terminal, or rely on the only known workspace when exactly one exists. In --json or --no-interactive mode, ambiguous selection fails with a structured status error and suggests --workspace <name>.

JSON responses use typed objects plus status arrays. Primary data lives in workspace, workspaces, or link; warnings and errors live in status.

`openspec workspace update`

Refresh workspace-local OpenSpec guidance and agent skills.

openspec workspace update [name] [options]

Options:

Option	Description
`--workspace <name>`	Select a known workspace from the local registry
`--tools <tools>`	Select agents for workspace skills. Use `all`, `none`, or comma-separated tool IDs
`--json`	Output JSON
`--no-interactive`	Disable workspace picker prompts

Examples:

openspec workspace update
openspec workspace update platform
openspec workspace update --workspace platform --tools codex,claude
openspec workspace update --workspace platform --tools none

workspace update refreshes the generated workspace guidance block and local open surface. For agent skills, it reuses the stored workspace skill agent selection when --tools is omitted. Passing --tools replaces that stored selection. It refreshes only OpenSpec-managed workflow skill directories in the workspace root, removes deselected managed workflow skills, and leaves linked repos and folders untouched.

Running openspec update from inside a workspace redirects to openspec workspace update; run openspec update inside repo-local projects when you want repo-owned tool files updated.

`openspec workspace open`

Open a workspace working set through the stored preferred opener, a one-session agent override, or VS Code editor mode.

openspec workspace open [name] [options]

Options:

Option	Description
`--workspace <name>`	Alias for the positional workspace name
`--initiative <id>`	Open an initiative as a local workspace view. Accepts `<id>` or `<store>/<id>`
`--store <id>`	Registered context store id for `--initiative`
`--store-path <path>`	Existing local context store root for `--initiative`
`--agent <tool>`	One-session agent override: `codex`, `claude`, or `github-copilot`
`--editor`	Open the maintained VS Code workspace file as a normal editor workspace
`--no-interactive`	Disable workspace and opener picker prompts

Examples:

openspec workspace open
openspec workspace open platform
openspec workspace open platform --agent github-copilot
openspec workspace open --agent codex
openspec workspace open --editor
openspec workspace open --initiative billing-launch --store platform
openspec workspace open --initiative platform/billing-launch

workspace open uses the current workspace when run inside one, auto-selects the only known workspace when run elsewhere, and asks the user to choose when multiple workspaces are known. --agent and --editor do not change the stored preferred opener. Passing both opener overrides is an error; choose either --agent <tool> or --editor.

When --initiative is used, OpenSpec prepares or selects a private local workspace view for that initiative. Registry-selected stores are stored by id; --store-path stores a runtime-local path selector because workspace views are private local state.

OpenSpec maintains <workspace-name>.code-workspace at the workspace root for VS Code editor and GitHub Copilot-in-VS-Code opens. That file is machine-local and ignored by default with a specific <workspace-name>.code-workspace .gitignore entry, so user-authored *.code-workspace files remain eligible for tracking.

The maintained VS Code workspace includes the coordination root as . plus valid linked repos or folders as additional roots. VS Code displays those entries as a multi-root workspace.

Root workspace open makes linked repos or folders visible for exploration and context. Implementation edits should start only after an explicit user request and a normal OpenSpec implementation workflow.

Shared Context Commands

Context stores and initiatives are beta coordination surfaces. A context store is a local registration for durable shared context, usually a Git-backed folder or clone. An initiative is shared coordination context inside a context store; repo-local changes can link to it without copying the shared plan into every repo.

`openspec context-store setup`

Create and register a local context store.

openspec context-store setup [id] [options]

Options:

Option	Description
`--path <path>`	Context store folder path; defaults to `./<id>`
`--init-git`	Initialize a Git repository in the context store
`--no-init-git`	Do not initialize a Git repository
`--json`	Output JSON

Examples:

openspec context-store setup team-context
openspec context-store setup team-context --path /repos/team-context --no-init-git
openspec context-store setup team-context --json --no-init-git

`openspec context-store register`

openspec context-store register [path] [options]

Options:

Option	Description
`--id <id>`	Context store id; defaults to store metadata or folder name
`--json`	Output JSON

`openspec context-store list`

List locally registered context stores.

openspec context-store list [--json]
openspec context-store ls [--json]

`openspec context-store doctor`

Check local context-store registration, metadata, and Git presence.

openspec context-store doctor [id] [--json]

Doctor is diagnostic-only; it reports missing roots, metadata mismatches, and invalid local registry state without modifying the store.

`openspec initiative create`

Create an initiative in a context store.

openspec initiative create <id> --title <title> --summary <summary> [options]

Options:

Option	Description
`--store <id>`	Context store id from the local registry
`--store-path <path>`	Existing local context store root
`--title <title>`	Initiative title
`--summary <summary>`	Initiative summary
`--json`	Output JSON

`openspec initiative list`

List initiatives. Without a selector, this searches all registered context stores and reports partial-read warnings in status.

openspec initiative list [options]
openspec initiative ls [options]

Options:

Option	Description
`--store <id>`	List one registered context store
`--store-path <path>`	List one existing local context store root
`--json`	Output JSON

`openspec initiative show`

Resolve an initiative and print its canonical location.

openspec initiative show <id> [options]
openspec initiative show <store>/<id> [options]

Without --store, OpenSpec searches registered context stores. If the same initiative id exists in multiple stores, pass --store <id> or use the <store>/<id> form.

Browsing Commands

`openspec list`

List changes or specs in your project.

openspec list [options]

Options:

Option	Description
`--specs`	List specs instead of changes
`--changes`	List changes (default)
`--sort <order>`	Sort by `recent` (default) or `name`
`--json`	Output as JSON

Examples:

# List all active changes
openspec list

# List all specs
openspec list --specs

# JSON output for scripts
openspec list --json

Output (text):

Active changes:
  add-dark-mode     UI theme switching support
  fix-login-bug     Session timeout handling

`openspec view`

Display an interactive dashboard for exploring specs and changes.

openspec view

Opens a terminal-based interface for navigating your project's specifications and changes.

`openspec show`

Display details of a change or spec.

openspec show [item-name] [options]

Arguments:

Argument	Required	Description
`item-name`	No	Name of change or spec (prompts if omitted)

Options:

Option	Description
`--type <type>`	Specify type: `change` or `spec` (auto-detected if unambiguous)
`--json`	Output as JSON
`--no-interactive`	Disable prompts

Change-specific options:

Option	Description
`--deltas-only`	Show only delta specs (JSON mode)

Spec-specific options:

Option	Description
`--requirements`	Show only requirements, exclude scenarios (JSON mode)
`--no-scenarios`	Exclude scenario content (JSON mode)
`-r, --requirement <id>`	Show specific requirement by 1-based index (JSON mode)

Examples:

# Interactive selection
openspec show

# Show a specific change
openspec show add-dark-mode

# Show a specific spec
openspec show auth --type spec

# JSON output for parsing
openspec show add-dark-mode --json

Validation Commands

`openspec validate`

Validate changes and specs for structural issues.

openspec validate [item-name] [options]

Arguments:

Argument	Required	Description
`item-name`	No	Specific item to validate (prompts if omitted)

Options:

Option	Description
`--all`	Validate all changes and specs
`--changes`	Validate all changes
`--specs`	Validate all specs
`--type <type>`	Specify type when name is ambiguous: `change` or `spec`
`--strict`	Enable strict validation mode
`--json`	Output as JSON
`--concurrency <n>`	Max parallel validations (default: 6, or `OPENSPEC_CONCURRENCY` env)
`--no-interactive`	Disable prompts

Examples:

# Interactive validation
openspec validate

# Validate a specific change
openspec validate add-dark-mode

# Validate all changes
openspec validate --changes

# Validate everything with JSON output (for CI/scripts)
openspec validate --all --json

# Strict validation with increased parallelism
openspec validate --all --strict --concurrency 12

Output (text):

Validating add-dark-mode...
  ✓ proposal.md valid
  ✓ specs/ui/spec.md valid
  ⚠ design.md: missing "Technical Approach" section

1 warning found

Output (JSON):

{
  "version": "1.0.0",
  "results": {
    "changes": [
      {
        "name": "add-dark-mode",
        "valid": true,
        "warnings": ["design.md: missing 'Technical Approach' section"]
      }
    ]
  },
  "summary": {
    "total": 1,
    "valid": 1,
    "invalid": 0
  }
}

Lifecycle Commands

`openspec archive`

Archive a completed change and merge delta specs into main specs.

openspec archive [change-name] [options]

Arguments:

Argument	Required	Description
`change-name`	No	Change to archive (prompts if omitted)

Options:

Option	Description
`-y, --yes`	Skip confirmation prompts
`--skip-specs`	Skip spec updates (for infrastructure/tooling/doc-only changes)
`--no-validate`	Skip validation (requires confirmation)

Examples:

# Interactive archive
openspec archive

# Archive specific change
openspec archive add-dark-mode

# Archive without prompts (CI/scripts)
openspec archive add-dark-mode --yes

# Archive a tooling change that doesn't affect specs
openspec archive update-ci-config --skip-specs

What it does:

Validates the change (unless --no-validate)
Prompts for confirmation (unless --yes)
Merges delta specs into openspec/specs/
Moves change folder to openspec/changes/archive/YYYY-MM-DD-<name>/

Workflow Commands

These commands support the artifact-driven OPSX workflow. They're useful for both humans checking progress and agents determining next steps.

`openspec new change`

Create a repo-local change directory and optional checked-in metadata.

openspec new change <name> [options]

Options:

Option	Description
`--description <text>`	Description to add to `README.md`
`--goal <text>`	Workspace product goal to store with the change
`--areas <names>`	Comma-separated affected workspace link names
`--initiative <id>`	Link the repo-local change to an initiative
`--store <id>`	Context store id for `--initiative`
`--store-path <path>`	Existing local context store root for `--initiative`
`--schema <name>`	Workflow schema to use
`--json`	Output JSON

Examples:

openspec new change add-billing-api --initiative billing-launch --store platform
openspec new change add-billing-api --initiative platform/billing-launch --json

`openspec set change`

Update checked-in repo-local change metadata without recreating the change.

openspec set change <name> [options]

Options:

Option	Description
`--initiative <id>`	Link the repo-local change to an initiative
`--store <id>`	Context store id for `--initiative`
`--store-path <path>`	Existing local context store root for `--initiative`
`--json`	Output JSON

set change --initiative is idempotent when the requested link already exists and refuses to replace a different existing initiative link.

`openspec status`

Display artifact completion status for a change.

openspec status [options]

Options:

Option	Description
`--change <id>`	Change name (prompts if omitted)
`--schema <name>`	Schema override (auto-detected from change's config)
`--json`	Output as JSON

Examples:

# Interactive status check
openspec status

# Status for specific change
openspec status --change add-dark-mode

# JSON for agent use
openspec status --change add-dark-mode --json

Output (text):

Change: add-dark-mode
Schema: spec-driven
Progress: 2/4 artifacts complete

[x] proposal
[ ] design
[x] specs
[-] tasks (blocked by: design)

Output (JSON):

{
  "changeName": "add-dark-mode",
  "schemaName": "spec-driven",
  "isComplete": false,
  "applyRequires": ["tasks"],
  "artifacts": [
    {"id": "proposal", "outputPath": "proposal.md", "status": "done"},
    {"id": "design", "outputPath": "design.md", "status": "ready"},
    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done"},
    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "missingDeps": ["design"]}
  ]
}

`openspec instructions`

Get enriched instructions for creating an artifact or applying tasks. Used by AI agents to understand what to create next.

openspec instructions [artifact] [options]

Arguments:

Argument	Required	Description
`artifact`	No	Artifact ID: `proposal`, `specs`, `design`, `tasks`, or `apply`

Options:

Option	Description
`--change <id>`	Change name (required in non-interactive mode)
`--schema <name>`	Schema override
`--json`	Output as JSON

Special case: Use apply as the artifact to get task implementation instructions.

Examples:

# Get instructions for next artifact
openspec instructions --change add-dark-mode

# Get specific artifact instructions
openspec instructions design --change add-dark-mode

# Get apply/implementation instructions
openspec instructions apply --change add-dark-mode

# JSON for agent consumption
openspec instructions design --change add-dark-mode --json

Output includes:

Template content for the artifact
Project context from config
Content from dependency artifacts
Per-artifact rules from config

`openspec templates`

Show resolved template paths for all artifacts in a schema.

openspec templates [options]

Options:

Option	Description
`--schema <name>`	Schema to inspect (default: `spec-driven`)
`--json`	Output as JSON

Examples:

# Show template paths for default schema
openspec templates

# Show templates for custom schema
openspec templates --schema my-workflow

# JSON for programmatic use
openspec templates --json

Output (text):

Schema: spec-driven

Templates:
  proposal  → ~/.openspec/schemas/spec-driven/templates/proposal.md
  specs     → ~/.openspec/schemas/spec-driven/templates/specs.md
  design    → ~/.openspec/schemas/spec-driven/templates/design.md
  tasks     → ~/.openspec/schemas/spec-driven/templates/tasks.md

`openspec schemas`

List available workflow schemas with their descriptions and artifact flows.

openspec schemas [options]

Options:

Option	Description
`--json`	Output as JSON

Example:

openspec schemas

Output:

Available schemas:

  spec-driven (package)
    The default spec-driven development workflow
    Flow: proposal → specs → design → tasks

  my-custom (project)
    Custom workflow for this project
    Flow: research → proposal → tasks

Schema Commands

Commands for creating and managing custom workflow schemas.

`openspec schema init`

Create a new project-local schema.

openspec schema init <name> [options]

Arguments:

Argument	Required	Description
`name`	Yes	Schema name (kebab-case)

Options:

Option	Description
`--description <text>`	Schema description
`--artifacts <list>`	Comma-separated artifact IDs (default: `proposal,specs,design,tasks`)
`--default`	Set as project default schema
`--no-default`	Don't prompt to set as default
`--force`	Overwrite existing schema
`--json`	Output as JSON

Examples:

# Interactive schema creation
openspec schema init research-first

# Non-interactive with specific artifacts
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

What it creates:

openspec/schemas/<name>/
├── schema.yaml           # Schema definition
└── templates/
    ├── proposal.md       # Template for each artifact
    ├── specs.md
    ├── design.md
    └── tasks.md

`openspec schema fork`

Copy an existing schema to your project for customization.

openspec schema fork <source> [name] [options]

Arguments:

Argument	Required	Description
`source`	Yes	Schema to copy
`name`	No	New schema name (default: `<source>-custom`)

Options:

Option	Description
`--force`	Overwrite existing destination
`--json`	Output as JSON

Example:

# Fork the built-in spec-driven schema
openspec schema fork spec-driven my-workflow

`openspec schema validate`

Validate a schema's structure and templates.

openspec schema validate [name] [options]

Arguments:

Argument	Required	Description
`name`	No	Schema to validate (validates all if omitted)

Options:

Option	Description
`--verbose`	Show detailed validation steps
`--json`	Output as JSON

Example:

# Validate a specific schema
openspec schema validate my-workflow

# Validate all schemas
openspec schema validate

`openspec schema which`

Show where a schema resolves from (useful for debugging precedence).

openspec schema which [name] [options]

Arguments:

Argument	Required	Description
`name`	No	Schema name

Options:

Option	Description
`--all`	List all schemas with their sources
`--json`	Output as JSON

Example:

# Check where a schema comes from
openspec schema which spec-driven

Output:

spec-driven resolves from: package
  Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven

Schema precedence:

Project: openspec/schemas/<name>/
User: ~/.local/share/openspec/schemas/<name>/
Package: Built-in schemas

Configuration Commands

`openspec config`

View and modify global OpenSpec configuration.

openspec config <subcommand> [options]

Subcommands:

Subcommand	Description
`path`	Show config file location
`list`	Show all current settings
`get <key>`	Get a specific value
`set <key> <value>`	Set a value
`unset <key>`	Remove a key
`reset`	Reset to defaults
`edit`	Open in `$EDITOR`
`profile [preset]`	Configure workflow profile interactively or via preset

Examples:

# Show config file path
openspec config path

# List all settings
openspec config list

# Get a specific value
openspec config get telemetry.enabled

# Set a value
openspec config set telemetry.enabled false

# Set a string value explicitly
openspec config set user.name "My Name" --string

# Remove a custom setting
openspec config unset user.name

# Reset all configuration
openspec config reset --all --yes

# Edit config in your editor
openspec config edit

# Configure profile with action-based wizard
openspec config profile

# Fast preset: switch workflows to core (keeps delivery mode)
openspec config profile core

openspec config profile starts with a current-state summary, then lets you choose:

Change delivery + workflows
Change delivery only
Change workflows only
Keep current settings (exit)

If you keep current settings, no changes are written and no update prompt is shown. If there are no config changes but the current project or workspace files are out of sync with your global profile/delivery, OpenSpec will show a warning and suggest openspec update for repo-local projects or openspec workspace update for workspace-local guidance and skills. Pressing Ctrl+C also cancels the flow cleanly (no stack trace) and exits with code 130. In the workflow checklist, [x] means the workflow is selected in global config. To apply those selections to project files, run openspec update (or choose Apply changes to this project now? when prompted inside a project). From inside a workspace, use openspec workspace update to refresh workspace-local guidance and skills; this remains skills-only for generated agent workflow files and does not generate workspace slash commands.

Interactive examples:

# Delivery-only update
openspec config profile
# choose: Change delivery only
# choose delivery: Skills only

# Workflows-only update
openspec config profile
# choose: Change workflows only
# toggle workflows in the checklist, then confirm

Utility Commands

`openspec feedback`

Submit feedback about OpenSpec. Creates a GitHub issue.

openspec feedback <message> [options]

Arguments:

Argument	Required	Description
`message`	Yes	Feedback message

Options:

Option	Description
`--body <text>`	Detailed description

Requirements: GitHub CLI (gh) must be installed and authenticated.

Example:

openspec feedback "Add support for custom artifact types" \
  --body "I'd like to define my own artifact types beyond the built-in ones."

`openspec completion`

Manage shell completions for the OpenSpec CLI.

openspec completion <subcommand> [shell]

Subcommands:

Subcommand	Description
`generate [shell]`	Output completion script to stdout
`install [shell]`	Install completion for your shell
`uninstall [shell]`	Remove installed completions

Supported shells: bash, zsh, fish, powershell

Examples:

# Install completions (auto-detects shell)
openspec completion install

# Install for specific shell
openspec completion install zsh

# Generate script for manual installation
openspec completion generate bash > ~/.bash_completion.d/openspec

# Uninstall
openspec completion uninstall

Exit Codes

Code	Meaning
`0`	Success
`1`	Error (validation failure, missing files, etc.)

Environment Variables

Variable	Description
`OPENSPEC_TELEMETRY`	Set to `0` to disable telemetry
`DO_NOT_TRACK`	Set to `1` to disable telemetry (standard DNT signal)
`OPENSPEC_CONCURRENCY`	Default concurrency for bulk validation (default: 6)
`EDITOR` or `VISUAL`	Editor for `openspec config edit`
`NO_COLOR`	Disable color output when set

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Summary

Human vs Agent Commands

Human-Only Commands

Agent-Compatible Commands

Global Options

Setup Commands

openspec init

openspec update

Workspace Commands

openspec workspace setup

openspec workspace list

openspec workspace link

openspec workspace relink

openspec workspace doctor

openspec workspace update

openspec workspace open

Shared Context Commands

openspec context-store setup

openspec context-store register

openspec context-store list

openspec context-store doctor

openspec initiative create

openspec initiative list

openspec initiative show

Browsing Commands

openspec list

openspec view

openspec show

Validation Commands

openspec validate

Lifecycle Commands

openspec archive

Workflow Commands

openspec new change

openspec set change

openspec status

openspec instructions

openspec templates

openspec schemas

Schema Commands

openspec schema init

openspec schema fork

openspec schema validate

openspec schema which

Configuration Commands

openspec config

Utility Commands

openspec feedback

openspec completion

Exit Codes

Environment Variables

Related Documentation

`openspec init`

`openspec update`

`openspec workspace setup`

`openspec workspace list`

`openspec workspace link`

`openspec workspace relink`

`openspec workspace doctor`

`openspec workspace update`

`openspec workspace open`

`openspec context-store setup`

`openspec context-store register`

`openspec context-store list`

`openspec context-store doctor`

`openspec initiative create`

`openspec initiative list`

`openspec initiative show`

`openspec list`

`openspec view`

`openspec show`

`openspec validate`

`openspec archive`

`openspec new change`

`openspec set change`

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

`openspec config`

`openspec feedback`

`openspec completion`