forcedotcom/sf-skills / skills/dx-org-manage
dx-org-manage
VerifiedUse to EXECUTE Salesforce org operations immediately via the sf CLI (this skill runs them, it does NOT generate scripts): create scratch orgs (from edition, definition file, snapshot, or org shape), list/display/resume/delete scratch orgs, open orgs in browser. Trigger: 'create scratch org', 'create org from snapshot', 'delete scratch org', 'open my org'. Do NOT use for switching the default org (use dx-org-switch), deploying metadata (use platform-metadata-deploy), or creating/checking/listing/deleting org snapshots (use dx-org-snapshot-manage).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.5 KB |
| assets/derive-alias.shexecutable | script | 3.2 KB |
| assets/scratch-def.seed.json | config | 92 B |
| examples/README.md | markdown | 1.5 KB |
| examples/scratch-orgs/delete_output.json | config | 130 B |
| examples/scratch-orgs/display_output.json | config | 649 B |
| examples/scratch-orgs/error_no_devhub.json | config | 316 B |
| examples/scratch-orgs/error_timeout.json | config | 437 B |
| examples/scratch-orgs/list_output.json | config | 1.9 KB |
| examples/scratch-orgs/resume_output.json | config | 1.2 KB |
| examples/scratch-orgs/success_definition_file.json | config | 891 B |
| examples/scratch-orgs/success_edition.json | config | 789 B |
| examples/scratch-orgs/success_shape.json | config | 1.2 KB |
| examples/scratch-orgs/success_snapshot.json | config | 828 B |
| references/creating-scratch-org.md | markdown | 7.9 KB |
| references/definition_file_options.md | markdown | 7.3 KB |
| references/edition_types.md | markdown | 3.5 KB |
| references/opening-org.md | markdown | 7.5 KB |
| references/scratch-org-create.md | markdown | 16.0 KB |
| references/scratch-org-operations.md | markdown | 6.7 KB |
references/creating-scratch-org.md
View on GitHub# Creating Scratch Orgs
Detailed workflow for creating Salesforce scratch orgs using `sf org create scratch`. Supports four creation methods: definition file, edition flag, snapshot, and org shape.
---
## Required Inputs
Gather or infer before proceeding:
- **Dev Hub org**: Username or alias of authenticated Dev Hub (or use default from `target-dev-hub` config)
- **Creation method**: Which approach to use (see Workflow step 1)
- **Alias**: Optional but recommended for easy reference
Optional but commonly used:
- **Duration**: Days before org expires (default: 7, max: 30)
- **Set as default**: Whether to make this the default org
- **Source tracking**: Whether to enable (default: yes, disable for CI/CD performance)
---
## Workflow
### 1. Identify creation method
Determine which approach based on user request:
| Method | When to use | Required flags |
|--------|-------------|----------------|
| Definition file | User provides config file or needs org features/settings | `--definition-file <path>` |
| Edition only | Quick simple org, no special config needed | `--edition <edition>` |
| Snapshot | Clone from existing snapshot | `--snapshot <name>` |
| Org shape | Mimic another org's structure | `--source-org <id>` |
**Mutually exclusive**: `--edition`, `--snapshot`, and `--source-org` cannot be combined.
### 2. Verify Dev Hub authentication
Check if Dev Hub is authenticated (this mirrors the canonical Step 2 in `SKILL.md` — follow that as the source of truth):
- If `--target-dev-hub` not provided, check `sf config get target-dev-hub`
- If that is empty, enumerate every `sf org list --json` bucket (`devHubs`, `nonScratchOrgs`, `other`, `sandboxes`, `scratchOrgs`) for entries with `isDevHub: true`, then resolve by count:
- **Exactly one** → use that username.
- **Two or more** → ask the user which one; never pick arbitrarily.
- **Zero** → no hub is authenticated. Do NOT run `sf org create` (there is nothing to pass to `--target-dev-hub`). Stop and advise the user to authenticate: `sf org login web --set-default-dev-hub`.
### 3. Build the command
Construct based on creation method:
**Definition file approach:**
```bash
sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json
```
**Edition-only approach:**
```bash
sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json
```
**Snapshot approach:**
```bash
sf org create scratch --snapshot <name> --target-dev-hub <alias> --alias <name> --json
```
**Org shape approach:**
```bash
sf org create scratch --source-org <id> --target-dev-hub <alias> --alias <name> --json
```
**Common optional flags:**
- `--duration-days <days>` — Set expiration (default 7, max 30)
- `--set-default` — Make this the default org
- `--no-track-source` — Disable source tracking for CI/CD performance
- `--wait <minutes>` — Number of minutes to wait for the org to be ready
- `--async` — Return immediately, don't wait for completion
**⚠️ CRITICAL: This is a BLOCKING command**
- The command **WAITS** until the scratch org is fully created (or times out)
- When the command returns success, the org is **READY TO USE** — do NOT poll with `sf org list` waiting for it to become ready
- The JSON response with `username` and `orgId` means creation is **COMPLETE**
- Only use `--async` if you want to check status later with `sf org resume scratch`
- **Note**: SKILL.md Step 4 requires running `sf org list --json` once after creation for artifact collection (not for polling status)
**Before executing, verify:**
- [ ] `--json` flag is present in the command
- [ ] At least ONE of `--edition`, `--snapshot`, `--source-org`, or `--definition-file` is specified (flags can override definition file values)
- [ ] `--snapshot` and `--source-org` are not combined (mutually exclusive)
- [ ] `--target-dev-hub` is resolved (either in command or from config)
### 4. Handle async creation
If `--async` or `--wait` timeout occurs:
- CLI displays: "The scratch org did not complete within your wait time."
- CLI automatically shows the resume command with Request ID
- Timeout exits with code 69
- User can resume with the displayed command: `sf org resume scratch --job-id <request-id> --json`
### 5. Report result
When the command returns, check JSON response. If it contains `username` and `orgId`, the org is **COMPLETE and READY**. Do NOT run additional commands to verify completion.
Successful creation returns:
```json
{
"username": "test-...@example.com",
"orgId": "00D...",
"scratchOrgInfo": {
"Id": "2SR...",
"ScratchOrg": "00D...",
"SignupUsername": "test-...@example.com"
}
}
```
This JSON response means: org is created, authenticated, and ready for `sf org open`, `sf project deploy`, or any other commands.
---
## Rules / Constraints
| Constraint | Rationale |
|-----------|-----------|
| Always include `--json` flag | Returns structured output for parsing success/failure |
| **Command blocks until completion — do NOT poll for status** | The command waits until the org is created (or times out). When it returns with `username` and `orgId` in JSON, the org is ready. Do NOT poll repeatedly with `sf org list` waiting for it to become ready — the command already waited for you. Only exception: if using `--async` flag or command timed out (exit code 69), then use `sf org resume scratch` to check status. **Note**: SKILL.md Step 4 requires a single `sf org list --json` call after creation for artifact collection (not polling) |
| Dev Hub must be authenticated | Scratch org creation requires Dev Hub access |
| `--edition`, `--snapshot`, `--source-org` are mutually exclusive | Only one creation source allowed per command |
| Definition file overrides can use flags | Flags like `--edition`, `--name`, `--username`, `--release`, `--admin-email` override definition file values |
| Snapshot requires same Dev Hub | Snapshot must be created in the same Dev Hub you're using |
| Duration max is 30 days | Platform limit for scratch org expiration |
| Source tracking enabled by default | Disable with `--no-track-source` only for CI/CD or performance needs |
---
## Troubleshooting
| Issue | Resolution |
|-------|------------|
| `No default Dev Hub org found` | Authenticate Dev Hub with `sf org login web --set-default-dev-hub` or specify `--target-dev-hub` |
| `NamedOrgNotFoundError` on Dev Hub | Dev Hub org is not authenticated — run `sf org login web` |
| `edition value must be one of` | Invalid edition specified — use developer, enterprise, group, professional, or partner variants |
| `Snapshot not found` | Snapshot doesn't exist in this Dev Hub — run `sf org list snapshot` to see available |
| `sourceOrg value must be 15 or 18 characters` | Org shape ID format incorrect — use output from `sf org list shape` |
| `The org could not be created` | Generic creation failure — check Dev Hub limits, licensing, or try again |
| Timeout during creation (exit code 69) | Command timed out waiting for org. CLI displays the resume command with Request ID. User can run the displayed command or increase `--wait` time for next attempt |
| `Definition file not found` | Path to definition file is incorrect — verify file exists |
| Partner editions unavailable | Partner editions only work if Dev Hub is a Partner Business Org |
---
## Output Expectations
Deliverables:
- **Created scratch org**: Authenticated and ready to use
- **JSON response**: Contains `username`, `orgId`, `scratchOrgInfo` with Request ID
- **Local auth info**: Stored in `.sf/` directory for future CLI commands
If `--async` used or timeout occurs:
- **Request ID**: Returned in `scratchOrgInfo.Id` (format: `2SR...`)
- **Resume command**: `sf org resume scratch --job-id <request-id> --json`
- **Timeout exit code**: 69
---
## Additional Resources
- See `definition_file_options.md` for org features, settings, and configuration templates
- See `edition_types.md` for available edition types and when to use each
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |