dx-org-snapshot-manage

dx-org-snapshot-manage

Coordinates the full lifecycle of Salesforce scratch org snapshots — create, get (status), list, and delete — via sf org create snapshot, sf org get snapshot, sf org list snapshot, and sf org delete snapshot. A snapshot is a point-in-time copy of a scratch org (its metadata and data) that you reference by name in a scratch org definition file to spin up new orgs from saved state.

Tool Restrictions

Use ONLY the Bash tool to execute the sf org ... snapshot commands. Do NOT use MCP tools — ignore them completely.

Output artifacts for eval/testing: ALWAYS write the command's complete JSON response to a file when an output directory is available. Do NOT ask the user what file to write — this skill defines the filenames. After executing each command: (1) if the user specified an output path, write there immediately; (2) otherwise run [ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output' to detect the eval directory; (3) write the command's full, unmodified JSON response to <output-dir>/<filename> using these filenames: create-snapshot-result.json, get-snapshot-result.json, list-snapshots-result.json, or delete-snapshot-result.json. This is the generated output — write it without asking. (4) If no output directory can be found by either check, include the command's complete, unmodified JSON response verbatim (e.g. in a fenced code block) in your final reply instead of skipping the artifact.

Relationship to Other Skills

This skill owns the full snapshot lifecycle — create, get status, list, and delete. It does not create scratch orgs.

• Any snapshot operation (create, status, list, delete, expiry check) → this skill.
• Create a scratch org, including from an existing snapshot (--snapshot <name>) → dx-org-manage.
• Org shapes (baseline config without data, sf org create/list/delete shape) → dx-org-shape-manage. Shapes and snapshots are different artifacts with different commands — see the comparison below.

| | Snapshot (this skill) | Org Shape (dx-org-shape-manage) | |--|----------|-----------| | Captures | Full point-in-time copy: metadata and data | Baseline config only: features, limits, edition, Metadata API settings | | Commands | sf org create/get/list/delete snapshot | sf org create/list/delete shape | | Referenced via | snapshot (name) in the scratch def file | sourceOrg (org ID) in the scratch def file | | Prerequisite | Dev Hub has Scratch Org Snapshots enabled | Source org has Org Shape for Scratch Orgs enabled | | Operates against | A Dev Hub (--target-dev-hub) | The source org (--target-org) |

Scope

• In scope: Creating (sf org create snapshot), getting status (sf org get snapshot), listing (sf org list snapshot), and deleting (sf org delete snapshot) scratch org snapshots
• Out of scope: Creating org shapes (dx-org-shape-manage), creating scratch orgs — including from a snapshot (dx-org-manage)

Required Inputs

Infer from the user's request:

• Operation: create, get, list, or delete (see Workflow step 1)
• Dev Hub: Username or alias of the Dev Hub that owns the snapshots. Passed via --target-dev-hub (-v); optional if the target-dev-hub config variable is set. All four commands operate against a Dev Hub, never --target-org.
• Source org (create only): Scratch org ID (starts with 00D), username, or alias to snapshot. Passed via --source-org (-o).
• Snapshot name (create only): A unique name for the snapshot, max 15 characters. Passed via --name (-n).
• Snapshot name or ID (get & delete only): Name, or ID (starts with 0Oo), of the snapshot. Passed via --snapshot (-s).
• Description (create, optional): Documents snapshot contents.
• Expiry threshold in days (expiring-soon listing only): There is no CLI flag for this — it's a client-side filter on ExpirationDate (see Command Patterns).

Workflow

1. Identify the operation and match it to the command pattern below.
2. Resolve the Dev Hub — if --target-dev-hub isn't provided, check the default with sf config get target-dev-hub. Never fabricate a placeholder Dev Hub name (e.g. my-dev-hub) — an unresolved hub is a hard stop; advise sf org login web --set-default-dev-hub instead.
3. For create, confirm the source org and snapshot name — the source must be a scratch org; the name must be unique in the Dev Hub and ≤15 characters.
4. Execute via Bash tool with the --json flag.
5. Report the result (see Output Expectations and the example files).

Command Patterns

Snapshot creation is asynchronous. create returns a record whose Status is typically InProgress initially, with ExpirationDate still null. Poll with sf org get snapshot until Status is Active (verified live against a real Dev Hub — see examples/create_success_output.json vs examples/get_output.json) before using the snapshot to create scratch orgs.

Rules / Constraints

Troubleshooting

Output Expectations

All commands return JSON when --json is used. get/list return the raw OrgSnapshot sobject record(s) — verified live, these include the sobject attributes wrapper plus Id, SnapshotName, Description, Status (New, InProgress, Active, Error, Expired, or Deleted), SourceOrg, CreatedDate, LastModifiedDate, ExpirationDate (null until Active), and Error.

• Create → a single snapshot record (Status is InProgress immediately after creation; ExpirationDate is null).
• Get → a single snapshot record — use it to poll Status.
• List → an array of snapshot records, ordered by CreatedDate. Empty array if none exist.
• Delete → { "id": "0Oo...", "success": true, "errors": [] }. No result if the user declines the confirmation prompt.

See the example files below for exact response structures (captured live against a real Dev Hub, not assumed).

Cross-Skill Integration

Reference File Index

Example Files