CLI 参考

OpenSpec CLI (openspec) 提供用于项目设置、验证、状态检查和管理的终端命令。这些命令是对 [[[[命令]]]] 中记录的 AI 斜杠命令（如 /opsx:new）的补充。

概要

类别	命令	目的
设置	`init`, `update`	初始化和更新项目中的 OpenSpec
浏览	`list`, `view`, `show`	探索变更和规格
验证	`validate`	检查变更和规格的问题
生命周期	`archive`	完成并归档变更
工作流	`status`, `instructions`, `templates`, `schemas`	工件驱动的工作流支持
Schema	`schema init`, `schema fork`, `schema validate`, `schema which`	创建和管理自定义工作流
配置	`config`	查看和修改设置
实用工具	`feedback`, `completion`	反馈和 Shell 集成

人类 vs 智能体命令

大多数 CLI 命令设计用于终端中的 人类使用。一些命令也通过 JSON 输出支持 智能体/脚本使用。

仅限人类使用的命令

这些命令是交互式的，专为终端使用而设计：

命令	目的
`openspec init`	初始化项目（交互式提示）
`openspec view`	交互式仪表板
`openspec config edit`	在编辑器中打开配置
`openspec feedback`	通过 GitHub 提交反馈
`openspec completion install`	安装 Shell 补全

智能体兼容命令

这些命令支持 --json 输出，供 AI 智能体和脚本通过编程方式使用：

命令	人类使用	智能体使用
`openspec list`	浏览变更/规格	`--json` 获取结构化数据
`openspec show <item>`	读取内容	`--json` 用于解析
`openspec validate`	检查问题	`--all --json` 用于批量验证
`openspec status`	查看工件进度	`--json` 获取结构化状态
`openspec instructions`	获取后续步骤	`--json` 获取智能体指令
`openspec templates`	查找模板路径	`--json` 用于路径解析
`openspec schemas`	列出可用 Schemas	`--json` 用于 Schema 发现

全局选项

这些选项适用于所有命令：

选项	描述
`--version`, `-V`	显示版本号
`--no-color`	禁用彩色输出
`--help`, `-h`	显示命令帮助

设置命令

`openspec init`

在您的项目中初始化 OpenSpec。创建文件夹结构并配置 AI 工具集成。

openspec init [path] [options]

参数：

参数	必填	描述
`path`	否	目标目录（默认：当前目录）

选项：

选项	描述
`--tools <list>`	非交互式配置 AI 工具。使用 `all`, `none` 或逗号分隔列表
`--force`	不提示自动清理遗留文件

支持的工具： amazon-q, antigravity, auggie, claude, cline, codex, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, kilocode, opencode, qoder, qwen, roocode, windsurf

示例：

bash

# 交互式初始化
openspec init

# 在特定目录中初始化
openspec init ./my-project

# 非交互式：为 Claude 和 Cursor 配置
openspec init --tools claude,cursor

# 为所有支持的工具配置
openspec init --tools all

# 跳过提示并自动清理遗留文件
openspec init --force

它创建了什么：

openspec/
├── specs/              # 您的规格（事实来源）
├── changes/            # 提议的变更
└── config.yaml         # 项目配置

.claude/skills/         # Claude Code skill 文件（如果选择了 claude）
.cursor/rules/          # Cursor 规则（如果选择了 cursor）
... (其他工具配置)

`openspec update`

升级 CLI 后更新 OpenSpec 指令文件。重新生成 AI 工具配置文件。

openspec update [path] [options]

参数：

参数	必填	描述
`path`	否	目标目录（默认：当前目录）

选项：

选项	描述
`--force`	即使文件是最新的也强制更新

示例：

bash

# npm 升级后更新指令文件
npm update @fission-ai/openspec
openspec update

浏览命令

`openspec list`

列出项目中的变更或规格。

openspec list [options]

选项：

选项	描述
`--specs`	列出规格而不是变更
`--changes`	列出变更（默认）
`--sort <order>`	按 `recent`（默认）或 `name` 排序
`--json`	输出为 JSON

示例：

bash

# 列出所有活动变更
openspec list

# 列出所有规格
openspec list --specs

# JSON 输出用于脚本
openspec list --json

输出（文本）：

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

`openspec view`

显示用于探索规格和变更的交互式仪表板。

openspec view

打开一个基于终端的界面，用于导航项目的规格和变更。

`openspec show`

显示变更或规格的详细信息。

openspec show [item-name] [options]

参数：

参数	必填	描述
`item-name`	否	变更或规格的名称（如果省略则提示）

选项：

选项	描述
`--type <type>`	指定类型：`change` 或 `spec`（如果明确则自动检测）
`--json`	输出为 JSON
`--no-interactive`	禁用提示

变更特定选项：

选项	描述
`--deltas-only`	仅显示增量规格（JSON 模式）

规格特定选项：

选项	描述
`--requirements`	仅显示需求，排除场景（JSON 模式）
`--no-scenarios`	排除场景内容（JSON 模式）
`-r, --requirement <id>`	按 1-based 索引显示特定需求（JSON 模式）

示例：

bash

# 交互式选择
openspec show

# 显示特定变更
openspec show add-dark-mode

# 显示特定规格
openspec show auth --type spec

# JSON 输出用于解析
openspec show add-dark-mode --json

验证命令

`openspec validate`

验证变更和规格的结构问题。

openspec validate [item-name] [options]

参数：

参数	必填	描述
`item-name`	否	要验证的特定项目（如果省略则提示）

选项：

选项	描述
`--all`	验证所有变更和规格
`--changes`	验证所有变更
`--specs`	验证所有规格
`--type <type>`	当名称模棱两可时指定类型：`change` 或 `spec`
`--strict`	启用严格验证模式
`--json`	输出为 JSON
`--concurrency <n>`	最大并行验证数（默认：6，或 `OPENSPEC_CONCURRENCY` 环境变量）
`--no-interactive`	禁用提示

示例：

bash

# 交互式验证
openspec validate

# 验证特定变更
openspec validate add-dark-mode

# 验证所有变更
openspec validate --changes

# 验证所有内容并输出 JSON（用于 CI/脚本）
openspec validate --all --json

# 使用增加的并行度进行严格验证
openspec validate --all --strict --concurrency 12

输出（文本）：

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

1 warning found

输出（JSON）：

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
  }
}

生命周期命令

`openspec archive`

归档已完成的变更并将增量规格合并到主规格中。

openspec archive [change-name] [options]

参数：

参数	必填	描述
`change-name`	否	要归档的变更（如果省略则提示）

选项：

选项	描述
`-y, --yes`	跳过确认提示
`--skip-specs`	跳过规格更新（用于仅涉及基础设施/工具/文档的变更）
`--no-validate`	跳过验证（需要确认）

示例：

bash

# 交互式归档
openspec archive

# 归档特定变更
openspec archive add-dark-mode

# 不提示归档（CI/脚本）
openspec archive add-dark-mode --yes

# 归档不影响规格的工具变更
openspec archive update-ci-config --skip-specs

它做什么：

验证变更（除非 --no-validate）
提示确认（除非 --yes）
将增量规格合并到 openspec/specs/
将变更文件夹移动到 openspec/changes/archive/YYYY-MM-DD-<name>/

工作流命令

这些命令支持工件驱动的 OPSX 工作流。它们对检查进度的人类和确定下一步的智能体都很有用。

`openspec status`

显示变更的工件完成状态。

openspec status [options]

选项：

选项	描述
`--change <id>`	变更名称（如果省略则提示）
`--schema <name>`	Schema 覆盖（从变更配置中自动检测）
`--json`	输出为 JSON

示例：

bash

# 交互式状态检查
openspec status

# 特定变更的状态
openspec status --change add-dark-mode

# 智能体使用的 JSON
openspec status --change add-dark-mode --json

输出（文本）：

Change: add-dark-mode
Schema: spec-driven

Artifacts:
  ✓ proposal     proposal.md exists
  ✓ specs        specs/ exists
  ◆ design       ready (requires: specs)
  ○ tasks        blocked (requires: design)

Next: Create design using /opsx:continue

输出（JSON）：

json

{
  "change": "add-dark-mode",
  "schema": "spec-driven",
  "artifacts": [
    {"id": "proposal", "status": "complete", "path": "proposal.md"},
    {"id": "specs", "status": "complete", "path": "specs/"},
    {"id": "design", "status": "ready", "requires": ["specs"]},
    {"id": "tasks", "status": "blocked", "requires": ["design"]}
  ],
  "next": "design"
}

`openspec instructions`

获取用于创建工件或应用任务的丰富指令。由 AI 智能体用于了解下一步要创建什么。

openspec instructions [artifact] [options]

参数：

参数	必填	描述
`artifact`	否	工件 ID：`proposal`, `specs`, `design`, `tasks`, 或 `apply`

选项：

选项	描述
`--change <id>`	变更名称（非交互模式下必填）
`--schema <name>`	Schema 覆盖
`--json`	输出为 JSON

特殊情况： 使用 apply 作为工件以获取任务实施指令。

示例：

bash

# 获取下一个工件的指令
openspec instructions --change add-dark-mode

# 获取特定工件的指令
openspec instructions design --change add-dark-mode

# 获取实施/应用指令
openspec instructions apply --change add-dark-mode

# 智能体使用的 JSON
openspec instructions design --change add-dark-mode --json

输出包括：

工件的模板内容
来自 config 的项目上下文
来自依赖工件的内容
来自 config 的每个工件规则

`openspec templates`

显示 Schema 中所有工件的解析模板路径。

openspec templates [options]

选项：

选项	描述
`--schema <name>`	要检查的 Schema（默认：`spec-driven`）
`--json`	输出为 JSON

示例：

bash

# 显示默认 Schema 的模板路径
openspec templates

# 显示自定义 Schema 的模板
openspec templates --schema my-workflow

# 编程使用的 JSON
openspec templates --json

输出（文本）：

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`

列出可用工作流 Schema 及其描述和工件流程。

openspec schemas [options]

选项：

选项	描述
`--json`	输出为 JSON

示例：

bash

openspec schemas

输出：

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 命令

用于创建和管理自定义工作流 Schema 的命令。

`openspec schema init`

创建一个新的项目本地 Schema。

openspec schema init <name> [options]

参数：

参数	必填	描述
`name`	是	Schema 名称 (kebab-case)

选项：

选项	描述
`--description <text>`	Schema 描述
`--artifacts <list>`	逗号分隔的工件 ID（默认：`proposal,specs,design,tasks`）
`--default`	设置为项目默认 Schema
`--no-default`	不提示设置为默认
`--force`	覆盖现有 Schema
`--json`	输出为 JSON

示例：

bash

# 交互式 Schema 创建
openspec schema init research-first

# 具有特定工件的非交互式创建
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

它创建了什么：

openspec/schemas/<name>/
├── schema.yaml           # Schema 定义
└── templates/
    ├── proposal.md       # 每个工件的模板
    ├── specs.md
    ├── design.md
    └── tasks.md

`openspec schema fork`

将现有 Schema 复制到您的项目中以进行自定义。

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

参数：

参数	必填	描述
`source`	是	要复制的 Schema
`name`	否	新 Schema 名称（默认：`<source>-custom`）

选项：

选项	描述
`--force`	覆盖现有目标
`--json`	输出为 JSON

示例：

bash

# Fork 内置的 spec-driven Schema
openspec schema fork spec-driven my-workflow

`openspec schema validate`

验证 Schema 的结构和模板。

openspec schema validate [name] [options]

参数：

参数	必填	描述
`name`	否	要验证的 Schema（如果省略则验证所有）

选项：

选项	描述
`--verbose`	显示详细验证步骤
`--json`	输出为 JSON

示例：

bash

# 验证特定 Schema
openspec schema validate my-workflow

# 验证所有 Schema
openspec schema validate

`openspec schema which`

显示 Schema 从哪里解析（用于调试优先级）。

openspec schema which [name] [options]

参数：

参数	必填	描述
`name`	否	Schema 名称

选项：

选项	描述
`--all`	列出所有 Schema 及其来源
`--json`	输出为 JSON

示例：

bash

# 检查 Schema 来自哪里
openspec schema which spec-driven

输出：

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

Schema 优先级：

项目：openspec/schemas/<name>/
用户：~/.local/share/openspec/schemas/<name>/
包：内置 Schemas

配置命令

`openspec config`

查看和修改全局 OpenSpec 配置。

openspec config <subcommand> [options]

子命令：

子命令	描述
`path`	显示配置文件位置
`list`	显示所有当前设置
`get <key>`	获取特定值
`set <key> <value>`	设置值
`unset <key>`	移除键
`reset`	重置为默认值
`edit`	在 `$EDITOR` 中打开

示例：

bash

# 显示配置文件路径
openspec config path

# 列出所有设置
openspec config list

# 获取特定值
openspec config get telemetry.enabled

# 设置值
openspec config set telemetry.enabled false

# 显式设置字符串值
openspec config set user.name "My Name" --string

# 移除自定义设置
openspec config unset user.name

# 重置所有配置
openspec config reset --all --yes

# 在编辑器中编辑配置
openspec config edit

brownfield

核心功能特性

CLI 参考

概要

人类 vs 智能体命令

仅限人类使用的命令

智能体兼容命令

全局选项

设置命令

`openspec init`

`openspec update`

浏览命令

`openspec list`

`openspec view`

`openspec show`

验证命令

`openspec validate`

生命周期命令

`openspec archive`

工作流命令

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

Schema 命令

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

配置命令

`openspec config`

CLI 参考 ​

概要 ​

人类 vs 智能体命令 ​

仅限人类使用的命令 ​

智能体兼容命令 ​

全局选项 ​

设置命令 ​

openspec init ​

openspec update ​

浏览命令 ​

openspec list ​

openspec view ​

openspec show ​

验证命令 ​

openspec validate ​

生命周期命令 ​

openspec archive ​

工作流命令 ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

Schema 命令 ​

openspec schema init ​

openspec schema fork ​

openspec schema validate ​

openspec schema which ​

配置命令 ​

openspec config ​

CLI 参考

概要

人类 vs 智能体命令

仅限人类使用的命令

智能体兼容命令

全局选项

设置命令

`openspec init`

`openspec update`

浏览命令

`openspec list`

`openspec view`

`openspec show`

验证命令

`openspec validate`

生命周期命令

`openspec archive`

工作流命令

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

Schema 命令

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

配置命令

`openspec config`