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`	檢查、分支或建立結構描述（實驗性）。

多儲存庫（測試版）

指令	功能說明
`openspec 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>`	覆寫本次執行所使用的全域設定 profile:`core`(標準工作流程集)或 `custom`(儲存在全域設定中的工作流程)。
`--no-animation`	顯示靜態歡迎畫面,而非動畫版本。

輸出

每個選定的工具都會在其專屬目錄中取得 OpenSpec 的 skills 與 commands:

▌ 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 功能推出前安裝的環境取得 profile 時,一併儲存全域設定;
同步 GitHub Copilot 雲端代理程式檔案;
搭配 --force 時,設定僅存在於舊版殘留物中的工具,並清理這些殘留物,包括已淘汰的全域 Codex prompts。

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`	相對於專案的路徑。位於專案之外的檔案(例如全域 skill 或全域設定)會以家目錄為基準顯示為 `~/...`;若檔案也不在家目錄內,則顯示為絕對路徑。
`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 文件:空白計畫加上一個含 severity、code(update_error)與 message 的 status 陣列。結束代碼為 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]`	設定 delivery 模式與工作流程。

設定為整台機器全域共用,以 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          # 可讀的設定與 profile 摘要
openspec config list --json   # 以 JSON 輸出原始設定

選項

旗標	作用
`--json`	以 JSON 格式輸出設定物件。

輸出

依序列出每項設定,最後是將各值標示為明確設定或預設值的 profile 摘要:

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".

在修復之前,telemetry 與更新檢查會保持停用。

openspec config unset

bash

openspec config unset delivery

移除該鍵,讓預設值重新生效。具有內建預設值的鍵一律視為已設定,因此即使您從未設定過,此指令仍會回報成功:

Unset delivery (reverted to default)

完全沒有值的鍵會輸出 Key "featureFlags.nothere" was not set。兩種情況都以結束代碼 0 結束。若設定檔無法解析,則如同 config set 一樣改為以結束代碼 1 結束。

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`。它會選用核心工作流程,並保留您目前的 delivery 設定。

未指定 preset 時,互動式選擇器會顯示您目前的 delivery 與工作流程,讓您變更其中一項或兩者都變更(delivery:兩者、僅 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:已儲存 profile,或您保留了目前的設定。
1:preset 不明、沒有終端機,或所提議的 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 會加入任務計數，以及 no-tasks、in-progress 或 complete 的 status：

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 需求顯示與對應主需求的統一差異。

如果 MODIFIED 標頭僅在忽略大小寫或空白字元後才相符，輸出會同時包含差異與一則警告，說明封存比對是精確的。如果主規格或需求遺失，輸出會發出警告並列印完整的差異區塊。沒有文字差異的 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>`	使用已註冊的 store 作為 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>`	使用已註冊的 store 作為 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 會針對目前的主規格執行封存的合併建構器，但不寫入檔案。它會將合併衝突（例如缺少 MODIFIED 目標，或 ADDED 需求衝突）回報為 INFO：

text

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

即使驗證通過，這些發現項仍會出現在文字與 JSON 輸出中。INFO 永遠不會改變結束代碼，包括在 --strict 之下：缺少的目標可能屬於尚未封存的同層變更。已同步至主規格的差異遵循封存現有的合併規則。

此檢查不會執行封存的後續合併規格驗證或退休檢查。乾淨的報告並不保證封存一定會成功。

如果合併預檢無法啟動，會有一則 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 報告或成功的空報告。

無效的報告請求

兩種明確的報告模式都會在根目錄選擇或項目探索之前拒絕以下請求：

不支援的報告值，包括空字串。
位置項目名稱，即使搭配批次旗標。
沒有明確的批次範圍。
--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 是 Commander 在 stderr 上的語法錯誤，包括搭配 --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

若未指定名稱，封存時會提示您挑選一個變更。在非互動式終端機環境中，它會以退出碼 1 結束，並改為印出重新執行的命令。

引數

引數	說明
`change-name`	要封存的變更，以資料夾名稱（例如 `add-rate-limit`）指定。

選項

旗標	效果
`-y, --yes`	對所有確認提示自動回答「是」：規格更新、未完成的任務、略過的驗證。
`--skip-specs`	封存時不更動主要規格（適用於基礎設施、工具或純文件性質的變更）。
`--no-validate`	略過驗證。封存程式會先要求您確認，而 `-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/，並在名稱前冠上當天日期。每一項差異（delta）都會合併至其主要規格中：上述的 ADDED 需求即被附加至 openspec/specs/api/spec.md。若未加入 -y，封存程式會先顯示預覽，然後在更新前詢問。若拒絕更新，仍會封存變更，但不會異動規格。

搭配 --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"
  }
}

封存前會先驗證變更，若未通過則會拒絕執行：

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.

未完成的任務會發出警告，但不會阻止封存。在互動模式下，封存程式會詢問是否繼續，而 -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 模式中出現。

搭配 --json 且在已有 openspec/ 的專案中：

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

回報單一變更或所有作用中變更的產出物完成狀態。

bash

openspec status --change add-rate-limit          # checklist view
openspec status --change add-rate-limit --json   # structured report
openspec status --all                            # every active change
openspec status --all --json                     # one batch report

當存在作用中的變更時，請恰好使用 --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` 自動偵測到的結構定義。未知名稱會造成錯誤。
`--json`	輸出結構化報告，而非文字。
`--store <id>`	使用已註冊的 store 作為 OpenSpec 根目錄，而非目前專案。

輸出

結構定義中產出物的檢查清單：[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、同時合併了這兩個旗標、變更不存在，或結構定義覆寫為未知名稱。

openspec instructions

輸出建立產出物、套用或封存所需的指示。你的代理程式會在流程中執行此命令，以取得下一步的指示文字。

bash

openspec instructions proposal --change add-rate-limit   # how to write one artifact
openspec instructions apply --change add-rate-limit      # how to implement the change
openspec instructions archive --change add-rate-limit    # inputs for archiving

引數

引數	說明
`artifact`	結構定義中的產出物 ID（在 `spec-driven` 中為 `proposal`、`specs`、`design`、`tasks`），或保留字 `apply` 與 `archive`。

選項

旗標	作用
`--change <id>`	要為其產生指示的變更。必填。
`--schema <name>`	覆寫結構定義。否則會從 `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 一律是布林值：當結構定義設定了非 null 的 apply.tracks 時為 true，即使沒有任何檔案符合也一樣；否則為 false。若某個符合的追蹤檔案無法讀取，unavailableTrackingFiles 會包含其絕對 path 與錯誤 reason。當每個符合的檔案都可讀取時，會省略此欄位。可讀取的檔案仍會納入 tasks 與 progress，但在讀取每個符合的檔案之前，state 不能是 all_done。

結束碼

0：已輸出指示。
1：未知的產出物、未知的變更、未知的結構定義，或缺少 --change。每個錯誤都會列出有效值。

openspec templates

印出結構描述產出物的已解析模板路徑。

bash

openspec templates          # 預設結構描述：spec-driven
openspec templates --json   # 產出物 ID 對路徑的對應

Options

Flag	Effect
`--schema <name>`	要解析的結構描述。預設：`spec-driven`。
`--json`	印出產出物 ID 對模板路徑的 JSON 對應。

Output

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 說明結構描述的解析來源：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"
  }
}

Exit codes

0：已印出路徑。
1：未知的結構描述。錯誤訊息會列出可用的結構描述。

openspec schemas

列出可用的工作流程結構描述。

bash

openspec schemas          # 名稱、描述、產出物順序
openspec schemas --json   # 機器可讀格式，供代理程式使用

Options

Flag	Effect
`--json`	以 JSON 輸出（供代理程式使用）。

Output

Available schemas:

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

來自您專案的結構描述會標記為 (project)，全域覆寫會標記為 (user override)。

json

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

Exit codes

0：已列出結構描述。
1：無法讀取結構描述列表。

openspec schema

檢查、分叉或建立 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`	顯示 schema 的解析來源。
`validate`	檢查 schema 的結構和範本。
`fork`	將現有的 schema 複製到專案中以便自訂。
`init`	建立新的專案本地 schema。

Schema 從三個位置解析。第一個符合的項目優先：

來源	位置
`project`	目前專案中的 `openspec/schemas/`。
`user`	`~/.local/share/openspec/schemas/`（遵循 `XDG_DATA_HOME` 和 Windows `%LOCALAPPDATA%`）。
`package`	CLI 隨附的 schema。`spec-driven` 位於此處。

openspec schema which

顯示 CLI 將使用哪個 schema 複本。

bash

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

Arguments

Argument	說明
`name`	要查詢的 schema。除非設定了 `--all`，否則為必填。若兩者皆未設定，則 which 以退出碼 1 結束。

Options

Flag	效果
`--all`	列出所有 schema 及其解析來源。
`--json`	以 JSON 格式印出解析結果。

Output

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 結束並列出可用的 schema。

openspec schema validate

檢查 schema 的結構和範本。

bash

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

它會驗證 schema.yaml 是否存在且可解析、結構是否符合 schema 格式、每個 artifact 的範本檔案是否存在於 schema 的 templates/ 目錄中，以及相依關係圖沒有循環或未知參照，包括 apply.requires 中的項目。若 apply.tracks 值與任何 artifact 的 generates 值不完全相等，會印出 warning: 行但不會導致驗證失敗，因為 OpenSpec 無法判斷該檔案屬於哪個 artifact 的進度。

Options

Flag	效果
`--json`	印出結構化報告而非文字。
`--verbose`	印出每個驗證步驟。

Output

✓ Schema 'spec-driven' is valid

若未指定名稱，每個專案 schema 會在 Validation Results: 標頭下顯示一行。驗證失敗的 schema 會列出其問題，且執行以退出碼 1 結束：

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

openspec schema fork

將現有的 schema 複製到專案中以便自訂。

bash

openspec schema fork spec-driven my-flow

Arguments

Argument	說明
`source`	要複製的 schema，可來自任何來源位置。
`name`	複本的名稱。Kebab-case（`my-workflow`）。預設值：`<source>-custom`。

Options

Flag	效果
`--force`	覆寫現有的目標 schema。
`--json`	以 JSON 格式印出結果。

Output

✔ 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

分叉後的 schema 位於 openspec/schemas/，且其 schema.yaml 中的 name: 欄位會被改寫為新名稱：

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

若目標已存在，除非傳入 --force，否則會發生錯誤。保留來源名稱的分叉會遮蔽原始 schema。

openspec schema init

建立具有起始範本的新專案本地 schema。

bash

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

在互動式終端機中若未提供 --description 和 --artifacts，init 會提示輸入描述、artifact 檢查清單，以及是否將 schema 設為專案預設值。在非終端機環境中則使用下列預設值。

Arguments

Argument	說明
`name`	新 schema 的名稱。Kebab-case（`my-workflow`）。

Options

Flag	效果
`--description <text>`	Schema 描述。預設值：`Custom workflow schema for <name>`。
`--artifacts <list>`	以逗號分隔的 artifact ID，可選值為 `proposal`、`specs`、`design`、`tasks`。預設值：全部四個。
`--default`	將 `schema: <name>` 寫入現有的 `openspec/config.yaml` 或 `openspec/config.yml`。若兩者皆不存在則建立 `openspec/config.yaml`。新的變更將使用此 schema。
`--no-default`	跳過關於預設值的提示。
`--force`	覆寫同名 schema。
`--json`	以 JSON 格式印出結果。

Schema 建立和 --default 設定更新是一個單一操作。若 OpenSpec 無法驗證或寫入設定，則設定和任何現有 schema 皆維持不變。

Output

✔ 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 將選定的 artifact 與其相依關係連結起來。當包含 tasks 時，還會獲得一個追蹤 tasks.md 的 apply 階段。使用 openspec new --schema my-schema 來使用此 schema。

openspec store

建立和管理 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]`	建立 store 資料夾並註冊。
`register [path]`	註冊現有的 store 資料夾。
`unregister <id>`	移除註冊。資料夾保留在磁碟上。
`remove <id>`	移除註冊並刪除資料夾。
`list`（別名 `ls`）	列出已註冊的 store。
`doctor [id]`	檢查已註冊 store 的註冊狀態、中繼資料和 Git 狀態。

openspec store setup

建立 store 資料夾並註冊。

bash

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

在互動式終端機中，setup 會提示輸入缺失的名稱和位置，並在建立任何內容之前要求確認。在互動式終端機之外，缺失名稱或 --path 會以退出碼 1 結束並顯示應傳入的旗標。對已註冊的 store 重新執行 setup 會報告 Registry: already registered。

當 --path 位於另一個 Git 儲存庫內時，setup 會以 store_setup_inside_git_repo 錯誤碼 1 結束，因為在該處初始化 store 會導致儲存庫巢狀嵌套。--no-init-git 不會建立儲存庫，因此會跳過該檢查。當您的主目錄本身就是 Git 儲存庫（例如 dotfiles 儲存庫）時，可使用它在 ~/openspec/<id> 保留 store。

Arguments

Argument	說明
`id`	Store 名稱。它會成為您傳給 `--store` 的 id。

Options

Flag	效果
`--path <path>`	Store 應存放的資料夾（`~` 會展開）。
`--init-git`	初始化 Git 儲存庫並建立初始提交。預設值。
`--no-init-git`	跳過所有 Git 操作：不初始化、不建立初始提交。
`--remote <url>`	記錄在 `store.yaml` 中的標準 clone 來源。

Output

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

註冊現有的 store 資料夾，例如您克隆的團隊成員 store。

bash

openspec store register ~/stores/design-system

資料夾必須包含健康的 openspec/ 根目錄。若存在 .openspec-store/store.yaml，register 會重複使用記錄的 id。若不存在，register 會在建立該中繼資料之前先詢問。在互動式終端機之外，請改為傳入 --yes。每台機器可為每個 store id 註冊一個 checkout。同一 id 下的第二個路徑，或第二個 id 下的相同路徑，會以退出碼 1 結束。

Arguments

Argument	說明
`path`	要註冊的 store 資料夾（`~` 會展開）。必填。

Options

Flag	效果
`--id <id>`	Store id。預設值為中繼資料或資料夾名稱。
`--yes`	確認為健康的 OpenSpec 根目錄建立 store 身分中繼資料。

Output

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

當資料夾缺少相符的 store 中繼資料，或包含另一個已註冊的 store（例如作為 Git submodule 引入的 store）時，remove 會以退出碼 1 結束且不刪除任何內容。在這種情況下，錯誤為 store_remove_contains_registered_store：請先執行 openspec store unregister <nested-id>，或執行 openspec store unregister <id> 以移除 store 但不刪除檔案。

Options

Flag	效果
`--yes`	確認刪除本機 store 資料夾。

Output

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

openspec store list

列出已註冊的 store。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

檢查已註冊 store 的註冊狀態、中繼資料和 Git 狀態。

bash

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

Output

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

Exit codes

0：報告已印出，即使 store 回報問題。
1：報告無法執行（例如未知的 store id）。

openspec doctor

報告已解析 OpenSpec 根目錄的關係健康狀態。

bash

openspec doctor                       # cwd 上方最近的 openspec/ 根目錄
openspec doctor --store team-context  # 以已註冊的 store 作為根目錄

Doctor 為唯讀：它從不進行複製、同步或修復。它會報告根目錄是否健康，以及 openspec/config.yaml 中宣告的每個參考是否可於本機解析。如果 cwd 上方沒有根目錄且未指定 --store，它會以退出碼 1 結束並列出已註冊的 stores。

選項

旗標	效果
`--store <id>`	使用已註冊的 store 作為 OpenSpec 根目錄，而非目前專案。
`--json`	以 JSON 格式輸出健康報告。

輸出

Doctor

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

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

使用 --store 時，根目錄為 store，且報告會新增一行 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 中宣告的每個參考 store，並附上擷取指令。

bash

openspec context                       # cwd 上方最近的 openspec/ 根目錄
openspec context --store team-context  # 以已註冊的 store 作為根目錄
openspec context --json                # agent brief

在本機上無法解析的參考會列在「Not available on this machine」區段中，並附上修復方式。

選項

旗標	效果
`--store <id>`	使用已註冊的 store 作為 OpenSpec 根目錄，而非目前專案。
`--json`	以 JSON 格式輸出 agent brief。
`--code-workspace <path>`	同時為這個集合寫入 VS Code workspace 檔案。
`--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 時，該 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": []
}

寫入 workspace 檔案

--code-workspace 會在指定的路徑寫入 VS Code workspace 檔案：根目錄一個資料夾，每個可用的參考 store 一個 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   # 別名：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                # 已儲存的工具，或出現提示
openspec workset open checkout --tool cursor  # 僅這一次使用此工具

引數

引數	說明
`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                 # 本機版本與安裝細節
openspec version --json          # 結構化本機報告
openspec version --check         # 同時檢查 registry 是否有更新
openspec version --check --json  # 結構化本機與更新報告

在沒有 --check 的情況下，此命令只在本機運作，不會連絡 registry。它可在 OpenSpec 專案之外運作。既有的 openspec --version 旗標仍是最簡短的形式，只會輸出單純的版本號碼。

選項

旗標	效果
`--json`	輸出一份具版本編號的 JSON 文件，而非純文字。
`--check`	檢查所設定的 registry 是否有較新的版本。

輸出

以 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`	registry 回傳了比目前執行版本更新的安全版本。
`current`	檢查已完成，未發現較新的版本。
`disabled`	既有的隱私或更新檢查設定阻擋了對 registry 的存取。`latest` 為 `null`。
`offline`	registry 無法使用，或回傳了無法使用的回應。`latest` 為 `null`。

若是獨立安裝，更新命令為 openspec install。

DO_NOT_TRACK、遙測退出設定、OPENSPEC_NO_UPDATE_CHECK、CI 偵測，以及遭拒絕的非 HTTPS registry 覆寫，都會停用此檢查。已停用與離線的檢查仍會以結束代碼 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，將你的訊息提交為 Fission-AI/OpenSpec 儲存庫上的 GitHub issue。標題會變成 Feedback: <message>。內文使用錯誤回報表單的區段標題：你的訊息置於 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 --- 標記之間，然後印出一個可開啟錯誤回報表單的連結，表單中的標題、發生什麼事（你的訊息與 --body 文字）、CLI 版本與環境（平台與 Node 版本）皆已填好。你在瀏覽器中完成表單其餘部分。未登入的情況會附加 To auto-submit in the future: gh auth login。

結束代碼

0：已建立 issue，或已執行手動提交的備援流程（沒有 gh，或 gh 未登入）。
1：未提供訊息。
gh 自身的結束代碼：gh 在驗證後失敗（網路、速率限制、issues 已停用）。CLI 會先重新印出你的回饋與手動提交 URL。

openspec completion

安裝或產生 shell 補全。

bash

openspec completion install        # 偵測你的 shell、安裝並設定好 config
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

# OpenSpec CLI 的 Zsh 補全指令碼
# 自動產生 - 請勿手動編輯

_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	`OpenSpecCompletion.ps1` 位於你的 profile 旁	`$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：已產生、安裝或移除指令碼。取消的 uninstall 也會以 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