Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Set Up Salesforce DX Tools for Developer Users
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Supported Scratch Org Editions and Allocations
Build Your Own Scratch Org Definition File
Create a Scratch Org Based on an Org Shape
Create Scratch Orgs
Scratch Org Snapshots (Beta)
Select the Salesforce Release for a Scratch Org
Deploy Source From Your Project to the Scratch Org
Retrieve Source from the Scratch Org to Your Project
Scratch Org Users
Manage Scratch Orgs from the Dev Hub Org
Scratch Org Error Codes
Sandboxes
Track Changes Between Your Project and Org
Development
Build and Release Your App
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 Scratch Orgs

Easily spin up a scratch org and open it directly from the command line.

Before you create a scratch org:

  • Set up your Salesforce DX project
  • Authorize the Dev Hub org
  • Create the scratch org definition file (build your own or use an org shape)

You can create scratch orgs for different functions, such as for feature development, for development of packages that contain a namespace, or for user acceptance testing.

Delete any unneeded or malfunctioning scratch orgs in the Dev Hub org or via the command line so that they don’t count against your active scratch org allocations.

Tip

Indicate the path to the scratch definition file relative to your current directory. For sample repos and new projects, this file is located in the config directory.

Ways to Create Scratch Orgs

Create a scratch org for development using a scratch org definition file, give the scratch org an alias, and indicate that this scratch org is the default. Use the --target-dev-hub flag to specify your Dev Hub org’s username or alias; if you don’t specify this flag, the command uses your default Dev Hub. 
1sf org create scratch --definition-file config/project-scratch-def.json --alias MyScratchOrg --set-default --target-dev-hub MyHub

You can override many of the options in the user definition file by specifying the corresponding flag at the command line when you run org create scratch. This technique allows multiple users or continuous integration jobs to share a base definition file and then customize options when they run the command. This example overrides the adminEmail and edition options.

1sf org create scratch --definition-file config/project-scratch-def.json --admin-email me@email.com --edition developer

You’re not required to specify a definition file when you create a scratch org, as long as you specify the required flag --edition. 

1sf org create scratch --edition developer

This example creates a scratch org from an org shape with the specified ID. 

1sf org create scratch --source-org 00DB1230000Ifx5

Create a scratch org for user acceptance testing or to test installations of packages. In this case, you don’t want to create a scratch org with a namespace. You can use this command to override the namespace value in the scratch org definition file. This example also specifies the scratch org’s duration, which indicates when the scratch org expires (in 1-30 days). The default duration is 7 days.

1sf org create scratch --definition-file config/project-scratch-def.json --no-namespace --duration-days 30

Specify the Salesforce release for the scratch org. During the Salesforce release transition, you can specify the release (preview or previous) when creating a scratch org. See Select the Salesforce Release for a Scratch Org for details.

1sf org create scratch --edition developer --release preview

Request a scratch org, but don’t wait for it complete, by specifying the --async flag. 

1sf org create scratch --edition developer --async

The command displays a job ID that you pass to the org resume scratch command. Use this command to also resume a scratch org creation that times out. 

1sf org resume scratch --job-id 2SRB0000CSqdJOAT

Create a scratch org with source tracking disabled.

1sf org create scratch --definition-file config/project-scratch-def.json --no-track-source

If Scratch Org Creation Is Successful

While executing, the org create scratch command displays running information about the background processes, such as sending requests, deploying org settings, and so on. When the command completes, it displays two important pieces of information: the org ID and the username.

1Creating Scratch Org... 
2RequestId: 2SRB000000CSqdEOAT (https://cbdocorg.my.salesforce.com/2SRB000000CSqdEOAT)
3OrgId: 00D8I000000PhAk 
4Username: test-st9thgoyyyq3@example.com 
5✓ Prepare Request
6✓ Send Request
7✓ Wait For Org
8✓ Available
9✓ Authenticate
10✓ Deploy Settings
11Done
12
13Your scratch org is ready.
You can now open the org.
1sf org open --target-org test-st9thgoyyyq3@example.com

If you used the --alias flag to set an alias, you can use that value for --target-org.

1sf org open --target-org MyScratchOrg

Troubleshooting Tips

If the create command runs into an error, it’s not always clear if the scratch org was created. Issue this command on your Dev Hub org to see if it returns the scratch org ID, which confirms the existence of a scratch org created today and owned by you:

1sf data query --query "SELECT ID, Name, Status FROM ScratchOrgInfo WHERE CreatedBy.Name = '<your name>' AND CreatedDate = TODAY" --target-org <Dev Hub org>

Use this information to determine if the creation actually worked. For example, let’s say your name is Jane Doe, and you created an alias for your Dev Hub org called DevHub:

1sf data query --query "SELECT ID, Name, Status FROM ScratchOrgInfo WHERE CreatedBy.Name = 'Jane Doe' AND CreatedDate = TODAY" --target-org DevHub