CLI リファレンス

OpenSpec CLI（openspec）は、プロジェクトのセットアップ、検証、ステータス確認、および管理のためのターミナルコマンドを提供します。これらのコマンドは、Commands に記載されている AI スラッシュコマンド（/opsx:propose など）を補完します。

サマリー

カテゴリ	コマンド	目的
セットアップ	`init`, `update`	プロジェクト内で OpenSpec を初期化および更新します
ストア（スタンドアロン OpenSpec リポジトリ）	`store setup`, `store register`, `store unregister`, `store remove`, `store list`, `store doctor`	ストアの管理 — 登録したスタンドアロン OpenSpec リポジトリ
健全性	`doctor`	解決されたルートに関する関係の健全性を報告します
作業コンテキスト	`context`	作業セット（ルート + 参照ストア）をアセンブルします
個人ワークセット	`workset create`, `workset list`, `workset open`, `workset remove`	ツール内で個人用のローカル作業ビューを保持および開きます
ブラウジング	`list`, `view`, `show`	変更と仕様を探索します
検証	`validate`	変更と仕様の問題を確認します
ライフサイクル	`archive`	完了した変更を確定します
ワークフロー	`new change`, `status`, `instructions`, `templates`, `schemas`	アーティファクト駆動のワークフローサポート
スキーマ	`schema init`, `schema fork`, `schema validate`, `schema which`	カスタムワークフローの作成および管理
設定	`config`	設定の表示および変更
ユーティリティ	`feedback`, `completion`	フィードバックとシェル統合

Human vs Agent Commands

ほとんどの CLI コマンドは、ターミナルでの人間による使用を前提に設計されています。一部のコマンドは、JSON 出力を通じてエージェント/スクリプトによる使用もサポートしています。

Human-Only Commands

これらのコマンドは対話式であり、ターミナルでの使用を前提としています。

Command	Purpose
`openspec init`	プロジェクトの初期化（対話式プロンプト）
`openspec view`	対話式ダッシュボード
`openspec workset open <name>`	保存済みのワークセットを開く（エディタウィンドウまたはターミナルのエージェントセッション）
`openspec config edit`	エディタで設定を開く
`openspec feedback`	GitHub 経由でフィードバックを送信
`openspec completion install`	シェル補完をインストール

Agent-Compatible Commands

これらのコマンドは、AI エージェントやスクリプトによるプログラム的な使用のために --json 出力をサポートしています。

Command	Human Use	Agent Use
`openspec list`	変更/spec の閲覧	`--json` で構造化データ
`openspec show <item>`	コンテンツの読み取り	`--json` でパース
`openspec validate`	問題のチェック	`--all --json` で一括バリデーション
`openspec status`	成果物の進捗確認	`--json` で構造化ステータス
`openspec instructions`	次のステップの取得	`--json` でエージェント向け指示
`openspec templates`	テンプレートパスの特定	`--json` でパス解決
`openspec schemas`	利用可能なスキーマのリスト表示	`--json` でスキーマ探索; `--store <id>` で登録済みのルートを選択
`openspec store setup <id>`	ローカルストアの作成と登録	`--json` と明示的な入力値で構造化セットアップ出力
`openspec store register <path>`	既存のストアを登録	`--json` で構造化登録出力
`openspec store unregister <id>`	ローカルストアの登録を削除	`--json` で構造化クリーンアップ出力
`openspec store remove <id>`	登録済みのローカルストアフォルダを削除	`--yes --json` で非対話式削除
`openspec store list`	登録済みのストアの閲覧	`--json` で構造化登録情報
`openspec store doctor`	ローカルストアのセットアップ確認	`--json` で構造化診断
`openspec new change <id>`	リポジトリローカルの変更スキャフォールディングを作成	`--json`、および `--store <id>` で登録済みのストアを OpenSpec ルートとして使用
`openspec workset create [name]`	個人用ワークビューを構成	`--member <path> --json` で非対話式構成
`openspec workset list`	保存済みのワークセットの閲覧	`--json` で構造化ビュー
`openspec workset remove <name>`	保存済みのビューを削除	`--yes --json` で非対話式削除

Global Options

これらのオプションはすべてのコマンドで動作します。

Option	Description
`--version`, `-V`	バージョン番号を表示
`--no-color`	カラー出力を無効化
`--help`, `-h`	コマンドのヘルプを表示

Setup Commands

`openspec init`

プロジェクトで OpenSpec を初期化します。フォルダ構造を作成し、AI ツールの統合を設定します。

デフォルトの動作はグローバル設定のデフォルト値を使用します: プロファイル core、デリバリー both、ワークフロー propose, explore, apply, update, sync, archive。

openspec init [path] [options]

--language <language> を使用すると、新しいプロジェクトの openspec/config.yaml に言語指示を追加できます。既存のプロジェクトでは、設定の context フィールドを編集して、OpenSpec がプロジェクト固有のガイダンスを上書きしないようにしてください。

Arguments:

Argument	Required	Description
`path`	No	ターゲットディレクトリ（デフォルト: 現在のディレクトリ）

Options:

Option	Description
`--tools <list>`	AI ツールを非対話式で設定。`all`、`none`、またはカンマ区切りのリストを使用
`--language <language>`	新しい設定を作成する際に、この言語で成果物を書き出す
`--force`	プロンプトなしでレガシーファイルを自動クリーンアップ
`--profile <profile>`	この init 実行時のグローバルプロファイルを上書き（`core` または `custom`）
`--no-animation`	アニメーション付きのウェルカム画面の代わりに静的なウェルカム画面を表示
`--copilot-cloud`	プロンプトなしで GitHub Copilot cloud coding-agent files をセットアップ
`--no-copilot-cloud`	プロンプトなしで GitHub Copilot cloud coding-agent files をスキップ

--profile custom は、グローバル設定（openspec config profile）で現在選択されているワークフローを使用します。

ウェルカムアニメーションは、OPENSPEC_NO_ANIMATION 環境変数が設定されている場合（値は任意、空文字を含む）、NO_COLOR が空でない値に設定されている場合、または OS のモーション軽減設定が有効な場合（macOS Reduce Motion、GNOME アニメーション無効）にもスキップされます。

Supported tool IDs (--tools) — windsurf も devin のエイリアスとして受け付けられます: amazon-q, antigravity, auggie, bob, claude, cline, command-code, codeartsagent, codex, devin, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, hermes, iflow, junie, kilocode, kimi, kiro, lingma, minimax-code, vibe, oh-my-pi, opencode, pi, codeassistant, qoder, qwen, rovodev, roocode, trae, zed, zcode, agents

このリストは src/core/config.ts の AI_TOOLS と対応しています。各ツールのスキルとコマンドパスについては Supported Tools を参照してください。

Examples:

bash

# Interactive initialization
openspec init

# Initialize in a specific directory
openspec init ./my-project

# Non-interactive: configure for Claude and Cursor
openspec init --tools claude,cursor

# Non-interactive: configure global MiniMax Code skills
openspec init --tools minimax-code

# Configure for all supported tools
openspec init --tools all

# Override profile for this run
openspec init --profile core

# Skip prompts and auto-cleanup legacy files
openspec init --force

What it creates:

openspec/
├── specs/              # Your specifications (source of truth)
├── changes/            # Proposed changes
└── config.yaml         # Project configuration

.claude/skills/         # Claude Code skills (if claude selected)
.cursor/skills/         # Cursor skills (if cursor selected)
.cursor/commands/       # Cursor OPSX commands (if delivery includes commands)
.agents/skills/         # Shared skills for AGENTS.md-compatible tools (if agents selected)
... (other tool configs)

`openspec update`

CLI をアップグレードした後、OpenSpec の指示ファイルを更新します。現在のグローバルプロファイル、選択されたワークフロー、デリバリーモードを使用して、AI ツールの設定ファイルを再生成します。

openspec update [path] [options]

Arguments:

Argument	Required	Description
`path`	No	ターゲットディレクトリ（デフォルト: 現在のディレクトリ）

Options:

Option	Description
`--force`	ファイルが最新であっても強制更新

Example:

bash

# Update instruction files after npm upgrade
npm install -g @fission-ai/openspec@latest
openspec update

まずパッケージをアップグレードしてください。指示ファイルはインストールされた CLI によって生成されるため、古いインストールに対して openspec update を実行すると、すべて最新と報告され、新しいリリースに含まれるワークフローが追加されません。

これを可視化するために、openspec update は npm レジストリに新しい CLI が公開されていないか問い合わせます。あなたのバージョンが古い場合、アップグレードを提案します:

text

A newer OpenSpec CLI is available (v1.6.0 → v1.7.0).
  Running from: /usr/local/lib/node_modules/@fission-ai/openspec
? Upgrade to v1.7.0 now? (Y/n)

はいと答えると npm install -g @fission-ai/openspec@latest が実行され、新しい CLI で更新が再実行されるため、新しいワークフローが同じコマンド内で反映されます。アップグレードの確認は、npm の終了コードに頼らず、インストールされたバイナリにバージョンを問い合わせることで行われるため、PATH 上で別のインストールがまだ応答している場合は、成功を主張する代わりにそれを通知します。いいえと答えると、コマンドが表示され、現在の CLI で更新が行われます。Ctrl-C でコマンドを停止できます。

この提案は対話式ターミナルでのみ表示され、npm がインストールを管理している場合のみ表示されます — npm install -g が実際に修正できる唯一のケースです。それ以外のケースでは、インストール方法に応じたコマンドが表示されます:

How OpenSpec is installed	What you get
Global npm install	プロンプトが表示され、対話式ターミナルではアップグレードが実行されます — パイプ出力では表示されたコマンドが表示されます
Global pnpm, bun, yarn, or volta install	それぞれのマネージャーのコマンド: `pnpm add -g …@latest`, `bun add -g …@latest`, `yarn global add …@latest`, または `volta install …@latest`
A dependency of the project	パッケージマネージャーがロックファイルを管理しているため、依存関係の更新を促す通知
An `npx` / `dlx` cache	`npx @fission-ai/openspec@latest update` — そのコマンド自体が更新なので、第二段階は不要です
A git clone	なし — バージョンはブランチが示すものです

何かが表示される場合、実行中の CLI が読み込まれたディレクトリ名が示されます — アップグレードしたが古いシムがまだ PATH を占有している場合に確認すべきものです。

npm がエクスポートしている場合は npm_config_registry のレジストリに問い合わせ、それ以外の場合は https://registry.npmjs.org に問い合わせます。.npmrc は読み込まれません: ファイルの内容でアウトバウンドリクエストの先を選択させるフローは避けるべきであり、プロジェクトの .npmrc はリポジトリとともに移動するためです。プライベートミラーを使用する場合は npm_config_registry をエクスポートしてください — または OPENSPEC_NO_UPDATE_CHECK を設定してチェックを完全にスキップできます。チェックは CI が明示的なオフ値（false, 0, no, off, または空）以外に設定されている場合、NODE_ENV=test の下、OPENSPEC_NO_UPDATE_CHECK（値は任意）、DO_NOT_TRACK=1、または OPENSPEC_TELEMETRY=0 が設定されている場合にスキップされます。更新前に実行され、最大 1.5 秒遅延させる可能性があります — ネットワークがパケットをサイレントにドロップしてもその時点で諦め、レジストリに到達できない場合は静かに終了します。

How "up to date" is decided: スキルファイルには生成元のバージョンが記録されるため、OpenSpec はそれをインストールされた CLI と比較します。コマンドファイルにはバージョンスタンプがないため、コマンドはあるがスキルがないツール（デリバリー commands）については、OpenSpec はファイルの内容を現在生成されるものと比較します — これらのファイルへの編集はドリフトとみなされ、上書きされます。デリバリーが skills または both の場合、記録されたバージョンのみがチェックされるため、バージョンがまだ一致する手動編集されたファイルはそのままにされます; 書き直すには --force を使用してください。いずれにせよ、生成されたファイルは OpenSpec が所有するものです — 独自の指示は別の場所に保管してください。

Stores（スタンドアロン OpenSpec リポジトリ）

ベータ版。 Stores およびそれに基づいて構築された機能（references、working context、worksets）は新機能です。コマンド名、フラグ、ファイル形式、JSON 出力の構造はリリースごとに変わる可能性があります。問題起点のウォークスルーについては、stores ガイドを参照してください。

Store とは、このマシンに登録したスタンドアロンの OpenSpec リポジトリです。例えば、プランニング用リポジトリやコントラクト用リポジトリなどが該当します。Store を登録すると、--store <id> を渡すことで、通常のコマンド（list、show、status、validate、new change、archive など）をどこからでもその Store に対して実行できます。

`openspec store setup`

ローカル Store を作成して登録します。ターミナルで引数なしで実行すると、OpenSpec がユーザーにセットアップをガイドします。エージェントやスクリプトは明示的な入力値を渡し、--json を使用してください。

bash

openspec store setup [id] [options]

オプション:

オプション	説明
`--path <path>`	Store を配置するフォルダ（例：`~/openspec/<id>`）
`--remote <url>`	正規のリモートを新しい Store の `store.yaml` に記録する
`--init-git`	初期コミット付きで Git リポジトリを初期化する（デフォルト）
`--no-init-git`	すべての Git 操作をスキップする（init なし、初期コミットなし）
`--json`	JSON を出力する

非対話実行（--json、スクリプト、エージェント）では、Store ID と --path の両方を渡す必要があります。対話的ターミナルでは、ユーザーが所有する目に見える場所（例：~/openspec/<id>）に編集可能な提案を提示して配置先を尋ねます。OpenSpec が管理するデータディレクトリをデフォルトにすることは決してありません。

例：

bash

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

`openspec store register`

既存のローカル Store フォルダを登録します。Stores ベータ期間中、変更が存在する前、スペックが適用される前、変更がアーカイブされる前にルートが登録される場合があります。その場合、openspec/changes/、openspec/specs/、openspec/changes/archive/ は通常のコマンドがそれらを作成するまで存在しない可能性があります。store: <id> を宣言する設定専用のリポジトリは、別の Store へのポインターとして残り続けます。そのポインターが削除されない限り、Store ルートとして登録されません。

bash

openspec store register [path] [options]

オプション:

オプション	説明
`--id <id>`	Store ID。デフォルトは Store メタデータまたはフォルダ名
`--yes`	健全な OpenSpec ルートに対して Store アイデンティティメタデータを作成することを確認する
`--json`	JSON を出力する

`openspec store unregister`

ファイルを削除せずにローカル Store の登録を解除します。

bash

openspec store unregister <id> [--json]

Store が移動された場合、別の場所にクローンされた場合、またはこのマシン上で OpenSpec によって表示されなくなった場合に使用します。

`openspec store remove`

ローカル Store の登録を解除し、そのローカルフォルダを削除します。

bash

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

remove は対話的ターミナルで削除前に正確なフォルダを表示します。エージェント、スクリプト、JSON 呼び出し元は削除を確認するために --yes を渡す必要があります。OpenSpec は、対応する Store メタデータが含まれていないフォルダの削除を拒否します。

`openspec store list`

ローカルに登録された Store を一覧表示します。

bash

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

`openspec store doctor`

ローカル Store の登録状態、メタデータ、Git の存在を確認します。

bash

openspec store doctor [id] [--json]

Doctor は診断専用です。Store を変更することなく、欠落しているルート、メタデータの不一致、無効なローカルレジストリ状態を報告します。

プロジェクトから Store を参照する

プロジェクトリポジトリは、openspec/config.yaml で作業に使用する Store を宣言できます：

yaml

schema: spec-driven
references:
  - team-context

これ以降、そのリポジトリでの openspec instructions の出力（各成果物および apply サーフェス、JSON モードと人間向けモードの両方）には、参照された各 Store のスペックのインデックスが含まれます — スペック ID、各スペックの Purpose セクションからの1行サマリー、フェッチコマンド（openspec show <spec-id> --type spec --store <id>）です。インデックスは実行のたびに登録されたチェックアウトからライブで構築されます。スペックの内容は出力にコピーされません。

References は読み取り専用のコンテキストです。コマンドが作用する場所を変えることはありません。作業はリポジトリ自身のルートで行われ、参照された Store への書き込みは引き続き明示的な --store 操作が必要です。解決できない参照（例：このマシンに登録されていない Store）は、インデックス上で正確な修正方法付きの警告に格下げされ、instructions は引き続き生成されます。openspec doctor は参照の健全性を1箇所で報告します。

Store のクローン元を記録する

Store は、その正規のクローン元をコミットされたアイデンティティファイルに記録できます。これにより、オンボーディングが「Store を登録する」で途切れることはありません：

bash

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

リモートは初期コミット内の .openspec-store/store.yaml に記録されるため、すべてのクローンはそれを認識した状態で誕生します。既存の Store では、store.yaml を手動で編集してコミットしてください。store doctor は記録されたリモート（およびチェックアウトの観察された Git origin）を表示します。setup/register の共有ガイダンスではそれが名前付けされ、register はチェックアウトの origin をマシンローカルのレジストリに記録します。

参照宣言にもクローン元を含めることができます。これにより、まだ Store を持っていないチームメイトは完全で貼り付け可能な修正（git clone <remote> <path> && openspec store register <path> --id <id>）を得られます：

yaml

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

リモートを記録することは同期ではありません。OpenSpec は決して独自にクローン、プル、プッシュしません。

デフォルト Store を宣言する

プランニングが完全に外部化されたリポジトリ（ローカルの openspec/specs/ や openspec/changes/ が存在しない）は、すべてのコマンドで --store を渡す代わりに、Store を一度宣言できます：

yaml

# openspec/config.yaml（openspec/ 配下の唯一のファイル）
store: team-context

これにより、通常のコマンドは宣言された Store に自動的に解決されます。ルートバナーと JSON の root ブロックは Store ID 付きで source: "declared" を報告し、表示されるヒントには引き続き --store <id> が含まれます。宣言はフォールバックであり、オーバーライドではありません。明示的な --store が常に優先され、実際のプランニングフォルダを持つディレクトリはポインターを無視します（警告付き）。ポインターリポジトリをローカルの OpenSpec ルートに変換するには、store: 行を削除し openspec init を実行してください — init は宣言が存在する間はスキャフォールドを拒否します。

マシンレベルのバリアントはすべてのリポジトリを一括でカバーします：openspec config set defaultStore <id>（Configuration を参照）。これは --store、ローカルルート、プロジェクトポインターのすべてが解決に失敗した後にのみ参照されます。その場合、ルートバナーと JSON の root ブロックは source: "global_default" を報告します。

ドクター（関係性の健全性）

読み取り専用の質問が1つ、場所が1つ：OpenSpecルートは健全か、そして参照しているストアはこのマシン上で利用可能か？

bash

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

レポートは、ルートの健全性、ストアメタデータの健全性（記録されたリモートとチェックアウトのオリジンが乖離している場合のメモ、およびストアのチェックアウトが最後にフェッチした上流の追跡参照より後方にずれている場合のメモを含む）、そして参照の健全性（診断が示すのと同じ指示で、未解決の参照に対するクローン修正を含む）を分けて示します。健全性の調査結果は重大度に関係なく終了コード0で終了します — エージェントはstatus配列を読み取ります。コマンドの失敗（ルートなし、不明なストア）のみ終了コード1で終了します。ドクターは決してクローン、同期、修復を行いません。組み立てられたセット自体を健全性ではなく取得するには、openspec contextを使用してください。

作業コンテキスト（組み立てられたセット）

この作業がOpenSpecの宣言を通じて関連するすべてのものを、1つの作業セットにまとめたもの：OpenSpecルートとそれが参照するストアです。

bash

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

JSONの概要はエージェントが消費可能です（利用可能な各参照ストアにはそのフェッチ手順が含まれ、未解決のメンバーにはドクターが示すのと同じ修正指示が含まれます）。--code-workspaceはさらに、ルートと利用可能な参照ストア（ref:<id>フォルダ）を含むVS Codeワークスペースファイルを書き込みます — このコマンドが実行する唯一の書き込みであり、ファイルが存在する場合は--forceなしでは拒否されます。利用できないメンバーは報告され、推測されることはありません。

「作業コンテキスト」は組み立てられたセットを指します。openspec/config.yamlのcontext:フィールドは、指示に注入されるプロジェクトの背景情報です — これらは別物です。openspec doctorはセットが健全かどうかを答え、openspec contextはセットが何かを答えます。

個人用ワークセット

ベータ版。 ワークセットは新しいベータ版サーフェスの一部です。コマンド、フラグ、ファイル形式はリリース間で変更される可能性があります。チュートリアルについては、ストアガイドを参照してください。

ワークセットとは、一緒に作業するフォルダを個人用に名前を付けて表示したもので、プランニングルートと、選択したその他のものを含み、自分のマシン上に保持され、ツール内で名前を指定して再度開きます。これは純粋にローカルなものです。コミットされることも、共有されることも、宣言から導出されることもなく、削除してもメンバーフォルダに影響を与えることはありません。

bash

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

createは短いガイド付きフローを実行します（または--memberフラグを非対話的に受け取ります。最初のメンバーがプライマリで、セッションはそこから開始されます）。openは選択したツールを起動します。エディタ（VS Code、Cursor）はすべてのメンバーを含むウィンドウを開いて戻ります。CLIエージェント（Claude Code、codex）はこのターミナルを、すべてのメンバーが接続されプロンプトが事前入力されていないセッションとして引き継ぎ、終了時に終了します。開く時点でメンバーフォルダが存在しない場合は、メモ付きでスキップされ、残りは開きます。保存されたツールの設定は、--toolを使用して開くごとに上書きできます。

新しいツールのサポートは設定であり、コードではありません。すべてのツールは2つの起動スタイルのいずれかです — workspace-file（生成された.code-workspaceで起動）またはattach-dirs（メンバーごとに1つのアタッチフラグ）— そしてグローバルconfig.json（openspec config editで開く）のopenersキーは、フィールドごとにツールを追加したり内蔵ツールを調整したりします：

json

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

すべてのワークセット状態は、グローバルデータディレクトリのworksets/フォルダの下に置かれます（保存されたビューと生成された<name>.code-workspaceファイルを含み、開くたびに再生成されます）。そのフォルダを削除すると、すべての痕跡が除去されます。

閲覧コマンド

`openspec list`

プロジェクト内の変更またはスペックを一覧表示します。

openspec list [options]

オプション：

オプション	説明
`--specs`	変更の代わりにスペックを一覧表示
`--changes`	変更を一覧表示（デフォルト）
`--sort <order>`	`recent`（デフォルト）または`name`で並べ替え
`--json`	JSONとして出力

例：

bash

# すべてのアクティブな変更を一覧表示
openspec list

# すべてのスペックを一覧表示
openspec list --specs

# スクリプト用のJSON出力
openspec list --json

出力（テキスト）：

Changes:
  add-dark-mode     No tasks      just now

`openspec view`

スペックと変更を探索するための対話型ダッシュボードを表示します。

openspec view

プロジェクトの仕様と変更をナビゲートするためのターミナルベースのインターフェースを開きます。

`openspec show`

変更またはスペックの詳細を表示します。

openspec show [item-name] [options]

引数：

引数	必須	説明
`item-name`	いいえ	変更またはスペックの名前（省略時はプロンプトが表示されます）

オプション：

オプション	説明
`--type <type>`	タイプを指定：`change`または`spec`（曖昧でない場合は自動検出）
`--json`	JSONとして出力
`--no-interactive`	プロンプトを無効化

変更固有のオプション：

オプション	説明
`--deltas-only`	デルタスペックのみを表示（JSONモード）

スペック固有のオプション：

オプション	説明
`--requirements`	要件のみを表示、シナリオを除外（JSONモード）
`--no-scenarios`	シナリオコンテンツを除外（JSONモード）
`-r, --requirement <id>`	1ベースのインデックスで特定の要件を表示（JSONモード）

例：

bash

# 対話型選択
openspec show

# 特定の変更を表示
openspec show add-dark-mode

# 特定のスペックを表示
openspec show auth --type spec

# 解析用のJSON出力
openspec show add-dark-mode --json

Validation Commands

`openspec validate`

変更と仕様を構造的な問題に対して検証し、変更の MODIFIED 要件が置き換えるメイン仕様に対してチェックします。

openspec validate [item-name] [options]

仕様デルタがゼロの変更は、.openspec.yaml で skip_specs: true を宣言していない限り検証に失敗します（純粋なリファクタリング、ツール、またはドキュメント作業向け — Recipe 5 を参照）。

引数:

引数	必須	説明
`item-name`	いいえ	検証する特定の商品（省略時はプロンプトが表示されます）

オプション:

オプション	説明
`--all`	すべての変更と仕様を検証します
`--changes`	すべての変更を検証します
`--specs`	すべての仕様を検証します
`--archived`	アーカイブされた変更のすべてのタスクが完了していることを検証します（pre-commit リント用）
`--type <type>`	名前が曖昧な場合のタイプを指定します: `change` または `spec`
`--strict`	厳格な検証モードを有効にします
`--json`	JSON 形式で出力します
`--concurrency <n>`	最大並列検証数（デフォルト: 6、または `OPENSPEC_CONCURRENCY` 環境変数）
`--no-interactive`	プロンプトを無効にします

--archived は独自のスコープです: 仕様デルタの検証は行いません（アーカイブ時にすでに適用済み）、changes/archive/ 配下のすべての変更の tasks.md のチェックボックスがすべてチェックされていることを確認し、未チェックがある場合は非ゼロで終了します。これにより、未完了の作業が残ったままアーカイブされた変更を検出できます — pre-commit フックで便利です。

例:

bash

# インタラクティブな検証
openspec validate

# 特定の変更を検証
openspec validate add-dark-mode

# すべての変更を検証
openspec validate --changes

# JSON 出力ですべてを検証（CI/スクリプト用）
openspec validate --all --json

# 並列度を上げて厳格な検証
openspec validate --all --strict --concurrency 12

# アーカイブされた変更で未チェックのタスクがある場合に失敗
openspec validate --archived

出力（テキスト）:

Validating add-dark-mode...
  ✓ proposal.md valid
  ✓ specs/ui/spec.md valid
  ⚠ design.md: missing "Technical Approach" section

1 warning found

出力（JSON）:

json

{
  "version": "1.0.0",
  "results": {
    "changes": [
      {
        "name": "add-dark-mode",
        "valid": true,
        "warnings": ["design.md: missing 'Technical Approach' section"]
      }
    ]
  },
  "summary": {
    "total": 1,
    "valid": 1,
    "invalid": 0
  }
}

Lifecycle Commands

`openspec archive`

完了した変更をアーカイブし、デルタ仕様をメイン仕様にマージします。

openspec archive [change-name] [options]

引数:

引数	必須	説明
`change-name`	いいえ	アーカイブする変更（省略時はプロンプトが表示されます。プロンプトに応答できない場合は必須です）

オプション:

オプション	説明
`-y, --yes`	確認プロンプトをスキップします。プロンプトに応答できない場合（AI エージェント、CI ジョブ、または stdin が閉じられている実行）に必須です
`--skip-specs`	1 回のアーカイブ実行で仕様更新をスキップします。永続的に仕様デルタを持たない変更は、代わりに `.openspec.yaml` で `skip_specs: true` を宣言すべきです — フラグなしでアーカイブされます
`--no-validate`	検証をスキップします（確認が必要）。また、capability の廃止も無効になります — 検証結果がないため、何も廃止されません

例:

bash

# インタラクティブなアーカイブ（どの変更か尋ね、確認します）
openspec archive

# 特定の変更をアーカイブ
openspec archive add-dark-mode

# プロンプトなしでアーカイブ（エージェント、CI、スクリプト）
openspec archive add-dark-mode --yes

# 仕様に影響しないツール変更をアーカイブ
openspec archive update-ci-config --skip-specs

capability を廃止する: 変更メタデータに廃止マーカーを追加します:

yaml

# openspec/changes/retire-legacy/.openspec.yaml
schema: spec-driven
retire_capabilities: true

その後、通常どおり変更をアーカイブします:

bash

openspec archive retire-legacy --yes

変更が capability の最後の要件を削除する場合、OpenSpec はそのライブ spec.md を削除します。同じ変更内の他の capability デルタは引き続きメイン仕様を更新します。マーカーがない場合、アーカイブはファイルを変更する前に停止し、マーカーを追加するよう指示します。

実行内容:

変更を検証します（--no-validate 指定時は除く）
確認をプロンプトします（--yes 指定時は除く）
メイン仕様を変更する前に、アーカイブ先を確保します
アクティブなデルタ仕様を検証し、openspec/specs/ にマージします — 変更が最後の要件を削除する capability は廃止され、その仕様ファイルは削除されますが、これは変更の .openspec.yaml が schema: の隣に retire_capabilities: true を宣言した場合のみです
変更フォルダを openspec/changes/archive/YYYY-MM-DD-<name>/ に移動します
完全なアーカイブが確保される前に仕様変更または最終移動が失敗した場合、仕様を復元し、変更をアクティブなパスに留めまたは戻します
検証済みのフォールバックコピーが完了したがステージングソースのクリーンアップが失敗した場合、完全なアーカイブとコミット済みの仕様状態を復旧のために保持します

ターミナルなしの場合: AI エージェント、CI ジョブ、または stdin が閉じられている実行はステップ 2 に応答できないため、アーカイブは何も触らずに停止し、終了コード 1 で終了し、再実行するコマンドを指定します — openspec archive <name> --yes（渡した他のフラグも引き継ぎます）。往復をスキップするには、最初から --yes（および変更名）を渡してください。

ワークフローコマンド

これらのコマンドは、アーティファクト駆動のOPSXワークフローをサポートします。人間が進捗を確認する場合と、エージェントが次のステップを判断する場合の両方に役立ちます。

`openspec new change`

解決されたOpenSpecルートに変更ディレクトリとオプションのチェックインメタデータを作成します。

bash

openspec new change <name> [options]

変更名には小文字のケバブケースを使用する必要があります。小文字、数字、単一のハイフンが使用できます。スペース、アンダースコア、大文字、連続するハイフン、先頭・末尾のハイフンは使用できません。先頭の数字は許可されているため、順序付けや階層化のために名前の前に数字を付けることができます。例：100-add-featureや00001-add-auth。

オプション:

オプション	説明
`--description <text>`	`index.md`に追加する説明
`--goal <text>`	変更とともに保存するオプションの目標メタデータ
`--schema <name>`	使用するワークフロースキーマ
`--store <id>`	OpenSpecルートとして使用するストアID（登録したスタンドアロンのOpenSpecリポジトリ）
`--json`	JSONで出力

例:

bash

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

`openspec status`

変更のアーティファクト完了状況を表示します。

openspec status [options]

オプション:

オプション	説明
`--change <id>`	変更名（省略時はプロンプト）
`--schema <name>`	スキーマの上書き（変更の設定から自動検出）
`--json`	JSONとして出力

例:

bash

# 対話的な状況確認
openspec status

# 特定の変更の状況
openspec status --change add-dark-mode

# エージェント用のJSON
openspec status --change add-dark-mode --json

出力 (テキスト):

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

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

skip_specs: trueを宣言する変更では、スペックステージが[~] specs (skipped: change declares skip_specs)と表示され、進捗カウントから除外されます。

出力 (JSON):

json

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

isPlanningCompleteは、スキップされていないすべての計画アーティファクトが存在するかどうかを報告します。スキップされたアーティファクトは作成されなくても満たされたものとして扱われます。実装タスクが完了しているかどうかは報告しません。isCompleteは互換性のためのエイリアスであり、同じ値を持ちます。

アーティファクトは依存関係の順序で一覧表示されます。依存先がそれを必要とするものよりも後に現れることはありません。同時に準備完了となるアーティファクト（spec-drivenのspecsとdesignはどちらもproposalのみが必要）は、アルファベット順ではなくスキーマが宣言する順序を維持します。したがって、最初のreadyエントリが次に作成すべきアーティファクトです。

`openspec instructions`

アーティファクトの作成またはタスクの適用のための拡張指示を取得します。AIエージェントが次に何を作成すべきかを理解するために使用されます。

openspec instructions [artifact] [options]

引数:

引数	必須	説明
`artifact`	No	アーティファクトID、またはワークフローの入力サーフェス: `apply` または `archive`

オプション:

オプション	説明
`--change <id>`	変更名（非対話モードでは必須）
`--schema <name>`	スキーマの上書き
`--json`	JSONとして出力

特別なケース: applyを使用するとタスクの実装指示を取得します。archiveを使用すると、有効な変更の現在の読み取り専用アーカイブ入力（contextとoperationGuidance）を取得します。アーカイブや変更は行いません。

例:

bash

# 次のアーティファクトの指示を取得
openspec instructions --change add-dark-mode

# 特定のアーティファクトの指示を取得
openspec instructions design --change add-dark-mode

# 適用/実装指示を取得
openspec instructions apply --change add-dark-mode

# アーカイブせずに現在のアーカイブ操作入力を取得
openspec instructions archive --change add-dark-mode --json

# エージェントが利用するJSON
openspec instructions design --change add-dark-mode --json

出力には以下が含まれます:

アーティファクトのテンプレート内容
設定からのプロジェクトコンテキスト
依存アーティファクトの内容
設定からのアーティファクトごとのルール
apply/archive用の現在のプロジェクトコンテキストと一致する操作ガイダンス

操作入力は呼び出しのたびに解決されたリポジトリまたは選択されたストアから読み取られます。プロジェクトコンテキストは必須のプロンプトレベルの入力です。エージェントはそれを読み取り、関連するプロジェクトの事実、慣習、制約を適用します。操作ガイダンスは任意の追加的な助言です。エージェントはすべてのエントリを考慮し、適用可能で組み込みワークフローと互換性のあるエントリのみに従います。どちらのフィールドも、明示的なユーザー選択、CLIで制御される状態、組み込み指示、アーティファクトルールとは独立しています。競合するコンテキストは報告され、競合するまたは適用できないガイダンスは従わず、その理由が説明されます。これらは生成されたエージェントに対する動作上の契約であり、CLIで強制されるチェックではありません。instructions archiveは選択された変更、オプションの入力、ルートメタデータのみを返し、静的なアーカイブワークフローは含みません。

skip_specs: trueによってスキップされたアーティファクトの場合、出力は警告のみです（JSONではskipped/warningフィールドが追加されます）。そのアーティファクトを作成してはいけません。

`openspec templates`

スキーマ内の全アーティファクトの解決済みテンプレートパスを表示します。

openspec templates [options]

オプション:

オプション	説明
`--schema <name>`	調査するスキーマ（デフォルト: `spec-driven`）
`--json`	JSONとして出力

例:

bash

# デフォルトスキーマのテンプレートパスを表示
openspec templates

# カスタムスキーマのテンプレートを表示
openspec templates --schema my-workflow

# プログラムで使用するJSON
openspec templates --json

出力 (テキスト):

スキーマ: spec-driven

テンプレート:
  proposal  → ~/.openspec/schemas/spec-driven/templates/proposal.md
  specs     → ~/.openspec/schemas/spec-driven/templates/specs.md
  design    → ~/.openspec/schemas/spec-driven/templates/design.md
  tasks     → ~/.openspec/schemas/spec-driven/templates/tasks.md

`openspec schemas`

利用可能なワークフロースキーマを説明とアーティファクトフローとともに一覧表示します。

openspec schemas [options]

オプション:

オプション	説明
`--json`	JSONとして出力
`--store <id>`	OpenSpecルートとして登録済みストアを使用

例:

bash

openspec schemas

出力:

利用可能なスキーマ:

  spec-driven (package)
    デフォルトの仕様駆動開発ワークフロー
    フロー: proposal → specs → design → tasks

  my-custom (project)
    このプロジェクトのカスタムワークフロー
    フロー: research → proposal → tasks

スキーマコマンド

カスタムワークフロースキーマの作成と管理に関するコマンド。

`openspec schema init`

新しいプロジェクトローカルのスキーマを作成します。

openspec schema init <name> [options]

引数:

引数	必須	説明
`name`	はい	スキーマ名（kebab-case）

オプション:

オプション	説明
`--description <text>`	スキーマの説明
`--artifacts <list>`	カンマ区切りのアーティファクトID（デフォルト: `proposal,specs,design,tasks`）
`--default`	プロジェクトのデフォルトスキーマとして設定
`--no-default`	デフォルトとして設定するか確認しない
`--force`	既存のスキーマを上書き
`--json`	JSON形式で出力

例:

bash

# インタラクティブなスキーマ作成
openspec schema init research-first

# 特定のアーティファクトを指定して非インタラクティブに実行
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

作成されるもの:

openspec/schemas/<name>/
├── schema.yaml           # スキーマ定義
└── templates/
    ├── proposal.md       # 各アーティファクト用のテンプレート
    ├── specs.md
    ├── design.md
    └── tasks.md

`openspec schema fork`

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

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

引数:

引数	必須	説明
`source`	はい	コピーするスキーマ
`name`	いいえ	新しいスキーマ名（デフォルト: `<source>-custom`）

オプション:

オプション	説明
`--force`	既存の宛先を上書き
`--json`	JSON形式で出力

例:

bash

# 組み込みの spec-driven スキーマをフォーク
openspec schema fork spec-driven my-workflow

`openspec schema validate`

スキーマの構造とテンプレートを検証します。

openspec schema validate [name] [options]

引数:

引数	必須	説明
`name`	いいえ	検証対象のスキーマ（省略するとすべて検証）

オプション:

オプション	説明
`--verbose`	詳細な検証ステップを表示
`--json`	JSON形式で出力

例:

bash

# 特定のスキーマを検証
openspec schema validate my-workflow

# すべてのスキーマを検証
openspec schema validate

`openspec schema which`

スキーマがどこから解決されるかを表示します（優先順位のデバッグに有用）。

openspec schema which [name] [options]

引数:

引数	必須	説明
`name`	いいえ	スキーマ名

オプション:

オプション	説明
`--all`	ソースを含むすべてのスキーマを一覧表示
`--json`	JSON形式で出力

例:

bash

# スキーマのソースを確認
openspec schema which spec-driven

出力:

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

スキーマの優先順位:

プロジェクト: openspec/schemas/<name>/
ユーザー: ~/.local/share/openspec/schemas/<name>/
パッケージ: 組み込みスキーマ

設定コマンド

`openspec config`

グローバルな OpenSpec 設定を表示および変更します。

openspec config <subcommand> [options]

サブコマンド:

サブコマンド	説明
`path`	設定ファイルの場所を表示
`list`	現在のすべての設定を表示
`get <key>`	特定の値を取得
`set <key> <value>`	値を設定
`unset <key>`	キーを削除
`reset`	デフォルトに戻す
`edit`	`$EDITOR` で開く
`profile [preset]`	ワークフロープロファイルをインタラクティブに、またはプリセットで構成

例:

bash

# 設定ファイルのパスを表示
openspec config path

# すべての設定を一覧表示
openspec config list

# 特定の値を取得
openspec config get telemetry.enabled

# 値を設定（匿名の使用状況テレメトリを無効化）
openspec config set telemetry.enabled false

# 文字列値を明示的に設定
openspec config set user.name "My Name" --string

# カスタム設定を削除
openspec config unset user.name

# マシンレベルのデフォルトストアを設定（--store、ローカルルート、またはプロジェクトストアのポインターが解決されない場合のフォールバックルート）
openspec config set defaultStore team-plans

# すべての設定をリセット
openspec config reset --all --yes

# エディターで設定を編集
openspec config edit

# アクションベースのウィザードでプロファイルを構成
openspec config profile

# 高速プリセット：ワークフローを core に切り替え（delivery モードは保持）
openspec config profile core

テレメトリのオプトアウト: telemetry.enabled は未設定の場合、デフォルトでオンになっています（オプトアウトモデル）。匿名の使用状況統計と openspec update のバージョンチェックを無効にするには、これを false に設定してください。環境変数は設定より優先されます：OPENSPEC_TELEMETRY=0、DO_NOT_TRACK=1、そして真値を持つ CI 値（例：true/1/yes）は、設定値に関係なく常にテレメトリを無効にします。

openspec config profile は現在の状態の要約から始まり、以下の選択を促します：

delivery とワークフローの変更
delivery のみ変更
ワークフローのみ変更
現在の設定を維持（終了）

現在の設定を維持する場合、変更は保存されず、更新プロンプトも表示されません。設定に変更がない場合でも、現在のプロジェクトファイルがグローバルプロファイル/delivery と同期していない場合、OpenSpec は警告を表示し、openspec update を提案します。 Ctrl+C を押すと、クリーンにフローがキャンセルされ（スタックトレースなし）、コード 130 で終了します。ワークフローチェックリストでは、[x] はグローバル設定でワークフローが選択されていることを意味します。これらの選択をプロジェクトファイルに適用するには、openspec update を実行するか（プロジェクト内でプロンプトが表示された場合は Apply changes to this project now? を選択）、該当するオプションを選択します。

インタラクティブ例:

bash

# delivery のみの更新
openspec config profile
# 選択: Change delivery only
# delivery の選択: Skills only

# ワークフローのみの更新
openspec config profile
# 選択: Change workflows only
# チェックリストでワークフローを切り替え、確認

ユーティリティコマンド

`openspec feedback`

OpenSpec に関するフィードバックを送信します。GitHub イシューを作成します。

openspec feedback <message> [options]

引数:

引数	必須	説明
`message`	はい	フィードバックの要約；長いテキストはイシュータイトルでは短縮され、本文にはそのまま保持されます

オプション:

オプション	説明
`--body <text>`	要約の後に含まれる追加の詳細

要件: GitHub CLI (gh) がインストールされ、認証されている必要があります。

例:

bash

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

`openspec completion`

OpenSpec CLI のシェルスクリプト補完を管理します。

openspec completion <subcommand> [shell]

サブコマンド:

サブコマンド	説明
`generate [shell]`	補完スクリプトを stdout に出力
`install [shell]`	シェルに対して補完をインストール
`uninstall [shell]`	インストールされた補完を削除

サポートされているシェル: bash, zsh, fish, powershell

例:

bash

# 補完をインストール（シェルを自動検出）
openspec completion install

# 特定のシェルに対してインストール
openspec completion install zsh

# 手動インストール用のスクリプトを生成（bash）
openspec completion generate bash > ~/.bash_completion.d/openspec

# アンインストール
openspec completion uninstall

Windows (PowerShell): 現在の PowerShell ホストに対して補完をインストールします：

powershell

$env:PROFILE = $PROFILE
openspec completion install powershell
. $PROFILE

$env:PROFILE は、このセッションでどのプロファイルを構成すべきかを OpenSpec に伝えます。インストーラーは不足しているプロファイルディレクトリを作成し、OpenSpecCompletion.ps1 をロードする管理ブロックを追加します。プロファイルを再読み込みすると、即座に補完が有効になります。

現在のホストからアンインストールするには、以下を実行します：

powershell

$env:PROFILE = $PROFILE
openspec completion uninstall powershell

アンインストール後は、現在のセッションから補完をクリアするために PowerShell を再起動してください。

補完はオプトインです。CLI は対話型ターミナルでコマンドを初めて実行した際に一度だけ stderr に通知し、それ以降は沈黙します（すでに補完がインストールされている場合も同様です）。OPENSPEC_NO_COMPLETIONS=1 を設定すると、そのヒント全体を抑制できます。

終了コード

コード	意味
`0`	成功
`1`	エラー（検証失敗、ファイル欠落など）

環境変数

変数	説明
`OPENSPEC_TELEMETRY`	`0` に設定すると、テレメトリと `openspec update` のバージョンチェックが無効になります（グローバル設定の `telemetry.enabled` を上書き）
`DO_NOT_TRACK`	`1` に設定すると、テレメトリと `openspec update` のバージョンチェックが無効になります（標準的な DNT シグナル；設定を上書き）
`OPENSPEC_CONCURRENCY`	バルク検証のデフォルトの並列数（デフォルト: 6）
`EDITOR` または `VISUAL`	`openspec config edit` で使用するエディター
`NO_COLOR`	設定するとカラー出力が無効になります
`OPENSPEC_NO_ANIMATION`	設定すると、`openspec init` のウェルカムアニメーションが無効になります
`OPENSPEC_NO_COMPLETIONS`	`1` に設定すると、シェル補完に関する一回限りのヒントが抑制されます
`OPENSPEC_NO_UPDATE_CHECK`	設定すると、新しい公開済み CLI に対する `openspec update` チェックが無効になります（空値を含む任意の値）。`CI` が設定されている場合（`false`/`0`/`no`/`off` 以外の場合）または `NODE_ENV=test` の場合もスキップされます
`npm_config_registry`	`openspec update` のバージョンチェックが問い合わせるレジストリ。`http(s)` URL である必要があり、そうでない場合は `https://registry.npmjs.org` にフォールバックします。`.npmrc` ファイルは読み込まれません

CLI リファレンス ​

サマリー ​

Human vs Agent Commands ​

Human-Only Commands ​

Agent-Compatible Commands ​

Global Options ​

Setup Commands ​

openspec init ​

openspec update ​

Stores（スタンドアロン OpenSpec リポジトリ） ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

プロジェクトから Store を参照する ​

Store のクローン元を記録する ​

デフォルト Store を宣言する ​

ドクター（関係性の健全性） ​

作業コンテキスト（組み立てられたセット） ​

個人用ワークセット ​

閲覧コマンド ​

openspec list ​

openspec view ​

openspec show ​

Validation Commands ​

openspec validate ​

Lifecycle Commands ​

openspec archive ​

ワークフローコマンド ​

openspec new change ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

スキーマコマンド ​

openspec schema init ​

openspec schema fork ​

openspec schema validate ​

openspec schema which ​

設定コマンド ​

openspec config ​

ユーティリティコマンド ​

openspec feedback ​

openspec completion ​

終了コード ​

環境変数 ​

関連ドキュメント ​

CLI リファレンス

サマリー

Human vs Agent Commands

Human-Only Commands

Agent-Compatible Commands

Global Options

Setup Commands

`openspec init`

`openspec update`

Stores（スタンドアロン OpenSpec リポジトリ）

`openspec store setup`

`openspec store register`

`openspec store unregister`

`openspec store remove`

`openspec store list`

`openspec store doctor`

プロジェクトから Store を参照する

Store のクローン元を記録する

デフォルト Store を宣言する

ドクター（関係性の健全性）

作業コンテキスト（組み立てられたセット）

個人用ワークセット

閲覧コマンド

`openspec list`

`openspec view`

`openspec show`

Validation Commands

`openspec validate`

Lifecycle Commands

`openspec archive`

ワークフローコマンド

`openspec new change`

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

スキーマコマンド

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

設定コマンド

`openspec config`

ユーティリティコマンド

`openspec feedback`

`openspec completion`

終了コード

環境変数

関連ドキュメント