CLI

openspec 终端命令。

命令

设置

命令	说明
`openspec init`	在项目中初始化 OpenSpec。
`openspec update`	更新 OpenSpec 已安装的指令文件。
`openspec config`	查看和修改全局配置。

变更与规范

命令	说明
`openspec list`	列出变更，使用 `--specs` 时列出规范。
`openspec show`	以 markdown 或 JSON 格式打印变更或规范。
`openspec view`	规范和变更的单屏仪表板。
`openspec validate`	检查变更和规范是否存在结构问题。
`openspec archive`	将已完成的变更移入归档，并更新主规范。

工作流与模式

你的智能体会在工作流过程中运行其中大部分命令。

命令	说明
`openspec new`	创建新的变更目录。
`openspec status`	单个或所有活跃变更的工件完成状态。
`openspec instructions`	用于创建工件、应用或归档的指令。
`openspec templates`	某模式下各工件的已解析模板路径。
`openspec schemas`	列出可用的工作流模式。
`openspec schema`	查看、派生或创建模式（实验性功能）。

多仓库（beta）

命令	说明
`openspec store`	创建和管理存储库（store）：注册在你机器上的独立 OpenSpec 仓库。
`openspec doctor`	报告已解析 OpenSpec 根目录的关系健康状况。
`openspec context`	打印已解析 OpenSpec 根目录的工作上下文。
`openspec workset`	组合、保存并打开个人工作视图。

实用工具

命令	说明
`openspec version`	显示已安装的版本，并可选择检查更新。
`openspec install`	安装独立的 `openspec`，无需 Node.js 即可运行。
`openspec feedback`	提交关于 OpenSpec 的反馈。
`openspec completion`	安装或生成 shell 自动补全。

已弃用

命令	说明
`openspec change`	面向变更的 show、list 和 validate 的名词形式。CLI 会发出警告，并提示使用动词优先的命令。
`openspec spec`	面向规范的 show、list 和 validate 的名词形式，并带有相同的警告。

每个命令都支持 -h, --help。单独运行 openspec 命令时还支持：

-V, --version：打印 CLI 版本。
--no-color：禁用彩色输出。

openspec init

在项目中初始化 OpenSpec。

bash

openspec init                        # 当前目录，交互式工具选择器
openspec init --tools claude,cursor  # 设置特定工具，不提示
openspec init --tools none           # 仅 openspec/ 结构，不生成工具文件

未指定 --tools 时，init 会在交互式终端中提示你选择工具。在非交互环境中，它会配置在项目中检测到的工具。如果未检测到任何工具，则以 1 退出并列出有效 id。

仅存储仓库

当 openspec/config.yaml 包含 store: 行，且仓库中没有本地 specs 或 changes 时，请从仓库根目录运行 init：

bash

# 在代码仓库中安装 Claude Code 集成文件
openspec init --tools claude

集成文件：写入代码仓库。
openspec/config.yaml：逐字节保留。
openspec/specs/ 和 openspec/changes/：不会在代码仓库中创建。

从子目录运行 init 会以 1 退出，并提示你从仓库根目录运行。--language 也会以 1 退出，因为语言设置应放在外部存储的配置中。请在存储根目录运行 init，或直接编辑该配置。

参数

参数	说明
`path`	要初始化的项目目录。默认：当前目录。不存在时创建。

选项

标志	作用
`--tools <tools>`	以逗号分隔的工具 id、`all` 或 `none`。跳过选择器。id 列于支持的工具。
`--language <language>`	向新的项目配置添加语言指令。当仓库的 `store:` 行指向外部存储时会被拒绝。
`--force`	无需询问即移除旧版 OpenSpec 布局中的文件。否则交互式运行会先确认清理。
`--profile <profile>`	本次运行覆盖全局配置方案：`core`（标准工作流集）或 `custom`（全局配置中保存的工作流）。
`--no-animation`	显示静态欢迎界面，而非动画界面。

输出

每个选中的工具都会在其自己的目录中获得 OpenSpec 的技能和命令：

▌ OpenSpec structure created
✔ Setup complete for Claude Code

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Restart your IDE for the new commands to take effect.

--tools none 只会创建 openspec/config.yaml。在已初始化的项目上，init 会就地重写已安装的文件，摘要显示 Refreshed: Claude Code 和 Config: openspec/config.yaml (exists)。

退出码

0：设置完成。
1：--tools 或 --profile 值无效；非交互运行且未检测到工具且未指定 --tools；或仅存储仓库调用无效。

openspec update

更新 OpenSpec 已安装的指令文件。

bash

openspec update             # 刷新文件早于 CLI 的工具
openspec update --force     # 即使文件已是最新也重写
openspec update --dry-run   # 列出更新会更改的内容，且不做任何更改

update 会找出 init 配置过的工具，并将其生成的文件与 CLI 版本进行比较。当存在更新版本的 OpenSpec 时，它会先提示升级 CLI，然后用升级后的版本重新运行。设置 OPENSPEC_NO_UPDATE_CHECK=1 可跳过检查。

参数

参数	说明
`path`	要更新的项目目录。默认：当前目录。

选项

标志	作用
`--force`	即使已是最新，也重写每个已配置工具的文件。
`--dry-run`	报告更新会新增、更改或删除的每个文件，但不写入任何内容。不检查 CLI 升级，也不出现提示。与 `--force` 结合可预览强制执行更新。
`--json`	与 `--dry-run` 一起使用时，以 JSON 打印计划。不带 `--dry-run` 时以 1 退出。

预览更新

--dry-run 会规划非交互运行将执行的更新：走同一代码路径，但记录而非执行每次写入和删除。真实更新会涉及的每个文件都会被列出，包括：

将 OpenSpec 文件从工具以前的目录移出（.kimi/ 到 .kimi-code/，.windsurf/ 到 .devin/，.codex/ 和 .agent/ 到 .agents/）；
当早于 profile 机制的安装获得全局配置时，保存全局配置；
同步 GitHub Copilot 云代理文件；
使用 --force 时，配置仅在遗留产物中发现的工具并清理这些产物，包括已弃用的全局 Codex 提示。

bash

openspec update --dry-run

2 file(s) would change:
  update  .claude/skills/openspec-propose/SKILL.md  (claude)
  add     ~/.config/openspec/config.json  (openspec)

--dry-run --json 会将同一计划打印为一个 JSON 文档：

json

{
  "changes": [
    { "path": ".claude/skills/openspec-propose/SKILL.md", "action": "update", "tool": "claude" },
    { "path": "~/.config/openspec/config.json", "action": "add", "tool": "openspec" }
  ],
  "notes": [],
  "failures": []
}

字段	内容
`changes[].path`	相对于项目的路径。项目之外的文件（例如全局技能或全局配置）会以相对于主目录的 `~/...` 显示；如果也在主目录之外，则显示为绝对路径。
`changes[].action`	`add`、`update` 或 `delete`。新字节与旧内容相同的文件不会列出。
`changes[].tool`	文件所属的已配置工具，例如 `claude`。属于 OpenSpec 本身而非某个工具的文件（全局配置和遗留产物清理）为 `openspec`。
`notes[]`	`{ code, message }`，表示终端用户会被询问的步骤。`legacy-tool-directories`：交互式运行会先询问的移动操作；`changes` 会将其列为已执行。`legacy-artifacts`：发现了来自 OpenSpec 旧布局的文件，例如 `openspec-proposal.md` 斜杠命令或 `AGENTS.md` 中的 OpenSpec 标记块。不带 `--force` 时，非交互式更新会保留它们，因此 `changes` 也会如此；`--dry-run --force` 会列出对这些文件的清理。普通刷新时为空。
`failures[]`	`{ tool, error }`，表示真实更新会失败的每个工具，包括无法执行的写入：文件应在的位置是目录、目录应在的位置是文件，或文件/文件夹没有写入权限。对于该工具，`changes` 会在真实更新停止的位置停止；其他工具仍会继续规划。磁盘只在写入时才报告的错误（例如空间不足）无法预知。

规划之前的失败（例如没有 OpenSpec 目录）仍会只打印一个 JSON 文档：空计划加上一个 status 数组，包含 severity、code（update_error）和 message。退出码为 1。

输出

当每个工具的文件都与 CLI 版本匹配时：

✓ All 1 tool(s) up to date (v1.7.0)
  Tools: claude

Use --force to refresh files anyway.

当某个工具的文件来自旧版 CLI 时（或者使用 --force 时，此时会改为打印 Force updating 1 tool(s): claude）：

Updating 1 tool(s): claude (1.6.0 → 1.7.0)

✔ Updated Claude Code

✓ Updated: Claude Code (v1.7.0)
Tools: Claude Code

Restart your IDE for changes to take effect.

在没有 OpenSpec 的目录中，update 会拒绝执行：

✖ Error: No OpenSpec directory found. Run 'openspec init' first.

退出码

0：文件已更新，或所有内容都已是最新。
1：路径下没有 OpenSpec 目录，或更新失败。

openspec config

查看和更改全局配置。

bash

openspec config list                  # 查看当前设置
openspec config set delivery skills   # 更改一个值
openspec config profile               # 交互式工作流选择器

子命令	作用
`path`	打印配置文件位置。
`list`	显示所有当前设置。
`get <key>`	打印单个值，原始格式，便于脚本处理。
`set <key> <value>`	设置值，并进行类型转换。
`unset <key>`	移除键，使其默认值生效。
`reset`	将所有配置重置为默认值。
`edit`	在 `$EDITOR` 中打开配置文件。
`profile [preset]`	配置交付模式和工作流。

配置是机器级的全局配置，以 JSON 形式存储在 config path 指向的位置：如果设置了 $XDG_CONFIG_HOME，则为 $XDG_CONFIG_HOME/openspec/config.json，否则为 ~/.config/openspec/config.json（macOS、Linux）或 %APPDATA%\openspec\config.json（Windows）。每个子命令都接受 --scope <scope>，但目前只有 global 可用。其他任何 scope 都会以 1 退出，并显示 Error: Project-local config is not yet implemented。

openspec config path

bash

openspec config path

/Users/you/.config/openspec/config.json

openspec config list

bash

openspec config list          # 可读设置以及配置方案摘要
openspec config list --json   # 原始配置 JSON

选项

标志	作用
`--json`	以 JSON 打印配置对象。

输出

先显示每项设置，然后显示配置方案摘要，并标记值是显式设置还是默认值：

featureFlags: {}
profile: core
delivery: both

Profile settings:
  profile: core (default)
  delivery: both (default)
  workflows: propose, explore, apply, update, sync, archive (from core profile)

openspec config get

bash

openspec config get delivery

参数

参数	说明
`key`	要读取的键。点号可访问嵌套值（`featureFlags.workspaces`）。

输出

裸值，可直接用于脚本。对象会以紧凑 JSON 打印：

both

退出码

0：已打印值。
1：键没有值，且不打印任何内容。

openspec config set

bash

openspec config set delivery skills
openspec config set featureFlags.workspaces true

参数

参数	说明
`key`	要写入的键，嵌套值使用点号。
`value`	新值。`true`/`false` 会转换为布尔值，数字字符串会转换为数字。

选项

标志	作用
`--string`	将值作为字符串存储，跳过类型转换。
`--allow-unknown`	允许 schema 不认识的键。

输出

Set featureFlags.workspaces = true

未知键和无效值会在保存任何内容之前以 1 失败：

Error: Invalid configuration key "bogus.key". Unknown top-level key "bogus".
Use "openspec config list" to see available keys.
Pass --allow-unknown to bypass this check.

Error: Invalid configuration - delivery: Invalid option: expected one of "both"|"skills"|"commands"

如果配置文件存在但其内容不是 JSON 对象——无论是因为它根本不是有效 JSON，还是因为其根节点是 null 或数组等其他内容——config set、config unset 和 config profile 都会以 1 退出，并保持文件不变。可用 openspec config edit 修复，或用 openspec config reset --all 替换它：

Error: /home/you/.config/openspec/config.json could not be parsed, so it was left unchanged.
Fix it with "openspec config edit", or reset it with "openspec config reset --all".

在修复之前，遥测和更新检查会保持关闭。

openspec config unset

bash

openspec config unset delivery

移除该键，使默认值重新生效。带内置默认值的键始终视为已设置，因此即使你从未设置过它们，这里也会报告成功：

Unset delivery (reverted to default)

完全没有值的键会打印 Key "featureFlags.nothere" was not set。这两种情况都以 0 退出。无法解析的配置文件则会以 1 退出，与 config set 相同。

openspec config reset

bash

openspec config reset --all      # 请求确认
openspec config reset --all -y   # 不提示

选项

标志	作用
`--all`	必需。重置所有内容。
`-y, --yes`	跳过确认提示。

输出

Configuration reset to defaults

不带 --all 时，它会以 1 退出并打印用法行。

退出码

0：重置完成，或你在提示处回答否。
1：缺少 --all。
130：提示被 Ctrl-C 取消。

openspec config edit

bash

openspec config edit

在 $EDITOR 中打开配置文件（回退到 $VISUAL），如果文件不存在则先用默认值创建。编辑器关闭后会校验文件。无效 JSON 或无效配置会以 1 退出。

编辑器取值可以携带参数和带引号的路径，例如 code --wait 或 "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w。它会在不经过 shell 的情况下拆分为单词，因此 $VAR、~ 和 ; 会按字面传递。无法启动或退出码非零的编辑器会打印一行错误并以 1 退出。

未配置编辑器时，它会以 1 退出：

Error: No editor configured
Set the EDITOR or VISUAL environment variable to your preferred editor
Example: export EDITOR=vim

openspec config profile

bash

openspec config profile        # 交互式选择器（需要终端）
openspec config profile core   # 直接应用 core 预设

参数

参数	说明
`preset`	可选的预设名称。仅存在 `core`。它会选择核心工作流，并保留你的交付设置。

不带预设时，交互式选择器会显示你当前的交付模式和工作流，允许你更改其中一项或两项（交付模式：both、仅 skills 或仅 commands；工作流：复选框列表），打印差异，并在 OpenSpec 项目内提供为你运行 openspec update 的选项。在非终端环境中会以 1 退出：

Interactive mode required. Use `openspec config profile core` or set config via environment/flags.

输出

更改后的配置只有在项目执行更新后才会生效：

Config updated. Run `openspec update` in your projects to apply.

退出码

0：配置方案已保存，或你保留了当前设置。
1：未知预设、没有终端，或所提供的 openspec update 失败。
130：选择器被 Ctrl-C 取消。

openspec list

列出变更，或使用 --specs 列出规格。

bash

openspec list                    # 活动变更，最近修改的在前
openspec list --archived         # 已归档变更
openspec list --all              # 活动及已归档变更
openspec list --specs            # 带需求计数的规格
openspec list --json             # 机器可读，包含解析后的根目录

行数据来自解析后的根目录下的 openspec/changes/ 和 openspec/specs/。默认的变更列表会跳过 openspec/changes/archive/。

选项

标志	效果
`--specs`	列出规格而不是变更。
`--changes`	列出变更。这是默认值。
`--archived`	仅列出已归档的变更。不能与 `--specs` 组合。
`--all`	列出活动和已归档的变更。不能与 `--specs` 组合。优先于 `--archived`。
`--sort <order>`	`recent`（最近修改优先）或 `name`。默认：`recent`。规格始终按名称排序。
`--json`	打印 JSON 而不是表格。
`--store <id>`	使用已注册的存储作为 OpenSpec 根目录，而不是当前项目。

输出

每个变更一行：名称、任务状态、最后修改时间。状态列显示 No tasks、2/5 tasks 或 ✓ Complete。

Changes:
  add-rate-limit     No tasks      just now

--all 将活动和已归档的变更分组到不同的标题下。每个组使用选定的排序顺序：

Changes:
  add-rate-limit     No tasks      just now

Archived Changes:
  2026-08-10-add-login     ✓ Complete    2d ago

Specs:
  api     requirements 1

--json 添加任务计数和 status 字段，值为 no-tasks、in-progress 或 complete：

json

{
  "changes": [
    {
      "name": "add-rate-limit",
      "completedTasks": 0,
      "totalTasks": 0,
      "lastModified": "2026-08-11T13:44:40.171Z",
      "status": "no-tasks"
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

使用 --archived 或 --all 时，每个变更对象都包含一个 archived 布尔值。合并后的数组使用选定的排序顺序。当已归档变更的跟踪任务文件中有未勾选的任务时，它仍然可以具有 in-progress 状态。不使用任一标志时，JSON 结构保持不变。

空列表会打印 No active changes found.、No archived changes found.、No changes found. 或 No specs found.，并且仍然以 0 退出。

变更是指 openspec/changes/ 下的直接子目录。与规格不同，变更不能嵌套在命名空间文件夹中。像 changes/mobile/ 这样仅包装一个变更（changes/mobile/refresh-token/）的文件夹会以状态 not a change 列出，并附带一个警告，指出嵌套的目录。--json 会用 nested 数组标记该条目，并添加一个顶层 warnings 数组。show、status、validate 和 archive 会以相同的消息拒绝该文件夹。要修复它，请将变更上移，并将命名空间折叠到其名称中：

bash

mv openspec/changes/mobile/refresh-token openspec/changes/mobile-refresh-token
rmdir openspec/changes/mobile

退出码

0：列表已打印，即使为空。
1：未找到 OpenSpec 根目录（在项目外部，且未使用 --store）。

openspec show

打印变更或规格，以 markdown 或 JSON 格式。

bash

openspec show add-rate-limit              # 变更：打印 proposal.md
openspec show add-rate-limit --diff       # 变更：追加需求差异
openspec show api                         # 规格：打印 spec.md
openspec show api --json --no-scenarios   # 规格 JSON，不含场景文本

未提供名称时，show 会询问是变更还是规格，然后列出可选项。在非交互式终端中，它会以 1 退出并打印直接形式。

参数

参数	说明
`item-name`	要显示的变更或规格，按文件夹名称（`add-rate-limit`、`api`）。

选项

标志	效果
`--json`	打印结构化 JSON 而不是原始 markdown。
`--type <change\|spec>`	当变更和规格同名时选择类型。
`--no-interactive`	从不提示：缺少名称则报错。
`--deltas-only`	JSON，变更：将输出限制为增量。变更 JSON 已经是仅增量，因此输出与普通 `--json` 相同。
`--requirements-only`	`--deltas-only` 的已弃用别名。在 stderr 上发出警告。
`--diff`	变更：追加每个需求的增量差异。对于规格会忽略并发出警告。
`--requirements`	JSON，规格：保留需求文本，清空 `scenarios` 数组。
`--no-scenarios`	JSON，规格：与 `--requirements` 相同的输出。
`-r, --requirement <id>`	JSON，规格：按从 1 开始的位置输出一个需求。不能与 `--requirements` 组合。
`--store <id>`	使用已注册的存储作为 OpenSpec 根目录，而不是当前项目。

不适用于解析类型的标志会被忽略，并在 stderr 上发出警告。

输出

文本模式是原始直通：变更打印其 proposal.md，规格打印其 spec.md。

# Add rate limiting

为什么

未经身份验证的客户端可能会耗尽 API。

变更内容

为公共 API 添加按客户端速率限制。


对于变更，`--diff` 会先打印提案，然后打印 `Specifications Changed (diffs)` 部分。ADDED 需求会包含其完整文本。REMOVED 需求会保留编写时填写的 Reason 和 Migration。RENAMED 需求会显示 FROM 和 TO。MODIFIED 需求会显示与匹配的主需求之间的统一 diff。

如果 MODIFIED 标题仅在忽略大小写或空白差异后才匹配，输出会同时包含 diff 和一条警告，说明归档匹配是精确匹配。如果主规范或需求缺失，输出会发出警告并打印完整的增量块。没有文本差异的 MODIFIED 块会打印 `(no textual changes)`。

使用 `--json` 的变更呈现为增量结构：

```json
{
  "id": "add-rate-limit",
  "title": "Add rate limiting",
  "deltaCount": 1,
  "deltas": [
    {
      "spec": "api",
      "operation": "ADDED",
      "description": "Add requirement: The API SHALL limit each client to 100 requests per minute.",
      "requirement": {
        "name": "Rate limit",
        "text": "The API SHALL limit each client to 100 requests per minute.",
        "scenarios": [
          {
            "name": "Client exceeds the limit",
            "rawText": "- **WHEN** a client sends its 101st request within a minute\n- **THEN** the API responds 429"
          }
        ]
      },
      ...
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

每项需求都带有其 name，即 Requirement: 之后的标题文本。归档会使用该名称来匹配 MODIFIED、REMOVED 和 RENAMED 条目。每个场景都带有其 name，即 Scenario: 之后的标题文本。任一标题末尾连续出现的 # 不属于名称的一部分。

--json --diff 保持此顶层结构。MODIFIED 增量会获得 diff 字符串、warning 字符串，或两者兼有。其他操作保持不变。空的 diff 字符串表示主块和增量块在文本上完全相同。

使用 --json 的规范会列出其需求及场景。需求和场景带有与变更 JSON 相同的 name 字段：

json

{
  "id": "api",
  "title": "api",
  "overview": "Public HTTP API behavior.",
  "requirementCount": 1,
  "requirements": [
    {
      "name": "Health endpoint",
      "text": "The API SHALL expose a health endpoint.",
      "scenarios": [
        {
          "name": "Health check succeeds",
          "rawText": "- **WHEN** a client requests GET /health\n- **THEN** the API responds 200"
        }
      ]
    }
  ],
  "metadata": {
    "version": "1.0.0",
    "format": "openspec"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

未知名称会提示相近匹配：Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?。同时匹配变更和规范的名称会报错并要求使用 --type。

退出码

0：已打印条目。
1：名称未知或有歧义、在终端外未提供名称、-r 索引越界、--requirements 与 -r 组合使用，或无法为 --diff 读取增量或主规范。

openspec view

打印规范与变更的单屏仪表板。

bash

openspec view   # project summary in one screen

view 会打印一次仪表板然后退出。它不读取任何按键。变更按任务进度分组：Draft（尚无任务）、Active（任务进行中，带进度条和百分比）、Completed（所有任务均已勾选）。规范列表会显示需求数量，并按数量从大到小排列。

选项

标志	效果
`--store <id>`	使用已注册存储作为 OpenSpec 根目录，而不是当前项目。

输出

OpenSpec Dashboard

════════════════════════════════════════════════════════════
Summary:
  ● Specifications: 1 specs, 1 requirements
  ● Draft Changes: 1
  ● Active Changes: 0 in progress
  ● Completed Changes: 0

Draft Changes
────────────────────────────────────────────────────────────
  ○ add-rate-limit

Specifications
────────────────────────────────────────────────────────────
  ▪ api                            1 requirement

════════════════════════════════════════════════════════════

Use openspec list --changes or openspec list --specs for detailed views

当任一变更存在进行中的任务时，会出现一行 Task Progress 摘要。

每个活动变更还会在其任务进度条下方显示其 schema 和制品状态：

text

    └─ [spec-driven] proposal✓ specs→ design→ tasks✓

标记	制品状态
`✓`	其输出已存在。现有 tasks 制品即使检查清单未完成，也算已完成。
`→`	已准备好创建。
无标记	由于缺少依赖项而被阻塞。
`(skipped)`	变更跳过它。

如果无法加载工作流，view 会打印警告，并保持该变更的任务进度可见。运行 openspec status --change <name> 可单独检查工作流。执行 openspec view --store <id> 后，请将相同的 --store <id> 传给 status。

退出码

0：已打印仪表板。
1：未找到 OpenSpec 根目录（在项目外，且未提供 --store）。

openspec validate

检查变更和规范的结构问题。

bash

openspec validate add-rate-limit   # one change or spec, by name
openspec validate --all            # every change and spec

未提供名称且未使用批量标志时，validate 会提示你选择条目。在非交互式终端中，它会以退出码 1 退出，并改为打印批量标志。

参数

参数	说明
`item-name`	要验证的变更或规范，按文件夹名称指定（`add-rate-limit`、`api`）。

选项

标志	效果
`--all`	验证每个变更和规范。
`--changes`	验证每个变更。
`--specs`	验证每个规范。
`--archived`	检查已归档变更中的任务完成情况，但不验证其已应用的规范增量。
`--strict`	将警告视为失败。
`--type <change\|spec>`	当变更和规范同名时选择类型。
`--json`	打印结构化报告，而不是文本。
`--report <mode>`	批量输出：`full`（默认）或 `findings`。需要显式的批量范围。
`--concurrency <n>`	批量运行中的最大并行验证数。默认值：`OPENSPEC_CONCURRENCY`，否则为 6。
`--no-interactive`	从不提示：名称缺失或有歧义会变为错误。
`--store <id>`	使用已注册存储作为 OpenSpec 根目录，而不是当前项目。

输出

批量运行会为每个条目打印一行状态，随后打印所有发现项，最后打印总计：

✓ change/add-rate-limit
✓ spec/api
Totals: 2 passed, 0 failed (2 items)

任务复选框发现项

进度只统计复选框，不统计其他内容，因此以纯项目符号编写的任务文件会被视为零个任务：openspec list 和 openspec status 会报告无工作，openspec archive 也没有可标记为未完成的内容。validate 会在每个列出工作但没有复选框的被跟踪任务文件上报告 WARNING：

text

⚠ [WARNING] tasks.md: This change counts as 0 tasks: no line in its tracked task files is a checkbox, so "openspec list" and "openspec status" report no work and "openspec archive" has nothing to flag as incomplete. Write each task as "- [ ] 1.1 Description".

仅当变更的整个被跟踪集合中完全没有复选框时，才会触发该警告。真正的检查清单旁边有一个纯文本文件不会被报告，而正在编写中的变更只要存在一个复选框，就会保留其进度。--strict 会将警告变为失败。行号位于 --json 报告中。

围栏代码块、HTML 注释、YAML 前置元数据和缩进代码不会被扫描，因此粘贴的终端示例绝不会被误认为任务列表。

归档合并发现项

对于变更，validate 会针对当前主规范运行 archive 的合并构建器，但不写入文件。它会将合并冲突报告为 INFO，例如缺少 MODIFIED 目标或存在冲突的 ADDED 需求：

text

ℹ [INFO] api/spec.md: Archive would refuse this delta: api MODIFIED failed for header "### Requirement: Rate limiting" - not found

即使验证通过，这些发现项也会出现在文本和 JSON 输出中。INFO 永远不会改变退出码，包括在 --strict 下也是如此：缺失的目标可能属于尚未归档的同级变更。已同步到主规范中的增量遵循 archive 现有的合并规则。

此检查不会运行 archive 后续的合并规范验证或退役检查。一份干净的报告并不保证 archive 会成功。

如果合并预检无法启动，会有一个 INFO 发现项说明原因。现有验证发现项和退出码保持不变。

失败条目会列出每个问题和修复方法：

Change 'add-rate-limit' has issues
✗ [ERROR] api/spec.md: ADDED "Rate limiting" must include at least one scenario
Next steps:
  - Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements
  - Each requirement MUST include at least one #### Scenario: block
  - Debug parsed deltas: openspec show add-rate-limit --json --deltas-only

--json 会为本次运行打印一份报告：

json

{
  "items": [
    {
      "id": "add-rate-limit",
      "type": "change",
      "valid": true,
      "issues": [],
      "durationMs": 2
    }
  ],
  "summary": {
    "totals": {
      "items": 1,
      "passed": 1,
      "failed": 0
    },
    "byType": {
      "change": {
        "items": 1,
        "passed": 1,
        "failed": 0
      }
    }
  },
  "version": "1.0",
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

issues 条目带有一个 level，取值为 ERROR、WARNING 或 INFO。

退出码

0：每个已验证条目均通过，包括空的批量范围。
1：某个条目失败、报告请求无效、openspec/config.yaml 无法读取或不是有效的 YAML，或运行失败（例如名称未知或没有 OpenSpec 根目录）。无法读取或解析的配置会在检查任何条目之前停止运行；使用 --json 时，它会作为单个 status 条目报告，代码为 unreadable_config 或 unparseable_config。

--report full|findings

为显式的批量验证范围选择输出：

full：每个条目。这是默认值。显式使用 --report full 会保留现有输出结构，不添加报告元数据。
findings：仅包含有问题的条目，包括带有警告或信息的通过条目。每个条目仍会被验证。总计、严格模式行为和退出码保持不变。

bash

openspec validate --all --report findings
openspec validate --archived --report findings --json

范围

标志	findings `report.scope`
`--all`	`all`
`--changes`	`changes`
`--specs`	`specs`
`--changes --specs`，或搭配任一标志的 `--all`	`all`
`--archived`	`archived`

两种显式报告模式都会拒绝位置参数形式的条目名称、缺少批量范围，或将归档范围与活动范围组合使用。

findings 文本输出

人类可读输出：stdout 打印 Scope: <scope> (<count> items)，然后打印总计。当没有带问题的条目时：

text

Scope: all (2 items)
No item findings.
Totals: 2 passed, 0 failed (2 items)

带问题的条目标签、严重性标签、路径和消息会打印到 stderr。活动范围的失败会在总计后保留 Details: 重跑提示。现有的根横幅和进度输出可能会出现在报告之前。

findings JSON 输出

--report findings --json 打印一份文档。此示例有两个无问题条目：

json

{
  "report": {
    "kind": "validation-findings",
    "version": "1.0",
    "scope": "all",
    "returnedItems": 0,
    "totalItems": 2
  },
  "itemFindings": [],
  "summary": {
    "totals": { "items": 2, "passed": 2, "failed": 0 },
    "byType": {
      "change": { "items": 1, "passed": 1, "failed": 0 },
      "spec": { "items": 1, "passed": 1, "failed": 0 }
    }
  },
  "root": { "path": "/Users/you/projects/my-app", "source": "nearest" }
}

report.kind 和 report.version：标识 validation-findings 结构，版本为 1.0。没有顶层 version 或 items。
report.returnedItems 和 report.totalItems：分别统计返回的记录数和所有已验证条目数。
itemFindings：issues 数组非空的完整条目记录。包含 ERROR、WARNING 和 INFO 问题。每条记录保留 id、type、valid、issues 和 durationMs。归档条目使用 type: "change"。
summary：完整运行的总计和按类型统计的数量，而不是返回子集的数量。空范围的统计总数为零，退出码为 0。
root：与完整报告相同的所选根目录元数据。

记录保留：返回的条目保持完整报告中的顺序，以及条目或问题上的任何附加字段。过滤不会重写消息或位置，包括可选的 line 和 column 字段。

命令失败：根目录选择或条目发现失败会保留现有的 status 诊断，并以退出码 1 退出。它们不会返回已完成的 findings 报告，也不会返回成功的空报告。

无效的报告请求

两种显式报告模式都会在根目录选择或条目发现之前拒绝这些请求：

不支持的 report 值，包括空字符串。
位置参数形式的条目名称，即使带有批量标志。
没有显式的批量范围。
--archived 与 --all、--changes 或 --specs 组合使用。

在 JSON 模式下，被拒绝的请求会以退出码 1 退出，且仅包含单元素 status 数组。它没有 root 或报告负载：

bash

openspec validate --all --report bogus --json

json

{
  "status": [
    {
      "severity": "error",
      "code": "invalid_validation_report_request",
      "message": "Unknown validation report 'bogus'.",
      "fix": "Use --report full|findings with --all, --changes, --specs, or --archived, without an item name. Do not combine archived and active scopes."
    }
  ]
}

人类可读模式会将错误打印到 stderr。不带值的裸 --report 会在 stderr 上产生 Commander 语法错误，包括与 --json 一起使用时；它不使用此诊断封装。

在外部过滤完整报告

如需自定义 JSON 视图，可使用 jq 或 PowerShell 过滤完整报告。这些脚本示例会保留验证退出码，并保持命令错误文档不变。

在 Bash 中使用 jq：

bash

if validation_json=$(openspec validate --all --json); then
  validation_exit=0
else
  validation_exit=$?
fi
printf '%s\n' "$validation_json" |
  jq 'if has("items") then .items |= map(select(.issues | length > 0)) else . end'
exit "$validation_exit"

在 PowerShell 中：

powershell

$validationJson = openspec validate --all --json
$validationExit = $LASTEXITCODE
$validationReport = $validationJson | ConvertFrom-Json
if ($validationReport.PSObject.Properties.Name -contains 'items') {
  $validationReport.items = @($validationReport.items | Where-Object { $_.issues.Count -gt 0 })
}
$validationReport | ConvertTo-Json -Depth 100
exit $validationExit

这些自定义视图保留完整报告的键，但省略无问题条目。它们既不是完整的 full-v1 报告，也不是带版本的 --report findings 结构。

openspec archive

将已完成的变更移至归档并更新主规格。

bash

openspec archive add-rate-limit -y                # archive one change, merge its deltas
openspec archive add-rate-limit -y --skip-specs   # archive without touching the specs

未提供名称时，archive 会提示你选择一个变更。在非交互式终端中，它以退出码 1 退出，并打印重新运行的命令。

参数

参数	说明
`change-name`	要归档的变更，按文件夹名称（`add-rate-limit`）指定。

选项

标志	效果
`-y, --yes`	对所有确认一律回答“是”：规格更新、未完成的任务、跳过验证。
`--skip-specs`	归档时不改动主规格（适用于基础设施、工具或仅文档的变更）。
`--no-validate`	跳过验证。archive 会先要求你确认，而 `-y` 会代为确认。
`--json`	以结构化结果而非文本形式输出。需要 `--yes` 才能确认规格更新。
`--store <id>`	使用已注册的存储作为 OpenSpec 根目录，而非当前项目。

输出

成功运行时会报告任务状态、预览规格更新、应用更新，并给出归档文件夹的名称：

Task status: ✓ Complete

Specs to update:
  api: update
Applying changes to openspec/specs/api/spec.md:
  + 1 added
Totals: + 1, ~ 0, - 0, → 0
Specs updated successfully.
Change 'add-rate-limit' archived as '2026-08-11-add-rate-limit'.

变更文件夹整体移至 openspec/changes/archive/2026-08-11-add-rate-limit/，其名称前缀为当天日期。每个增量都会合并到其主规格中：上面新增（ADDED）的需求已追加到 openspec/specs/api/spec.md。不带 -y 时，archive 会显示预览并在更新前询问。拒绝后仍会归档该变更，但保持规格不变。

使用 --json --yes 时：

json

{
  "archive": {
    "change": "add-rate-limit",
    "archivedAs": "2026-08-11-add-rate-limit",
    "path": "/Users/you/projects/my-app/openspec/changes/archive/2026-08-11-add-rate-limit",
    "specsUpdated": true,
    "totals": {
      "added": 1,
      "modified": 0,
      "removed": 0,
      "renamed": 0
    }
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

archive 会先验证变更，并拒绝未通过验证的变更：

Validation errors in change delta specs:
  ✗ ADDED "Rate limiting" must include at least one scenario

Validation failed. Please fix the errors before archiving.
To skip validation (not recommended), use --no-validate flag.

未完成的任务只会发出警告，不会造成阻塞。在交互式环境中，archive 会询问是否继续，而 -y 会自动继续：

Task status: 1/2 tasks
Warning: 1 incomplete task(s) found. Continuing due to --yes flag.

退出码

0：变更已归档，无论是否更新了规格。
1：验证失败、变更名称未知，或需要确认但无法读取回答。

openspec new

创建新的变更目录。

bash

openspec new change add-caching                                # metadata only
openspec new change add-search --goal "Users can search docs"  # record a goal

new 有一个子命令 new change <name>。它会创建 openspec/changes/<name>/，其中包含一个 .openspec.yaml 元数据文件：

yaml

schema: spec-driven
created: 2026-08-11

产物（提案、规格、设计、任务）不会在此处生成脚手架。你稍后编写它们，openspec status 会告诉你下一个该写哪一个。

参数

参数	说明
`name`	变更的文件夹名称（`add-caching`）。

选项

标志	效果
`--description <text>`	同时在变更目录中使用该文本创建 `README.md`。
`--goal <text>`	在 `.openspec.yaml` 中存储一行 `goal:`。
`--schema <name>`	变更的工作流模式。默认值：`spec-driven`，即随附的唯一模式。
`--json`	以 JSON 而非文本形式输出已创建的变更。
`--store <id>`	使用已注册的存储作为 OpenSpec 根目录，而非当前项目。

输出

Created change 'add-caching' at openspec/changes/add-caching/
Schema: spec-driven
Next: openspec status --change add-caching

当未找到 openspec/ 目录时，new change 会在当前位置创建一个并提示：

Created change 'add-caching' at openspec/changes/add-caching/
Schema: spec-driven
Next: openspec status --change add-caching

Note: no OpenSpec root was found here, so one was created at openspec/.
Run `openspec init` to finish setting this project up, or delete that directory if you meant a different project.

该提示会与其他面向人的输出一起发送到 stdout，并且在使用 --json 时永不出现。

在已有 openspec/ 的项目中使用 --json 时：

json

{
  "change": {
    "id": "add-caching",
    "path": "/Users/you/projects/my-app/openspec/changes/add-caching",
    "metadataPath": "/Users/you/projects/my-app/openspec/changes/add-caching/.openspec.yaml",
    "schema": "spec-driven"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

当未找到 openspec/ 目录且 new change 创建了一个时，JSON 结构相同。root.path 是你运行该命令所在的目录，root.source 为 implicit：

json

"root": {
  "path": "/Users/you/projects/my-app",
  "source": "implicit"
}

退出码

0：变更已创建。
1：变更已存在，或模式未知。

openspec status

报告单个变更或所有活跃变更的工件（artifact）完成状态。

bash

openspec status --change add-rate-limit          # 清单视图
openspec status --change add-rate-limit --json   # 结构化报告
openspec status --all                            # 所有活跃变更
openspec status --all --json                     # 单个批量报告

当存在活跃变更时，必须且只能使用 --change 或 --all 中的一个。若两者均未指定，status 将以退出码 1 结束，并列出可用的变更，即使只存在一个变更：

text

✖ Error: Missing required option --change (or --all for every active change). Available changes:
  add-rate-limit

当项目没有活跃变更时，即使未指定任何标志，status 也会打印 No active changes. Create one with: openspec new change <name> 并以退出码 0 结束。使用 --all --json 时，同样的空状态显示为 { "changes": [], "message": "No active changes.", "root": ... }。

选项

标志	作用
`--change <id>`	要报告的变更，按文件夹名称指定。
`--all`	报告所有活跃变更，按名称排序。不能与 `--change` 组合使用。
`--schema <name>`	覆盖从 `openspec/config.yaml` 自动检测到的 schema。名称未知时将报错。
`--json`	输出结构化报告而非文本。
`--store <id>`	使用已注册的 store 作为 OpenSpec 根目录，而非当前项目。

输出

该 schema 各工件的清单：[x] 已完成，[ ] 可写入，[-] 被阻塞（在其依赖的工件存在之前无法开始）。

Change: add-rate-limit
Schema: spec-driven
Change root: /Users/you/projects/my-app/openspec/changes/add-rate-limit
Progress: 2/4 artifacts complete

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

Next: openspec instructions design --change "add-rate-limit" --json

Next: 行会指出推动变更继续前进的那一条命令，因此在全新的会话中，仅凭 openspec status 就足以接续对某个变更的工作。当规划尚未完成时，它会指出下一个可写入的工件；当所有规划工件都已存在时，它则指向 openspec instructions apply：

[x] proposal
[x] specs
[x] design
[x] tasks

All planning artifacts complete!
Next: openspec instructions apply --change "add-rate-limit" --json

只要解析出的根目录是 store，该命令就会携带 --store <id>，且所指命令与 JSON 中 nextSteps 语句一致。

--json 会额外输出每个工件的依赖关系、解析后的文件路径以及建议的下一步。以下为精简版：

json

{
  "changeName": "add-rate-limit",
  "schemaName": "spec-driven",
  "isComplete": false,
  "nextSteps": [
    "Run openspec instructions design --change \"add-rate-limit\" --json before writing that artifact."
  ],
  "artifacts": [
    {
      "id": "proposal",
      "outputPath": "proposal.md",
      "status": "done",
      "requires": []
    },
    {
      "id": "design",
      "outputPath": "design.md",
      "status": "ready",
      "requires": [
        "proposal"
      ]
    },
    {
      "id": "tasks",
      "outputPath": "tasks.md",
      "status": "blocked",
      "requires": [
        "specs",
        "design"
      ],
      "missingDeps": [
        "design"
      ]
    }
  ]
}

使用 --all --json 时，changes 为每个变更包含相同的状态对象，但不含各变更单独的 root。所选的根目录只在外层对象中出现一次。此示例省略了上文所示的各变更状态字段：

json

{
  "changes": [
    {
      "changeName": "add-rate-limit",
      "schemaName": "spec-driven",
      "artifacts": []
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

如果某个变更无法加载，批处理仍会继续。该变更的条目会包含 changeName 和 status 诊断信息，其他条目则保持可用。命令会以退出码 1 结束（JSON 模式下也是如此），因此 CI 不会将不完整的报告视为成功。JSON 输出仍是一个完整可解析的文档。

退出码

0：所有请求的状态均已打印；--all 报告为空时也返回退出码 0。
1：请求的变更加载失败、缺少 --change 或 --all、同时使用了这两个标志、变更不存在，或 schema 覆盖名称未知。

openspec instructions

打印用于创建工件、应用（apply）或归档（archive）的指令。你的 agent 会在工作流中运行此命令，以获取其下一步所需的指令文本。

bash

openspec instructions proposal --change add-rate-limit   # 如何编写单个工件
openspec instructions apply --change add-rate-limit      # 如何实现该变更
openspec instructions archive --change add-rate-limit    # 归档所需的输入

参数

参数	说明
`artifact`	schema 中的工件 id（`spec-driven` 中的 `proposal`、`specs`、`design`、`tasks`），或保留字 `apply` 和 `archive`。

选项

标志	作用
`--change <id>`	要为其生成指令的变更。必填。
`--schema <name>`	覆盖 schema。否则将从 `config.yaml` 自动检测。
`--json`	输出结构化对象而非文本。
`--store <id>`	使用已注册的 store 作为 OpenSpec 根目录，而非当前项目。

输出

工件形式会打印一个指令块：包含任务、要写入的文件、写入方式、工件的模板，以及完成该工件后将解锁的内容。

<artifact id="proposal" change="add-rate-limit" schema="spec-driven">

<task>
Create the proposal artifact for change "add-rate-limit".
Initial proposal document outlining the change
</task>

<output>
Write to: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
</output>

<instruction>
Create the proposal document that establishes WHY this change is needed.
...

apply 会打印上下文文件、任务进度以及工作指令：

## Apply: add-rate-limit
Schema: spec-driven

### Context Files
- proposal: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
- specs: /Users/you/projects/my-app/openspec/changes/add-rate-limit/specs/api/spec.md
- tasks: /Users/you/projects/my-app/openspec/changes/add-rate-limit/tasks.md

### Progress
1/3 complete

### Tasks
- [x] 1.1 Add rate limit middleware
- [ ] 1.2 Return 429 with Retry-After header
- [ ] 1.3 Add tests for burst traffic

### Instruction
Read context files, work through pending tasks, mark complete as you go.
Pause if you hit blockers or need clarification.

No project context or operation guidance configured.

当必需的工件缺失时，apply 会改为输出 ### ⚠️ Blocked 并列出缺失的工件。archive 会打印变更名称，以及来自配置的任何项目上下文和操作指南。如果这些内容均未配置，它只会说明这一点，此外不再输出其他信息。

使用 --json 时，每种形式都会返回一个对象。工件形式的开头如下：

json

{
  "changeName": "add-rate-limit",
  "artifactId": "proposal",
  "schemaName": "spec-driven",
  "changeDir": "/Users/you/projects/my-app/openspec/changes/add-rate-limit",
  ...

随后依次包含 outputPath、existingOutputPaths、完整的 instruction 和 template 字符串、dependencies、unlocks 以及 root。apply 形式则包含 contextFiles、progress、tasks、taskTrackingConfigured、state（blocked、ready、all_done）和 instruction。

每个 tasks 条目包含 id、description、done、sourcePath 和 line。sourcePath 是提供该任务的被跟踪文件的绝对路径。line 是该任务复选框在此文件中的行号（从 1 开始）。

taskTrackingConfigured 始终是布尔值：当 schema 将 apply.tracks 设置为非空值时为 true（即使没有任何文件匹配），否则为 false。如果某个匹配到的跟踪文件无法读取，unavailableTrackingFiles 会包含其绝对 path 和错误 reason。当所有匹配的文件均可读取时，该字段会被省略。可读取的文件仍会贡献到 tasks 和 progress 中，但在每个匹配的文件都被读取之前，state 不能为 all_done。

退出码

0：指令已打印。
1：工件未知、变更未知、schema 未知，或缺少 --change。每种错误都会列出有效值。

openspec templates

打印某个 schema 各产物解析出的模板路径。

bash

openspec templates          # 默认 schema：spec-driven
openspec templates --json   # 产物 ID 到路径的映射

选项

标志	作用
`--schema <name>`	要解析的 schema。默认值：`spec-driven`。
`--json`	打印从产物 ID 到模板路径的 JSON 映射。

输出

Schema: spec-driven
Source: package

proposal:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/proposal.md
specs:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/spec.md
design:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/design.md
tasks:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/tasks.md

Source 指明了 schema 的解析来源：project（你的项目中的 openspec/schemas/）、user（全局覆盖）或 package（CLI 内置）。project 优先于 user，user 优先于 package。

json

{
  "proposal": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/proposal.md",
    "source": "package"
  },
  "specs": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/spec.md",
    "source": "package"
  },
  "design": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/design.md",
    "source": "package"
  },
  "tasks": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/tasks.md",
    "source": "package"
  }
}

退出码

0：已打印路径。
1：未知 schema。错误信息会列出可用的 schema。

openspec schemas

列出可用的工作流 schema。

bash

openspec schemas          # 名称、描述、产物顺序
openspec schemas --json   # 机器可读，供智能体使用

选项

标志	作用
`--json`	以 JSON 输出（供智能体使用）。

输出

Available schemas:

  spec-driven
    Default OpenSpec workflow - proposal → specs → design → tasks
    Artifacts: proposal → specs → design → tasks

来自你项目的 schema 会被标记为 (project)，全局覆盖会被标记为 (user override)。

json

[
  {
    "name": "spec-driven",
    "description": "Default OpenSpec workflow - proposal → specs → design → tasks",
    "artifacts": [
      "proposal",
      "specs",
      "design",
      "tasks"
    ],
    "source": "package"
  }
]

退出码

0：已列出 schema。
1：无法读取 schema 列表。

openspec schema

检查、分叉或创建模式（实验性功能）。每个子命令首先会在 stderr 上打印 Note: Schema commands are experimental and may change.

bash

openspec schema which spec-driven          # where a schema resolves from
openspec schema fork spec-driven my-flow   # copy a schema into the project
openspec schema init my-schema             # create a schema from scratch

子命令	功能说明
`which`	显示模式的解析来源。
`validate`	检查模式的结构和模板。
`fork`	将现有模式复制到项目中以供自定义。
`init`	创建新的项目本地模式。

模式从三个位置解析。第一个匹配项优先：

来源	位置
`project`	当前项目中的 `openspec/schemas/`。
`user`	`~/.local/share/openspec/schemas/`（支持 `XDG_DATA_HOME` 和 Windows `%LOCALAPPDATA%`）。
`package`	CLI 附带的模式。`spec-driven` 位于此处。

openspec schema which

显示 CLI 将使用哪个模式副本。

bash

openspec schema which spec-driven
openspec schema which --all        # every schema, grouped by source

参数

参数	说明
`name`	要查找的模式名称。除非设置了 `--all`，否则为必填项。两者均未设置时，which 以退出码 1 退出。

选项

标志	效果
`--all`	列出所有模式及其解析来源。
`--json`	以 JSON 格式打印解析结果。

输出

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

当高优先级副本隐藏了另一个副本时，会显示 Shadows: 部分列出被隐藏的副本。使用 --json 时：

json

{
  "name": "my-flow",
  "source": "project",
  "path": "/Users/you/projects/my-app/openspec/schemas/my-flow",
  "shadows": []
}

未知名称以退出码 1 退出并列出可用模式。

openspec schema validate

检查模式的结构和模板。

bash

openspec schema validate spec-driven   # one schema, from any source
openspec schema validate               # every project-local schema

它会验证 schema.yaml 是否存在且可解析，结构是否与模式格式匹配，每个工件的模板文件是否存在于模式的 templates/ 目录中，以及依赖图是否存在循环或未知引用，包括 apply.requires 中的引用。如果 apply.tracks 的值与任何工件的 generates 值不完全相等，会打印 warning: 行但不会导致验证失败，因为 OpenSpec 无法判断该文件属于哪个工件的进度。

选项

标志	效果
`--json`	打印结构化报告而非文本。
`--verbose`	打印每个验证步骤。

输出

✓ Schema 'spec-driven' is valid

不指定名称时，每个项目模式在 Validation Results: 标题下各占一行。失败的模式会列出其问题且运行以退出码 1 退出：

✗ Schema 'my-schema' has errors:
  error: Template file 'tasks.md' not found for artifact 'tasks'

openspec schema fork

将现有模式复制到项目中以便进行自定义。

bash

openspec schema fork spec-driven my-flow

参数

参数	说明
`source`	要复制的模式，可来自任何源位置。
`name`	副本的名称。短横线命名法（`my-workflow`）。默认值：`<source>-custom`。

选项

标志	效果
`--force`	覆盖已存在的目标模式。
`--json`	以 JSON 格式打印结果。

输出

✔ Forked 'spec-driven' to 'my-flow'

Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven (package)
Destination: /Users/you/projects/my-app/openspec/schemas/my-flow

分叉模式位于 openspec/schemas/ 中，其 schema.yaml 中的 name: 字段会被重写为新名称：

openspec/schemas/my-flow/
├── schema.yaml
└── templates/
    ├── design.md
    ├── proposal.md
    ├── spec.md
    └── tasks.md

除非传入 --force，否则目标已存在会报错。保留源名称的分叉将隐藏原始模式。

openspec schema init

创建新的项目本地模式，附带入门模板。

bash

openspec schema init my-schema --description "Lightweight flow" --artifacts proposal,tasks

在交互式终端中，如果未指定 --description 和 --artifacts，init 会提示输入描述、工件检查清单以及是否将该模式设为项目默认模式。在终端之外，使用以下默认值。

参数

参数	说明
`name`	新模式的名称。短横线命名法（`my-workflow`）。

选项

标志	效果
`--description <text>`	模式描述。默认值：`Custom workflow schema for <name>`。
`--artifacts <list>`	逗号分隔的工件 ID，可选值为 `proposal`、`specs`、`design`、`tasks`。默认值：全部四个。
`--default`	将 `schema: <name>` 写入现有的 `openspec/config.yaml` 或 `openspec/config.yml`。如果两者都不存在则创建 `openspec/config.yaml`。新变更将使用此模式。
`--no-default`	跳过关于默认模式的提示。
`--force`	覆盖同名已存在的模式。
`--json`	以 JSON 格式打印结果。

模式创建和 --default 配置更新是一个操作。如果 OpenSpec 无法验证或写入配置，它会保持配置和任何现有模式不变。

输出

✔ Created schema 'my-schema'

Schema created at: /Users/you/projects/my-app/openspec/schemas/my-schema

Artifacts: proposal, tasks

磁盘上的布局：

openspec/schemas/my-schema/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

schema.yaml 将选定的工件与其依赖关系连接起来。当包含 tasks 时，它还会获得一个跟踪 tasks.md 的 apply 阶段。使用 openspec new --schema my-schema 来使用此模式。

openspec store

创建和管理存储：在您的机器上注册的独立 OpenSpec 仓库。

bash

openspec store setup team-context --path ~/openspec/team-context   # create and register
openspec store register ~/stores/design-system                     # register an existing checkout
openspec store list                                                # see what's registered

注册信息存储在每台机器的注册表中：~/.local/share/openspec/stores/registry.yaml，当设置了 XDG_DATA_HOME 时为 $XDG_DATA_HOME/openspec/stores/registry.yaml。每个子命令都接受 --json 以打印结构化报告而非文本。运行 openspec store 时如果缺少子命令或子命令未知，将以退出码 1 退出并列出子命令。

子命令	功能说明
`setup [id]`	创建存储文件夹并注册。
`register [path]`	注册现有的存储文件夹。
`unregister <id>`	取消注册。文件夹保留在磁盘上。
`remove <id>`	取消注册并删除文件夹。
`list`（别名 `ls`）	列出已注册的存储。
`doctor [id]`	检查已注册存储的注册、元数据和 Git 状态。

openspec store setup

创建存储文件夹并注册。

bash

openspec store setup team-context --path ~/openspec/team-context

在交互式终端中，setup 会提示输入缺失的名称和位置，并在创建任何内容之前确认。在终端之外，缺少名称或 --path 会以退出码 1 退出并提示要传递的标志。对已注册的存储重新运行 setup 会报告 Registry: already registered。

当 --path 位于另一个 Git 仓库内时，setup 会以退出码 1 退出并显示 store_setup_inside_git_repo，因为在该处初始化存储会导致仓库嵌套。--no-init-git 不创建仓库，因此会跳过该检查。当您的主目录本身就是一个 Git 仓库（例如 dotfiles 仓库）时，可使用它将存储保留在 ~/openspec/<id>。

参数

参数	说明
`id`	存储名称。它将成为您传递给 `--store` 的 id。

选项

标志	效果
`--path <path>`	存储所在的文件夹（`~` 会展开）。
`--init-git`	初始化 Git 仓库并进行初始提交。默认。
`--no-init-git`	跳过所有 Git 操作：不初始化、不提交。
`--remote <url>`	在 `store.yaml` 中记录规范克隆源。

输出

Store ready: team-context
Location: /Users/you/stores/team-context
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-context
Share this store by committing and pushing it like any Git repo.

--json 报告创建的内容及其注册位置：

json

{
  "store": {
    "id": "design-system",
    "root": "/Users/you/stores/design-system",
    "metadata_path": "/Users/you/stores/design-system/.openspec-store/store.yaml"
  },
  "registry": {
    "path": "/Users/you/.local/share/openspec/stores/registry.yaml",
    "registered": true,
    "already_registered": false
  },
  "git": {
    "is_repository": true,
    "initialized": true,
    "committed": true
  },
  "created_files": [
    "openspec/",
    "openspec/specs/",
    "openspec/changes/",
    "openspec/changes/archive/",
    "openspec/config.yaml",
    "openspec/specs/.gitkeep",
    "openspec/changes/archive/.gitkeep",
    ".openspec-store/store.yaml"
  ],
  "status": []
}

openspec store register

注册现有的存储文件夹，例如您克隆的队友的存储。

bash

openspec store register ~/stores/design-system

该文件夹必须包含健康的 openspec/ 根目录。如果存在 .openspec-store/store.yaml，register 会重用记录的 id。如果不存在，register 会在创建该元数据之前询问。在交互式终端之外，请传入 --yes。一台机器每个存储 id 只能注册一个检出。同一 id 下的第二个路径，或第二个 id 下的同一路径，将以退出码 1 退出。

参数

参数	说明
`path`	要注册的存储文件夹（`~` 会展开）。必填。

选项

标志	效果
`--id <id>`	存储 id。默认为元数据或文件夹名称。
`--yes`	确认为健康的 OpenSpec 根目录创建存储身份元数据。

输出

Store registered: design-system
Location: /Users/you/stores/design-system
OpenSpec root: ready
Registry: registered

--json 打印与 store setup --json 相同的文档结构。

openspec store unregister

取消注册。文件夹保留在磁盘上。

bash

openspec store unregister design-system

Unregistered store: design-system
Files kept at: /Users/you/stores/design-system

openspec store remove

取消注册并删除文件夹。

bash

openspec store remove design-system --yes

在交互式环境中，remove 会在删除前询问。使用 --json 或在交互式终端之外时，删除需要 --yes：

Error: Pass --yes to delete store files non-interactively.
Fix: openspec store remove design-system --yes

当文件夹缺少匹配的存储元数据，或包含另一个已注册的存储（例如作为 Git 子模块引入的存储）时，remove 以退出码 1 退出且不删除任何内容。在这种情况下错误为 store_remove_contains_registered_store：先运行 openspec store unregister <nested-id>，或运行 openspec store unregister <id> 取消注册而不删除文件。

选项

标志	效果
`--yes`	确认删除本地存储文件夹。

输出

Removed store: design-system
Deleted: /Users/you/stores/design-system

openspec store list

列出已注册的存储。ls 是别名。

bash

openspec store list

OpenSpec stores (2)

ID              Location
design-system   /Users/you/stores/design-system
team-context    /Users/you/stores/team-context

当没有注册任何存储时，list 打印 No stores registered. 以及接下来要运行的 setup 和 register 命令。

openspec store doctor

检查已注册存储的注册、元数据和 Git 状态。

bash

openspec store doctor                # every registered store
openspec store doctor team-context  # one store

输出

Store doctor

team-context
  Location: /Users/you/stores/team-context
  OpenSpec root: ok
  Metadata: ok
  Git: repository detected (commits: yes, uncommitted changes: no, remote: none)
  Issues: none

退出码

0：报告已打印，即使存储报告了问题。
1：报告无法运行（例如未知的存储 id）。

openspec doctor

报告已解析的 OpenSpec 根目录的关系健康状况。

bash

openspec doctor                       # nearest openspec/ root above your cwd
openspec doctor --store team-context  # a registered store as the root

Doctor 是只读的：它不会克隆、同步或修复。它报告根目录是否健康，以及 openspec/config.yaml 中声明的每个引用在此机器上是否可解析。如果 cwd 上方没有根目录且未指定 --store，则退出码为 1 并列出已注册的存储。

选项

标志	效果
`--store <id>`	使用已注册的存储作为 OpenSpec 根目录，而不是当前项目。
`--json`	以 JSON 格式打印健康报告。

输出

Doctor

Root
  Location: /Users/you/projects/my-app
  OpenSpec root: ok

References
  - team-context: ok (/Users/you/stores/team-context)

使用 --store 时，根目录为该存储，报告会添加一行存储信息：

Using OpenSpec root: team-context (/Users/you/stores/team-context)
Doctor

Root
  Location: /Users/you/stores/team-context
  OpenSpec root: ok
  Store: team-context (metadata ok)

References
  (none declared)

json

{
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest",
    "healthy": true,
    "status": []
  },
  "store": null,
  "references": [
    {
      "store_id": "team-context",
      "root": "/Users/you/stores/team-context",
      "status": []
    }
  ],
  "status": []
}

退出码

0: 报告已打印，包括列出问题时。
1: 未解析到根目录（cwd 上方没有 openspec/ 且未指定 --store），或 --store ID 未知。

openspec context

打印已解析的 OpenSpec 根目录的工作上下文：根目录加上 openspec/config.yaml 中声明的每个引用存储，每个存储附带一个获取命令。

bash

openspec context                       # nearest openspec/ root above your cwd
openspec context --store team-context  # a registered store as the root
openspec context --json                # agent brief

在此机器上无法解析的引用会归入“此机器上不可用”部分，每个引用附带修复建议。

选项

标志	效果
`--store <id>`	使用已注册的存储作为 OpenSpec 根目录，而不是当前项目。
`--json`	以 JSON 格式打印智能体简报。
`--code-workspace <path>`	同时为该集合写入 VS Code 工作区文件。
`--force`	覆盖已存在的 `--code-workspace` 文件。

输出

Working context for my-app (/Users/you/projects/my-app)

OpenSpec root
  my-app  /Users/you/projects/my-app

Referenced stores
  team-context  /Users/you/stores/team-context
    Fetch: openspec show <spec-id> --type spec --store team-context

使用 --store 时，该存储即为整个集合：

Using OpenSpec root: team-context (/Users/you/stores/team-context)
Working context for team-context (/Users/you/stores/team-context)

OpenSpec root
  team-context  /Users/you/stores/team-context

No references declared; the working set is this root alone.

json

{
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest",
    "role": "openspec_root"
  },
  "members": [
    {
      "role": "referenced_store",
      "id": "team-context",
      "path": "/Users/you/stores/team-context",
      "fetch": "openspec show <spec-id> --type spec --store team-context",
      "status": []
    }
  ],
  "status": []
}

写入工作区文件

--code-workspace 在你指定的路径写入 VS Code 工作区文件：根目录一个文件夹，每个可用的引用存储一个 ref:<id> 文件夹。不可用的引用会被跳过，并在摘要行中列出名称，Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders)。摘要打印在 stderr 上，因此 --json 的 stdout 仍保持为一个 JSON 文档。除非传入 --force，否则文件已存在时退出码为 1。

json

{
  "folders": [
    {
      "name": "my-app",
      "path": "/Users/you/projects/my-app"
    },
    {
      "name": "ref:team-context",
      "path": "/Users/you/stores/team-context"
    }
  ]
}

退出码

0: 报告已打印。
1: 未解析到根目录（cwd 上方没有 openspec/ 且未指定 --store），或 --code-workspace 写入被拒绝。

openspec workset

组合、保存并打开个人工作视图。workset 是一个已保存、具名的文件夹列表，其中的文件夹是你在其中协同工作的一组文件夹。

bash

openspec workset create checkout --member ~/projects/checkout-api --member web=~/projects/checkout-web
openspec workset list
openspec workset remove checkout --yes

子命令	作用
`create [name]`	组合并保存一个由你选择的文件夹组成的具名工作视图。
`list`, `ls`	显示已保存的 workset 及其成员。
`open <name>`	在你的工具中打开已保存的 workset（编辑器窗口或 agent 会话）。
`remove <name>`	删除已保存的 workset（绝不会改动成员文件夹）。

workset 完全本地：

其状态保存在一个文件夹中：~/.local/share/openspec/worksets/（设置后为 $XDG_DATA_HOME/openspec/worksets/；Windows 上为 %LOCALAPPDATA%\openspec\worksets\）。
不会向成员文件夹写入任何内容，也不会提交或共享任何内容。
删除那一个文件夹即可移除所有痕迹。

openspec workset create

保存一个具名的文件夹工作视图。

bash

openspec workset create checkout \
  --member ~/projects/checkout-api \
  --member web=~/projects/checkout-web

在交互式终端中，create 会提示补充命令行标志未提供的内容：名称、逐个文件夹、一个工具，然后询问是否立即打开该 workset。在非交互式终端中，缺少名称或成员即为错误。已保存的名称始终是错误。请先将其移除。

参数

参数	说明
`name`	workset 名称。采用 kebab-case：小写字母、数字、单个连字符。在非交互式终端中为必需项。

选项

标志	效果
`--member <member>`	成员文件夹，格式为 `<path>` 或 `<name>=<path>`，可重复。第一个为主成员。路径必须是已存在的文件夹，标签默认为文件夹自身的名称。
`--tool <id>`	用于打开此 workset 的首选工具。内置 ID：`code`（VS Code）、`cursor`（Cursor）。`claude` 和 `codex` 暂时禁用。
`--json`	以 JSON 格式打印已保存的 workset。

输出

Saved workset 'checkout' (2 members) to your machine.
Open it any time with: openspec workset open checkout

openspec workset list

显示已保存的 workset 及其成员，按名称排序。

bash

openspec workset list   # alias: ls

选项

标志	效果
`--json`	以 JSON 格式打印 worksets。

输出

每个 workset 一个块：名称、其工具（如果有），然后每个成员一行 name path。在未保存任何内容时，list 会输出 No worksets saved. Create one with: openspec workset create。

checkout
  checkout-api  /Users/you/projects/checkout-api
  web           /Users/you/projects/checkout-web
checkout-tool  (opens in VS Code)
  checkout-api  /Users/you/projects/checkout-api

使用 --json 时：

json

{
  "worksets": [
    {
      "name": "checkout",
      "members": [
        {
          "name": "checkout-api",
          "path": "/Users/you/projects/checkout-api"
        },
        {
          "name": "web",
          "path": "/Users/you/projects/checkout-web"
        }
      ]
    }
  ],
  "status": []
}

openspec workset open

在你的工具中打开已保存的 workset。编辑器工具（code、cursor）会获得一个生成的 .code-workspace 文件。会打开一个窗口，然后命令返回。CLI agent 工具（claude、codex）会接管此终端并附加每个成员。在该流程重新设计期间，它们暂时禁用，因此目前 workset 会在 IDE 中打开。

bash

openspec workset open checkout                # saved tool, or a prompt
openspec workset open checkout --tool cursor  # this tool just this once

参数

参数	说明
`name`	要打开的 workset。

选项

标志	效果
`--tool <id>`	仅此次使用此工具打开。

如果没有 --tool 且没有已保存的工具，open 会提示你选择一个已安装的工具。在非交互式终端中，它会改为以退出码 1 退出。

不再存在的成员文件夹会被跳过并发出警告。当主成员缺失时，下一个仍然存在的成员将成为本次打开的主成员。当没有任何成员文件夹存在时，打开失败。
--json 会被拒绝：open 将终端交给工具，没有 JSON 模式。
启动失败时，错误信息末尾会提供手动方式：工作区文件的路径和成员列表。

退出码

与工具保持一致：命令以工具自身的退出码退出，信号会变为 128+n（Ctrl-C 后为 130）。
1：未知 workset、没有可用的成员文件夹，或没有可用的工具。

openspec workset remove

删除已保存的 workset 及其生成的 .code-workspace 文件。绝不会改动成员文件夹。

bash

openspec workset remove checkout --yes

在交互式终端中，remove 会显示该 workset 并要求你确认。使用 --json 时，或在终端外运行时，它需要 --yes，否则以退出码 1 退出。

选项

标志	效果
`--yes`	非交互式确认移除。
`--json`	以 JSON 格式打印移除结果。

输出

Removed workset 'checkout'. Member folders were not touched.

openspec version

报告正在运行的 OpenSpec 版本以及此副本的安装方式。

bash

openspec version                 # local version and install details
openspec version --json          # structured local report
openspec version --check         # also check the registry for an update
openspec version --check --json  # structured local and update report

不使用 --check 时，此命令在本地执行，不会联系注册表。它可以在 OpenSpec 项目之外运行。现有的 openspec --version 标志仍是最简短的形式，仅打印版本号本身。

选项

标志	效果
`--json`	打印一个带版本号的 JSON 文档，而不是文本。
`--check`	检查配置的注册表是否有更新的版本。

输出

对于全局 npm 安装：

text

OpenSpec 1.13.2 (npm, global)

安装范围为 global、project、temporary（用于 npx 等临时运行器）、source（用于源代码检出）或 standalone（用于独立安装）。OpenSpec 会省略无法识别的详细信息，而不是进行猜测。

--json 会将未知详细信息保留为显式的 null 值：

json

{
  "schemaVersion": 1,
  "version": "1.13.2",
  "install": {
    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
    "packageManager": "npm",
    "scope": "global"
  }
}

使用 --check 时，如果有可用更新，则会添加最新版本和一个命令（当 OpenSpec 能为该安装识别出安全命令时）：

text

OpenSpec 1.13.2 (npm, global)
Update available: 1.14.0
  npm install -g @fission-ai/openspec@latest

json

{
  "schemaVersion": 1,
  "version": "1.13.2",
  "install": {
    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
    "packageManager": "npm",
    "scope": "global"
  },
  "update": {
    "status": "available",
    "latest": "1.14.0",
    "command": "npm install -g @fission-ai/openspec@latest",
    "canSelfUpgrade": true
  }
}

更新状态值：

状态	含义
`available`	注册表返回了比正在运行的版本更新的安全版本。
`current`	检查已完成，未发现更新的版本。
`disabled`	现有的隐私或更新检查设置阻止了注册表访问。`latest` 为 `null`。
`offline`	注册表不可用或返回了不可用的响应。`latest` 为 `null`。

对于独立安装，更新命令是 openspec install。

DO_NOT_TRACK、遥测退出设置、OPENSPEC_NO_UPDATE_CHECK、CI 检测以及被拒绝的非 HTTPS 注册表覆盖会禁用检查。禁用和离线检查仍会以退出码 0 退出，因为更新可用性仅供参考。此命令永远不会升级 OpenSpec；canSelfUpgrade 仅报告现有的 openspec update 路径是否可以安全升级此副本。

退出码

0：打印了本地报告，包括被禁用或离线的更新检查。
1：命令语法无效，例如不支持的 --upgrade 选项。

openspec install

安装独立版 openspec。若当前是 npm 或 Homebrew 安装,运行它可切换到独立版;若已是独立版安装,运行它可原地升级。

bash

openspec install          # 最新发行版
openspec install 1.15.0   # 指定发行版

它会运行安装脚本,该脚本会选取文件均已附上的最新发行版以及与你机器匹配的文件,并对照该发行版的 SHA256SUMS 进行校验:

从包管理器安装:安装到 ~/.local/bin(Windows:%LOCALAPPDATA%\Programs\openspec),并打印移除旧副本的命令,例如 npm uninstall -g @fission-ai/openspec。它绝不会自行移除该副本。
从独立版安装:以原有名称就地替换正在运行的文件。

完成后,它会说明 openspec 现在运行的是哪个副本,因为 PATH 中位置靠前的包管理器副本会一直被使用,直到你将其移除。

参数

参数	说明
`version`	要安装的发行版,例如 `1.15.0`。可选;默认为最新版本。

OPENSPEC_INSTALL_DIR 和 OPENSPEC_INSTALL_NAME 可用于指定其他文件夹或文件名。

退出码

0:安装成功。
1:该版本不是发行版版本,或下载或安装失败。你现有的副本保持不变。

openspec feedback

提交关于 OpenSpec 的反馈。

bash

openspec feedback "Validate output is hard to scan"
openspec feedback "Archive fails on Windows" --body "Steps: init, propose, archive. Error: EPERM."

CLI 会通过你的 gh CLI,将你的消息作为 GitHub issue 提交到 Fission-AI/OpenSpec 仓库。标题会变为 Feedback: <message>。正文沿用 bug 表单的标题结构:你的消息位于 What happened 之下,你的 --body 文本位于 Details 之下,另有一个 Minimal steps to reproduce 部分提示你补充复现步骤,因为 CLI 无法替你填写。页脚会附上 CLI 版本、平台和时间戳。该 issue 会被打上 feedback 标签。如果仓库未定义该标签,CLI 会在不带标签的情况下重试,并会说明这一点。

参数

参数	说明
`message`	一行摘要,将作为 issue 标题。必填。

选项

标志	作用
`--body <text>`	添加到 issue 正文中的更详细描述。

输出

成功时:

✓ Feedback submitted successfully!
Issue URL: https://github.com/Fission-AI/OpenSpec/issues/1234

未安装 gh 或 gh 未登录时,不会提交任何内容。CLI 会在 --- FORMATTED FEEDBACK --- 标记之间打印格式化后的反馈,然后打印一个链接;点击该链接会打开 bug 报告表单,其中标题、What happened 内容(你的消息和 --body 文本)、CLI 版本以及环境(平台和 Node 版本)均已填好。表单的其余部分由你在浏览器中补全。未登录的情况下,输出中还会附加一行 To auto-submit in the future: gh auth login。

退出码

0:issue 已创建,或已执行手动提交的回退流程(未安装 gh,或 gh 未登录)。
1:未提供消息。
gh 自身的退出码:gh 在认证后失败(网络问题、速率限制、issue 功能被禁用)。CLI 会先重新打印你的反馈和手动提交 URL。

openspec completion

安装或生成 shell 自动补全。

bash

openspec completion install        # 检测你的 shell、执行安装并接入配置
openspec completion generate zsh   # 将脚本打印到 stdout

支持的 shell:zsh、bash、fish、powershell。每个子命令都可接受一个可选的 shell 参数。省略该参数时,CLI 会从环境中检测你的 shell。

子命令	作用
`generate [shell]`	将补全脚本打印到 stdout。
`install [shell]`	写入脚本并配置你的 shell 启动文件。
`uninstall [shell]`	移除脚本和配置块。

通过 Nix 安装时,补全已预先就位:flake 软件包已在标准位置附带 Bash、Fish 和 Zsh 脚本,因此无需 install(安装)。

openspec completion generate

打印脚本,不写入任何内容。

#compdef openspec

# Zsh completion script for OpenSpec CLI
# Auto-generated - do not edit manually

_openspec() {
  local context state line
  typeset -A opt_args
...

openspec completion install

写入脚本并编辑你的 shell 配置。配置修改位于 # OPENSPEC:START 与 # OPENSPEC:END 标记之间。已有脚本会先被备份(.backup-<timestamp> 副本)。

Shell	脚本位置	编辑的配置
zsh	`~/.zsh/completions/_openspec`	`ZDOTDIR` 为绝对路径时为 `$ZDOTDIR/.zshrc`,否则为 `~/.zshrc`
bash	`~/.local/share/bash-completion/completions/openspec`	`~/.bashrc`
fish	`~/.config/fish/completions/openspec.fish`	无:fish 会自动加载。
powershell	位于你的 profile 旁边的 `OpenSpecCompletion.ps1`	`$PROFILE`

若安装了 Oh My Zsh,脚本则会放入 $ZSH_CUSTOM/completions/_openspec(默认为 ~/.oh-my-zsh/custom/completions/_openspec)。

相对路径或以 ~ 开头的 ZDOTDIR 会被忽略,转而编辑 ~/.zshrc。即使脚本已是最新,再次运行 install 仍会向 zsh 实际读取的 .zshrc 添加该配置块。

选项

标志	作用
`--verbose`	额外打印已安装的路径、备份路径(如有)以及被编辑的配置文件。

输出

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

移除脚本以及带标记的配置块。改动你的配置前会先询问(默认:否)。

对于 zsh,它会清理 install 所编辑的 .zshrc;如果旧版安装在 ZDOTDIR 环境下曾在 ~/.zshrc 中留下配置块,也会一并清理。如果某个配置块无法移除,uninstall 会指出该文件并以退出码 1 退出。

选项

标志	作用
`-y, --yes`	跳过确认提示。

输出

✓ Completion script removed from /Users/you/.zsh/completions/_openspec. Removed OpenSpec configuration from ~/.zshrc

退出码

0:脚本已生成、已安装或已移除。取消卸载时同样以 0 退出。
1:shell 不受支持或未能检测到,或某个安装/卸载步骤失败。

openspec change

已弃用的 show、list 和 validate 名词形式。每次运行都会发出警告并指向动词优先的命令,然后仍会照常执行:

Warning: The "openspec change ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec list", "openspec validate --changes").
Warning: "openspec change list" is deprecated. Use "openspec list".
add-rate-limit

已弃用	改用
`openspec change show <name>`	`openspec show <name>`
`openspec change list`	`openspec list`
`openspec change validate <name>`	`openspec validate <name>`(所有变更:`openspec validate --changes`)

各标志的说明见动词优先命令的相关章节。

openspec spec

已弃用的 show、list 和 validate 名词形式。每次运行都会发出警告并指向动词优先的命令,然后仍会照常执行:

Warning: The "openspec spec ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec show", "openspec validate --specs").
api

已弃用	改用
`openspec spec show <id>`	`openspec show <id>`
`openspec spec list`	`openspec list --specs`
`openspec spec validate <id>`	`openspec validate <id>`(所有规格:`openspec validate --specs`)

各标志的说明见动词优先命令的相关章节。

CLI ​

命令 ​

openspec init ​

openspec update ​

openspec config ​

openspec config path ​

openspec config list ​

openspec config get ​

openspec config set ​

openspec config unset ​

openspec config reset ​

openspec config edit ​

openspec config profile ​

openspec list ​

openspec show ​

为什么 ​

变更内容 ​

openspec view ​

openspec validate ​

--report full|findings ​

findings 文本输出 ​

findings JSON 输出 ​

无效的报告请求 ​

在外部过滤完整报告 ​

openspec archive ​

openspec new ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

openspec schema ​

openspec schema which ​

openspec schema validate ​

openspec schema fork ​

openspec schema init ​

openspec store ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

openspec doctor ​

openspec context ​

openspec workset ​

openspec workset create ​

openspec workset list ​

openspec workset open ​

openspec workset remove ​

openspec version ​

openspec install ​

openspec feedback ​

openspec completion ​

openspec completion generate ​

openspec completion install ​

openspec completion uninstall ​

openspec change ​

openspec spec ​

CLI

命令

openspec init

openspec update

openspec config

openspec config path

openspec config list

openspec config get

openspec config set

openspec config unset

openspec config reset

openspec config edit

openspec config profile

openspec list

openspec show

为什么

变更内容

openspec view

openspec validate

--report full|findings

findings 文本输出

findings JSON 输出

无效的报告请求

在外部过滤完整报告

openspec archive

openspec new

openspec status

openspec instructions

openspec templates

openspec schemas

openspec schema

openspec schema which

openspec schema validate

openspec schema fork

openspec schema init

openspec store

openspec store setup

openspec store register

openspec store unregister

openspec store remove

openspec store list

openspec store doctor

openspec doctor

openspec context

openspec workset

openspec workset create

openspec workset list

openspec workset open

openspec workset remove

openspec version

openspec install

openspec feedback

openspec completion

openspec completion generate

openspec completion install

openspec completion uninstall

openspec change

openspec spec