CLI 参考

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

摘要

类别	命令	用途
设置	`init`, `update`	在项目中初始化和更新 OpenSpec
存储库（独立 OpenSpec 仓库）	`store setup`, `store register`, `store unregister`, `store remove`, `store list`, `store doctor`	管理存储库 — 你已注册的独立 OpenSpec 仓库
健康检查	`doctor`	报告已解析根节点的关系健康状况
工作上下文	`context`	组装工作集（根节点 + 引用存储库）
个人工作集	`workset create`, `workset list`, `workset open`, `workset remove`	在你的工具中保持和打开个人的本地工作视图
浏览	`list`, `view`, `show`	探索变更和规范
验证	`validate`	检查变更和规范中的问题
生命周期	`archive`	完成已完成的变更
工作流	`new change`, `status`, `instructions`, `templates`, `schemas`	支持基于工件的工作流
模式	`schema init`, `schema fork`, `schema validate`, `schema which`	创建和管理自定义工作流
配置	`config`	查看和修改设置
实用工具	`feedback`, `completion`	反馈和 Shell 集成

人类与 Agent 命令

大多数 CLI 命令是为人类在终端中使用而设计的。部分命令还支持通过 JSON 输出进行Agent/脚本使用。

仅限人类使用的命令

以下命令为交互式命令，专为终端使用而设计：

命令	用途
`openspec init`	初始化项目（交互式提示）
`openspec view`	交互式仪表盘
`openspec workset open <name>`	打开已保存的工作集（编辑器窗口或终端 Agent 会话）
`openspec config edit`	在编辑器中打开配置文件
`openspec feedback`	通过 GitHub 提交反馈
`openspec completion install`	安装 Shell 补全

兼容 Agent 的命令

以下命令支持 --json 输出，供 AI Agent 和脚本进行程序化使用：

命令	人类使用	Agent 使用
`openspec list`	浏览变更/规范	`--json` 获取结构化数据
`openspec show <item>`	阅读内容	`--json` 用于解析
`openspec validate`	检查问题	`--all --json` 用于批量验证
`openspec status`	查看产物进度	`--json` 获取结构化状态
`openspec instructions`	获取下一步操作	`--json` 获取 Agent 指令
`openspec templates`	查找模板路径	`--json` 用于路径解析
`openspec schemas`	列出可用模式	`--json` 用于模式发现；`--store <id>` 选择已注册的根目录
`openspec store setup <id>`	创建并注册本地存储	`--json` 配合显式输入参数，获取结构化设置输出
`openspec store register <path>`	注册现有存储	`--json` 获取结构化注册输出
`openspec store unregister <id>`	取消本地存储注册	`--json` 获取结构化清理输出
`openspec store remove <id>`	删除已注册的本地存储文件夹	`--yes --json` 用于非交互式删除
`openspec store list`	浏览已注册的存储	`--json` 获取结构化注册信息
`openspec store doctor`	检查本地存储设置	`--json` 获取结构化诊断信息
`openspec new change <id>`	创建仓库本地变更脚手架	`--json`，配合 `--store <id>` 使用已注册的存储作为 OpenSpec 根目录
`openspec workset create [name]`	组合个人工作视图	`--member <path> --json` 用于非交互式组合
`openspec workset list`	浏览已保存的工作集	`--json` 获取结构化视图
`openspec workset remove <name>`	删除已保存的视图	`--yes --json` 用于非交互式删除

全局选项

以下选项适用于所有命令：

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

设置命令

`openspec init`

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

默认行为使用全局配置默认值：profile 为 core，delivery 为 both，workflows 为 propose, explore, apply, update, sync, archive。

openspec init [path] [options]

使用 --language <language> 为新项目的 openspec/config.yaml 添加语言指令。对于现有项目，请编辑配置的 context 字段，以避免 OpenSpec 覆盖项目特定的指导内容。

参数：

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

选项：

选项	描述
`--tools <list>`	非交互式配置 AI 工具。使用 `all`、`none` 或逗号分隔的列表
`--language <language>`	创建新配置时以该语言编写产物
`--force`	自动清理遗留文件，无需提示
`--profile <profile>`	覆盖本次初始化的全局 profile（`core` 或 `custom`）
`--no-animation`	显示静态欢迎界面而非动画界面
`--copilot-cloud`	设置 GitHub Copilot 云端编码 Agent 文件，无需提示
`--no-copilot-cloud`	跳过 GitHub Copilot 云端编码 Agent 文件，无需提示

--profile custom 使用全局配置（openspec config profile）中当前选中的工作流。

当设置了 OPENSPEC_NO_ANIMATION 环境变量（任意值，包括空值）、NO_COLOR 设置为非空值，或操作系统开启了减少动态效果偏好（macOS 减少动态效果、GNOME 禁用动画）时，欢迎动画也会被跳过。

支持的工具 ID（--tools） — windsurf 也作为 devin 的别名被接受：amazon-q、antigravity、auggie、bob、claude、cline、command-code、codeartsagent、codex、devin、forgecode、codebuddy、continue、costrict、crush、cursor、factory、gemini、github-copilot、hermes、iflow、junie、kilocode、kimi、kiro、lingma、minimax-code、vibe、oh-my-pi、opencode、pi、codeassistant、qoder、qwen、rovodev、roocode、trae、zed、zcode、agents

此列表与 src/core/config.ts 中的 AI_TOOLS 保持一致。各工具的技能路径和命令路径请参阅支持的工具。

示例：

bash

# 交互式初始化
openspec init

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

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

# 非交互式：配置全局 MiniMax Code 技能
openspec init --tools minimax-code

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

# 覆盖本次运行的 profile
openspec init --profile core

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

创建的内容：

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

.claude/skills/         # Claude Code 技能（如果选择了 claude）
.cursor/skills/         # Cursor 技能（如果选择了 cursor）
.cursor/commands/       # Cursor OPSX 命令（如果 delivery 包含 commands）
.agents/skills/         # 兼容 AGENTS.md 的工具的共享技能（如果选择了 agents）
... (其他工具配置)

`openspec update`

在升级 CLI 后更新 OpenSpec 指令文件。使用当前全局 profile、选中的工作流和交付模式重新生成 AI 工具配置文件。

openspec update [path] [options]

参数：

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

选项：

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

示例：

bash

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

请先升级包。指令文件由已安装的 CLI 生成，因此对旧版本运行 openspec update 会报告一切已是最新，而不会添加新版本发布的工作流。

为了让这一点可见，openspec update 会向 npm 注册表查询是否有更新的 CLI 版本。如果你的版本落后，它会提供升级选项：

text

A newer OpenSpec CLI is available (v1.6.0 → v1.7.0).
  Running from: /usr/local/lib/node_modules/@fission-ai/openspec
? Upgrade to v1.7.0 now? (Y/n)

回答 yes 后，它会运行 npm install -g @fission-ai/openspec@latest，然后使用新 CLI 重新执行更新，使新工作流在同一条命令中落地。它会通过询问已安装二进制的版本来确认升级，而不是依赖 npm 的退出码，因此如果 PATH 中更早的安装仍在响应，它会告知你而不是声称成功。回答 no 后，它会打印命令并使用你当前的 CLI 进行更新。Ctrl-C 可停止命令。

该提示仅在交互式终端中出现，且仅在 npm 拥有安装权限时出现——这是 npm install -g 实际能修复的唯一情况。其他情况会显示与安装方式匹配的命令：

OpenSpec 的安装方式	你会得到什么
全局 npm 安装	提示框，并为你执行升级——在交互式终端中；管道输出则显示打印的命令
全局 pnpm、bun、yarn 或 volta 安装	对应包管理器的命令：`pnpm add -g …@latest`、`bun add -g …@latest`、`yarn global add …@latest` 或 `volta install …@latest`
项目依赖	提示更新依赖，因为其包管理器管理锁文件
`npx` / `dlx` 缓存	`npx @fission-ai/openspec@latest update` — 该命令本身就是更新，无需第二步
Git clone	无 — 你的版本取决于分支内容

每当有任何输出时，都会标明运行中的 CLI 加载自哪个目录——当你确实升级了但 PATH 中仍有旧 shim 时，这是需要检查的地方。

当 npm 导出 npm_config_registry 时，它会查询该注册表，否则查询 https://registry.npmjs.org。不会读取 .npmrc：让文件内容决定出站请求的目标是一个应避免的流程，而且项目的 .npmrc 会随仓库一起传播。在私有镜像上，请导出 npm_config_registry — 或设置 OPENSPEC_NO_UPDATE_CHECK 以完全跳过检查。当 CI 设置为非显式关闭值（false、0、no、off 或空值）以外的任何值时、在 NODE_ENV=test 下、以及设置了 OPENSPEC_NO_UPDATE_CHECK（任意值）、DO_NOT_TRACK=1 或 OPENSPEC_TELEMETRY=0 时，检查会被跳过。它在更新之前运行，最多延迟 1.5 秒 — 即使网络静默丢包也会在此后放弃，并且在注册表不可达时保持静默。

如何判定"已是最新"： 技能文件记录了生成它们的版本，因此 OpenSpec 会将该版本与已安装的 CLI 进行比较。命令文件不携带版本标记，因此对于有命令但无技能的工具（delivery 为 commands），OpenSpec 会将文件内容与当前生成的内容进行对比 — 对这些文件的编辑会被视为偏差并被覆盖。当 delivery 为 skills 或 both 时，仅检查记录的版本，因此版本仍匹配的手工编辑文件会被保留；使用 --force 可强制重写。无论如何，生成的文件归 OpenSpec 所有 — 请将你自己的指令放在其他地方。

Stores（独立的 OpenSpec 仓库）

Beta 版。 Stores 及其基于其构建的功能（引用、工作上下文、工作集）是新增功能；命令名称、标志、文件格式和 JSON 输出可能会在版本之间变化。有关以问题为导向的演练，请参阅 stores 指南。

store 是您在此机器上注册的独立 OpenSpec 仓库——例如规划仓库或契约仓库。注册 store 后，普通命令（list、show、status、validate、new change、archive 等）可以通过传递 --store <id> 在任何位置对其进行操作。

`openspec store setup`

创建并注册本地 store。在终端中不带参数运行时，OpenSpec 会引导用户完成设置。代理和脚本应传递显式输入并使用 --json。

bash

openspec store setup [id] [options]

选项：

选项	描述
`--path <path>`	store 所在的文件夹（例如 `~/openspec/<id>`）
`--remote <url>`	在新 store 的 `store.yaml` 中记录规范远程地址
`--init-git`	初始化 Git 仓库并创建初始提交（默认）
`--no-init-git`	跳过所有 Git 操作：不初始化，不创建初始提交
`--json`	输出 JSON

非交互式运行（--json、脚本、代理）必须同时传递 store id 和 --path。在交互式终端中，setup 会提示位置，并在可见、用户拥有的位置提供可编辑的建议（例如 ~/openspec/<id>）；它绝不会默认使用 OpenSpec 托管的数据目录。

示例：

bash

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

`openspec store register`

注册现有的本地 store 文件夹。在 stores beta 期间，可能在存在任何变更、已应用规范或已归档变更之前注册根目录；在这种情况下，openspec/changes/、openspec/specs/ 和 openspec/changes/archive/ 在普通命令创建它们之前可能不存在。声明了 store: <id> 的仅配置仓库仍然是指向另一个 store 的指针，除非移除该指针，否则不会注册为 store 根目录。

bash

openspec store register [path] [options]

选项：

选项	描述
`--id <id>`	Store id；默认为 store 元数据或文件夹名称
`--yes`	确认为健康的 OpenSpec 根目录创建 store 身份元数据
`--json`	输出 JSON

`openspec store unregister`

忘记本地 store 注册而不删除文件。

bash

openspec store unregister <id> [--json]

当 store 被移动、克隆到其他位置，或不应再在此机器上由 OpenSpec 显示时，使用此命令。

`openspec store remove`

忘记本地 store 注册并删除其本地文件夹。

bash

openspec store remove <id> [--yes] [--json]

remove 在交互式终端中删除前会显示确切的文件夹。代理、脚本和 JSON 调用者必须传递 --yes 来确认删除。OpenSpec 拒绝删除不包含匹配 store 元数据的文件夹。

`openspec store list`

列出本地注册的 store。

bash

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

`openspec store doctor`

检查本地 store 注册、元数据和 Git 存在情况。

bash

openspec store doctor [id] [--json]

Doctor 仅用于诊断；它报告缺失的根目录、元数据不匹配和无效的本地注册表状态，而不修改 store。

从项目引用 store

项目仓库可以在 openspec/config.yaml 中声明其工作所依赖的 store：

yaml

schema: spec-driven
references:
  - team-context

此后，该仓库中的 openspec instructions 输出（包括每种工件和 apply 界面、JSON 和人类可读模式）都携带每个被引用 store 的规范索引——规范 ID、每个规范 Purpose 部分的一行摘要，以及获取命令（openspec show <spec-id> --type spec --store <id>）。该索引在每次运行时从已注册的检出实时构建；规范内容绝不会复制到输出中。

引用是只读上下文。它们绝不会改变命令的作用位置：工作保持在仓库自身的根目录中，写入被引用的 store 仍然是显式的 --store 操作。无法解析的引用（例如，此机器上未注册的 store）会在索引中降级为警告，并给出确切的修复方法，指令仍然会生成。openspec doctor 会集中报告引用健康状况。

记录 store 的克隆来源

store 可以在其已提交的身份文件中记录其规范的克隆来源，因此入职流程不会以"注册 store"为死胡同：

bash

openspec store setup team-context --path ~/openspec/team-context \
  --remote git@github.com:acme/team-context.git

远程地址位于初始提交内部的 .openspec-store/store.yaml 中，因此每个克隆从一开始就知道它。对于现有的 store，手动编辑 store.yaml 并提交。store doctor 显示记录的远程地址（以及检出中观察到的 Git origin）；setup/register 共享指南会命名它；register 会在机器本地注册表中记录检出的 origin。

引用声明也可以携带克隆来源，因此尚未拥有该 store 的队友可以获得完整、可粘贴的修复方法（git clone <remote> <path> && openspec store register <path> --id <id>）：

yaml

references:
  - { id: team-context, remote: "git@github.com:acme/team-context.git" }

记录远程地址不是同步：OpenSpec 从不自行克隆、拉取或推送。

声明默认 store

一个规划完全外部化的仓库——没有本地 openspec/specs/ 或 openspec/changes/——可以一次性声明其 store，而无需在每条命令上传递 --store：

yaml

# openspec/config.yaml（openspec/ 下唯一的文件）
store: team-context

然后普通命令会自动解析到声明的 store；根目录横幅和 JSON root 块报告 source: "declared" 以及 store id，打印的提示仍然携带 --store <id>。该声明是回退，绝不是覆盖：显式的 --store 始终优先，具有真实规划文件夹的目录会忽略该指针（并发出警告）。要将指针仓库转换为本地 OpenSpec 根目录，请移除 store: 行并运行 openspec init——在声明存在时，init 拒绝搭建脚手架。

机器级变体一次涵盖所有仓库：openspec config set defaultStore <id>（请参阅 Configuration）。仅在所有 --store、本地根目录和项目指针均无法解析后才查阅该配置；根目录横幅和 JSON root 块随后报告 source: "global_default"。

医生（关系健康）

一个只读问题，一个位置：OpenSpec 根目录是否健康，以及它所引用的存储库在此机器上是否可用？

bash

openspec doctor [--store <id>] [--json]

报告将根健康、存储元数据健康（包括记录远程与检出来源分叉时的说明，以及存储检出版本落后于上次获取的上游跟踪引用时的说明）和引用健康分开。任何严重程度的健康发现都会退出代码 0——代理读取 status 数组；只有命令失败（无根目录、未知存储）才会退出代码 1。Doctor 永远不会克隆、同步或修复。若要获取组装后的集合本身而非其健康状况，请使用 openspec context。

工作上下文（组装后的集合）

通过 OpenSpec 声明与此工作相关的所有内容，在一个工作集中：OpenSpec 根目录及其引用的存储库。

bash

openspec context [--store <id>] [--json] [--code-workspace <path> [--force]]

JSON 摘要可供代理消费（每个可用的引用存储都携带其获取配方；未解决的成员携带相同的修复说明和医生显示）。--code-workspace 还会写入一个 VS Code 工作区文件，其中包含根目录和可用的引用存储（ref:<id> 文件夹）——这是该命令执行的唯一写入操作，如果文件已存在，除非使用 --force，否则拒绝写入。不可用的成员会被报告，但不会被猜测。

“工作上下文”是组装后的集合；openspec/config.yaml 中的 context: 字段是注入到指令中的项目背景——这是两回事。openspec doctor 回答集合是否健康；openspec context 回答集合是什么。

个人工作集

Beta。 工作集是新 Beta 表面的一部分；命令、标志和文件格式可能会在版本之间发生变化。有关演练，请参阅存储指南。

工作集是你共同工作的文件夹的个人命名视图——一个规划根目录加上你选择的任何其他内容——保存在你的机器上并通过名称在你的工具中重新打开。它完全是本地的：从不提交，从不共享，不从声明派生，删除一个工作集永远不会触及成员文件夹。

bash

openspec workset create [name] [--member <path> | --member <name>=<path>]... [--tool <id>] [--json]
openspec workset list [--json]
openspec workset open <name> [--tool <id>]
openspec workset remove <name> [--yes] [--json]

create 运行简短的引导流程（或以非交互方式接受 --member 标志；第一个成员是主要成员——会话从那里开始）。open 启动所选工具：编辑器（VS Code、Cursor）打开一个包含所有成员的窗口并返回；CLI 代理（Claude Code、codex）接管此终端作为附带所有成员的会话，且不预填提示符，当你退出时结束。如果在打开时缺少成员文件夹，则跳过并附带说明；其余部分打开。保存的工具偏好可以通过 --tool 在每个打开时覆盖。

支持新工具是配置，而不是代码。每个工具都是两种启动样式之一——workspace-file（使用生成的 .code-workspace 启动）或 attach-dirs（每个成员一个附加标志）——全局 config.json 中的 openers 键（使用 openspec config edit 打开）添加工具或根据字段调整内置项：

json

{
  "openers": {
    "zed": { "style": "workspace-file" },
    "claude": { "attach_flag": "--dir" }
  }
}

所有工作集状态都位于全局数据目录的 worksets/ 文件夹下（保存的视图以及每次打开时重新生成的 <name>.code-workspace 文件）；删除该文件夹会移除所有痕迹。

浏览命令

`openspec list`

列出项目中的更改或规范。

openspec list [options]

选项：

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

示例：

bash

# 列出所有活动更改
openspec list

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

# 脚本使用的 JSON 输出
openspec list --json

输出（文本）：

Changes:
  add-dark-mode     No tasks      just now

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

验证变更和规范的结构问题，并检查变更的 MODIFIED 需求与其将替换的主规范之间的匹配情况。

openspec validate [item-name] [options]

如果变更的规范差异为零，则验证将失败，除非其 .openspec.yaml 声明了 skip_specs: true（适用于纯重构、工具或文档工作——参见 Recipe 5）。

参数：

参数	必填	描述
`item-name`	否	要验证的特定项目（省略时会提示输入）

选项：

选项	描述
`--all`	验证所有变更和规范
`--changes`	验证所有变更
`--specs`	验证所有规范
`--archived`	验证已归档的变更是否所有任务均已完成（用于预提交检查）
`--type <type>`	当名称存在歧义时指定类型：`change` 或 `spec`
`--strict`	启用严格验证模式
`--json`	以 JSON 格式输出
`--concurrency <n>`	最大并行验证数（默认：6，或 `OPENSPEC_CONCURRENCY` 环境变量）
`--no-interactive`	禁用提示

--archived 是独立的范围：它不验证规范差异（归档时已应用），而是验证 changes/archive/ 下的每个变更的 tasks.md 复选框是否全部勾选，如果有未勾选的则返回非零退出码。这可以捕获带有未完成工作却被归档的变更——在预提交钩子中非常实用。

示例：

bash

# 交互式验证
openspec validate

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

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

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

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

# 如果任何已归档变更仍有未勾选的任务则失败
openspec validate --archived

输出（文本）：

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`	跳过确认提示。当无法回答提示时为必填——例如 AI 代理、CI 任务或任何 stdin 关闭的运行环境
`--skip-specs`	跳过单次归档运行的规范更新。如果某个变更永久没有规范差异，应在其 `.openspec.yaml` 中声明 `skip_specs: true`——这样归档时无需使用此标志
`--no-validate`	跳过验证（需要确认）。同时禁用能力退役——没有验证器判定，不会退役任何内容

示例：

bash

# 交互式归档（询问要归档哪个变更，然后确认）
openspec archive

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

# 无提示归档（代理、CI、脚本）
openspec archive add-dark-mode --yes

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

退役一个能力： 在变更元数据中添加退役标记：

yaml

# openspec/changes/retire-legacy/.openspec.yaml
schema: spec-driven
retire_capabilities: true

然后正常归档该变更：

bash

openspec archive retire-legacy --yes

当变更移除了该能力的最后一个需求时，OpenSpec 会删除其活跃的 spec.md。同一变更中其他能力的差异仍会更新其主规范。如果没有该标记，归档会在修改任何文件之前停止，并提示你添加该标记。

执行内容：

验证该变更（除非使用 --no-validate）
提示确认（除非使用 --yes）
在修改任何主规范之前锁定归档目标
验证并将活跃的差异规范合并到 openspec/specs/ 中——如果变更移除了某能力的最后一个需求，该能力将被退役，其规范文件将被删除，但仅在变更的 .openspec.yaml 中声明了 retire_capabilities: true 且位于其 schema: 旁边时才生效
将变更文件夹移动到 openspec/changes/archive/YYYY-MM-DD-<name>/
如果在完整归档确认之前发生规范修改或最终移动失败，则恢复规范并将变更保留或返回到其活跃路径
如果已验证的备用副本完成但暂存源清理失败，则保留完整的归档和已提交的规范状态以供恢复

无终端环境： AI 代理、CI 任务或任何 stdin 关闭的运行环境无法回答第 2 步，因此归档会在触及任何内容之前停止，退出码为 1，并指明需要重新运行的命令——openspec archive <name> --yes，携带你传递的其他标志。预先传递 --yes（和变更名称）可跳过往返交互。

工作流命令

这些命令支持基于工件的 OPSX 工作流。它们既方便人工检查进度，也方便智能体确定下一步操作。

`openspec new change`

在已解析的 OpenSpec 根目录下创建变更目录和可选的已签入元数据。

bash

openspec new change <name> [options]

变更名称必须使用小写短横线命名法：小写字母、数字和单个短横线。不能包含空格、下划线、大写字母、连续短横线或首尾短横线。允许以数字开头，因此可以通过前缀来排序或分级变更，例如 100-add-feature 或 00001-add-auth。

选项：

选项	描述
`--description <text>`	添加到 `index.md` 的描述
`--goal <text>`	与变更一起存储的可选目标元数据
`--schema <name>`	要使用的工作流模式
`--store <id>`	用作 OpenSpec 根目录的存储 ID（存储是您注册的独立 OpenSpec 仓库）
`--json`	输出 JSON

示例：

bash

openspec new change add-billing-api
openspec new change add-billing-api --store team-context --json

`openspec status`

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

openspec status [options]

选项：

选项	描述
`--change <id>`	变更名称（省略时会提示输入）
`--schema <name>`	模式覆盖（从变更配置中自动检测）
`--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
Progress: 2/4 artifacts complete

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

声明了 skip_specs: true 的变更会将其 specs 阶段显示为 [~] specs (skipped: change declares skip_specs)，并将其排除在进度计数之外。

输出（JSON）：

json

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

isPlanningComplete 报告是否所有未跳过的规划工件都已存在；跳过的工件视为已满足，无需创建。它不报告实现任务是否完成。isComplete 作为兼容性别名保留，值相同。

工件按依赖顺序列出——依赖项永远不会出现在需要它的工件之后——同时就绪的工件（spec-driven 的 specs 和 design 都只需要 proposal）保持模式声明的顺序，而非字母顺序。因此第一个 ready 条目就是下一个要编写的工件。

`openspec instructions`

获取创建工件或应用任务的增强指令。供 AI 智能体了解下一步要创建什么。

openspec instructions [artifact] [options]

参数：

参数	必填	描述
`artifact`	否	工件 ID，或工作流输入面：`apply` 或 `archive`

选项：

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

特殊情况： 使用 apply 获取任务实现指令。使用 archive 获取有效变更的当前只读归档输入（context 和 operationGuidance）；它不会执行归档或修改任何内容。

示例：

bash

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

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

# 获取 apply/实现指令
openspec instructions apply --change add-dark-mode

# 获取当前归档操作输入而不执行归档
openspec instructions archive --change add-dark-mode --json

# 以 JSON 格式输出供智能体消费
openspec instructions design --change add-dark-mode --json

输出包含：

工件的模板内容
来自配置的上下文信息
来自依赖工件的内容
来自配置的每个工件的规则
针对 apply/archive 的当前项目上下文和匹配的操作指导

操作输入在每次调用时从已解析的仓库或选定的存储中读取。项目上下文是必需的提示级输入：智能体读取它并应用相关的项目事实、约定和约束。操作指导是可选的附加建议：智能体考虑每个条目，仅遵循适用且与内置工作流兼容的条目。这两个字段都与显式用户选择、CLI 控制的状态、内置指令和工件规则保持分离。冲突的上下文会被报告；冲突或不适用的指导不会被遵循，并会解释原因。这些是生成智能体的行为契约，而非可强制执行的 CLI 检查。instructions archive 仅返回选定的变更、可选输入和根元数据；不包含静态归档工作流。

对于通过 skip_specs: true 跳过的工件，输出仅为警告（JSON 会添加 skipped/warning 字段）——该工件不得创建。

`openspec templates`

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

openspec templates [options]

选项：

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

示例：

bash

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

# 显示自定义模式的模板
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`

列出可用的工作流模式及其描述和工件流程。

openspec schemas [options]

选项：

选项	描述
`--json`	以 JSON 格式输出
`--store <id>`	使用已注册的存储作为 OpenSpec 根目录

示例：

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

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

`openspec schema init`

创建一个新的项目本地模式。

openspec schema init <name> [options]

参数：

参数	必填	描述
`name`	是	模式名称（kebab-case 短横线命名）

选项：

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

示例：

bash

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

# 非交互式并指定工件
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

它创建的内容：

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

`openspec schema fork`

复制现有模式到你的项目中进行自定义。

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

参数：

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

选项：

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

示例：

bash

# 复制内置的 spec-driven 模式
openspec schema fork spec-driven my-workflow

`openspec schema validate`

验证模式的结构和模板。

openspec schema validate [name] [options]

参数：

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

选项：

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

示例：

bash

# 验证特定模式
openspec schema validate my-workflow

# 验证所有模式
openspec schema validate

`openspec schema which`

显示模式的解析来源（用于调试优先级）。

openspec schema which [name] [options]

参数：

参数	必填	描述
`name`	否	模式名称

选项：

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

示例：

bash

# 检查模式的来源
openspec schema which spec-driven

输出：

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

模式优先级：

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

配置命令

`openspec config`

查看和修改全局 OpenSpec 配置。

openspec config <subcommand> [options]

子命令：

子命令	描述
`path`	显示配置文件位置
`list`	显示所有当前设置
`get <key>`	获取特定值
`set <key> <value>`	设置值
`unset <key>`	移除键
`reset`	重置为默认值
`edit`	在 `$EDITOR` 中打开
`profile [preset]`	通过交互或预设配置工作流配置文件

示例：

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

# 设置机器级默认存储（在没有 --store、本地根目录或项目存储时，指针解析的回退根目录）
openspec config set defaultStore team-plans

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

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

# 使用基于操作的向导配置配置文件
openspec config profile

# 快速预设：将工作流切换为核心（保持交付模式）
openspec config profile core

遥测退出（Telemetry opt-out）： 当未设置时，telemetry.enabled 默认为开启（选择退出模式）。将其设置为 false 以禁用匿名使用统计和 openspec update 版本检查。环境变量优先于配置：OPENSPEC_TELEMETRY=0、DO_NOT_TRACK=1 以及 truthy 的 CI 值（例如 true/1/yes）始终禁用遥测，无论配置值如何。

openspec config profile 以当前状态摘要开始，然后让你选择：

更改交付和工作流
仅更改交付
仅更改工作流
保持当前设置（退出）

如果保持当前设置，不会写入更改，也不会显示更新提示。如果没有配置更改，但当前项目文件与你的全局配置文件/交付不同步，OpenSpec 将显示警告并建议运行 openspec update。按 Ctrl+C 也会干净地取消该流程（无堆栈跟踪）并以代码 130 退出。在工作流清单中，[x] 表示该工作流已在全局配置中选择。要将这些选择应用于项目文件，请运行 openspec update（或在项目中提示时选择 Apply changes to this project now?）。

交互示例：

bash

# 仅交付更新
openspec config profile
# 选择：仅更改交付
# 选择交付：仅技能

# 仅工作流更新
openspec config profile
# 选择：仅更改工作流
# 在清单中切换工作流，然后确认

实用命令

`openspec feedback`

提交关于 OpenSpec 的反馈。创建一个 GitHub issue。

openspec feedback <message> [options]

参数：

参数	必填	描述
`message`	是	反馈摘要；长文本在 issue 标题中缩短，并在正文中保留

选项：

选项	描述
`--body <text>`	包含在摘要之后的其他详细信息

要求： 必须安装并认证 GitHub CLI（gh）。

示例：

bash

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`

管理 OpenSpec CLI 的 shell 补全。

openspec completion <subcommand> [shell]

子命令：

子命令	描述
`generate [shell]`	将补全脚本输出到 stdout
`install [shell]`	为你的 shell 安装补全
`uninstall [shell]`	移除已安装的补全

支持的 shell： bash、zsh、fish、powershell

示例：

bash

# 安装补全（自动检测 shell）
openspec completion install

# 为特定 shell 安装
openspec completion install zsh

# 为手动安装生成脚本（bash）
openspec completion generate bash > ~/.bash_completion.d/openspec

# 卸载
openspec completion uninstall

Windows（PowerShell）： 为当前 PowerShell 主机安装补全：

powershell

$env:PROFILE = $PROFILE
openspec completion install powershell
. $PROFILE

$env:PROFILE 告诉 OpenSpec 在当前会话中配置哪个配置文件。安装程序会创建缺失的配置文件目录，并添加一个加载 OpenSpecCompletion.ps1 的管理块。重新加载配置文件可立即启用补全。

要从当前主机卸载，请运行：

powershell

$env:PROFILE = $PROFILE
openspec completion uninstall powershell

卸载后重启 PowerShell，以清除当前会话中的补全。

补全是选择加入的。CLI 在交互式终端中首次运行命令时，会在 stderr 上提示一次，以后不再提示——如果你已经安装了补全，它也会保持安静。设置 OPENSPEC_NO_COMPLETIONS=1 可完全抑制该提示。

退出代码

代码	含义
`0`	成功
`1`	错误（验证失败、缺少文件等）

环境变量

变量	描述
`OPENSPEC_TELEMETRY`	设置为 `0` 以禁用遥测和 `openspec update` 版本检查（覆盖全局配置中的 `telemetry.enabled`）
`DO_NOT_TRACK`	设置为 `1` 以禁用遥测和 `openspec update` 版本检查（标准 DNT 信号；覆盖配置）
`OPENSPEC_CONCURRENCY`	批量验证的默认并发数（默认：6）
`EDITOR` 或 `VISUAL`	用于 `openspec config edit` 的编辑器
`NO_COLOR`	设置时禁用彩色输出
`OPENSPEC_NO_ANIMATION`	设置时禁用 `openspec init` 欢迎动画
`OPENSPEC_NO_COMPLETIONS`	设置为 `1` 以抑制关于 shell 补全的一次性提示
`OPENSPEC_NO_UPDATE_CHECK`	设置时禁用检查是否有更新的已发布 CLI（任何值，包括空值）。当设置 `CI` 时（除非为 `false`/`0`/`no`/`off`）或 `NODE_ENV=test` 时也会跳过
`npm_config_registry`	`openspec update` 版本检查所询问的注册表。必须是 `http(s)` URL，否则回退到 `https://registry.npmjs.org`。不读取 `.npmrc` 文件

CLI 参考 ​

摘要 ​

人类与 Agent 命令 ​

仅限人类使用的命令 ​

兼容 Agent 的命令 ​

全局选项 ​

设置命令 ​

openspec init ​

openspec update ​

Stores（独立的 OpenSpec 仓库） ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

从项目引用 store ​

记录 store 的克隆来源 ​

声明默认 store ​

医生（关系健康） ​

工作上下文（组装后的集合） ​

个人工作集 ​

浏览命令 ​

openspec list ​

openspec view ​

openspec show ​

验证命令 ​

openspec validate ​

生命周期命令 ​

openspec archive ​

工作流命令 ​

openspec new change ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

Schema 命令 ​

openspec schema init ​

openspec schema fork ​

openspec schema validate ​

openspec schema which ​

配置命令 ​

openspec config ​

实用命令 ​

openspec feedback ​

openspec completion ​

退出代码 ​

环境变量 ​

相关文档 ​

CLI 参考

摘要

人类与 Agent 命令

仅限人类使用的命令

兼容 Agent 的命令

全局选项

设置命令

`openspec init`

`openspec update`

Stores（独立的 OpenSpec 仓库）

`openspec store setup`

`openspec store register`

`openspec store unregister`

`openspec store remove`

`openspec store list`

`openspec store doctor`

从项目引用 store

记录 store 的克隆来源

声明默认 store

医生（关系健康）

工作上下文（组装后的集合）

个人工作集

浏览命令

`openspec list`

`openspec view`

`openspec show`

验证命令

`openspec validate`

生命周期命令

`openspec archive`

工作流命令

`openspec new change`

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

Schema 命令

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

配置命令

`openspec config`

实用命令

`openspec feedback`

`openspec completion`

退出代码

环境变量

相关文档