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 a snapshot with the specified name.

1sf org create scratch --snapshot dhsnapshot --wait 10 --target-dev-hub MyHub

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

View Scratch Org Creation Progress

While executing, the org create scratch command displays running information about the background processes. When the command completes, it displays two important pieces of information: the org ID and the username.

1────────────── Creating Scratch Org ──────────────
2
3 ✔ Prepare Request 11ms
4 ✔ Send Request 11.73s
5 ◯ Wait For Org - Skipped
6 ✔ Available 12ms
7 ✔ Authenticate 1.51s
8 ✔ Deploy Settings 2.14s
9 ✔ Done 0ms
10
11 Request Id: 2SRWs000003y7mUOAQ (https://cbdocorg.my.salesforce.com/2SRWs000003y7mUOAQ)
12 OrgId: 00DE200000DHqsM
13 Username: test-lvsbbdryeaxn@example.com
14 Alias: myscratch
15 Elapsed Time: 15.40s
16
17Your scratch org is ready.

Open the Scratch 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

Salesforce Release Transition Periods

Timing is everything during the Salesforce release transition period. During the transition period, you can intend to create a scratch org on the current release but find that the scratch org is unexpectedly created on the preview release. If the instance on which the scratch is created transitions to the preview release after the creation request is initiated, the scratch org is created on the preview version instead of the current version. During this transition period, there’s no way to know when the sandbox (CS) instance will be upgraded.

If you open the scratch org and it isn’t on the expected version, you have some options. See “How Release Transitions Can Affect the Scratch Org Version” in Select the Salesforce Release for a Scratch Org.

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 that was 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

Salesforce DX Developer Guide