Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Enable Dev Hub Features in Your Org
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Sandboxes
Authorize in to Your Production Org
Create a Sandbox Definition File
Create, Clone, or Delete a Sandbox
Track Changes Between Your Project and Org
Development
Build and Release Your App
First-Generation Managed Packages
Second-Generation Managed Packages
Unlocked Packages
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Create, Clone, or Delete a Sandbox

Create a sandbox to use for development, testing, or training. Clone a sandbox to copy its data and metadata to another sandbox.
Before you create or clone a sandbox:
  • Create a Salesforce DX project with a manifest file.
  • Authorize to a production org with available sandbox licenses.
  • Create the sandbox definition file.

Why We Recommend Using Aliases

When you create or clone a sandbox, the usernames generated in the sandbox are based on the usernames present in the production org or sandbox. The username looks like an email address, such as username@company.com.dev1. If the resulting username is not unique, we prepend some characters and digits to the username. The modified username looks something like 00x7Vqusername@company.com.dev1.

As you can imagine, remembering these usernames can be challenging, especially if you have several sandboxes you’re managing. Aliasing is a powerful way to manage and track your orgs, and we consider it a best practice. So when you issue a command that requires the username, using an alias that you can remember can speed up things.

If you didn’t set an alias when you created the sandbox, you can set one later.
1sfdx alias:set MyDevSandbox=username@company.com.dev1

Create a Sandbox

Optional: Create a Sandbox Definition File

When you create a sandbox, Salesforce copies the metadata and optionally data from your production org to a sandbox org.

1sfdx force:org:create --type sandbox --targetusername prodOrg --definitionfile config/dev-sandbox-def.json -a MyDevSandbox -s -w 30

The -s flag indicates that this sandbox is your default org for all CLI commands. If you’re working with several orgs and you don’t want this one to be the default, exclude this flag.

To directly define the required sandbox options, or to override the values defined in the sandbox definition file, specify key=value pairs on the command line.

1sfdx force:org:create -t sandbox sandboxName=FullSbx licenseType=Full -u prodOrg -a MyFullSandbox -w 30

Because the sandbox is processed in a queue, the sandbox creation process can take longer than the default wait time of 6 minutes. We recommend setting a larger value for --wait, for example, 30 minutes.

Tip

How long the creation process takes depends on the size and complexity of your production org. You see status messages posted to output:

1Sandbox request dev1(0GXQ0000000CftJOWS) is Pending (0% completed). Sleeping 30 seconds. Will wait 30 minutes more before timing out.
2Sandbox request dev1(0GXQ0000000CftJOWS) is Processing (0% completed). Sleeping 30 seconds. Will wait 29 minutes 30 seconds more before timing out.

Once the wait period is over, you can run the force:org:status command to check the status of the sandbox creation process. If the sandbox is created within the wait time, the CLI automatically authenticates in to the sandbox. And the sandbox appears in the output of the force:org:list command. Team members can authenticate to the sandbox by running the auth:web:login command and providing their usernames and passwords.

1sfdx auth:web:login -r https://test.salesforce.com

Clone a Sandbox

You can create a sandbox by cloning an existing sandbox rather than using your production org as your source. You can save time by customizing a sandbox with a set of data and metadata and then replicating it.

Sandbox cloning simplifies having multiple concurrent streams of work in your application life cycle. You can set up a sandbox for each type of work, such as development, testing, and staging. Your colleagues can easily clone individual sandboxes instead of sharing one sandbox and stepping on each other’s toes.

1sfdx force:org:clone -t sandbox -f config/dev-sandbox-def.json -u prodOrg -a MyDevSandbox -s -w 30

To override the configuration values defined in the sandbox definition file, specify key=value pairs on the command line.

1sfdx force:org:clone -t sandbox SandboxName=DevSbx1 SourceSandboxName=Sbx2Clone -u prodOrg -a MyDevSandbox -w 30

Because the sandbox is processed in a queue, the sandbox cloning process can take longer than the default wait time of 6 minutes. We recommend setting a larger value for --wait, for example, 30 minutes.

Tip

Once the wait period is over, you can run the force:org:status command to check the status of the sandbox cloning process. If the sandbox is cloned within the wait time, the CLI automatically authenticates in to the sandbox. And the sandbox appears in the output of the force:org:list command. Team members can authenticate to the sandbox by running the auth:web:login command and providing their usernames and passwords.

1sfdx auth:web:login -r https://test.salesforce.com

Check the Sandbox Status

Creating or cloning a sandbox can take several minutes. Once the command times out, you can run the force:org:status command to report on creation or cloning status. When the sandbox is ready, this command authenticates to the sandbox.

If the org:create or org:clone command times out, the alias isn’t set. However, you can set it using the org:status command:

1sfdx force:org:status -n DevSbx1 -a MyDevSandbox -u prodOrg

Open a Sandbox

Once the sandbox is ready, you can open it by specifying its username or alias. However, you don’t have to provide its password because the CLI manages the authentication details for you.

1sfdx force:org:open -u MyDevSandbox

Delete a Sandbox

You can delete a sandbox using the CLI if it was authenticated when running org:create, org:clone, or org:status. Other sandboxes that you authenticated using auth:web:login or auth:jwt:grant also appear on the org list, but must be deleted using the sandbox detail page in your production org.

1sfdx force:org:delete -u MyDevSandbox

Next:

  • Retrieve metadata from your sandbox to your local DX project.
  • Develop directly in your sandbox, then retrieve the changes to your local DX project.
  • Deploy local changes to a sandbox.