dx-org-snapshot-manage

dx-org-snapshot-manage

Salesforce スクラッチ組織のスナップショットのライフサイクル全体（作成、状態の取得、一覧表示、削除）を、sf org create snapshot、sf org get snapshot、sf org list snapshot、sf org delete snapshot を使って管理します。スナップショットとは、スクラッチ組織（メタデータとデータ）の特定時点のコピーです。スクラッチ組織定義ファイルで名前を指定することで、保存した状態から新しい組織を作成できます。

---

ツールの制限

sf org ... snapshot コマンドの実行には、Bash ツールのみを使用してください。MCP ツールは使用せず、完全に無視してください。

評価／テスト用の出力アーティファクト： 出力ディレクトリが利用可能な場合は、コマンドの完全な JSON レスポンスを必ずファイルに書き込んでください。どのファイルに書き込むかをユーザーに尋ねないでください。このスキルでファイル名を指定しています。各コマンドの実行後、次の手順に従ってください。（1）ユーザーが出力先を指定した場合は、ただちにそこへ書き込みます。（2）指定がない場合は、[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output' を実行して評価用ディレクトリを確認します。（3）コマンドの完全かつ未変更の JSON レスポンスを、次のファイル名で <output-dir>/<filename> に書き込みます。create-snapshot-result.json、get-snapshot-result.json、list-snapshots-result.json、delete-snapshot-result.json を使用してください。これは生成された出力です。確認を求めずに書き込んでください。（4）いずれの方法でも出力ディレクトリが見つからない場合は、アーティファクトの作成を省略する代わりに、最終返信にコマンドの完全かつ未変更の JSON レスポンスをそのまま含めてください（たとえば、フェンス付きコードブロックを使用します）。

---

他のスキルとの関係

このスキルは、スナップショットのライフサイクル全体（作成、状態の取得、一覧表示、削除）を担当します。スクラッチ組織は作成しません。

• スナップショットに関する操作全般（作成、状態確認、一覧表示、削除、有効期限の確認）→ このスキル。
• スクラッチ組織の作成（既存のスナップショットからの作成を含む）（--snapshot <name>）→ dx-org-manage。
• 組織シェイプ（データを含まないベースライン設定、sf org create/list/delete shape）→ dx-org-shape-manage。シェイプとスナップショットは、コマンドも異なる別々のアーティファクトです。以下の比較を参照してください。

	スナップショット（このスキル）	組織シェイプ（dx-org-shape-manage）
取得内容	特定時点の完全なコピー：メタデータとデータ	ベースライン設定のみ：機能、制限、エディション、Metadata API 設定
コマンド	sf org create/get/list/delete snapshot	sf org create/list/delete shape
参照方法	スクラッチ組織定義ファイルで snapshot（名前）を指定	スクラッチ組織定義ファイルで sourceOrg（組織 ID）を指定
前提条件	Dev Hub で Scratch Org Snapshots が有効になっている	Source org で Org Shape for Scratch Orgs が有効になっている
操作対象	Dev Hub（--target-dev-hub）	ソース組織（--target-org）

---

対象範囲

• 対象：スクラッチ組織スナップショットの作成（sf org create snapshot）、状態取得（sf org get snapshot）、一覧表示（sf org list snapshot）、削除（sf org delete snapshot）
• 対象外：組織シェイプの作成（dx-org-shape-manage）、スナップショットから作成する場合を含むスクラッチ組織の作成（dx-org-manage）

---

必須入力

ユーザーの依頼から以下を判断します。

• 操作：作成、取得、一覧表示、削除のいずれかです（ワークフローの手順 1 を参照）。
• Dev Hub：スナップショットを所有する Dev Hub のユーザー名またはエイリアスです。--target-dev-hub（-v）で渡します。target-dev-hub 設定変数が設定されている場合は省略できます。4 つすべてのコマンドは Dev Hub に対して実行され、--target-org は使用しません。
• ソース組織（作成のみ）：スナップショットを作成するスクラッチ組織の ID（00D で始まります）、ユーザー名、またはエイリアスです。--source-org（-o）で渡します。
• スナップショット名（作成のみ）：スナップショットに付ける一意の名前です。最大 15 文字です。--name（-n）で渡します。
• スナップショット名または ID（取得と削除のみ）：スナップショットの名前、または ID（0Oo で始まります）です。--snapshot（-s）で渡します。
• 説明（作成時、任意）：スナップショットの内容を記録します。
• 有効期限が近いと判断する日数のしきい値（有効期限が近いものの一覧表示のみ）：これを指定する CLI フラグはありません。ExpirationDate に対するクライアント側のフィルターです（コマンドパターンを参照）。

---

ワークフロー

1. 操作を特定し、以下のコマンドパターンに当てはめます。
2. Dev Hub を解決します。--target-dev-hub が指定されていない場合は、sf config get target-dev-hub でデフォルトを確認します。Dev Hub 名のプレースホルダー（例：my-dev-hub）を捏造してはいけません。Hub を解決できない場合は処理を中止し、代わりに sf org login web --set-default-dev-hub を案内します。
3. 作成の場合は、ソース組織とスナップショット名を確認します。ソースはスクラッチ組織である必要があり、名前は Dev Hub 内で一意かつ 15 文字以下である必要があります。
4. --json フラグを使い、Bash ツールで実行します。
5. 結果を報告します（出力に関する期待事項とサンプルファイルを参照）。

コマンドパターン

操作	ユーザーの意図	Bash ツールで実行
作成	名前のみを指定してスナップショットを作成する	sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --json
作成	説明を指定してスナップショットを作成する	sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --description "<desc>" --json
作成	Dev Hub を明示的に指定する	sf org create snapshot --source-org <orgId|alias> --name <SnapshotName> --target-dev-hub <devHub> --json
取得	スナップショットのステータス／詳細を確認する	sf org get snapshot --snapshot <name|0Oo...> --json
一覧表示	Dev Hub 内のすべてのスナップショットを一覧表示する	sf org list snapshot --json
一覧表示	N 日以内に有効期限を迎えるスナップショットを一覧表示する	sf org list snapshot --json → jq で ExpirationDate をフィルターします（references/cli_flags.md を参照）
削除	スナップショットを削除する（確認プロンプトあり）	sf org delete snapshot --snapshot <name|0Oo...> --json
削除	プロンプトなしで削除する（スクリプト／CI）	sf org delete snapshot --snapshot <name|0Oo...> --no-prompt --json
削除	複数またはすべてのスナップショットを削除する	最初に sf org list snapshot --json を実行して対象の名前をユーザーに確認し、その後、スナップショットごとに sf org delete snapshot --snapshot <name> を 1 回ずつ実行します。一括削除コマンドはありません

スナップショットの作成は非同期です。 create は、通常、初期状態で Status が InProgress、ExpirationDate が null のレコードを返します。スナップショットを使ってスクラッチ組織を作成する前に、Status が Active になるまで sf org get snapshot でポーリングします（実際の Dev Hub でのライブ検証については、examples/create_success_output.json と examples/get_output.json を参照してください）。

---

ルール／制約

制約	理由
常に --json フラグを使用する	信頼性の高い解析とエラー処理のために、構造化された出力が得られます
すべてのコマンドは Dev Hub を対象に実行する	--target-dev-hub（--target-org ではありません）を使用します。target-dev-hub の設定がある場合に限り、省略できます
Dev Hub で Scratch Org Snapshots が有効になっている必要がある	有効でない場合、コマンドは失敗します。有効化するには Salesforce に問い合わせてください
ソース組織（作成対象）は スクラッチ組織 である必要がある	スナップショットはスクラッチ組織でのみ機能します
スナップショット名は Dev Hub 内で 一意 かつ 15 文字以下 である必要がある	15 文字を超えると STRING_TOO_LONG で失敗します（実環境で確認済み）
作成は 非同期 で行われる	create はスナップショットが Active になる前に返る場合があります。sf org get snapshot でポーリングしてください
更新／名前変更／有効期限延長のコマンドはありません。	確認済みです。CLI（および基盤となるプラットフォームオブジェクト）で利用できるのは、create／get／list／delete のみです。スナップショットの名前、説明、有効期限を変更するには、削除して新しく作成してください。
一括削除コマンドはありません。	sf org delete snapshot の呼び出しごとに、削除されるスナップショットは 1 つだけです
sf org list snapshot にサーバー側のフィルターはありません	表示可能なすべてのスナップショットが返されます。ステータスや有効期限による絞り込みはクライアント側で行ってください（例：jq を使用）
delete はデフォルトで確認を求める	非対話型／CI 環境で使用する場合は --no-prompt（-p）を使用してください
一括削除／--no-prompt による削除には、明示的な確認手順が必要です	複数またはすべてのスナップショットを削除する前、または --no-prompt を指定して削除する前に、まず sf org list snapshot --json を実行し、対象として確定した名前をユーザーに提示して、明示的な確認を得てください。削除は取り消せません。
権限によって表示／削除の可否が異なる	Dev Hub 管理者が View All／Modify All を付与しない限り、ユーザーに表示されるのは自身のスナップショットのみで、削除できるのも自身のスナップショットのみです

---

トラブルシューティング

問題	解決策
@salesforce/plugin-signups does not exist in the registry	スナップショットコマンドは signups プラグインに含まれており、通常の sf インストールに同梱されています。このエラーは CLI 環境が不完全であることを意味します（スリム版／オフラインイメージ）。オフライン環境で sf plugins install を実行しないでください。失敗して繰り返し実行されます。ネットワークに接続されたマシンから環境を修復するよう案内してください（sf update、または新規インストール）。
Scratch Org Snapshots isn't enabled for your Dev Hub.	Dev Hub でスナップショット機能が有効になっていません。有効化するには Salesforce に問い合わせてください
No snapshot found with the given name or id: <value> (SingleRecordQuery_NoRecords)	get／delete で実環境にて確認済みです。この Dev Hub に該当する名前／IDはありません。利用可能なスナップショットを確認するには sf org list snapshot --json を実行してください
STRING_TOO_LONG — "Org Snapshot Name: data value too large... (max length=15)"	実環境にて確認済みです。--name の値が 15 文字を超えています。短くして再試行してください
スナップショット名がすでに存在する（DuplicateValue）	名前は Dev Hub ごとに一意である必要があります。別の名前を選んでください
Status がしばらく InProgress のまま	作成は非同期で行われます。Status が Active になるまで sf org get snapshot でポーリングを続けてください
Status が Error（Error フィールドを確認）	Error フィールドを読み、失敗したスナップショットを削除してから再作成してください
NotADevHubError	対象の組織は Dev Hub ではありません。--target-dev-hub に実際の Dev Hub を指定してください
デフォルトの Dev Hub 組織が見つからない	--target-dev-hub <alias> を指定するか、sf config set target-dev-hub=<alias> でデフォルトを設定してください

---

出力の想定

--json を使用すると、すべてのコマンドが JSON を返します。get／list は生の OrgSnapshot sobject レコードを返します。実環境で確認したところ、これらには sobject の attributes ラッパーに加え、Id、SnapshotName、Description、Status（New、InProgress、Active、Error、Expired、Deleted のいずれか）、SourceOrg、CreatedDate、LastModifiedDate、ExpirationDate（Active になるまでは null）、Error が含まれます。

• 作成 → 単一のスナップショットレコード（作成直後の Status は InProgress、ExpirationDate は null です）。
• 取得 → 単一のスナップショットレコード。Status のポーリングに使用します。
• 一覧表示 → CreatedDate 順のスナップショットレコードの配列。存在しない場合は空の配列です。
• 削除 → { "id": "0Oo...", "success": true, "errors": [] }。ユーザーが確認プロンプトで拒否した場合、結果はありません。

実際の Dev Hub に対して実行して取得した正確なレスポンス構造については、以下のサンプルファイルを参照してください（推測に基づくものではありません）。

---

スキル間の連携

必要な操作	委譲先
スナップショットからスクラッチ組織を作成する	dx-org-manage スキル（定義ファイルで snapshot にスナップショット名を設定するか、--snapshot <name> を指定）
スナップショットではなく組織の シェイプ を作成／一覧表示／削除する	dx-org-shape-manage スキル

---

参照ファイル一覧

ファイル	参照するタイミング
references/cli_flags.md	作成／取得／一覧表示／削除に関する詳細なフラグリファレンス。期限が近いスナップショットを絞り込む jq パイプラインも含まれます
references/snapshot_usage.md	スナップショットが Active になった後、スクラッチ組織の定義ファイルでスナップショット名を使用する方法

サンプルファイル

ファイル	用途
examples/create_success_output.json	スナップショットの作成成功（Status: InProgress）
examples/create_error_output.json	STRING_TOO_LONG — 15 文字を超える名前
examples/get_output.json	Active スナップショットの取得レスポンス（ExpirationDate が設定されています）
examples/list_output.json	一覧表示レスポンス — スナップショットレコードの配列
examples/delete_output.json	削除成功レスポンス