CLI 参考

OpenSpec CLI (openspec) 提供用于项目初始化、验证、状态检查与管理的终端命令。这些命令与 Commands 中介绍的 AI slash command(如 /opsx:propose)互为补充。

概览

类别	命令	用途
初始化	`init`, `update`	在项目中初始化和更新 OpenSpec
Stores（独立的 OpenSpec 规划仓库）	`store setup`, `store register`, `store unregister`, `store remove`, `store list`, `store doctor`	管理已注册的 stores——你注册过的独立 OpenSpec 规划仓库
健康检查	`doctor`	报告当前根目录及其关联 store 的健康状态
工作上下文	`context`	组装工作集(根目录 + 引用的 stores)
个人 workset	`workset create`, `workset list`, `workset open`, `workset remove`	在工具中保存并打开个人的本地视图
浏览	`list`, `view`, `show`	探索变更与 specs
验证	`validate`	检查变更和 specs 是否存在问题
生命周期	`archive`	定稿已完成的变更
工作流	`new change`, `status`, `instructions`, `templates`, `schemas`	制品驱动的工作流支持
Schemas	`schema init`, `schema fork`, `schema validate`, `schema which`	创建并管理自定义工作流
配置	`config`	查看与修改设置
实用工具	`feedback`, `completion`	反馈与 shell 集成

人工命令与 Agent 命令

大多数 CLI 命令都是为终端中的人工使用而设计的。部分命令也支持通过 JSON 输出供 agent/脚本使用。

仅人工命令

这些命令是交互式的,专为终端使用设计:

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

兼容 Agent 的命令

这些命令支持 --json 输出,供 AI agents 和脚本以编程方式使用:

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

全局选项

这些选项对所有命令均生效:

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

初始化命令

`openspec-cn init`

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

默认行为使用全局配置默认值:profile core、交付方式 both、工作流 propose, explore, apply, sync, archive。

openspec-cn init [path] [options]

参数:

参数	是否必填	描述
`path`	否	目标目录(默认:当前目录)

选项:

选项	描述
`--tools <list>`	非交互式配置 AI 工具。使用 `all`、`none` 或逗号分隔的列表
`--force`	自动清理旧版文件,不提示
`--profile <profile>`	本次 init 运行覆盖全局 profile(`core` 或 `custom`)

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

支持的工具 ID(--tools): amazon-q, antigravity, auggie, bob, claude, cline, codex, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, junie, kilocode, kimi, kiro, lingma, vibe, oh-my-pi, opencode, pi, qoder, qwen, roocode, trae, windsurf

该列表与 src/core/config.ts 中的 AI_TOOLS 对应。各工具的 skill 与命令路径见 Supported Tools。

示例:

# 交互式初始化
openspec-cn init

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

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

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

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

# 跳过提示并自动清理旧版文件
openspec-cn init --force

创建内容:

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

.claude/skills/         # Claude Code skills(若选中 claude)
.cursor/skills/         # Cursor skills(若选中 cursor)
.cursor/commands/       # Cursor OPSX commands(若交付方式包含 commands)
... (其他工具配置)

`openspec-cn update`

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

openspec-cn update [path] [options]

参数:

参数	是否必填	描述
`path`	否	目标目录(默认:当前目录)

选项:

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

示例:

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

Stores（独立的 OpenSpec 规划仓库）

Beta。 Stores 及其上构建的功能(引用、工作上下文、worksets)为新增功能;命令名、标志、文件格式与 JSON 输出在版本间可能发生变化。如需以问题为导向的导览,见 stores 指南。

store 是你在本机注册过的独立 OpenSpec 仓库——例如一个团队规划仓库。注册 store 后,常规命令(list、show、status、validate、new change、archive 等)可通过传入 --store <id> 从任意位置作用于它。

`openspec-cn store setup`

创建并注册本地 store。在终端中无参数运行时,OpenSpec 会引导用户完成 setup。Agent 和脚本应传入显式输入并使用 --json。

openspec-cn store setup [id] [options]

选项:

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

非交互式运行(--json、脚本、agents)必须同时传入 store id 和 --path。在交互式终端中,setup 会在一个可见的、用户拥有的位置(例如 ~/openspec/<id>)以可编辑的建议值提示输入位置;它绝不会默认使用 OpenSpec 管理的 data 目录。

示例:

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

`openspec-cn store register`

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

openspec-cn store register [path] [options]

选项:

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

`openspec-cn store unregister`

取消本地 store 注册,但不删除文件。

openspec-cn store unregister <id> [--json]

当你移动了某个 store、把它克隆到了别处,或希望本机上的 OpenSpec 不再显示它时使用。

`openspec-cn store remove`

取消本地 store 注册并删除其本地文件夹。

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

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

`openspec-cn store list`

列出本地已注册的 stores。

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

`openspec-cn store doctor`

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

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

doctor 仅用于诊断;它报告缺失的根目录、元数据不匹配和无效的本地注册状态,不会修改 store。

从项目引用 stores

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

schema: spec-driven
references:
  - team-context

此后,该仓库中 openspec-cn instructions 的输出(每个制品与 apply 表面、JSON 和人类模式)都会携带一个索引,列出每个被引用 store 的 specs——spec id、每个 spec 的 Purpose 段落中的一行摘要,以及 fetch 命令(openspec-cn show <spec-id> --type spec --store <id>)。该索引在每次运行时从已注册的 checkout 实时构建;spec 内容绝不会被复制到输出中。

引用是只读上下文。它们绝不会改变命令的作用位置:工作仍保留在仓库自己的根目录中,写入被引用的 store 仍然是一个显式的 --store 操作。无法解析的引用(例如本机未注册的 store)会在索引中降级为一条带确切修复方法的警告,指令仍会生成。openspec-cn doctor 会在一处报告引用健康状态。

记录 store 的克隆来源

store 可以在其已提交的身份文件中记录规范的克隆来源,这样新成员在"注册 store"这一步就不会走入死胡同:

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

该 remote 会落在初始提交内的 .openspec-store/store.yaml 中,因此每一次克隆自诞生起就知道它的来源。对于已有的 store,手动编辑 store.yaml 并提交。store doctor 会显示记录的 remote(以及 checkout 实际观察到的 Git origin);setup/register 共享指引会指出它;register 会将 checkout 的 origin 记录到本地机器的注册表中。

引用声明也可以携带克隆来源,这样尚未拥有该 store 的队友会得到一个完整、可粘贴的修复命令(git clone <remote> <path> && openspec-cn store register <path> --id <id>):

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

记录 remote 并非同步:OpenSpec 绝不会自行 clone、pull 或 push。

声明默认 store

一个规划完全外置化——没有本地 openspec/specs/ 或 openspec/changes/——的仓库,可以声明一次其 store,而不必在每个命令上都传入 --store:

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

常规命令随后会自动解析到声明的 store;根目录横幅和 JSON root 块会报告 source: "declared" 及 store id,打印的提示仍会携带 --store <id>。该声明是兜底方案,而非覆盖:显式的 --store 始终优先,而一个带有真实规划文件夹的目录会忽略该指针(并给出警告)。要将指针仓库转换为本地 OpenSpec 根目录,移除 store: 行并运行 openspec-cn init——在声明存在期间,init 拒绝搭建脚手架。

Doctor(关系健康)

一个只读诊断，回答一个问题：OpenSpec 根目录是否健康？它引用的 stores 在本机是否可用？

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

报告将根目录健康、store 元数据健康(包括一条说明记录 remote 与 checkout origin 不一致时的备注)、以及引用健康(与指令显示的同样诊断,并附带未解析引用的克隆修复)分开。任何严重程度的健康发现都会以退出码 0 结束——agents 读取 status 数组;只有命令失败(无根目录、未知 store)才会以退出码 1 结束。doctor 绝不会 clone、同步或修复。若要获取组装后的集合本身而非其健康状态,使用 openspec-cn context。

工作上下文(组装后的集合)

通过 OpenSpec 声明与本工作相关的所有内容,汇聚到一个工作集中:OpenSpec 根目录及其引用的 stores。

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

JSON 摘要可供 agent 消费(每个可用的被引用 store 都带有它的 fetch 配方;未解析成员携带与指令和 doctor 相同的修复)。--code-workspace 还会额外写入一个 VS Code 工作区文件,包含根目录和可用被引用 stores(ref:<id> 文件夹)——这是该命令执行的唯一一次写入,若文件已存在则在不加 --force 时被拒绝。不可用成员会被报告,绝不会被猜测。

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

个人 worksets

Beta。 Worksets 属于新增 beta 表面;命令、标志和文件格式在版本间可能发生变化。如需导览,见 stores 指南。

workset 是你一起工作的文件夹的一个个人、具名视图——一个规划根目录加上你挑选的其他内容——保存在本机,并可在工具中按名称重新打开。它是纯本地的:从不提交、从不共享、从不从声明派生;移除一个 workset 也绝不会触碰成员文件夹。

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

create 会运行一个简短的引导流程(或以非交互式方式接收 --member 标志;第一个成员是主成员——会话从这里开始)。open 启动所选工具:编辑器(VS Code、Cursor)打开一个包含所有成员的窗口并返回;CLI agents(Claude Code、codex)将接管本终端作为一个会话,附加所有成员、不预填任何提示,在你退出时结束。打开时缺失的成员文件夹会被跳过并附带说明;其余成员照常打开。保存的工具偏好可在每次打开时通过 --tool 覆盖。

支持新工具是配置而非代码。每种工具都是两种启动风格之一——workspace-file(用生成的 .code-workspace 启动)或 attach-dirs(每个成员一个 attach 标志)——全局 config.json 中的 openers 键(用 openspec-cn config edit 打开它)可按字段添加工具或调整内置工具:

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

所有 workset 状态都位于全局 data 目录的 worksets/ 文件夹下(已保存的视图加上生成的 <name>.code-workspace 文件,每次打开都会重新生成);删除该文件夹会清除所有痕迹。

浏览命令

`openspec-cn list`

列出项目中的变更或 specs。

openspec-cn list [options]

选项:

选项	描述
`--specs`	列出 specs 而非变更
`--changes`	列出变更(默认)
`--sort <order>`	按 `recent`(默认)或 `name` 排序
`--json`	以 JSON 输出

示例:

# 列出所有活跃变更
openspec-cn list

# 列出所有 specs
openspec-cn list --specs

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

输出(文本):

Changes:
  add-dark-mode     No tasks      just now

`openspec-cn view`

显示用于探索 specs 和变更的交互式仪表盘。

openspec-cn view

打开一个基于终端的界面,用于浏览项目的规范与变更。

`openspec-cn show`

显示某个变更或 spec 的详情。

openspec-cn show [item-name] [options]

参数:

参数	是否必填	描述
`item-name`	否	变更或 spec 的名称(省略时提示)

选项:

选项	描述
`--type <type>`	指定类型:`change` 或 `spec`(无歧义时自动检测)
`--json`	以 JSON 输出
`--no-interactive`	关闭提示

变更专属选项:

选项	描述
`--deltas-only`	仅显示增量规范(delta spec)(JSON 模式)

Spec 专属选项:

选项	描述
`--requirements`	仅显示需求,排除场景(JSON 模式)
`--no-scenarios`	排除场景内容(JSON 模式)
`-r, --requirement <id>`	按 1 起始的索引显示指定需求(JSON 模式)

示例:

# 交互式选择
openspec-cn show

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

# 显示指定 spec
openspec-cn show auth --type spec

# 供解析的 JSON 输出
openspec-cn show add-dark-mode --json

验证命令

`openspec-cn validate`

验证变更和 specs 是否存在结构性问题。

openspec-cn validate [item-name] [options]

参数:

参数	是否必填	描述
`item-name`	否	要验证的具体条目(省略时提示)

选项:

选项	描述
`--all`	验证所有变更和 specs
`--changes`	验证所有变更
`--specs`	验证所有 specs
`--type <type>`	名称有歧义时指定类型:`change` 或 `spec`
`--strict`	启用严格验证模式
`--json`	以 JSON 输出
`--concurrency <n>`	最大并行验证数(默认:6,或环境变量 `OPENSPEC_CONCURRENCY`)
`--no-interactive`	关闭提示

示例:

# 交互式验证
openspec-cn validate

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

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

# 以 JSON 输出验证全部(CI/脚本用)
openspec-cn validate --all --json

# 提高并行度的严格验证
openspec-cn 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):

{
  "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-cn archive`

归档已完成的变更,并将增量规范(delta spec)合并进主 specs。

openspec-cn archive [change-name] [options]

参数:

参数	是否必填	描述
`change-name`	否	要归档的变更(省略时提示)

选项:

选项	描述
`-y, --yes`	跳过确认提示
`--skip-specs`	跳过 spec 更新(用于基础设施/工具/纯文档类变更)
`--no-validate`	跳过验证(需确认)

示例:

# 交互式归档
openspec-cn archive

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

# 无提示归档(CI/脚本用)
openspec-cn archive add-dark-mode --yes

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

执行动作:

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

工作流命令

这些命令支持制品驱动的 OPSX 工作流。它们对检查进度的人工和决定下一步的 agents 都很有用。

`openspec-cn new change`

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

openspec-cn new change <name> [options]

变更名称必须使用小写 kebab-case。它们以小写字母开头,随后包含小写字母、数字和单个连字符。不能以数字开头,不能包含空格、下划线、大写字母、连续连字符,或前导/尾随连字符。若需包含外部工单 ID,请用一个单词作为前缀,例如 ticket-123-add-notifications 而非 123-add-notifications。

选项:

选项	描述
`--description <text>`	添加到 `README.md` 的描述
`--goal <text>`	随变更存储的可选 goal 元数据
`--schema <name>`	要使用的工作流 schema
`--store <id>`	用作 OpenSpec 根目录的 store id(指你注册过的独立 OpenSpec 仓库)
`--json`	输出 JSON

示例:

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

`openspec-cn status`

显示变更的制品完成状态。

openspec-cn status [options]

选项:

选项	描述
`--change <id>`	变更名称(省略时提示)
`--schema <name>`	schema 覆盖(从变更配置自动检测)
`--json`	以 JSON 输出

示例:

# 交互式状态检查
openspec-cn status

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

# 供 agent 使用的 JSON
openspec-cn status --change add-dark-mode --json

输出(文本):

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

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

输出(JSON):

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

`openspec-cn instructions`

获取用于创建制品或应用任务的增强指令。供 AI agents 理解下一步要创建什么。

openspec-cn instructions [artifact] [options]

参数:

参数	是否必填	描述
`artifact`	否	制品 ID:`proposal`、`specs`、`design`、`tasks` 或 `apply`

选项:

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

特殊情况: 使用 apply 作为制品以获取任务实现指令。

示例:

# 获取下一个制品的指令
openspec-cn instructions --change add-dark-mode

# 获取指定制品的指令
openspec-cn instructions design --change add-dark-mode

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

# 供 agent 消费的 JSON
openspec-cn instructions design --change add-dark-mode --json

输出包含:

制品的模板内容
来自配置的項目上下文
来自依赖制品的内容
来自配置的逐制品规则

`openspec-cn templates`

显示 schema 中所有制品的解析后模板路径。

openspec-cn templates [options]

选项:

选项	描述
`--schema <name>`	要检查的 schema(默认:`spec-driven`)
`--json`	以 JSON 输出

示例:

# 显示默认 schema 的模板路径
openspec-cn templates

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

# 供编程使用的 JSON
openspec-cn 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-cn schemas`

列出可用的工作流 schemas 及其描述与制品流程。

openspec-cn schemas [options]

选项:

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

示例:

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

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

`openspec-cn schema init`

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

openspec-cn 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 输出

示例:

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

# 指定制品的非交互式创建
openspec-cn 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-cn schema fork`

复制一个已有 schema 到你的项目以做自定义。

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

参数:

参数	是否必填	描述
`source`	是	要复制的 schema
`name`	否	新 schema 名称(默认:`<source>-custom`)

选项:

选项	描述
`--force`	覆盖已有的目标
`--json`	以 JSON 输出

示例:

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

`openspec-cn schema validate`

验证一个 schema 的结构与模板。

openspec-cn schema validate [name] [options]

参数:

参数	是否必填	描述
`name`	否	要验证的 schema(省略则验证全部)

选项:

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

示例:

# 验证指定 schema
openspec-cn schema validate my-workflow

# 验证所有 schemas
openspec-cn schema validate

`openspec-cn schema which`

显示某个 schema 从哪里解析而来(有助于调试优先级)。

openspec-cn schema which [name] [options]

参数:

参数	是否必填	描述
`name`	否	schema 名称

选项:

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

示例:

# 检查 schema 来自何处
openspec-cn 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-cn config`

查看并修改全局 OpenSpec 配置。

openspec-cn config <subcommand> [options]

子命令:

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

示例:

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

# 列出所有设置
openspec-cn config list

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

# 设置一个值
openspec-cn config set telemetry.enabled false

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

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

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

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

# 用基于动作的向导配置 profile
openspec-cn config profile

# 快速预设:将工作流切换到 core(保留交付模式)
openspec-cn config profile core

openspec-cn config profile 以一个当前状态摘要开始,然后让你选择:

修改交付方式 + 工作流
仅修改交付方式
仅修改工作流
保留当前设置(退出)

若保留当前设置,则不写入任何更改,也不显示更新提示。若没有配置更改但当前项目文件与你的全局 profile/交付方式不同步,OpenSpec 会显示警告并建议使用 openspec-cn update。按 Ctrl+C 也会干净地取消流程(无堆栈跟踪)并以退出码 130 退出。在 workflow 清单中,[x] 表示工作流已在全局配置中选中。要将这些选择应用到项目文件,运行 openspec-cn update(或在项目内被提示时选择 Apply changes to this project now?)。

交互式示例:

# 仅更新交付方式
openspec-cn config profile
# 选择: Change delivery only
# 选择交付方式: Skills only

# 仅更新工作流
openspec-cn config profile
# 选择: Change workflows only
# 在清单中切换工作流,然后确认

实用工具命令

`openspec-cn feedback`

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

openspec-cn feedback <message> [options]

参数:

参数	是否必填	描述
`message`	是	反馈消息

选项:

选项	描述
`--body <text>`	详细描述

要求: 必须安装并已认证 GitHub CLI(gh)。

示例:

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

`openspec-cn completion`

管理 OpenSpec CLI 的 shell 补全。

openspec-cn completion <subcommand> [shell]

子命令:

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

支持的 shell: bash, zsh, fish, powershell

示例:

# 安装补全(自动检测 shell)
openspec-cn completion install

# 为指定 shell 安装
openspec-cn completion install zsh

# 生成脚本以手动安装
openspec-cn completion generate bash > ~/.bash_completion.d/openspec

# 卸载
openspec-cn completion uninstall

退出码

码	含义
`0`	成功
`1`	错误(验证失败、文件缺失等)

环境变量

变量	描述
`OPENSPEC_TELEMETRY`	设为 `0` 以关闭遥测
`DO_NOT_TRACK`	设为 `1` 以关闭遥测(标准 DNT 信号)
`OPENSPEC_CONCURRENCY`	批量验证的默认并发度(默认:6)
`EDITOR` 或 `VISUAL`	`openspec-cn config edit` 使用的编辑器
`NO_COLOR`	设置时关闭彩色输出

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI 参考

概览

人工命令与 Agent 命令

仅人工命令

兼容 Agent 的命令

全局选项

初始化命令

openspec-cn init

openspec-cn update

Stores（独立的 OpenSpec 规划仓库）

openspec-cn store setup

openspec-cn store register

openspec-cn store unregister

openspec-cn store remove

openspec-cn store list

openspec-cn store doctor

从项目引用 stores

记录 store 的克隆来源

声明默认 store

Doctor(关系健康)

工作上下文(组装后的集合)

个人 worksets

浏览命令

openspec-cn list

openspec-cn view

openspec-cn show

验证命令

openspec-cn validate

生命周期命令

openspec-cn archive

工作流命令

openspec-cn new change

openspec-cn status

openspec-cn instructions

openspec-cn templates

openspec-cn schemas

Schema 命令

openspec-cn schema init

openspec-cn schema fork

openspec-cn schema validate

openspec-cn schema which

配置命令

openspec-cn config

实用工具命令

openspec-cn feedback

openspec-cn completion

退出码

环境变量

相关文档

`openspec-cn init`

`openspec-cn update`

`openspec-cn store setup`

`openspec-cn store register`

`openspec-cn store unregister`

`openspec-cn store remove`

`openspec-cn store list`

`openspec-cn store doctor`

`openspec-cn list`

`openspec-cn view`

`openspec-cn show`

`openspec-cn validate`

`openspec-cn archive`

`openspec-cn new change`

`openspec-cn status`

`openspec-cn instructions`

`openspec-cn templates`

`openspec-cn schemas`

`openspec-cn schema init`

`openspec-cn schema fork`

`openspec-cn schema validate`

`openspec-cn schema which`

`openspec-cn config`

`openspec-cn feedback`

`openspec-cn completion`