A Salesforce scratch org is a temporary, source-driven Salesforce environment used for development, testing, automation, and feature work. It is created from a Dev Hub and can be configured with a scratch org definition file so that developers can reproduce the required edition, features, and settings.

This Salesforce tutorial explains how to create a scratch org from the command line, deploy project metadata, assign a permission set, import sample data, open the org, and remove it when the work is complete. The current Salesforce CLI uses the sf command. The original sfdx force: examples are retained later in this tutorial for developers maintaining older scripts.

Requirements for Creating a Salesforce Scratch Org

  • Salesforce CLI must be installed and available through the sf command.
  • A Salesforce org with Dev Hub enabled is required.
  • The Dev Hub must be authorized in Salesforce CLI.
  • A Salesforce DX project is recommended when you plan to deploy metadata, track source, run tests, or store project configuration in version control.
  • The project should contain a scratch org definition file, commonly config/project-scratch-def.json.

In Salesforce Setup, enter Dev Hub in the Quick Find box, open the Dev Hub page, and enable it. Review the setting before enabling it because Salesforce does not allow Dev Hub to be disabled afterward.

Authorize the Dev Hub in Salesforce CLI

Authorize the Dev Hub once and assign it an alias. The --set-default-dev-hub flag makes this org the default Dev Hub for later scratch-org commands.

</>
Copy
sf org login web --set-default-dev-hub --alias DevHub

A browser window opens for Salesforce authentication. Sign in to the org in which Dev Hub is enabled and approve CLI access. You can then verify the connection with the following command.

</>
Copy
sf org list

Configure project-scratch-def.json for the Scratch Org

The scratch org definition file is a blueprint for the new org. It can specify the org edition, enabled features, language, and supported settings. Keep the file in the project repository so that each developer and automated job can create a consistent environment.

</>
Copy
{
  "orgName": "TutorialKart Development",
  "edition": "Developer",
  "features": [],
  "settings": {
    "lightningExperienceSettings": {
      "enableS1DesktopEnabled": true
    }
  }
}

Only add features and settings that the project requires. A scratch org definition does not create a precise copy of every item in an existing production or sandbox org. When a closer baseline is needed, review Salesforce org shapes or scratch org snapshots and confirm which metadata, packages, settings, and sample data must still be deployed separately.

Create a Salesforce Scratch Org with the sf Command

Open Terminal or a command prompt, change to the root directory of the Salesforce DX project, and run sf org create scratch. The following command creates an org from the definition file, assigns the alias testScratchOrg, and sets it as the default org for the project.

</>
Copy
cd tutorialkart_sfdxproject/sfdx-dreamhouse
sf org create scratch \
  --definition-file config/project-scratch-def.json \
  --alias testScratchOrg \
  --set-default \
  --target-dev-hub DevHub \
  --duration-days 7 \
  --wait 10

The alias is easier to use than the generated scratch-org username. The duration controls when the org expires, subject to the limits supported by the Dev Hub and CLI. The --wait value specifies how long the command waits for creation to complete before returning control.

Check the Salesforce Scratch Org creation status

List the orgs known to Salesforce CLI and confirm that the scratch org is active.

</>
Copy
sf org list

If creation was started asynchronously or did not finish within the wait period, use the job ID returned by the CLI with the scratch-org resume command.

</>
Copy
sf org resume scratch --job-id YOUR_JOB_ID

Deploy Salesforce Project Metadata to the Scratch Org

After the scratch org is available, deploy the metadata from the Salesforce DX project. Scratch orgs normally support source tracking, which helps Salesforce CLI identify differences between the local project and the org.

</>
Copy
sf project deploy start --target-org testScratchOrg

You can deploy a specific source directory when the project contains multiple package directories or when only one part of the project is required.

</>
Copy
sf project deploy start \
  --source-dir force-app \
  --target-org testScratchOrg

Assign a Permission Set in the Scratch Org

If the application includes a permission set, assign it to the scratch-org user before opening the app. This example assigns the Dreamhouse permission set.

</>
Copy
sf org assign permset \
  --name Dreamhouse \
  --target-org testScratchOrg

Import Sample Data into the Salesforce Scratch Org

Project metadata and business records are handled separately. When the repository contains an sObject tree import plan, load its sample records after deploying the metadata.

</>
Copy
sf data import tree \
  --plan data/sample-data-plan.json \
  --target-org testScratchOrg

Open the Salesforce Scratch Org

Open the default page of the scratch org in a browser with the following command.

</>
Copy
sf org open --target-org testScratchOrg

To open a specific Setup or Lightning page, use the --path option with a valid relative Salesforce URL.

Create a Salesforce Scratch Org in Visual Studio Code

The Salesforce extensions for Visual Studio Code expose the same workflow through the Command Palette. Open the Salesforce DX project, press Command+Shift+P on macOS or Ctrl+Shift+P on Windows and Linux, and run the commands to authorize a Dev Hub and create a default scratch org. Select the project’s project-scratch-def.json file and enter an alias when prompted.

After creation, use the Salesforce extension commands to deploy source to the org, or run the equivalent sf project deploy start command in the integrated terminal.

Delete a Salesforce Scratch Org After Development

Scratch orgs are disposable and expire automatically, but deleting an org as soon as it is no longer required releases the active scratch-org allocation in the Dev Hub.

</>
Copy
sf org delete scratch \
  --target-org testScratchOrg \
  --no-prompt

Common Salesforce Scratch Org Creation Problems

Dev Hub is not authorized or selected

Run sf org list and confirm that a Dev Hub is connected. If necessary, authorize it again with sf org login web --set-default-dev-hub --alias DevHub, or pass --target-dev-hub explicitly when creating the scratch org.

Scratch org definition contains an unsupported feature or setting

Check the feature and setting names in project-scratch-def.json. Remove properties that are not available for the selected edition or Dev Hub, then create a new scratch org.

Salesforce CLI command is run outside the DX project

Commands that deploy or retrieve project source should be run from a directory containing sfdx-project.json. Change to the project root before running them.

Scratch org does not match an existing sandbox or production org

A definition file creates a configured development environment; it does not clone all metadata, data, installed packages, and settings from another org. Add required features and settings to the definition file, deploy metadata from source control, install dependencies, and import suitable test data. Org shapes and snapshots can help with selected baseline configurations, but they still require a planned source-driven workflow.

Legacy sfdx Commands for the DreamHouse Scratch Org

The following original walkthrough uses the older sfdx force: command format. It remains useful when reading or maintaining existing scripts, although new workflows should use the corresponding sf commands shown above.

  • As already we have created Salesforce DX project from existing source (GitHub), now open Terminal and enter the following code

Create Salesforce Scratch Org

In this step, we are going to create Salesforce Scratch Org in Command Line Interface(CL) which will be used in our future development. Before creating a Scratch Org, check that developer hub account is linked to CLI.

Enter the following code and the result will be as shown below.

prasanth:sfdx-dreamhouse prasanth$ sfdx force:org:list
=== Orgs
     ALIAS   USERNAME         ORG ID              CONNECTED STATUS
???  ??????  ???????????????  ??????????????????  ????????????????
(D)  DevHub  prasanth@tk.com  00D6F000002SEW1UAO  Connected

Steps to create Salesforce Scratch Org

  1. Create directory.
  2. Clone the repository (dream house) from GitHub.
  3. Set a default username for the Org that you connect.
  4. Create a Scratch Org.
  5. Push source metadata to Salesforce Scratch Org.
  6. Assigning permissions to DreamHouse App.
  7. Importing test data.
  8. Open Scratch Org.

To create a scratch Org from CLI, enter cd into the project before running the following code.

prasanth:~ prasanth$ cd tutorialkart_sfdxproject

prasanth:tutorialkart_sfdxproject prasanth$ cd sfdx-dreamhouse

Setting default username to the Org

Salesforce recommends developers to set default username to the Org that we connect during development. CLI requires username to create a scratch Org, to synchronise source code between project and Scratch Org and other task to determine which Org that we are connecting.

Now when setting default username to the Org, we are not required to specify a username, the command used the default.

prasanth:sfdx-dreamhouse prasanth$ sfdx force:config:set 
defaultusername=prasanth@tk.com

Output

=== Set Config
NAME             VALUE
???????????????  ???????????????
defaultusername  prasanth@tk.com

Creating Salesforce Scratch Org with alias name

Scratch org usernames are long and unintuitive. Setting an alias each time you create a scratch org is a great way to track the scratch org’s function. And it’s much easier to remember when issuing subsequent CLI commands.

Run the following command to create Salesforce Scratch Org with alias

prasanth:sfdx-dreamhouse prasanth$ sfdx force:org:create
 -s -f config/project-scratch-def.json -a testScratchOrg

Output

Successfully created scratch org: 00DO00000055j0XMAQ, 
username: test-dvcyqr7qqond@example.com

Push Source Metadata to Scratch Org

After changing the source, we can sync the changes to our Scratch Org by pushing the changed source to it. All sources in the folders in the package directories are pushed to the Scratch Org. Run the following command to push source metadata to Scratch Org.

prasanth:sfdx-dreamhouse prasanth$ sfdx force:source:push
=== Pushed Source

Assigning Permset to Dreamhouse App

Before accessing DreamHouse app in Salesforce, we need to assign the Permset using CLI. Run the following command shown below.

prasanth:sfdx-dreamhouse prasanth$ sfdx force:user:permset:assign -n Dreamhouse
=== Permsets Assigned
USERNAME                       PERMISSION SET ASSIGNMENT
?????????????????????????????  ?????????????????????????
test-ocpbhvfglndm@example.com  Dreamhouse

Import Test Data

We are going to import test data using SObject Tree API. Run the following command in CLI.

prasanth:sfdx-dreamhouse prasanth$ sfdx force:data:tree:import --plan data/sample-data-plan.json

[Image: https://quip.com/-/blob/ZCbAAAmNFfl/22AIDViuFpI1dUsAmU0eww]=== Import Results
REFERENCE ID           TYPE         ID
?????????????????????  ???????????  ??????????????????
CarolineBrookerRef     Broker__c    a01p0000006rpGHAAY
MichaelJonesRef        Broker__c    a01p0000006rpGIAAY
JonathanBradleyRef     Broker__c    a01p0000006rpGJAAY
JenniferWuRef          Broker__c    a01p0000006rpGKAAY
OliviaGreenRef         Broker__c    a01p0000006rpGLAAY
MiriamAupontRef        Broker__c    a01p0000006rpGMAAY
MichelleLambertRef     Broker__c    a01p0000006rpGNAAY
SeniorBrokerRef        Broker__c    a01p0000006rpGOAAY
18HenryStRef           Property__c  a04p0000009UwhxAAC
24PearlStRef           Property__c  a04p0000009UwhyAAC
72FrancisStRef         Property__c  a04p0000009UwhzAAC
32PrinceStRef          Property__c  a04p0000009Uwi0AAC
110BaxterStRef         Property__c  a04p0000009Uwi1AAC
448HanoverStRef        Property__c  a04p0000009Uwi2AAC
127EndicottStRef       Property__c  a04p0000009Uwi3AAC
48BrattleStRef         Property__c  a04p0000009Uwi4AAC
121HarborwalkRef       Property__c  a04p0000009Uwi5AAC
640HarrisonAveRef      Property__c  a04p0000009Uwi6AAC
95GloucesterStRef      Property__c  a04p0000009Uwi7AAC
145CommonwealthAveRef  Property__c  a04p0000009Uwi8AAC

We have successfully created and configured Salesforce scratch Org. In our final step, open the Scratch Org.

Open Salesforce Scratch Org

To open Salesforce Scratch Org, run the following command : sfdx force:org:open. To open the DreamHouse app, click App launcher and then click DreamHouse icon as shown below.

Create Salesforce Scratch Org - Opening Dreamhouse App

Salesforce Scratch Org and Sandbox Differences

A scratch org is temporary, created from a Dev Hub, configured from source, and intended for isolated development or automated testing. A sandbox is a copy of a Salesforce production org at a selected data and metadata level and is generally used for longer-lived development, integration, testing, training, or staging workflows. Choose the environment according to the required lifespan, data fidelity, integration access, and release process.

Salesforce Scratch Org FAQs

Which command creates a scratch org in the current Salesforce CLI?

Use sf org create scratch. A common form is sf org create scratch --definition-file config/project-scratch-def.json --alias testScratchOrg --set-default.

How do I enable scratch org creation in Salesforce?

Enable Dev Hub in a supported Salesforce org, authorize that Dev Hub in Salesforce CLI, and create the scratch org from a definition file, edition, snapshot, or org shape supported by the command.

Can a Salesforce scratch org duplicate an existing environment exactly?

Not by using project-scratch-def.json alone. The file defines the desired edition, features, and settings, while project metadata, packages, permissions, and test records must be deployed or installed separately. Org shapes and snapshots can reproduce selected baseline characteristics but should not be treated as complete production clones.

How do I create a scratch org user?

The scratch org includes a default user when it is created. Additional users can be created with Salesforce CLI when the definition file and available licenses support them. Use sf org create user --target-org testScratchOrg with an optional user definition file when specific profile or user properties are required.

Why should I delete a scratch org before it expires?

Deleting an unused scratch org returns its active allocation to the Dev Hub and keeps the development org list easier to manage.

Salesforce Scratch Org Editorial QA Checklist

  • Confirm that the primary workflow uses the current sf org create scratch command.
  • Verify that Dev Hub authorization is described before scratch-org creation.
  • Check that project-scratch-def.json contains only supported editions, features, and settings.
  • Confirm that metadata deployment, permission-set assignment, and sample-data import are shown as separate steps.
  • Keep older sfdx force: examples clearly identified as legacy commands without altering their original code blocks.
  • Verify that the scratch org is deleted or allowed to expire after the development task is complete.

Official Salesforce Scratch Org References