dx org manage

Skill

INVOKE this skill to execute Salesforce org operations: create scratch orgs, create org snapshots, open orgs in browser. This skill EXECUTES operations immediately - it does NOT generate scripts or code files. ALWAYS invoke this skill (do not execute SF CLI commands directly) when user requests to: create a scratch org (Developer/Enterprise edition, from definition file (.json), from snapshot, or from org shape), create an org snapshot, or open a Salesforce org. Trigger phrases include: 'create a snapshot', 'create snapshot of my scratch org', 'take a snapshot', 'create scratch org', 'create a Developer edition scratch org', 'new scratch org', 'spin up an org', 'create org from snapshot', 'scratch-def.json', 'project-scratch-def.json', 'open my Salesforce org', 'open org in browser', 'get me the URL'. Do NOT use for switching default org (use dx-org-switch) or deploying metadata (use platform-metadata-deploy).

Files16
  • @skills/dx-org-manage/SKILL.md
  • @skills/dx-org-manage/examples/README.md
  • @skills/dx-org-manage/examples/scratch-orgs/error_no_devhub.json
  • @skills/dx-org-manage/examples/scratch-orgs/error_timeout.json
  • @skills/dx-org-manage/examples/scratch-orgs/success_definition_file.json
  • @skills/dx-org-manage/examples/scratch-orgs/success_edition.json
  • @skills/dx-org-manage/examples/scratch-orgs/success_snapshot.json
  • @skills/dx-org-manage/examples/snapshots/error_output.json
  • @skills/dx-org-manage/examples/snapshots/success_output.json
  • @skills/dx-org-manage/references/cli_flags.md
  • @skills/dx-org-manage/references/creating-scratch-org.md
  • @skills/dx-org-manage/references/creating-snapshot.md
  • @skills/dx-org-manage/references/definition_file_options.md
  • @skills/dx-org-manage/references/edition_types.md
  • @skills/dx-org-manage/references/opening-org.md
  • @skills/dx-org-manage/references/snapshot_usage.md

MANDATORY: Follow these instructions exactly. Do NOT fall back to MCP tools.

Tool constraint: Use the Bash tool for all sf CLI commands. Always include --json for structured output. Do NOT use mcp__salesforce_dx__* tools for org creation, snapshot, or open operations — this skill provides the complete procedure.
Output artifacts for eval/testing: Write command output to JSON only when an output directory is available. After executing the command: (1) if the user specified an output path, write there; (2) otherwise run [ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output' to detect the eval directory; (3) if the command printed a path, write the command's JSON response to <printed-path>/<filename> using these filenames: scratch-org-result.json for org creation, snapshot-result.json for snapshot creation, or org-url-result.json for open operations. The eval framework needs the real command output to verify success.

Creating Scratch Orgs

REQUIRED steps — execute in order:
Step 1. Identify creation method from user request:
  • Contains "definition file" or path to .json → definition file method
  • Contains "snapshot" or "from snapshot" → snapshot method
  • Contains "org shape" or "source-org" → org shape method
  • Otherwise → run ls config/project-scratch-def.json config/scratch-def.json 2>/dev/null | head -1 to detect a definition file. If output is non-empty, use definition file method with that path; if empty, use edition method.
Step 2. Check Dev Hub:
bash
sf config get target-dev-hub --json
  • If no Dev Hub is set, advise: sf org login web --set-default-dev-hub
  • Do NOT proceed until a Dev Hub is confirmed.
Step 3. Build and execute the command based on method:
Definition file:
bash
sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json
Edition only:
bash
sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json
From snapshot:
bash
sf org create scratch --snapshot <snapshot-name> --target-dev-hub <alias> --alias <name> --json
From org shape:
bash
sf org create scratch --source-org <org-id> --target-dev-hub <alias> --alias <name> --json
Apply these flags when requested:
  • --duration-days <days> — default 7, max 30
  • --set-default — make this the default org
  • --no-track-source — disable source tracking (for CI/CD)
Step 4. MANDATORY - Run org list and write output: After the org is created, you MUST run this command:
bash
sf org list --json
Then:
  1. Parse the JSON result and find the scratchOrgs array
  2. Find the entry where username matches the username from Step 3's creation result
  3. Extract that complete org object (it will include: alias, username, orgId, instanceUrl, loginUrl, isDefaultUsername, connectedStatus, lastUsed, etc.)
  4. Report to the user:
    • Created scratch org.
    • Alias: [alias from the org list entry]
    • Username: [username]
    • Org ID: [orgId]
  5. If an output directory is available (per the output artifacts rule above), write ONLY that extracted org object (NOT the full creation result) to <output-dir>/scratch-org-result.json
Example: If sf org list --json returns {"result": {"scratchOrgs": [{"alias": "feature-dev", "username": "test@example.com", "orgId": "00D...", ...}]}}, write just the inner org object {"alias": "feature-dev", "username": "test@example.com", "orgId": "00D...", ...} to the file.
Do NOT write the creation command's output. Do NOT suggest verification steps to the user.
Error handling:
  • "Snapshot not found" → suggest sf org list snapshot --target-dev-hub <alias>
  • "No default Dev Hub" → advise sf org login web --set-default-dev-hub
When you need more detail:
  • For available features, settings, and definition file structure → load references/definition_file_options.md
  • For edition selection guidance and comparison → load references/edition_types.md
  • For snapshot workflow and post-creation usage → load references/snapshot_usage.md
  • For complete scratch org creation workflow → load references/creating-scratch-org.md

Creating Snapshots

REQUIRED steps — execute in order:
Step 1. Get inputs:
  • Source org: scratch org ID or alias (from user)
  • Snapshot name: unique name (from user)
  • Description: optional (from user)
Step 2. Determine Dev Hub:
  • If user specifies a Dev Hub (alias or username) → use that value
  • Otherwise, check for default:
bash
sf config get target-dev-hub --json
  • If no default Dev Hub is set, advise: sf org login web --set-default-dev-hub
Step 3. Execute:
bash
sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --target-dev-hub <devHub> --json
With description:
bash
sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --description "<desc>" --target-dev-hub <devHub> --json
Step 4. Report result: Returns JSON with SnapshotId and Status. If an output directory is available (per the output artifacts rule above), write the JSON response to <output-dir>/snapshot-result.json.
Error handling:
  • "NOT_FOUND" → Dev Hub doesn't have snapshot feature enabled
  • "Snapshot name already exists" → use a different unique name
When you need more detail:
  • For complete snapshot creation workflow and flag reference → load references/creating-snapshot.md
  • For CLI flag reference → load references/cli_flags.md

Opening Orgs

REQUIRED steps — execute in order:
Step 1. Match user request to command:
User wantsCommand
Open default orgsf org open --json
Open specific orgsf org open --target-org <alias> --json
Specific browsersf org open --browser chrome --json
Incognito modesf org open --private --json
Navigate to pathsf org open --path '<path>' --json
URL only (don't open)sf org open --url-only --json
Open metadata filesf org open --source-file <file-path> --json
Step 2. Execute the matching command using the Bash tool.
Step 3. Report result: Returns URL or opens browser. If an output directory is available (per the output artifacts rule above), write the JSON response to <output-dir>/org-url-result.json.
Error handling:
  • "no target org" → advise sf config set target-org <alias>
  • "auth error" → advise sf org login web --alias <alias>
When you need more detail:
  • For complete opening org workflow and all available flags → load references/opening-org.md

Reference File Index

Load these reference files for detailed guidance:
FileWhen to read
references/definition_file_options.mdUser needs to configure org features, settings, or advanced definition file options beyond basic org creation
references/edition_types.mdUser asks which edition to choose or needs to understand edition differences
references/snapshot_usage.mdUser wants to use snapshots in definition files or needs post-snapshot workflow guidance
references/creating-scratch-org.mdTroubleshooting scratch org creation failures or need complete workflow with all options
references/cli_flags.mdUser needs complete snapshot CLI flag reference
references/creating-snapshot.mdTroubleshooting snapshot creation failures or need detailed snapshot workflow
references/opening-org.mdUser needs to navigate to specific setup paths, open metadata files, or use advanced open flags

Example Files

Example command outputs for testing and troubleshooting:
FilePurpose
examples/scratch-orgs/success_definition_file.jsonSuccessful scratch org creation using --definition-file
examples/scratch-orgs/success_edition.jsonSuccessful scratch org creation using --edition developer
examples/scratch-orgs/success_snapshot.jsonSuccessful scratch org creation using --snapshot
examples/scratch-orgs/error_no_devhub.jsonError when Dev Hub not authenticated
examples/scratch-orgs/error_timeout.jsonTimeout error during org creation (exit code 69)
examples/snapshots/success_output.jsonSuccessful snapshot creation
examples/snapshots/error_output.jsonCommon snapshot error scenarios
dx-org-manage — Kortix Marketplace | Kortix