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 整合

人類與代理命令

大多數 CLI 命令是為終端機中的人類使用而設計的。部分命令也透過 JSON 輸出支援代理/腳本使用。

僅限人類的命令

這些命令為互動式設計，適用於終端機使用：

命令	用途
`openspec init`	初始化專案（互動式提示）
`openspec view`	互動式儀表板
`openspec workset open <name>`	開啟已儲存的 workset（編輯器視窗或終端機代理工作階段）
`openspec config edit`	在編輯器中開啟設定檔
`openspec feedback`	透過 GitHub 提交回饋
`openspec completion install`	安裝 shell 補全功能

代理相容命令

這些命令支援 --json 輸出，供 AI 代理和腳本程式化使用：

命令	人類使用	代理使用
`openspec list`	瀏覽變更/規格	`--json` 取得結構化資料
`openspec show <item>`	閱讀內容	`--json` 供解析使用
`openspec validate`	檢查問題	`--all --json` 進行批量驗證
`openspec status`	查看產物進度	`--json` 取得結構化狀態
`openspec instructions`	取得下一步驟	`--json` 取得代理指示
`openspec templates`	尋找範本路徑	`--json` 供路徑解析
`openspec schemas`	列出可用 schema	`--json` 供 schema 探索；`--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>`	建立 repo 本地變更骨架	`--json`，另可搭配 `--store <id>` 使用已註冊的儲存庫作為 OpenSpec 根目錄
`openspec workset create [name]`	組合個人工作檢視	`--member <path> --json` 進行非互動式組合
`openspec workset list`	瀏覽已儲存的 workset	`--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>`	覆寫本次 init 的全域 profile（`core` 或 `custom`）
`--no-animation`	顯示靜態歡迎畫面而非動畫版本
`--copilot-cloud`	設定 GitHub Copilot 雲端編碼代理檔案，無需提示
`--no-copilot-cloud`	跳過 GitHub Copilot 雲端編碼代理檔案，無需提示

--profile custom 使用全域設定（openspec config profile）中目前選取的 workflows。

當設定 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 對應。各工具的 skill 和命令路徑請參閱支援的工具。

範例：

bash

# 互動式初始化
openspec init

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

# 非互動式：設定 Claude 和 Cursor
openspec init --tools claude,cursor

# 非互動式：設定全域 MiniMax Code skills
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 skills（若選取 claude）
.cursor/skills/         # Cursor skills（若選取 cursor）
.cursor/commands/       # Cursor OPSX 命令（若 delivery 包含 commands）
.agents/skills/         # 適用於 AGENTS.md 相容工具的共用 skills（若選取 agents）
...（其他工具設定）

`openspec update`

升級 CLI 後更新 OpenSpec 指示檔案。使用目前的全域 profile、選取的 workflows 和 delivery 模式重新產生 AI 工具設定檔案。

openspec update [path] [options]

參數：

參數	必要	說明
`path`	否	目標目錄（預設：目前目錄）

選項：

選項	說明
`--force`	即使檔案已是最新也強制更新

範例：

bash

# npm 升級後更新指示檔案
npm install -g @fission-ai/openspec@latest
openspec update

請先升級套件。指示檔案由已安裝的 CLI 產生，因此對舊版安裝執行 openspec update 會回報一切已是最新，而不會加入較新版本附帶的 workflows。

為了讓這個問題可見，openspec update 會向 npm registry 查詢是否有更新的 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 重新執行更新，使新的 workflows 在同一個命令中落地。它透過詢問已安裝二進位檔的版本來確認升級，而非信任 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`
專案的依賴套件	提示更新依賴套件，因為其 lockfile 由該套件管理器管理
`npx` / `dlx` 快取	`npx @fission-ai/openspec@latest update` — 該命令本身就是更新，因此沒有第二步
Git clone	無 — 您的版本取決於分支內容

無論何時印出內容，都會標示執行中的 CLI 所載入的目錄——當您已升級但舊的 shim 仍佔據 PATH 時，這是需要檢查的地方。

當 npm 匯出 npm_config_registry 時，它會向該 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 秒 — 即使網路靜默丟包也會在那之後放棄，且在 registry 無法連線時保持靜默。

「已是最新」的判定方式： skill 檔案會記錄產生它們的版本，因此 OpenSpec 會將其與已安裝的 CLI 進行比較。命令檔案不攜帶版本戳記，因此對於有命令但無 skills 的工具（delivery commands），OpenSpec 會將檔案內容與目前會產生的內容進行比較 — 對這些檔案的編輯視為漂移並會被覆寫。當 delivery 為 skills 或 both 時，僅檢查記錄的版本，因此手動編輯但版本仍相符的檔案會被保留；使用 --force 可強制重寫。無論如何，產生的檔案歸 OpenSpec 所有 — 請將您自己的指示存放在其他地方。

Stores（獨立的 OpenSpec 儲存庫）

Beta。 Stores 及其相關功能（references、working context、worksets）為新推出功能；指令名稱、旗標、檔案格式及 JSON 輸出可能在版本之間有所變動。如需問題導向的逐步教學，請參閱 stores 指南。

Store 是您在本機上註冊的獨立 OpenSpec 儲存庫——例如規劃儲存庫或合約儲存庫。註冊 store 後，一般指令（list、show、status、validate、new change、archive、...）即可透過傳遞 --store <id> 從任何位置在該 store 中操作。

`openspec store setup`

建立並註冊本機 store。在終端機中不帶參數執行時，OpenSpec 會引導使用者完成設定。Agent 和腳本應傳遞明確輸入並使用 --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、腳本、agent）必須同時傳遞 store id 和 --path。在互動式終端機中，設定會提示使用者輸入位置，並提供可編輯的建議路徑，位於使用者可視且擁有的位置（例如 ~/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 在互動式終端機中刪除前會顯示確切的資料夾。Agent、腳本和 JSON 呼叫者必須傳遞 --yes 以確認刪除。OpenSpec 拒絕刪除不包含相符 store 中繼資料的資料夾。

`openspec store list`

列出本機已註冊的 stores。

bash

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

`openspec store doctor`

檢查本機 store 註冊、中繼資料和 Git 狀態。

bash

openspec store doctor [id] [--json]

Doctor 僅供診斷用途；它會報告缺失的根目錄、中繼資料不匹配和無效的本機註冊表狀態，但不會修改 store。

從專案引用 stores

專案儲存庫可在 openspec/config.yaml 中宣告其工作所依賴的 stores：

yaml

schema: spec-driven
references:
  - team-context

從此之後，該儲存庫中的 openspec instructions 輸出（包括每個 artifact 和 apply 介面，JSON 和人類模式）都會包含每個被引用 store 的規格索引——規格 id、每個規格 Purpose 章節的一行摘要，以及擷取指令（openspec show <spec-id> --type spec --store <id>）。索引會從已註冊的 checkout 即時建立，每次執行都會重新生成；規格內容絕不會被複製到輸出中。

References 為唯讀上下文。它們絕不會改變指令的操作位置：工作仍留在儲存庫自身的根目錄中，而寫入被引用的 store 仍為明確的 --store 操作。無法解析的引用（例如，本機未註冊的 store）會降級為索引中的警告，並附上確切的修復方式，instructions 仍會正常生成。openspec doctor 會在一處報告引用健康狀態。

記錄 store 的克隆來源

Store 可在其已提交的識別檔案中記錄規範克隆來源，以便 onboarding 不會在「註冊 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 會顯示記錄的遠端（以及 checkout 觀察到的 Git origin）；setup/register 的共用指引會提及它；register 會將 checkout 的 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"。

Doctor（關係健康）

一個唯讀的檢查，集中於一個問題：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 摘要可供代理程式使用（每個可用的引用儲存庫都帶有取得配方；未解析的成員帶有相同的修復指令和 Doctor 顯示）。--code-workspace 額外寫入一個包含根目錄及可用引用儲存庫（ref:<id> 資料夾）的 VS Code 工作區檔案——這是此命令執行的唯一寫入操作，若檔案存在則需 --force 才會寫入。不可用的成員會被報告，絕不會被猜測。

「工作上下文」是組合集合；openspec/config.yaml 中的 context: 欄位是注入到指令中的專案背景——兩者不同。openspec doctor 回答集合是否健康；openspec context 回答集合是什麼。

個人工作集

測試版。 工作集是新的測試版功能的一部分；命令、旗標和檔案格式可能在不同版本間變更。如需逐步指南，請參閱儲存庫指南。

工作集是您一起工作的資料夾的個人命名視圖——規劃根目錄加上您選擇的其他內容——保存在您的機器上，並在您的工具中按名稱重新開啟。它純粹是本地性質：永遠不會提交、不會共享、不會從宣告中衍生，且移除一個工作集永遠不會影響成員資料夾。

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（使用 openspec config edit 開啟）中的 openers 鍵可新增工具或調整內建工具，依欄位設定：

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 起始的索引指定（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]

若一個變更的規格差異（spec deltas）為零，則驗證會失敗，除非其 .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 中的所有核取方塊，若有任何未勾選則以非零狀態退出。這能捕捉到帶有未完成工作的歸檔變更 — 非常適合用於預提交鉤子（pre-commit hook）。

範例：

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 作業，或任何標準輸入關閉的執行環境
`--skip-specs`	跳過此次歸檔的規格更新。若一個變更永久沒有規格差異，應在其 `.openspec.yaml` 中宣告 `skip_specs: true` — 歸檔時無需帶此旗標
`--no-validate`	跳過驗證（需確認）。同時停用能力退休（capability retirement）— 若無驗證器裁決，則不會進行退休操作

範例：

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 在 schema: 旁宣告了 retire_capabilities: true
將變更資料夾移至 openspec/changes/archive/YYYY-MM-DD-<name>/
若在完整歸檔完成前發生規格變更或最終移動失敗，則恢復規格，並將變更保留或返回至其活躍路徑
若已驗證的備份副本完成但暫存來源清理失敗，則保留完整的歸檔內容與已提交的規格狀態以供恢復

無終端環境下： AI 代理程式、CI 作業，或任何標準輸入關閉的執行環境無法回答第 2 步，因此歸檔會在觸及任何內容前停止，以狀態碼 1 退出，並列出重新執行的命令 — openspec archive <name> --yes，攜帶您傳遞的其他任何旗標。提前傳入 --yes（以及變更名稱）以跳過往返確認過程。

工作流程命令

以下命令支援以產物為導向的 OPSX 工作流程。它們對人類檢查進度以及代理程式判斷下一步驟都非常實用。

`openspec new change`

在已解析的 OpenSpec 根目錄中建立變更目錄及選填的已簽入元資料。

bash

openspec new change <name> [options]

變更名稱必須使用小寫 kebab-case：小寫字母、數字和單個連字號。不得包含空格、底線、大寫字母、連續連字號或首尾連字號。允許以數字開頭，因此您可以使用數字前綴來排序或分層變更，例如 100-add-feature 或 00001-add-auth。

選項：

選項	說明
`--description <text>`	要新增至 `index.md` 的說明
`--goal <text>`	要與變更一起儲存的選填目標元資料
`--schema <name>`	要使用的工作流程 schema
`--store <id>`	要作為 OpenSpec 根目錄的 store id（store 是您已註冊的獨立 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>`	Schema 覆寫（從變更的設定自動偵測）
`--json`	以 JSON 格式輸出

範例：

bash

# 互動式狀態檢查
openspec status

# 特定變更的狀態
openspec status --change add-dark-mode

# 供代理程式使用的 JSON
openspec status --change add-dark-mode --json

輸出（文字）：

Change: add-dark-mode
Schema: spec-driven
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）會保持 schema 宣告的順序，而非字母順序。因此第一個 ready 項目就是接下來要撰寫的產物。

`openspec instructions`

取得建立產物或套用任務的豐富指令。供 AI 代理程式了解接下來要建立什麼。

openspec instructions [artifact] [options]

參數：

參數	必填	說明
`artifact`	否	產物 ID，或工作流程輸入介面：`apply` 或 `archive`

選項：

選項	說明
`--change <id>`	變更名稱（非互動模式下必填）
`--schema <name>`	Schema 覆寫
`--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 的目前專案上下文和對應的操作指引

操作輸入會在每次調用時從已解析的儲存庫或選定的 store 讀取。專案上下文是必填的提示層級輸入：代理程式會讀取它並套用相關的專案事實、慣例和約束。操作指引是可選的附加建議：代理程式會考慮每個條目，僅遵循適用且與內建工作流程相容的條目。這兩個欄位均與明確的使用者選擇、CLI 控制的狀態、內建指令和產物規則保持分離。衝突的上下文會被報告；衝突或不適用的指引不會被遵循，並會說明原因。這些是為產生的代理程式設定的行為契約，而非可強制執行的 CLI 檢查。instructions archive 僅返回選定的變更、選填輸入和根元資料；不包含靜態封存工作流程。

對於透過 skip_specs: true 跳過的產物，輸出僅為警告（JSON 會新增 skipped/warning 欄位）——該產物不得建立。

`openspec templates`

顯示 schema 中所有產物的已解析範本路徑。

openspec templates [options]

選項：

選項	說明
`--schema <name>`	要檢視的 schema（預設：`spec-driven`）
`--json`	以 JSON 格式輸出

範例：

bash

# 顯示預設 schema 的範本路徑
openspec templates

# 顯示自訂 schema 的範本
openspec templates --schema my-workflow

# 供程式化使用的 JSON
openspec templates --json

輸出（文字）：

Schema: spec-driven

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

`openspec schemas`

列出可用的工作流程 schema 及其說明和產物流程。

openspec schemas [options]

選項：

選項	說明
`--json`	以 JSON 格式輸出
`--store <id>`	使用已註冊的 store 作為 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 指令

用於建立和管理自訂工作流程 schema 的指令。

`openspec schema init`

建立新的專案本地 schema。

openspec schema init <name> [options]

引數：

引數	必填	說明
`name`	是	Schema 名稱（kebab-case）

選項：

選項	說明
`--description <text>`	Schema 描述
`--artifacts <list>`	逗號分隔的 artifact ID（預設：`proposal,specs,design,tasks`）
`--default`	設為專案預設 schema
`--no-default`	不提示設為預設
`--force`	覆寫現有 schema
`--json`	以 JSON 輸出

範例：

bash

# 互動式建立 schema
openspec schema init research-first

# 非互動式並指定特定 artifacts
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

建立的內容：

openspec/schemas/<name>/
├── schema.yaml           # Schema 定義
└── templates/
    ├── proposal.md       # 每個 artifact 的範本
    ├── specs.md
    ├── design.md
    └── tasks.md

`openspec schema fork`

複製現有 schema 到您的專案以進行自訂。

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

引數：

引數	必填	說明
`source`	是	要複製的 Schema
`name`	否	新的 schema 名稱（預設：`<source>-custom`）

選項：

選項	說明
`--force`	覆寫現有目的地
`--json`	以 JSON 輸出

範例：

bash

# 複製內建的 spec-driven schema
openspec schema fork spec-driven my-workflow

`openspec schema validate`

驗證 schema 的結構和範本。

openspec schema validate [name] [options]

引數：

引數	必填	說明
`name`	否	要驗證的 Schema（省略時驗證全部）

選項：

選項	說明
`--verbose`	顯示詳細驗證步驟
`--json`	以 JSON 輸出

範例：

bash

# 驗證特定 schema
openspec schema validate my-workflow

# 驗證所有 schema
openspec schema validate

`openspec schema which`

顯示 schema 的解析來源（有助於除錯優先順序）。

openspec schema which [name] [options]

引數：

引數	必填	說明
`name`	否	Schema 名稱

選項：

選項	說明
`--all`	列出所有 schema 及其來源
`--json`	以 JSON 輸出

範例：

bash

# 檢查 schema 的來源
openspec schema which spec-driven

輸出：

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

Schema 優先順序：

專案：openspec/schemas/<name>/
使用者：~/.local/share/openspec/schemas/<name>/
套件：內建 schemas

設定指令

`openspec config`

檢視和修改全域 OpenSpec 設定。

openspec config <subcommand> [options]

子指令：

子指令	說明
`path`	顯示設定檔位置
`list`	顯示所有目前設定
`get <key>`	取得特定值
`set <key> <value>`	設定值
`unset <key>`	移除鍵
`reset`	重設為預設值
`edit`	在 `$EDITOR` 中開啟
`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、
# 本地根目錄或專案 store：指標解析時的備援根）
openspec config set defaultStore team-plans

# 重設所有設定
openspec config reset --all --yes

# 在編輯器中編輯設定
openspec config edit

# 以動作精靈設定設定檔
openspec config profile

# 快速預設值：將工作流程切換為 core（保留交付模式）
openspec config profile core

遙測退出： 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（或在專案內提示時選擇「立即將變更套用至此專案？」）。

互動式範例：

bash

# 僅更新交付
openspec config profile
# 選擇：僅變更交付
# 選擇交付：僅限 Skills

# 僅更新工作流程
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 完成（completion）。

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`	設定時（任何值，包括空）停用 `openspec update` 對較新發佈 CLI 的檢查。當設定 `CI`（除非為 `false`/`0`/`no`/`off`）或 `NODE_ENV=test` 時也會略過
`npm_config_registry`	`openspec update` 版本檢查所查詢的 registry。必須是 `http(s)` URL，否則會回退到 `https://registry.npmjs.org`。不會讀取任何 `.npmrc` 檔案

CLI 參考 ​

摘要 ​

人類與代理命令 ​

僅限人類的命令 ​

代理相容命令 ​

全域選項 ​

設定命令 ​

openspec init ​

openspec update ​

Stores（獨立的 OpenSpec 儲存庫） ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

從專案引用 stores ​

記錄 store 的克隆來源 ​

宣告預設 store ​

Doctor（關係健康） ​

工作上下文（組合集合） ​

個人工作集 ​

瀏覽命令 ​

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 參考

摘要

人類與代理命令

僅限人類的命令

代理相容命令

全域選項

設定命令

`openspec init`

`openspec update`

Stores（獨立的 OpenSpec 儲存庫）

`openspec store setup`

`openspec store register`

`openspec store unregister`

`openspec store remove`

`openspec store list`

`openspec store doctor`

從專案引用 stores

記錄 store 的克隆來源

宣告預設 store

Doctor（關係健康）

工作上下文（組合集合）

個人工作集

瀏覽命令

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

結束代碼

環境變數

相關文件