mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-05 06:41:42 +08:00
104 lines
3.6 KiB
Markdown
104 lines
3.6 KiB
Markdown
# 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
|
|
|
|
1. **Gather inputs** — get source org, snapshot name, and optional description
|
|
2. **Build command** — construct `sf org create snapshot` with appropriate flags
|
|
3. **Execute via Bash tool** — run command with `--json` flag
|
|
4. **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 <alias>" 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:
|
|
```json
|
|
{
|
|
"result": {
|
|
"SnapshotId": "0Ym...",
|
|
"SnapshotName": "MySnapshot",
|
|
"Status": "Active",
|
|
"SourceOrg": "00D..."
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Using Snapshots
|
|
|
|
After creating a snapshot, use it to create scratch orgs by:
|
|
|
|
1. **In scratch org definition file:**
|
|
```json
|
|
{
|
|
"snapshot": "MySnapshot"
|
|
}
|
|
```
|
|
|
|
2. **Or via command flag:**
|
|
```bash
|
|
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
|