Creating Snapshots

Creates a point-in-time snapshot of a scratch org using sf org create snapshot. Snapshots preserve scratch org state and configuration for reuse in scratch org definition files.

Required Inputs

Infer from the user's request:

Source org: Scratch org ID (starts with 00D) or username/alias to snapshot
Snapshot name: Unique name for the snapshot (required)
Dev Hub: Dev Hub org alias/username (uses default if not specified)
Description (optional): Document snapshot contents, version control reference

Workflow

Gather inputs — get source org, snapshot name, and optional description
Build command — construct sf org create snapshot with appropriate flags
Execute via Bash tool — run command with --json flag
Return result — report snapshot ID and status

Command Patterns

User intent	Execute via Bash tool
Create snapshot with name only	`sf org create snapshot --source-org <orgId or alias> --name <SnapshotName> --json`
Create snapshot with description	`sf org create snapshot --source-org <orgId or alias> --name <SnapshotName> --description "<desc>" --json`
Specify Dev Hub explicitly	`sf org create snapshot --source-org <orgId or alias> --name <SnapshotName> --target-dev-hub <devHubAlias> --json`

Rules / Constraints

Constraint	Rationale
Always use `--json` flag	Provides structured output for reliable parsing and error handling
Snapshot names must be unique in the Dev Hub	Duplicate names cause creation to fail
Source org must be a scratch org	Snapshots only work with scratch orgs, not sandboxes or production orgs
Dev Hub must have snapshot feature enabled	"NOT_FOUND" error means Dev Hub doesn't support snapshots
Source org accepts ID or username/alias	Command auto-resolves aliases to org IDs; org IDs start with 00D
Include description for tracking	Best practice: reference version control tag or commit ID in description

Troubleshooting

Issue	Resolution
"NOT_FOUND" error when creating snapshot	Dev Hub doesn't have snapshot feature enabled — contact admin to enable in Dev Hub settings
"No org found for " error	Source org alias doesn't exist or isn't authenticated — verify with `sf org list`
Snapshot name already exists	Use a different unique name — snapshot names must be unique per Dev Hub
"An error while created the org snapshot"	Generic error — check that source org is a scratch org and still active
Long-running snapshot creation	Use `sf org get snapshot --snapshot <name>` to check status — snapshot creation is asynchronous

Output Expectations

The command returns JSON output with the created snapshot details.

See examples/snapshots/success_output.json and examples/snapshots/error_output.json for complete response structures.

Example success response:

{
  "result": {
    "SnapshotId": "0Ym...",
    "SnapshotName": "MySnapshot",
    "Status": "Active",
    "SourceOrg": "00D..."
  }
}

Using Snapshots

After creating a snapshot, use it to create scratch orgs by:

In scratch org definition file:
```
{
  "snapshot": "MySnapshot"
}
```

Or via command flag:

sf org create scratch --snapshot MySnapshot --target-dev-hub <alias> --alias <name> --json

See snapshot_usage.md for detailed examples.

Additional Resources

See cli_flags.md for detailed explanation of all available flags
See snapshot_usage.md for how to use snapshots in scratch org creation

3.6 KiB Raw Permalink Blame History