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`	1 つまたはすべてのアクティブな変更の成果物の完了状態。
`openspec instructions`	成果物の作成、適用、アーカイブに関する指示。
`openspec templates`	スキーマの成果物に対する解決済みテンプレートパス。
`openspec schemas`	利用可能なワークフロースキーマを一覧表示します。
`openspec schema`	スキーマの検査、フォーク、作成（実験的）。

マルチリポジトリ（ベータ）

コマンド	説明
`openspec store`	マシンに登録されたスタンドアローンの OpenSpec リポジトリであるストアを作成・管理します。
`openspec doctor`	解決された OpenSpec ルートの関係健全性をレポートします。
`openspec context`	解決された OpenSpec ルートの作業コンテキストを出力します。
`openspec workset`	個人の作業ビューを構成、保持、開きます。

ユーティリティ

コマンド	説明
`openspec version`	インストール済みバージョンを報告し、オプションで更新を確認します。
`openspec install`	Node.js なしで動作するスタンドアローンの `openspec` をインストールします。
`openspec feedback`	OpenSpec に関するフィードバックを送信します。
`openspec completion`	シェル補完をインストールまたは生成します。

非推奨

コマンド	説明
`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: 行が含まれており、リポジトリにローカルの仕様や変更がない場合、init はリポジトリのルートから実行してください。

bash

# コードリポジトリに Claude Code 統合ファイルをインストール
openspec init --tools claude

統合ファイル: コードリポジトリに書き込まれます。
openspec/config.yaml: バイト単位で保持されます。
openspec/specs/ および openspec/changes/: コードリポジトリには作成されません。

サブディレクトリから init を実行すると終了コード 1 で終了し、リポジトリのルートから実行するよう指示します。--language も終了コード 1 で終了します。言語設定は外部ストアの設定に含まれるためです。init をストアのルートで実行するか、その設定を直接編集してください。

引数

引数	説明
`path`	初期化するプロジェクトディレクトリ。デフォルト: カレントディレクトリ。存在しない場合は作成されます。

オプション

フラグ	効果
`--tools <tools>`	コンマ区切りのツールID、`all`、または `none`。選択プロンプトをスキップします。ID はサポートされているツールに一覧があります。
`--language <language>`	新しいプロジェクト設定に言語指示を追加します。リポジトリの `store:` 行が外部ストアを指している場合は拒否されます。
`--force`	確認なしに古い OpenSpec レイアウトのファイルを削除します。インタラクティブ実行では、最初にクリーンアップの確認を求めます。
`--profile <profile>`	この実行でグローバル設定プロファイルを上書きします: `core`（標準ワークフローセット）または `custom`（グローバル設定に保存されたワークフロー）。
`--no-animation`	アニメーション画面の代わりに静的なウェルカム画面を表示します。

出力

選択された各ツールに対して、OpenSpec のスキルとコマンドがそれぞれのディレクトリに配置されます。

▌ OpenSpec 構造を作成しました
✔ Claude Code のセットアップが完了しました

OpenSpec のセットアップが完了しました

作成: Claude Code
.claude/ 内に 6 つのスキルと 6 つのコマンド
設定: openspec/config.yaml (スキーマ: spec-driven)

はじめに:
  最初の変更を開始: /opsx:propose "あなたのアイデア"

新しいコマンドを有効にするには IDE を再起動してください。

--tools none を指定すると、openspec/config.yaml のみが作成されます。既に初期化済みのプロジェクトでは、init はインストール済みファイルをその場で再書き込みし、サマリーには 更新: Claude Code と表示され、設定: openspec/config.yaml (存在) と表示されます。

終了コード

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/)
プロファイルが導入される前のインストールからのグローバル設定の保存
GitHub Copilot クラウドエージェントファイルの同期
--force 指定時: レガシーアーティファクトにのみ存在するツールのセットアップとそれらのクリーンアップ（廃止されたグローバル Codex プロンプトを含む）

bash

openspec update --dry-run

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

--dry-run --json は同じ計画を 1 つの JSON ドキュメントとして出力します:

json

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

フィールド	内容
`changes[].path`	プロジェクト相対パス。プロジェクト外のファイル（グローバルスキルやグローバル設定など）は、ホームディレクトリからの相対パス `~/...` またはホーム外の場合は絶対パスで表示されます。
`changes[].action`	`add`、`update`、または `delete`。新しい内容が以前と同じファイルは一覧に含まれません。
`changes[].tool`	ファイルが属する設定済みツール（例: `claude`）。ツールではなく OpenSpec 自体に属するファイル（グローバル設定やレガシーアーティファクトのクリーンアップ）は `openspec` です。
`notes[]`	ターミナルユーザーに確認が求められるステップの `{ code, message }`。`legacy-tool-directories`: インタラクティブ実行で最初に確認される移動。`changes` には実施済みとして表示されます。`legacy-artifacts`: 古いレイアウトのファイル（`openspec-proposal.md` スラッシュコマンドや `AGENTS.md` 内の OpenSpec マーカーブロックなど）が見つかった場合。`--force` がない非インタラクティブ更新ではそのままにされるため、`changes` にも含まれません。`--dry-run --force` ではそれらのクリーンアップが表示されます。通常の更新では空です。
`failures[]`	実際の更新が失敗するツールごとの `{ tool, error }`。ディレクトリがファイルに必要な場所にある、ファイルがディレクトリに必要な場所にある、または書き込み権限のないファイル/フォルダなど、書き込みが不可能な場合が含まれます。そのツールでは、`changes` は実際の更新が停止する地点で止まります。他のツールは引き続き計画されます。ディスク容量不足など、書き込み時にのみ報告される障害は予見できません。

計画前のエラー（OpenSpec ディレクトリがないなど）でも、正確に 1 つの JSON ドキュメントを出力します。空の計画に加え、severity、code（update_error）、message を含む status 配列が含まれます。終了コードは 1 です。

出力

すべてのツールのファイルが CLI バージョンと一致する場合:

✓ 1 個のツールが最新です (v1.7.0)
  ツール: claude

強制的にリフレッシュするには --force を使用してください。

ツールのファイルが古い CLI バージョンに由来する場合（または --force を指定し、1 個のツールを強制更新中: claude と表示される場合）:

1 個のツールを更新中: claude (1.6.0 → 1.7.0)

✔ Claude Code を更新しました

✓ 更新完了: Claude Code (v1.7.0)
ツール: Claude Code

変更を有効にするには IDE を再起動してください。

OpenSpec のないディレクトリでは、update は拒否されます:

✖ エラー: OpenSpec ディレクトリが見つかりません。最初に 'openspec init' を実行してください。

終了コード

0: ファイルが更新された、またはすべてが最新でした。
1: 指定パスに OpenSpec ディレクトリがない、または更新が失敗した。

openspec config

グローバル設定を表示・変更します。

bash

openspec config list                  # 現在の設定を表示
openspec config set delivery skills   # 値を変更
openspec config profile               # インタラクティブワークフロー選択

サブコマンド	説明
`path`	設定ファイルの場所を表示します。
`list`	現在の設定をすべて表示します。
`get <key>`	1 つの値を raw でスクリプト向けに出力します。
`set <key> <value>`	値を設定し、型を強制します。
`unset <key>`	キーを削除してデフォルトを適用します。
`reset`	全設定をデフォルトにリセットします。
`edit`	`$EDITOR` で設定ファイルを開きます。
`profile [preset]`	配信モードとワークフローを設定します。

設定はマシン全体でグローバルであり、config path が指す場所に JSON として保存されます。$XDG_CONFIG_HOME/openspec/config.json が設定されていればそれ、そうでなければ ~/.config/openspec/config.json（macOS, Linux）または %APPDATA%\openspec\config.json（Windows）です。すべてのサブコマンドは --scope <scope> を受け付けますが、現在は global のみが機能します。それ以外のスコープは終了コード 1 で Error: Project-local config is not yet implemented と表示されます。

openspec config path

bash

openspec config path

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

openspec config list

bash

openspec config list          # 読みやすい設定とプロファイルサマリー
openspec config list --json   # 生の設定を JSON で表示

オプション

フラグ	効果
`--json`	設定オブジェクトを JSON で表示します。

出力

各設定、続いて明示的かデフォルトかを示すプロファイルサマリー:

featureFlags: {}
profile: core
delivery: both

プロファイル設定:
  profile: core (デフォルト)
  delivery: both (デフォルト)
  workflows: propose, explore, apply, update, sync, archive (core プロファイルから)

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`	スキーマにないキーを許可します。

出力

featureFlags.workspaces を true に設定しました

不明なキーや無効な値は、保存前に終了コード 1 で失敗します:

エラー: 無効な設定キー "bogus.key"。不明なトップレベルキー "bogus"。
"openspec config list" で利用可能なキーを確認してください。
--allow-unknown を渡すと、このチェックを回避できます。

エラー: 無効な設定 - delivery: 無効なオプション: "both"|"skills"|"commands" のいずれかが必要です

設定ファイルが存在しても JSON オブジェクトを保持していない場合（有効な JSON ではない、ルートが null や配列など）、config set、config unset、config profile は終了コード 1 で終了し、ファイルは変更されません。openspec config edit で修正するか、openspec config reset --all で置き換えます:

エラー: /home/you/.config/openspec/config.json を解析できなかったため、変更されませんでした。
"openspec config edit" で修正するか、"openspec config reset --all" でリセットしてください。

修正されるまで、テレメトリと更新チェックはオフのままです。

openspec config unset

bash

openspec config unset delivery

キーを削除してデフォルトが再適用されるようにします。組み込みのデフォルトを持つキーは常に設定済みと見なされるため、設定したことがなくても成功が報告されます:

delivery を削除しました（デフォルトに戻りました）

まったく値のないキーは キー "featureFlags.nothere" は設定されていませんでした と出力します。どちらの場合も終了コード 0 です。config set と同様に、解析できない設定ファイルでは終了コード 1 になります。

openspec config reset

bash

openspec config reset --all      # 確認を求める
openspec config reset --all -y   # プロンプトなし

オプション

フラグ	効果
`--all`	必須。すべてをリセットします。
`-y, --yes`	確認プロンプトをスキップします。

出力

設定がデフォルトにリセットされました

--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）。これはシェルを介さずに単語分割されるため、$VAR、~、; はそのまま渡されます。起動できないエディタや、ゼロ以外の終了コードで終了するエディタは、1 行のエラーを表示して終了コード 1 で終了します。

エディタが設定されていない場合は終了コード 1 で終了します:

エラー: エディタが設定されていません
EDITOR または VISUAL 環境変数をお好みのエディタに設定してください
例: export EDITOR=vim

openspec config profile

bash

openspec config profile        # インタラクティブ選択（端末が必要）
openspec config profile core   # core プリセットを直接適用

引数

引数	説明
`preset`	オプションのプリセット名。存在するのは `core` のみです。core ワークフローを選択し、配信設定は維持されます。

プリセットなしの場合、インタラクティブ選択が表示され、現在の配信とワークフローを変更できます（配信: both、スキルのみ、コマンドのみ。ワークフロー: チェックボックスリスト）。差分を表示し、OpenSpec プロジェクト内であれば openspec update の実行を提案します。端末以外では終了コード 1 で終了します:

インタラクティブモードが必要です。`openspec config profile core` を使用するか、環境変数/フラグで設定してください。

出力

変更された設定は、プロジェクトで更新されるまで反映されません:

設定が更新されました。プロジェクトで `openspec update` を実行して適用してください。

終了コード

0: プロファイルが保存された、または現在の設定を維持した。
1: 不明なプリセット、端末がない、または提案された openspec update が失敗した。
130: Ctrl-C で選択がキャンセルされた。

openspec list

変更を一覧表示します。--specs を指定するとスペックを一覧表示します。

bash

openspec list                    # アクティブな変更を、最終更新が新しい順に表示
openspec list --archived         # アーカイブ済みの変更
openspec list --all              # アクティブおよびアーカイブ済みの変更
openspec list --specs            # 要件数を含むスペック
openspec list --json             # 機械可読形式。解決されたルートを含む

行は、解決されたルート配下の openspec/changes/ および openspec/specs/ から取得されます。デフォルトの変更一覧では openspec/changes/archive/ がスキップされます。

オプション

フラグ	効果
`--specs`	変更の代わりにスペックを一覧表示します。
`--changes`	変更を一覧表示します。これがデフォルトです。
`--archived`	アーカイブ済みの変更のみを一覧表示します。`--specs` と組み合わせることはできません。
`--all`	アクティブおよびアーカイブ済みの変更を一覧表示します。`--specs` と組み合わせることはできません。`--archived` より優先されます。
`--sort <order>`	`recent`（最終更新が新しい順）または `name`。デフォルト: `recent`。スペックは常に名前でソートされます。
`--json`	テーブルの代わりに JSON を出力します。
`--store <id>`	現在のプロジェクトの代わりに、登録済みストアを OpenSpec ルートとして使用します。

出力

変更ごとに 1 行: 名前、タスクステータス、最終更新。ステータス列には No tasks、2/5 tasks、または ✓ Complete が表示されます。

Changes:
  add-rate-limit     No tasks      just now

--all はアクティブな変更とアーカイブ済みの変更を別々の見出しの下にグループ化します。各グループは選択されたソート順を使用します:

Changes:
  add-rate-limit     No tasks      just now

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

Specs:
  api     requirements 1

--json はタスク数を追加し、status には no-tasks、in-progress、または complete を設定します:

json

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

--archived または --all を指定すると、各変更オブジェクトに archived ブール値が含まれます。結合された配列は選択されたソート順を使用します。アーカイブ済みの変更でも、追跡対象のタスクファイルに未チェックのタスクがある場合は in-progress ステータスになることがあります。どちらのフラグも指定しない場合、JSON の形状は変わりません。

一覧が空の場合、No active changes found.、No archived changes found.、No changes found.、または No specs found. を出力し、それでも終了コード 0 で終了します。

変更は openspec/changes/ 直下のディレクトリです。スペックとは異なり、変更を名前空間フォルダ内にネストすることはできません。変更をラップするだけの changes/mobile/ のようなフォルダ（changes/mobile/refresh-token/）は、ステータス not a change で一覧表示され、続いてネストされたディレクトリ名を示す警告が表示されます。--json はそのエントリを nested 配列でマークし、トップレベルの warnings 配列を追加します。show、status、validate、archive は同じメッセージでそのフォルダを拒否します。修正するには、変更を上へ移動し、名前空間をその名前に畳み込みます:

bash

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

終了コード

0: 一覧が出力された場合（空の場合も含む）。
1: OpenSpec ルートが見つからない場合（プロジェクト外で、--store がない場合）。

openspec show

変更またはスペックを、Markdown または JSON として出力します。

bash

openspec show add-rate-limit              # 変更: proposal.md を出力
openspec show add-rate-limit --diff       # 変更: 要件の差分を追加
openspec show api                         # スペック: spec.md を出力
openspec show api --json --no-scenarios   # シナリオテキストなしのスペック JSON

名前を指定しない場合、show は変更かスペックかを尋ね、次に選択肢として項目を一覧表示します。対話型ターミナル以外では、終了コード 1 で終了し、代わりに直接指定する形式を出力します。

引数

引数	内容
`item-name`	表示する変更またはスペック。フォルダ名で指定します（`add-rate-limit`、`api`）。

オプション

フラグ	効果
`--json`	生の Markdown の代わりに構造化 JSON を出力します。
`--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 始まりの位置で 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"
  }
}

各要件は Requirement: の後のヘッダーテキストである name を持ちます。これはアーカイブが MODIFIED、REMOVED、RENAMED エントリーとのマッチングに使用する名前です。各シナリオは Scenario: の後のヘッダーテキストである name を持ちます。いずれのヘッダーにある末尾の # の連続は名前の一部ではありません。

--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 インデックス、-r と --requirements の同時指定、または --diff のためにデルタまたはメインスペックが読み取れない。

openspec view

スペックと変更のダッシュボードを1画面で表示します。

bash

openspec view   # プロジェクトサマリーを1画面で表示

view はダッシュボードを一度出力して終了します。キー入力は読み取りません。変更はタスク進捗によってグループ化されます：Draft（まだタスクなし）、Active（タスク進行中、進捗バーとパーセント表示付き）、Completed（すべてのタスクにチェック済み）。スペックは要件数とともに、最大のものから順に表示されます。

オプション

フラグ	効果
`--store <id>`	現在のプロジェクトの代わりに、登録済みストアをOpenSpecルートとして使用します。

出力

OpenSpec Dashboard

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

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

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

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

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

いずれかの変更に進行中のタスクがある場合、Task Progress サマリー行が表示されます。

各アクティブな変更は、タスク進捗バーの下にスキーマとアーティファクトの状態も表示します：

text

    └─ [spec-driven] proposal✓ specs→ design→ 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   # 名前で1つの変更またはスペック
openspec validate --all            # すべての変更とスペック

名前も一括フラグも指定しない場合、validate はアイテムの選択を求めます。対話型ターミナル外では、終了コード1で終了し、一括フラグを出力します。

引数

引数	説明
`item-name`	検証する変更またはスペック。フォルダ名で指定します（`add-rate-limit`、`api`）。

オプション

フラグ	効果
`--all`	すべての変更とスペックを検証します。
`--changes`	すべての変更を検証します。
`--specs`	すべてのスペックを検証します。
`--archived`	アーカイブ済み変更のタスク完了を確認します。適用済みのスペックデルタは検証しません。
`--strict`	警告を失敗として扱います。
`--type <change\|spec>`	変更とスペックが同じ名前を共有する場合にタイプを選択します。
`--json`	テキストの代わりに構造化レポートを出力します。
`--report <mode>`	一括出力： `full`（デフォルト）または `findings`。明示的な一括スコープが必要です。
`--concurrency <n>`	一括実行時の最大並列検証数。デフォルト： `OPENSPEC_CONCURRENCY`、未設定の場合は6。
`--no-interactive`	プロンプトを表示しません。名前が見つからない場合や曖昧な場合はエラーになります。
`--store <id>`	現在のプロジェクトの代わりに、登録済みストアをOpenSpecルートとして使用します。

出力

一括実行では、各アイテムのステータス行を1行ずつ出力し、その後に所見があれば表示し、最後に合計を表示します：

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

タスクチェックボックスの所見

進捗カウントはチェックボックスのみをチェックするため、プレーンブレットとして書かれたタスクファイルは0タスクとして読み取られます： 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".

この警告は、変更の追跡対象セット全体にチェックボックスがまったくない場合にのみ発動します。実際のチェックリストの隣にある散文のファイルは報告されず、1つのチェックボックスが存在する限り、作成中の変更は進捗を維持します。--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 は実行ごとに1つのレポートを出力します：

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 エントリーは、ERROR、WARNING、または INFO の level を持ちます。

終了コード

0: 検証されたすべてのアイテムが合格しました。空の一括スコープも含みます。
1: アイテムが失敗した、レポートリクエストが無効、openspec/config.yaml が読み取れないか有効なYAMLではない、または実行が失敗した（不明な名前やOpenSpecルートがない場合など）。読み取れないまたは解析できない設定は、アイテムがチェックされる前に実行を停止します。--json では、コード unreadable_config または unparseable_config の単一の status エントリーとして報告されます。

--report full|findings

明示的な一括検証スコープの出力を選択します：

full: すべてのアイテム。これがデフォルトです。明示的な --report full は、レポートメタデータを追加せず、既存の出力形式を維持します。
findings: 問題を持つアイテムのみ。警告や情報を持つ合格アイテムを含みます。すべてのアイテムは依然として検証されます。合計、strictモードの動作、終了コードは変更されません。

bash

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

スコープ

フラグ	所見 `report.scope`
`--all`	`all`
`--changes`	`changes`
`--specs`	`specs`
`--changes --specs`、または `--all` とどちらかのフラグ	`all`
`--archived`	`archived`

両方の明示的なレポートモードは、位置引数のアイテム名、一括スコープの欠落、またはアーカイブとアクティブスコープの組み合わせを拒否します。

所見のテキスト出力

人間向け出力：stdout に Scope: <scope> (<count> items)、その後に合計を出力します。問題を持つアイテムがない場合：

text

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

問題を持つアイテムのラベル、重大度ラベル、パス、メッセージはstderrに出力されます。アクティブスコープの失敗は、合計の後に Details: の再実行ヒントを維持します。既存のルートバナーと進捗出力がレポートの前に表示される場合があります。

所見のJSON出力

--report findings --json は1つのドキュメントを出力します。この例では2つのクリーンなアイテムがあります：

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を返します。完了した所見レポートや成功した空のレポートは返しません。

無効なレポートリクエスト

両方の明示的なレポートモードは、ルート選択またはアイテム検出の前に、これらのリクエストを拒否します：

空文字列を含む、サポートされていないレポート値。
一括フラグがあっても、位置引数のアイテム名。
明示的な一括スコープがない。
--archived と --all、--changes、または --specs の組み合わせ。

JSONモードでは、拒否されたリクエストは、単一要素の status 配列のみで終了コード1になります。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 は、--json の場合を含め、stderr上のCommander構文エラーです。この診断エンベロープは使用しません。

完全なレポートを外部でフィルタリング

カスタム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                # 1つの変更をアーカイブし、その差分をマージします
openspec archive add-rate-limit -y --skip-specs   # スペックに触れずにアーカイブします

名前を指定しない場合、アーカイブは変更を選択するよう求めます。対話型ターミナル以外では終了コード1を返し、代わりに再実行コマンドを表示します。

引数

引数	説明
`change-name`	アーカイブする変更をフォルダ名で指定します（`add-rate-limit`）。

オプション

フラグ	効果
`-y, --yes`	すべての確認に「はい」と答えます：スペックの更新、未完了タスク、検証のスキップ。
`--skip-specs`	メインのスペックに触れずにアーカイブします（インフラ、ツール、ドキュメントのみの変更）。
`--no-validate`	検証をスキップします。アーカイブは最初に確認を求め、`-y` がそれに答えます。
`--json`	テキストではなく構造化された結果を出力します。スペックの更新を確認するには `--yes` が必要です。
`--store <id>`	現在のプロジェクトの代わりに登録されたストアをOpenSpecルートとして使用します。

出力

成功した実行では、タスクステータスを報告し、スペックの更新をプレビューして適用し、アーカイブフォルダ名を表示します：

タスクステータス: ✓ 完了

更新するスペック:
  api: 更新
openspec/specs/api/spec.md に変更を適用しています:
  + 1 追加
合計: + 1, ~ 0, - 0, → 0
スペックが正常に更新されました。
変更 'add-rate-limit' が '2026-08-11-add-rate-limit' としてアーカイブされました。

変更フォルダはその全体が openspec/changes/archive/2026-08-11-add-rate-limit/ に移動し、今日の日付が名前の前に付加されます。各差分はメインのスペックにマージされます：上記の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"
  }
}

アーカイブは最初に変更を検証し、失敗した変更は拒否します：

変更差分スペックの検証エラー:
  ✗ ADDED "Rate limiting" には少なくとも1つのシナリオを含める必要があります

検証に失敗しました。アーカイブする前にエラーを修正してください。
検証をスキップするには（非推奨）、--no-validate フラグを使用してください。

未完了のタスクは警告しますが、ブロックしません。対話的にアーカイブは続行するかどうかを尋ね、-y は自動的に続行します：

タスクステータス: 1/2 タスク
警告: 1つの未完了タスクが見つかりました。--yes フラグにより続行します。

終了コード

0: 変更がアーカイブされました（スペック更新の有無にかかわらず）。
1: 検証に失敗した、変更名が不明な、または確認が必要だが回答を読み取れなかった。

openspec new

新しい変更ディレクトリを作成します。

bash

openspec new change add-caching                                # メタデータのみ
openspec new change add-search --goal "Users can search docs"  # ゴールを記録

new には1つのサブコマンド new change <name> があります。これにより、単一の.openspec.yaml メタデータファイルを含む openspec/changes/<name>/ が作成されます：

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ルートとして使用します。

出力

変更 'add-caching' を openspec/changes/add-caching/ に作成しました
スキーマ: spec-driven
次: openspec status --change add-caching

openspec/ ディレクトリが見つからない場合、new change は現在地に作成し、その旨を通知します：

変更 'add-caching' を openspec/changes/add-caching/ に作成しました
スキーマ: spec-driven
次: openspec status --change add-caching

注記: ここにOpenSpecルートが見つからなかったため、openspec/ に作成されました。
このプロジェクトのセットアップを完了するには `openspec init` を実行するか、別のプロジェクトを意図していた場合はそのディレクトリを削除してください。

この通知は他の人間向け出力と共に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

1つの変更、またはすべてのアクティブな変更のアーティファクト完了ステータスを報告します。

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で終了し、利用可能な変更を一覧表示します（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>`	現在のプロジェクトの代わりに、登録されたストアを 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: 行には変更を進めるための1つのコマンドが表示されるため、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 <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 はありません。選択されたルートはエンベロープに1回表示されます。この例では上記の変更ごとのステータスフィールドは省略しています:

json

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

1つの変更が読み込めない場合でも、バッチは続行されます。そのエントリには changeName と status 診断が含まれ、他のエントリは利用可能なままとなります。JSON モードを含め、コマンドは終了コード1で終了するため、CI は不完全なレポートを成功として受け入れません。JSON 出力は解析可能な1つのドキュメントのままです。

終了コード

0: 要求されたすべてのステータスが出力されました。空の --all レポートも終了コード0になります。
1: 要求された変更の読み込みに失敗した、--change または --all がない、2つのフラグが同時に指定された、変更が存在しない、またはスキーマ上書きが不明です。

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>`	現在のプロジェクトの代わりに、登録されたストアを OpenSpec ルートとして使用します。

出力

アーティファクト形式では、タスク、書き込むファイル、記述方法、アーティファクトのテンプレート、完了時に解除されるものを含む1つの手順ブロックを出力します。

<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 を指定すると、各形式は1つのオブジェクトを返します。アーティファクト形式は次のように始まります:

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 は常に boolean です。スキーマが null でない apply.tracks を設定している場合は true になり、ファイルが一致しなくても同様です。一致する追跡ファイルが読み取れない場合、unavailableTrackingFiles にはその絶対 path とエラーの reason が含まれます。このフィールドは、一致したすべてのファイルが読み取り可能な場合は省略されます。読み取り可能なファイルは引き続き tasks と progress に貢献しますが、一致したすべてのファイルが読み取られるまで state は all_done になりません。

終了コード

0: 手順が出力されました。
1: 不明なアーティファクト、不明な変更、不明なスキーマ、または --change がありません。各エラーには有効な値が一覧表示されます。

openspec templates

スキーマのアーティファクトに対して解決されたテンプレートパスを出力します。

bash

openspec templates          # デフォルトスキーマ: spec-driven
openspec templates --json   # アーティファクトIDからパスへのマップ

オプション

フラグ	効果
`--schema <name>`	解決するスキーマ。デフォルト: `spec-driven`。
`--json`	アーティファクトIDからテンプレートパスへのマップをJSONで出力します。

出力

Schema: spec-driven
Source: package

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

Source はスキーマの解決元を示します: project(プロジェクト内の openspec/schemas/)、user(グローバルオーバーライド)、または package(CLIに組み込み)。プロジェクトはユーザーより優先され、ユーザーはパッケージより優先されます。

json

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

終了コード

0: パスが出力されました。
1: 不明なスキーマです。エラーには利用可能なスキーマが一覧表示されます。

openspec schemas

利用可能なワークフロースキーマを一覧表示します。

bash

openspec schemas          # 名前、説明、アーティファクトの順序
openspec schemas --json   # 機械可読形式(エージェント用)

オプション

フラグ	効果
`--json`	JSONとして出力します(エージェント用)。

出力

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"
  }
]

終了コード

0: スキーマが一覧表示されました。
1: スキーマリストを読み取れませんでした。

openspec schema

スキーマを検査、フォーク、または作成します（実験的）。各サブコマンドは最初に Note: Schema commands are experimental and may change. を stderr に出力します。

bash

openspec schema which spec-driven          # スキーマがどこから解決されるか
openspec schema fork spec-driven my-flow   # スキーマをプロジェクトにコピー
openspec schema init my-schema             # スキーマをゼロから作成

サブコマンド	機能
`which`	スキーマがどこから解決されるかを表示します。
`validate`	スキーマの構造とテンプレートをチェックします。
`fork`	カスタマイズ用に既存のスキーマをプロジェクトへコピーします。
`init`	新しいプロジェクトローカルスキーマを作成します。

スキーマは 3 つの場所から解決されます。最初に一致したものが優先されます:

ソース	場所
`project`	現在のプロジェクト内の `openspec/schemas/`。
`user`	`~/.local/share/openspec/schemas/`（`XDG_DATA_HOME` および Windows の `%LOCALAPPDATA%` が考慮されます）。
`package`	CLI に同梱されるスキーマ。`spec-driven` はここにあります。

openspec schema which

スキーマのどのコピーを CLI が使用するかを表示します。

bash

openspec schema which spec-driven
openspec schema which --all        # すべてのスキーマをソース別にグループ化

引数

引数	内容
`name`	検索するスキーマ。`--all` 指定時を除き必須。どちらも指定しない場合、which は終了コード 1 で終了します。

オプション

フラグ	効果
`--all`	すべてのスキーマを解決ソースとともに一覧表示します。
`--json`	解決結果を JSON で出力します。

出力

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

優先度の高いコピーが別のコピーを隠している場合、Shadows: セクションに隠されたコピーが一覧表示されます。--json の場合:

json

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

不明な名前は終了コード 1 で終了し、利用可能なスキーマを一覧表示します。

openspec schema validate

スキーマの構造とテンプレートをチェックします。

bash

openspec schema validate spec-driven   # 任意のソースから 1 つのスキーマ
openspec schema validate               # すべてのプロジェクトローカルスキーマ

schema.yaml が存在して解析できること、構造がスキーマ形式に一致すること、各アーティファクトのテンプレートファイルがスキーマの templates/ ディレクトリ内に存在すること、および依存関係グラフに循環や未知の参照（apply.requires 内のものを含む）がないことを検証します。apply.tracks の値が、いずれかのアーティファクトの generates 値と完全に一致しない場合、warning: 行を出力しますが、検証は失敗しません。その場合、OpenSpec はそのファイルがどのアーティファクトの進捗に属するかを判別できないためです。

オプション

フラグ	効果
`--json`	テキストではなく構造化レポートを出力します。
`--verbose`	各検証ステップを出力します。

出力

✓ Schema 'spec-driven' is valid

名前を指定しない場合、各プロジェクトスキーマは Validation Results: ヘッダーの下に 1 行ずつ表示されます。失敗したスキーマはその問題を一覧表示し、実行は終了コード 1 で終了します:

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

openspec schema fork

既存のスキーマをプロジェクトにコピーしてカスタマイズできるようにします。

bash

openspec schema fork spec-driven my-flow

引数

引数	内容
`source`	コピーするスキーマ。任意のソース場所から取得できます。
`name`	コピーの名前。ケバブケース（`my-workflow`）。デフォルト: `<source>-custom`。

オプション

フラグ	効果
`--force`	既存の宛先スキーマを上書きします。
`--json`	結果を JSON で出力します。

出力

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

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

フォークは openspec/schemas/ に配置され、その schema.yaml 内の name: フィールドが新しい名前に書き換えられます:

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

既存の宛先がある場合は、--force を指定しない限りエラーになります。ソースの名前を保持するフォークは、元のスキーマを隠します。

openspec schema init

スターターテンプレートを使用して、新しいプロジェクトローカルスキーマを作成します。

bash

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

対話型ターミナルで --description も --artifacts も指定しない場合、init は説明、アーティファクトのチェックリスト、およびこのスキーマをプロジェクトのデフォルトにするかどうかを尋ねます。ターミナル以外では、以下のデフォルト値を使用します。

引数

引数	内容
`name`	新しいスキーマの名前。ケバブケース（`my-workflow`）。

オプション

フラグ	効果
`--description <text>`	スキーマの説明。デフォルト: `Custom workflow schema for <name>`。
`--artifacts <list>`	`proposal`、`specs`、`design`、`tasks` からなるカンマ区切りのアーティファクト ID。デフォルト: 4 つすべて。
`--default`	既存の `openspec/config.yaml` または `openspec/config.yml` に `schema: <name>` を書き込みます。どちらも存在しない場合は `openspec/config.yaml` を作成します。新しい変更はこのスキーマを使用します。
`--no-default`	デフォルトに関するプロンプトをスキップします。
`--force`	同じ名前の既存スキーマを上書きします。
`--json`	結果を JSON で出力します。

スキーマの作成と --default による設定更新は 1 つの操作です。OpenSpec が設定を検証または書き込みできない場合、設定と既存のスキーマの両方を変更せずに残します。

出力

✔ Created schema 'my-schema'

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

Artifacts: proposal, tasks

ディスク上のレイアウト:

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

schema.yaml は、選択したアーティファクトを依存関係とともに結び付けます。tasks が含まれる場合は、tasks.md を追跡する apply フェーズも設定されます。このスキーマは openspec new --schema my-schema で使用します。

openspec store

ストアを作成および管理します。ストアは、マシン上に登録されたスタンドアロンの OpenSpec リポジトリです。

bash

openspec store setup team-context --path ~/openspec/team-context   # 作成して登録
openspec store register ~/stores/design-system                     # 既存のチェックアウトを登録
openspec store list                                                # 登録内容を表示

登録情報はマシンごとのレジストリに保存されます: ~/.local/share/openspec/stores/registry.yaml、または XDG_DATA_HOME が設定されている場合は $XDG_DATA_HOME/openspec/stores/registry.yaml。各サブコマンドは --json を指定すると、テキストではなく構造化レポートを出力します。サブコマンドを指定せずに、または不明なサブコマンドを指定して openspec store を実行すると、終了コード 1 で終了し、サブコマンドを一覧表示します。

サブコマンド	機能
`setup [id]`	ストアフォルダーを作成して登録します。
`register [path]`	既存のストアフォルダーを登録します。
`unregister <id>`	登録を解除します。フォルダーはディスク上に残ります。
`remove <id>`	登録を解除し、フォルダーを削除します。
`list` (エイリアス `ls`)	登録済みストアを一覧表示します。
`doctor [id]`	登録済みストアの登録、メタデータ、Git 状態をチェックします。

openspec store setup

ストアフォルダーを作成して登録します。

bash

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

対話型ターミナルでは、setup は不足している名前と場所を尋ね、何かを作成する前に確認します。ターミナル以外では、名前または --path が不足している場合、渡すべきフラグを示して終了コード 1 で終了します。登録済みストアに対して setup を再実行すると、Registry: already registered と報告されます。

--path が別の Git リポジトリ内にある場合、setup は store_setup_inside_git_repo を伴って終了コード 1 で終了します。そこでストアを初期化すると、リポジトリが別のリポジトリ内に入れ子になるためです。--no-init-git はリポジトリを作成しないため、このチェックをスキップします。ホームディレクトリ自体が Git リポジトリ（dotfiles リポジトリなど）である場合に、~/openspec/<id> にストアを置くために使用します。

引数

引数	内容
`id`	ストア名。`--store` に渡す ID になります。

オプション

フラグ	効果
`--path <path>`	ストアを配置するフォルダー（`~` は展開されます）。
`--init-git`	初回コミット付きで Git リポジトリを初期化します。デフォルト。
`--no-init-git`	すべての Git 操作をスキップします。init も初回コミットも行いません。
`--remote <url>`	`store.yaml` に記録される正規のクローン元。

出力

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

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

--json は、作成された内容と登録先を報告します:

json

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

openspec store register

既存のストアフォルダーを登録します。たとえば、クローンしたチームメイトのストアなどです。

bash

openspec store register ~/stores/design-system

フォルダーには正常な openspec/ ルートが含まれている必要があります。.openspec-store/store.yaml が存在する場合、register は記録された ID を再利用します。存在しない場合、register はそのメタデータを作成する前に確認を求めます。対話型ターミナル以外では、代わりに --yes を指定してください。1 台のマシンでは、ストア ID ごとに 1 つのチェックアウトを登録できます。同じ ID で 2 つ目のパスを登録する場合、または同じパスを 2 つ目の ID で登録する場合は、終了コード 1 で終了します。

引数

引数	内容
`path`	登録するストアフォルダー（`~` は展開されます）。必須。

オプション

フラグ	効果
`--id <id>`	ストア ID。デフォルトではメタデータまたはフォルダー名。
`--yes`	正常な OpenSpec ルートに対してストア識別メタデータを作成することを確認します。

出力

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

--json は store setup --json と同じドキュメント構造を出力します。

openspec store unregister

登録を解除します。フォルダーはディスク上に残ります。

bash

openspec store unregister design-system

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

openspec store remove

登録を解除し、フォルダーを削除します。

bash

openspec store remove design-system --yes

対話型では、remove は削除前に確認します。--json の場合、または対話型ターミナル以外では、削除には --yes が必要です:

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

フォルダーに一致するストアメタデータがない場合、または別の登録済みストア（たとえば Git サブモジュールとして組み込まれたストア）を含む場合、remove は終了コード 1 で終了し、何も削除しません。その場合のエラーは store_remove_contains_registered_store です。先に openspec store unregister <nested-id> を実行するか、ファイルを削除せずにストアの登録を解除するには openspec store unregister <id> を実行してください。

オプション

フラグ	効果
`--yes`	ローカルのストアフォルダーの削除を確認します。

出力

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

openspec store list

登録済みストアを一覧表示します。ls はエイリアスです。

bash

openspec store list

OpenSpec stores (2)

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

何も登録されていない場合、list は No stores registered. と、次に実行する setup および register コマンドを出力します。

openspec store doctor

登録済みストアの登録、メタデータ、Git 状態をチェックします。

bash

openspec store doctor                # すべての登録済みストア
openspec store doctor team-context  # 1 つのストア

出力

Store doctor

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

終了コード

0: レポートが出力された場合（ストアが問題を報告した場合でも）。
1: レポートを実行できなかった場合（不明なストア ID など）。

openspec doctor

解決された OpenSpec ルートの関係健全性をレポートします。

bash

openspec doctor                       # カレントディレクトリより上位の最も近い openspec/ ルート
openspec doctor --store team-context  # 登録済みストアをルートとして使用

Doctor は読み取り専用です: クローン、同期、修復は一切行いません。ルートが健全であるか、および openspec/config.yaml で宣言された各参照がこのマシンで解決できるかをレポートします。カレントディレクトリの上位にルートがなく --store も指定されていない場合、終了コード 1 で終了し、登録済みストアの一覧を表示します。

オプション

フラグ	効果
`--store <id>`	現在のプロジェクトではなく、登録済みストアを OpenSpec ルートとして使用します。
`--json`	健全性レポートを JSON として出力します。

出力

Doctor

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

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

--store を使用する場合、ルートはストアとなり、レポートにストア行が追加されます:

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

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

References
  (none declared)

json

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

終了コード

0: レポートが出力されました（問題が一覧表示されている場合も含みます）。
1: ルートが解決されませんでした（カレントディレクトリの上位に openspec/ がなく --store も指定されていない）、または不明な --store ID が指定されました。

openspec context

解決された OpenSpec ルートの作業コンテキストを出力します: ルートと openspec/config.yaml で宣言された参照先ストアすべてを、それぞれのフェッチコマンドと共に表示します。

bash

openspec context                       # カレントディレクトリより上位の最も近い openspec/ ルート
openspec context --store team-context  # 登録済みストアをルートとして使用
openspec context --json                # エージェントブリーフ

このマシンで解決できない参照は、それぞれ対応方法と共に Not available on this machine セクションに表示されます。

オプション

フラグ	効果
`--store <id>`	現在のプロジェクトではなく、登録済みストアを OpenSpec ルートとして使用します。
`--json`	エージェントブリーフを JSON として出力します。
`--code-workspace <path>`	セットの VS Code ワークスペースファイルも書き出します。
`--force`	既存の `--code-workspace` ファイルを上書きします。

出力

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

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

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

--store を使用する場合、ストアがセット全体となります:

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

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

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

json

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

ワークスペースファイルの書き込み

--code-workspace は指定されたパスに VS Code ワークスペースファイルを書き出します: ルートに 1 つのフォルダ、利用可能な参照先ストアごとに ref:<id> フォルダが作成されます。利用できない参照はスキップされ、サマリー行に名前が表示されます: Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders)。サマリーは stderr に出力されるため、--json の stdout は 1 つの 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: ルートが解決されませんでした（カレントディレクトリの上位に 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 をツール（エディタウィンドウまたはエージェントセッション）で開きます。
`remove <name>`	保存された workset を削除します（メンバーフォルダは一切変更されません）。

workset は完全にローカルです。

その状態は 1 つのフォルダに保存されます: ~/.local/share/openspec/worksets/（設定時は $XDG_DATA_HOME/openspec/worksets/、Windows では %LOCALAPPDATA%\openspec\worksets\）。
メンバーフォルダに何も書き込まれず、コミットや共有もされません。
その 1 つのフォルダを削除すれば、すべての痕跡が消去されます。

openspec workset create

フォルダの名前付き作業ビューを保存します。

bash

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

対話型ターミナルでは、フラグで指定されなかったものについて create がプロンプトを表示します: 名前、フォルダを 1 つずつ、ツール、そして workset を今すぐ開くかどうかの確認。対話型ターミナル以外では、名前またはメンバーが見つからない場合はエラーになります。既に保存されている名前も常にエラーになります。先に削除してください。

引数

引数	説明
`name`	workset の名前。ケバブケース: 小文字、数字、単一のハイフン。対話型ターミナル以外では必須です。

オプション

フラグ	効果
`--member <member>`	メンバーフォルダを `<path>` または `<name>=<path>` の形式で指定します（繰り返し可能）。最初のメンバーがプライマリになります。パスは既存のフォルダである必要があり、ラベルはデフォルトでフォルダ自身の名前になります。
`--tool <id>`	この workset を開くときに使用する優先ツール。組み込み id: `code`（VS Code）、`cursor`（Cursor）。`claude` と `codex` は一時的に無効化されています。
`--json`	保存された workset を JSON で出力します。

出力

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

openspec workset list

保存された workset とそのメンバーを名前順に表示します。

bash

openspec workset list   # alias: ls

オプション

フラグ	効果
`--json`	workset を JSON で出力します。

出力

workset ごとに 1 つのブロック: 名前、ツール（ある場合）、そしてメンバーごとの 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 エージェントツール（claude、codex）は、すべてのメンバーをアタッチしてこのターミナルを引き継ぎます。そのフローが作り直されている間は一時的に無効化されているため、今のところ workset は IDE で開きます。

bash

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

引数

引数	説明
`name`	開く workset。

オプション

フラグ	効果
`--tool <id>`	このツールで一度だけ開きます。

--tool も保存されたツールも指定されていない場合、open はインストール済みツールの選択を求めます。対話型ターミナル以外では、代わりに終了コード 1 で終了します。

存在しなくなったメンバーフォルダは警告とともにスキップされます。プライマリが存在しない場合、次に存在するメンバーがこの open のプライマリになります。メンバーフォルダがすべて存在しない場合、open は失敗します。
--json は拒否されます: open はターミナルをツールに渡すため、JSON モードはありません。
起動が失敗した場合、エラーは手動ルート（ワークスペースファイルのパスとメンバーリスト）で終わります。

終了コード

ツールを反映: コマンドはツール自身の終了コードで終了し、シグナルは 128+n になります（Ctrl-C 後は 130）。
1: 不明な workset、利用可能なメンバーフォルダがない、または使用可能なツールがない。

openspec workset remove

保存された workset と生成された .code-workspace ファイルを削除します。メンバーフォルダは一切変更されません。

bash

openspec workset remove checkout --yes

対話型ターミナルでは、remove は workset を表示して確認を求めます。--json の場合、またはターミナル以外では、--yes が必要であり、指定がない場合は終了コード 1 で終了します。

オプション

フラグ	効果
`--yes`	非対話的に削除を確認します。
`--json`	削除を JSON で出力します。

出力

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

openspec version

実行中の OpenSpec のバージョンと、このコピーがどのようにインストールされたかを報告します。

bash

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

--check なしでは、このコマンドはローカルで実行され、レジストリに連絡しません。OpenSpec プロジェクトの外でも動作します。既存の openspec --version フラグは最短形式のままで、素のバージョン番号のみを出力します。

オプション

フラグ	効果
`--json`	テキストの代わりにバージョン管理された JSON ドキュメントを 1 つ出力します。
`--check`	設定されたレジストリで新しいリリースを確認します。

出力

グローバル npm インストールの場合:

text

OpenSpec 1.13.2 (npm, global)

インストールスコープは global、project、npx などの一時ランナーでは temporary、チェックアウトでは source、スタンドアロンインストールでは standalone です。OpenSpec は識別できない詳細を推測せずに省略します。

--json は不明な詳細を明示的な null 値として保持します:

json

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

--check を指定すると、利用可能な更新がある場合、OpenSpec が安全なコマンドを識別できる場合は最新バージョンとコマンドが追加されます:

text

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

json

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

更新ステータスの値:

ステータス	意味
`available`	レジストリが実行中のバージョンより新しい安全なバージョンを返しました。
`current`	チェックが完了し、より新しいバージョンは見つかりませんでした。
`disabled`	既存のプライバシーまたは更新チェックの設定がレジストリアクセスをブロックしました。`latest` は `null` です。
`offline`	レジストリが利用できないか、使用できない応答を返しました。`latest` は `null` です。

スタンドアロンインストールの場合、更新コマンドは openspec install です。

DO_NOT_TRACK、テレメトリオプトアウト、OPENSPEC_NO_UPDATE_CHECK、CI 検出、および拒否された非 HTTPS レジストリのオーバーライドはチェックを無効にします。無効およびオフラインのチェックは、更新の可用性が参考情報であるため、引き続き終了コード 0 で終了します。このコマンドは OpenSpec をアップグレードしません。canSelfUpgrade は、既存の openspec update パスでこのコピーを安全にアップグレードできるかどうかのみを報告します。

終了コード

0: ローカルレポートが出力されました。無効またはオフラインの更新チェックを含みます。
1: コマンドの構文が無効でした。サポートされていない --upgrade オプションなど。

markdown

## 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 の下にあなたのメッセージ、Details の下に --body のテキスト、そして CLI が自動入力できないため追加を促す Minimal steps to reproduce セクションが配置されます。フッターには CLI バージョン、プラットフォーム、タイムスタンプが追加されます。Issue には feedback ラベルが付きます。リポジトリにそのラベルが定義されていない場合、CLI はラベルなしで再試行し、その旨を表示します。

引数

引数	説明
`message`	1行の要約。Issue のタイトルになります。必須。

オプション

フラグ	効果
`--body <text>`	Issue の本文に追加する詳細な説明。

出力

成功時:

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

gh がインストールされていない場合、または gh にログインしていない場合、何も送信されません。CLI は --- FORMATTED FEEDBACK --- マーカーの間に整形されたフィードバックを表示し、タイトル、What happened（メッセージと --body テキスト）、CLI バージョン、環境（プラットフォームと Node バージョン）が入力済みのバグレポートフォームを開くリンクを表示します。残りのフォームはブラウザで完成させます。未ログインのパスには To auto-submit in the future: gh auth login が追加されます。

終了コード

0: Issue 作成、または手動送信フォールバックの実行（gh なし、または gh 未ログイン）。
1: メッセージなし。
gh 独自のコード: 認証後に gh が失敗（ネットワーク、レート制限、Issue 無効化）。CLI はフィードバックと手動送信 URL を再表示します。

openspec completion

シェル補完をインストールまたは生成します。

bash

openspec completion install        # シェルを検出してインストール、設定を構成
openspec completion generate zsh   # スクリプトを stdout に出力

サポートされているシェル: zsh、bash、fish、powershell。すべてのサブコマンドはオプションでシェル引数を受け取ります。省略すると CLI が環境からシェルを検出します。

サブコマンド	説明
`generate [shell]`	補完スクリプトを stdout に出力します。
`install [shell]`	スクリプトを書き込み、シェルのスタートアップファイルを設定します。
`uninstall [shell]`	スクリプトと設定ブロックを削除します。

Nix でインストールした場合、補完はすでに設定されています。flake パッケージは標準の場所に Bash、Fish、Zsh のスクリプトを同梱しているため、install は不要です（インストール）。

openspec completion generate

スクリプトを表示し、何も書き込みません。

#compdef openspec

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

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

openspec completion install

スクリプトを書き込み、シェル設定を編集します。設定の編集は # OPENSPEC:START と # OPENSPEC:END マーカーの間に配置されます。既存のスクリプトは最初にバックアップされます（.backup-<timestamp> コピー）。

シェル	スクリプトの場所	編集される設定
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`

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

スクリプトとマーカー付きの設定ブロックを削除します。設定を変更する前に確認を求めます（デフォルト: No）。

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: シェルがサポートされていないか検出できない、またはインストール/アンインストールのステップが失敗。

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>`（すべての spec: `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 ​

所見のテキスト出力 ​

所見の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 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

所見のテキスト出力

所見の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 feedback

openspec completion

openspec completion generate

openspec completion install

openspec completion uninstall

openspec change

openspec spec