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

Identify the operation and match it to the command pattern below.
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.
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.
Execute via Bash tool with the
```
--json
```
flag.
Report the result (see Output Expectations and the example files).

Command Patterns

Operation	User intent	Execute via Bash tool
Create	Create snapshot with name only	`sf org create snapshot --source-org <orgId\|alias> --name <SnapshotName> --json`
Create	Create snapshot with description	`sf org create snapshot --source-org <orgId\|alias> --name <SnapshotName> --description "<desc>" --json`
Create	Specify Dev Hub explicitly	`sf org create snapshot --source-org <orgId\|alias> --name <SnapshotName> --target-dev-hub <devHub> --json`
Get	Check a snapshot's status/details	`sf org get snapshot --snapshot <name\|0Oo...> --json`
List	List all snapshots in the Dev Hub	`sf org list snapshot --json`
List	List snapshots expiring within N days	`sf org list snapshot --json` → filter on `ExpirationDate` with `jq` (see `references/cli_flags.md` )
Delete	Delete a snapshot (with confirm prompt)	`sf org delete snapshot --snapshot <name\|0Oo...> --json`
Delete	Delete without prompting (scripts/CI)	`sf org delete snapshot --snapshot <name\|0Oo...> --no-prompt --json`
Delete	Delete multiple/all snapshots	First `sf org list snapshot --json` , confirm the target names with the user, then run `sf org delete snapshot --snapshot <name>` once per snapshot — there is no bulk-delete command

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

Active

(verified live against a real Dev Hub — see

examples/create_success_output.json

examples/get_output.json

) before using the snapshot to create scratch orgs.

Rules / Constraints

Constraint	Rationale
Always use `--json` flag	Provides structured output for reliable parsing and error handling
All commands operate against a Dev Hub	`--target-dev-hub` (not `--target-org` ) — optional only if the `target-dev-hub` config is set
Dev Hub must have Scratch Org Snapshots enabled	Otherwise commands fail — contact Salesforce to enable it
Source org (create) must be a scratch org	Snapshots only work with scratch orgs
Snapshot names must be unique in the Dev Hub, ≤15 characters	Longer names fail with `STRING_TOO_LONG` (verified live)
Creation is asynchronous	`create` may return before the snapshot is `Active` — poll with `sf org get snapshot`
There is no update/rename/extend-expiration command.	Verified — the CLI (and the underlying platform object) exposes only create/get/list/delete. To change a snapshot's name, description, or expiration, delete it and create a new one.
There is no bulk-delete command.	Each `sf org delete snapshot` call removes exactly one snapshot
`sf org list snapshot` has no server-side filters	Returns every visible snapshot; filter status/expiry client-side (e.g. with `jq` )
`delete` prompts for confirmation by default	Use `--no-prompt` ( `-p` ) for non-interactive/CI use
Bulk/ `--no-prompt` deletes require an explicit confirmation step	Before deleting multiple or all snapshots — or any delete with `--no-prompt` — first run `sf org list snapshot --json` , echo the resolved target names back to the user, and get explicit confirmation. Deletion is irreversible.
Permissions affect visibility/deletion	Users see/delete only their own snapshots unless a Dev Hub admin grants View All / Modify All

Troubleshooting

Issue	Resolution
`@salesforce/plugin-signups does not exist in the registry`	Snapshot commands live in the `signups` plugin, bundled with a normal `sf` install. This means the CLI environment is incomplete (slim/offline image) — do NOT attempt `sf plugins install` in an offline environment, it will fail and loop. Advise repairing the environment ( `sf update` , or a fresh install) from a connected machine.
`Scratch Org Snapshots isn't enabled for your Dev Hub.`	The Dev Hub lacks the snapshot feature — contact Salesforce to enable it
`No snapshot found with the given name or id: <value>` ( `SingleRecordQuery_NoRecords` )	Verified live on `get` / `delete` — the name/ID doesn't exist in this Dev Hub. Run `sf org list snapshot --json` to see available snapshots
`STRING_TOO_LONG` — "Org Snapshot Name: data value too large... (max length=15)"	Verified live — the `--name` value exceeds 15 characters. Shorten it and retry
Snapshot name already exists ( `DuplicateValue` )	Names must be unique per Dev Hub — choose a different name
`Status` is `InProgress` for a while	Creation is asynchronous — keep polling `sf org get snapshot` until `Status` becomes `Active`
`Status` is `Error` (see the `Error` field)	Read the `Error` field, delete the failed snapshot, and recreate
`NotADevHubError`	The targeted org isn't a Dev Hub — point `--target-dev-hub` at an actual Dev Hub
No default Dev Hub org found	Provide `--target-dev-hub <alias>` or set a default with `sf config set target-dev-hub=<alias>`

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

Need	Delegate to
Create a scratch org from a snapshot	`dx-org-manage` skill (set `snapshot` to the snapshot name in the definition file, or `--snapshot <name>` )
Create/list/delete an org shape instead of a snapshot	`dx-org-shape-manage` skill

Reference File Index

File	When to read
`references/cli_flags.md`	Detailed flag reference across create/get/list/delete, including the `jq` pipeline for filtering snapshots expiring soon
`references/snapshot_usage.md`	Using a snapshot name in a scratch org definition file, once it's `Active`

Example Files

File	Purpose
`examples/create_success_output.json`	Successful snapshot creation ( `Status: InProgress` )
`examples/create_error_output.json`	`STRING_TOO_LONG` — name over 15 characters
`examples/get_output.json`	Get response for an `Active` snapshot ( `ExpirationDate` populated)
`examples/list_output.json`	List response — array of snapshot records
`examples/delete_output.json`	Successful delete response

dx-org-snapshot-manage

NPX Install

Tags

SKILL.md Content

dx-org-snapshot-manage

Tool Restrictions

Relationship to Other Skills

Scope

Required Inputs

Workflow

Command Patterns

Rules / Constraints

Troubleshooting

Output Expectations

Cross-Skill Integration

Reference File Index

Example Files