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/scratch-org-operations.md
View on GitHub# Scratch Org Operations
Workflow for operating on **existing** orgs with `sf`: **list**, **display**, **resume**, and
**delete**, plus the shared rules, constraints, and troubleshooting for the whole lifecycle. For
creating an org (edition, definition file, snapshot, org shape, AUTO MODE, STATE A/B, batch,
definition-file authoring), see `scratch-org-create.md`.
---
## Security posture — credential filtering (read first)
The skill relays every input to `sf` **unchanged** and surfaces the CLI's `--json` result —
success or error — for reporting. It does not pre-validate fields, does not normalize or translate
field names, and does not add or strip error text; the CLI already frames its own output. The skill
actively protects against credential leaks: it filters `accessToken` and `sfdxAuthUrl` from
written artifacts and agent context using `jq` before writing any output file. It never runs
`sf org display --verbose` (which returns a refresh token) and it never un-redacts a token the CLI
already redacted.
The skill's own docs/examples never claim a feature is "not enabled" or that a permission is
missing — that framing is the platform's job, delivered through the CLI's own error output.
---
## List
Show the developer's scratch orgs.
```bash
sf org list --json
```
- **Default view:** active scratch orgs from `result.scratchOrgs[]` (answers "which scratch orgs
do I have?").
- **Options (not the default):** `--all` (include expired/deleted/unknown), `--clean` (remove
stale local entries).
- **Report per active org:** alias, username, orgId, expiration date.
- **Artifact:** write the `result.scratchOrgs[]` **array** to `scratch-org-list-result.json`.
---
## Display
Show details of one org.
```bash
sf org display --target-org <alias> --json | jq 'if .status == 0 then {status, result: {alias: .result.alias, username: .result.username, id: .result.id, instanceUrl: .result.instanceUrl, status: .result.status, expirationDate: .result.expirationDate}} else . end'
```
- Plain output only — always the non-verbose form above. **Never add `--verbose`, and never run
it on request.** `--verbose` returns `sfdxAuthUrl` (a refresh token) in command output, which
would pull a live credential into agent context. If the user needs the auth URL, direct them to
run `sf org display --verbose` themselves in their own terminal — do not run it from this skill.
- **Report:** alias, username, orgId, instanceUrl, status, expiration.
- **Artifact:** write the filtered output from the command above to `org-display-result.json`. Never pass accessToken, sfdxAuthUrl, or other credential fields to agent context.
---
## Resume
Continue a create that ran with `--async` or timed out (exit code 69).
```bash
# With an explicit job/request id
sf org resume scratch --job-id <id> --json | jq 'del(.result.accessToken, .result.sfdxAuthUrl, .result.authFields.accessToken, .result.authFields.sfdxAuthUrl)'
# Otherwise, the most recent job
sf org resume scratch --use-most-recent --json | jq 'del(.result.accessToken, .result.sfdxAuthUrl, .result.authFields.accessToken, .result.authFields.sfdxAuthUrl)'
```
Behavior: if the user gives an explicit `--job-id`, use it; otherwise default to
`--use-most-recent`; if there is no recent job, surface the CLI's not-found result unchanged and
point the user to `sf org list`. Do not invent a job id. **Artifact:** write the filtered output
from the command above to `scratch-org-resume-result.json`.
---
## Delete
Delete a scratch org. **Destructive — no undo.**
```bash
sf org delete scratch --target-org <alias> --no-prompt --json | jq 'del(.result.accessToken, .result.sfdxAuthUrl, .result.authFields.accessToken, .result.authFields.sfdxAuthUrl)'
```
- **Always confirm first** ("Delete scratch org `X`?") before running — UNLESS the user already
gave explicit deletion intent.
- **Extra-guard the default org:** if the target is the current default org, call that out in the
confirmation.
- `--no-prompt` is passed on the CLI *after* the skill's own confirmation, so the agent isn't
left waiting on an interactive prompt.
- **Artifact:** write the filtered output from the command above to `scratch-org-delete-result.json`.
---
## Rules / constraints
| Constraint | Rationale |
|-----------|-----------|
| Always include `--json` | Structured output for parsing success/failure |
| Create blocks until completion — do NOT poll | The command waits until the org is ready; when it returns `username`/`orgId`, the org is ready. The single post-create `sf org list` call is for artifact collection, not polling. Exception: `--async` or a timeout (exit 69) → use `sf org resume scratch` |
| Dev Hub must be resolvable | Creation requires Dev Hub access (default hub, named hub, or pick-from-list when none is set) |
| One creation source *type* per command | Edition, snapshot, and shape are mutually exclusive; a same-dimension flag override is allowed |
| Duration max is 30 days | Platform limit |
| Confirm before delete | Destructive, no undo; extra-guard the default org |
---
## Troubleshooting (errors are pass-through — surface the CLI's own message)
| Issue | Next step |
|-------|-----------|
| `No default Dev Hub org found` | Authenticate with `sf org login web --set-default-dev-hub` or name one with `--target-dev-hub` |
| `NamedOrgNotFoundError` on Dev Hub | Dev Hub not authenticated — run `sf org login web` |
| `edition value must be one of` | Use developer/enterprise/group/professional, or a partner edition (CLI flag hyphenated, e.g. `partner-developer`) |
| `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` | Source org ID format incorrect — pass the 15/18-char `00D…` org ID of the org the shape was captured from |
| Timeout during creation (exit code 69) | CLI prints a resume command with the request ID; run it or increase `--wait` next time |
| `Definition file not found` | Path is incorrect — verify the file exists (re-ask/re-list rather than guessing) |
| Partner editions unavailable | Partner editions require the Dev Hub to be a Partner Business Org |
---
## Additional resources
- `scratch-org-create.md` — creating orgs (edition, definition file, snapshot, org shape),
AUTO MODE, STATE A/B, batch create, and definition-file authoring
- `definition_file_options.md` — features, settings, and definition-file schema
- `edition_types.md` — edition selection and the CLI-flag-vs-definition-file format distinction
- `dx-org-snapshot-manage` skill — create/check/list/delete a snapshot before referencing it here; this file only covers consuming an existing, `Active` snapshot via `--snapshot`/the `snapshot` definition-file field
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 |