Terminal
Terminal/Skill
Lists, checks, creates, refreshes, activates, and deletes Salesforce sandboxes through the Connect REST API, and reports license usage.
By Salesforce
Works with
npx skills add forcedotcom/sf-skills --skill platform-sandbox-configureManage Salesforce sandbox environments through Connect REST API — list inventory, activate or discard completed refreshes, create and refresh sandboxes, and permanently delete sandboxes.
Use platform-sandbox-configure when the work involves:
Delegate elsewhere when the user is:
SandboxInfo sObject)automation-sandbox-post-copy-config-generateautomation-sandbox-post-copy-configureWhen the user types sandbox -help or sandbox help, respond with ONLY a text message showing the numbered operation list below. Do NOT call any API or tool — just display this menu and wait for the user to reply with a number.
The agent MUST respond with this exact markdown (not in a code block — render it directly as a bullet list):
Sandbox Lifecycle Management
1. Inventory & Details
2. Create & Refresh
3. Activate, Discard & Delete
4. Verify & Monitor
5. Post-Copy Automation
Reply with a code (e.g. "3a") or describe what you need.
After the user replies, ask for the required input:
| Selection | Follow-up question |
|---|---|
| 1a | No input needed — proceed immediately |
| 1b | "What's the sandbox name?" |
| 1c | "What's the sandbox ID? (starts with 07E)" |
| 1d | No input needed — proceed immediately |
| 2a | First call GET /sandbox/licenses (Section 9) and show available/used counts; then ask for name + license type (Developer, Developer_Pro, Partial_Copy, Full) |
| 2b | First call GET /sandbox/reports (Section 1) and list refresh-eligible sandboxes (isPendingActivation: false); then ask which to refresh |
| 3a | "Which sandbox? Provide a name or 07E ID." |
| 3b | "Which sandbox? Provide a name or 07E ID." |
| 3c | "Which sandbox? Provide a name or 07E ID." |
| 4a | "Which sandbox did you activate? Provide a name or 07E ID." |
| 4b | "Which sandbox did you delete? Provide a name or 07E ID." |
| 5a | "Delegating to the post-copy config generator — please share the SOP (file, text, or screenshot)." |
| 5b | "Delegating to the post-copy config runner — please share the config JSON file and the target sandbox." |
Execute the corresponding operation below. Exception: 5a/5b delegate — 5a → automation-sandbox-post-copy-config-generate; 5b → automation-sandbox-post-copy-configure. This skill does not implement post-copy automation; do not generate or apply a config directly.
CRITICAL: For sandbox operations in this skill, use the Connect REST API. Two discovery paths exist:
GET /sandbox/reports to list all sandboxes and find the matching one by sandboxName.GET /sandbox/sandboxes/{sandboxId} directly — do NOT call /sandbox/reports.Both paths return sandbox records with sandboxId (prefix 07E) which is required for all lifecycle mutation operations.
sf api request rest "/services/data/v66.0/sandbox/reports" --method GET
See references/api-response-shapes.md for the full response shape.
IMPORTANT: Do NOT use Tooling API (SandboxInfo/SandboxProcess) for discovery — mutation endpoints require the Connect REST API's sandboxId (07E), NOT SandboxInfo.Id (0GQ) or SandboxProcess.Id (0GR).
NEVER use SOQL / run_soql_query / sf data query for lifecycle reads (status, inventory, details, license, pending-activation). This data lives ONLY in the Connect REST API — no SObject returns it. (sf data query --use-tooling-api on SandboxInfo is still valid for Create/Refresh mutations, not a lifecycle read.)
Report API results exactly as they come back — never invent an error or a cause. count: 0 is a successful result (sandbox absent) — record not_found, don't reinterpret as a failure or retry via SOQL. If the API errors, capture the error body verbatim — do NOT speculate why (e.g. "must be a scratch org"); this endpoint doesn't report org edition/type, so any such guess is a fabrication.
Required permission: ManageSandboxes
| Action | Why irreversible |
|---|---|
| Create | Consumes a license of the selected type |
| Activate | Overwrites sandbox with refreshed data |
| Discard | Refresh data is lost |
| Delete | Sandbox permanently removed |
Refresh with AutoActivate=true | Auto-applies on completion — same effect as Activate |
Endpoint: GET /services/data/v66.0/sandbox/reports
Returns a list of all sandboxes with their IDs, names, statuses, and license types.
sf api request rest "/services/data/v66.0/sandbox/reports" --method GET
See references/api-response-shapes.md for the full response shape.
Use when: User asks "show me all sandboxes", "how many sandboxes do I have", "what's the status of my sandboxes"
Key response fields:
sandbox.sandboxId (07E prefix) — Required for all mutation operationssandbox.sandboxName — The sandbox name (top-level field)sandbox.license — Developer, Developer Pro, Partial Copy, Fullsandbox.isPendingActivation — true if refresh is pending activationsandbox.canActivate / canDelete / canDiscard — Permission flagsEndpoint: GET /services/data/v66.0/sandbox/sandboxes/{sandboxId}
Returns detailed info for a specific sandbox.
Use when: User asks about a specific sandbox's status, configuration, or metadata.
Key response fields:
status — Active, Pending Activation, Activating, Completed, etc.isPendingActivation — true if a refresh completed and awaits user decisionsandboxType — Developer, DeveloperPro, PartialCopy, FullsourceId — ID of the source orgEndpoint: PATCH /services/data/v66.0/sandbox/activate/{sandboxId}
CRITICAL DOMAIN RULE: This operation ONLY applies to sandboxes with a completed refresh in "Pending Activation" state. It applies the refreshed data to the sandbox. It does NOT "bring an inactive sandbox online" or "start" a sandbox.
Pre-conditions:
Pending Activation statusManageSandboxes permissionBefore calling PATCH /activate:
Pending Activation status via GET /sandbox/sandboxes/{id} (isPendingActivation: true)Use when: User says "activate it", "apply the refresh", "use the latest data"
After activation: The sandbox runs with the newly refreshed production data.
Endpoint: GET /services/data/v66.0/sandbox/sandboxes/{sandboxId}
Poll this endpoint after activation to confirm status changed to Active. This is a verification step, not a standalone user action.
Use when: Agent needs to confirm activation completed (called automatically after activate).
Endpoint: DELETE /services/data/v66.0/sandbox/discardsandbox/{sandboxId}
CRITICAL DOMAIN RULE: This operation ONLY applies to sandboxes with a completed refresh in "Pending Activation" state. It rejects the refresh — the existing sandbox continues running with its current data unchanged. It does NOT:
Pre-conditions:
Pending Activation statusBefore calling DELETE /discardsandbox:
Pending Activation status via GET /sandbox/sandboxes/{id} (isPendingActivation: true)Use when: User says "discard the refresh", "keep existing data", "don't apply the refresh", "reject the refresh"
WARNING: Discard is not reversible. The user will need to trigger a new refresh if they want fresh production data later.
Endpoint: DELETE /services/data/v66.0/sandbox/deletesandbox/{sandboxId}
Permanently removes a sandbox and frees the license.
Pre-conditions:
ManageSandboxes permissionBefore calling DELETE /deletesandbox:
Use when: User says "delete this sandbox", "remove it permanently", "free up the license"
WARNING: This is irreversible. Always confirm with the user before executing. Surface the sandbox name, license, and status as a safety check.
If asked to restore a deleted sandbox: No recovery path is documented today — escalate to Support rather than guessing at one.
Creates a new sandbox from scratch. Two approaches are supported — pick based on the user's preference; default to Approach A unless the user asks for a definition file or a repeatable DX blueprint.
Pre-conditions:
ManageSandboxes permissionBefore creating — always confirm first:
Collected Name/License; asked about that license's optional inputs (references/definition-file-approach.md)
Shown this confirmation summary — common fields plus the license's own fields:
Creating a new sandbox — please confirm:
- Name:
<SandboxName>- Description:
<Description or "(none)">- Create From: Production
- License:
<Developer | Developer Pro | Partial Copy | Full>- (plus this license's fields — see
references/definition-file-approach.md)Feel free to change any of these before I proceed.
Received explicit confirmation — this consumes a license of the selected type
API: Tooling API — SandboxInfo sObject
Required inputs:
SandboxName — Name for the new sandbox (alphanumeric, max 10 chars)LicenseType — One of: Developer, Developer_Pro, Partial_Copy, FullOptional inputs:
Description — sandbox purposeFeatures — storage upgrade: Developer→400 MB, Developer_Pro→2 GB (irreversible); not for Partial_Copy/FullApexClassId — Apex class implementing SandboxPostCopy (runs post-creation)ActivationUserGroupId — Access group (default: All Active Users)TemplateId / HistoryDays / CopyChatter / CopyArchivedActivities — Partial_Copy/Full-only; per-license table in references/definition-file-approach.md# Create a Developer sandbox
sf data create record --sobject SandboxInfo --use-tooling-api --values "SandboxName='mybox' LicenseType='Developer'"
DX-native path: write a JSON definition file, then sf org create sandbox --definition-file <file> --alias <name> --target-org <org>. Prefer for a checked-in, repeatable config or name-based Apex/group references. See references/definition-file-approach.md for the JSON example, command, and field table.
After creation: A SandboxProcess record is created with Status = Processing. The sandbox copy begins immediately.
Wrong type created: Delete and recreate with the correct type.
Renaming: Not a standalone action — only takes effect via a Refresh's SandboxName input.
Refreshes a sandbox with the latest production data. Two approaches are supported — pick based on the user's preference; default to Approach A unless the user asks for a definition file.
API: Tooling API — SandboxInfo sObject (PATCH)
Refreshes by updating the existing SandboxInfo record.
Required inputs:
SandboxInfo record ID (0GQ prefix)Optional inputs:
SandboxName — New name for the refreshed sandbox (if user wants to rename it; alphanumeric, max 10 chars)Description — New or updated description for the sandboxAutoActivate — true to auto-activate when refresh completes (default: false)Features — storage upgrade: Developer→400 MB, Developer_Pro→2 GB (irreversible); not for Partial_Copy/FullActivationUserGroupId — Access group (default: All Active Users)TemplateId / HistoryDays / CopyChatter — Partial_Copy/Full-only; per-license table in references/definition-file-approach.mdBefore triggering refresh — always confirm first:
Collected the sandbox name; asked about its license's optional inputs (references/definition-file-approach.md)
Shown this confirmation summary:
Refreshing sandbox
<name>— please confirm:
- Rename to:
<SandboxName or "(no change)">- Description:
<Description or "(no change)">- Auto-Activate:
<Yes | No (default)>- Sandbox Access:
<ActivationUserGroupId or "All Active Users">- (plus this license's fields — see
references/definition-file-approach.md)Feel free to change any of these before I proceed.
Received explicit confirmation — refresh overwrites the sandbox with production data; Auto-Activate=Yes applies automatically (equivalent to Activate)
Steps:
# 1. Look up SandboxInfo record Id by name
sf data query --query "SELECT Id, SandboxName, LicenseType, Description FROM SandboxInfo WHERE SandboxName = '<name>'" --use-tooling-api --json
# 2. PATCH to trigger refresh; include SandboxName/Description only if the user changed them
# Description is free text — escape any embedded single quotes (' -> \') before interpolating
sf data update record --sobject SandboxInfo --use-tooling-api --record-id <0GQ-id> --values "AutoActivate=true SandboxName='<newName>' Description='<description>'"
Refresh from the same JSON definition-file blueprint used for create, using sf org refresh sandbox --name <name> --definition-file <file> --target-org <org>. See references/definition-file-approach.md for the JSON example, command, and field table.
Pre-conditions:
ManageSandboxes permissionAfter refresh: A new SandboxProcess record is created with Status = Processing. If AutoActivate=true, the sandbox activates automatically when done. Otherwise it enters Pending Activation state.
Refresh interval not met: State the last-refreshed date and eligible date. For a fresher copy sooner, a clone (delegated) works if a spare license exists.
Endpoint: GET /services/data/v66.0/sandbox/licenses
Returns license capacity, usage, and remaining counts per license type — no sandbox name or ID needed.
sf api request rest "/services/data/v66.0/sandbox/licenses" --method GET
See references/api-response-shapes.md for the full response shape.
Use when: User asks "how many sandbox licenses do I have left", "what's my license usage", "can I create another Full sandbox", or before creating/refreshing a sandbox to confirm capacity exists for that licenseType.
Key response fields:
licenseType — DEVELOPER, DEVELOPER_PRO, PARTIAL, FULLlimit — Total licenses of this typeused — Currently allocatedavailable — Remaining (i.e. limit - used)Create/Refresh blocked by a license limit: offer to pick an available type, free one up by deleting a stale sandbox, ask the admin for a license increase, or — if it's an expired Courtesy Full Copy — purchase/convert it.
Resolve sandboxId first: by name, call GET /sandbox/reports and match sandboxName; by ID (07E prefix), call GET /sandbox/sandboxes/{sandboxId} directly — don't call /sandbox/reports.
| User says... | Operation | Key check |
|---|---|---|
| "Show all my sandboxes" | GET /sandbox/reports | — |
| "What's the status of X?" | GET /sandbox/reports (by name) or GET /sandbox/sandboxes/{id} (by ID) | — |
| "Activate sandbox X" | 1. Resolve sandboxId2. PATCH /sandbox/activate/{sandboxId} | Must be isPendingActivation: true; confirm with user first |
| "Discard the refresh on X" | 1. Resolve sandboxId2. DELETE /sandbox/discardsandbox/{sandboxId} | Must be isPendingActivation: true; confirm with user first |
| "Delete sandbox X" | 1. Resolve sandboxId2. DELETE /sandbox/deletesandbox/{sandboxId} | Confirm with user first |
| Mistake | Correct understanding |
|---|---|
| Using activate to "start" any sandbox | Activate ONLY applies completed refreshes |
| Using discard to "hide" or "soft-delete" | Discard ONLY rejects a pending refresh |
| Activating without checking status first | Always verify isPendingActivation = true |
Skipping confirmation on Create, Activate, Discard, Delete, or Refresh with AutoActivate=true | See Irreversible Actions above — always confirm first |
Offering AutoActivate during Create | Refresh-only field |
Offering ApexClassId during Refresh | Create-only field |