dx-org-manage

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:

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:

sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json

Edition only:

sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json

From snapshot:

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

From org shape:

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:

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:

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:

sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --target-dev-hub <devHub> --json

With description:

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 wants	Command
Open default org	sf org open --json
Open specific org	sf org open --target-org <alias> --json
Specific browser	sf org open --browser chrome --json
Incognito mode	sf org open --private --json
Navigate to path	sf org open --path '<path>' --json
URL only (don't open)	sf org open --url-only --json
Open metadata file	sf 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:

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

Example Files

Example command outputs for testing and troubleshooting:

File	Purpose
examples/scratch-orgs/success_definition_file.json	Successful scratch org creation using --definition-file
examples/scratch-orgs/success_edition.json	Successful scratch org creation using --edition developer
examples/scratch-orgs/success_snapshot.json	Successful scratch org creation using --snapshot
examples/scratch-orgs/error_no_devhub.json	Error when Dev Hub not authenticated
examples/scratch-orgs/error_timeout.json	Timeout error during org creation (exit code 69)
examples/snapshots/success_output.json	Successful snapshot creation
examples/snapshots/error_output.json	Common snapshot error scenarios