As a part of the Salesforce CLI unification, we bundled two executables: sfdx and sf. The sf executable will eventually provide a single set of commands designed to develop and deploy applications across all Salesforce clouds. Currently, it supports the Salesforce Platform and Salesforce Functions. Some of the sf commands are entirely interoperable with their sfdx equivalent.

For the sfdx commands that have their sf equivalent, we encourage you to try out sf commands in your developer workflow for two main reasons:

1. sf commands are user-friendly and optionally can be interactive. The interactive commands actively prompt you for required information rather than passively accepting flag values, thus reducing errors.
2. Some of the sf commands are much more efficient and have enhanced features compared to their sfdx equivalent.

In this blog post, we will explore one such command, sf env create scratch (currently in Beta), which is used to manage scratch org creation. You’ll see why sf env create scratch is much better than its equivalent sfdx command, sfdx force:org:create.

But first, let’s go over the series of steps needed to run sfdx force:org:create.

How does the SFDX org creation command work?

When you run the sfdx force:org:create command, the following tasks are performed in the order listed below

1. First, the CLI builds the request body necessary for scratch org creation, which involves transforming the scratch org definition file
2. Next the CLI makes an HTTPS POST request to the Dev Hub org to kick off the scratch org creation process
3. Next, the CLI keeps polling to see if the scratch org creation is successful
4. Upon org creation, the CLI is authenticated to the org and we save the authorization information and configurations (like username and alias)
5. Next, the CLI deploys the Settings to the scratch org specified in the settings property of the scratch definition file
6. Finally, the CLI resets the source tracking from the result of Step 5

The above steps can be visualized as shown in the flowchart below:

Org creation is an asynchronous process; sometimes, any of the above steps can fail due to various issues like network failure, mdapi fault, or timeouts. There are also several types of scratch orgs, such as orgs created using the org shapes and org snapshots features, that could take a long time for creation and might produce a time out.

Let’s analyze a couple of error scenarios that can occur, along with their impact.

Error scenario A: Network outage

Let’s imagine that during the process of scratch org creation between Step 2 and Step 3 in the above diagram, there was a network outage. In this case, the org is created in your Dev Hub but you cannot connect to it. Orphaned scratch orgs still count towards your allocated scratch org limit.

In this case, your only option is to delete the scratch org manually by finding it in your Dev Hub.

Error scenario B: Deployment failure/timeouts when the platform is busy

You may notice that sometimes metadata deployments get stuck in pending when the platform is really busy, and it may timeout. This may happen during Step 5 shown in the diagram above.

Again, in this case, your only option is to delete the scratch org by finding it in your Dev Hub.

Introducing sf env create scratch/sandbox commands

With the new sf env create scratch command, we have added new features, including:

1. A visual indicator that shows progress throughout the creation process
2. A job ID that is linked with the org creation job
3. We stash the scratch org information, so the failing jobs can be resumed if needed

Let’s look at a sample command for scratch org creation:

In the above command, we specify the Dev Hub using its alias and a scratch org definition file. We set the scratch org as our default and specify that it expires in three days.

Also carefully note that at the end of the command, we have used an --async flag. Using --async, the scratch org creation happens asynchronously.

Whether the command does scratch org creation synchronously or asynchronously, it always returns a job ID. Using this ID, we can resume the org creation in case of failure. To resume, use a the sf env resume command as shown below.

Bonus — if you don’t want to use the job ID, you can also use the —use-most-recent flag to resume env creation for the most recent scratch org creation. The command with —use-most-recent flag would look as follows:

Now, let’s come back to the error scenarios we discussed above and see how using these new commands is more effective.

Revisiting error scenario A: Network outage

If you use sf env create scratch, the resume will find your scratch org and auth, and finish the remaining steps

Revisiting error scenario B: Deployment failure/timeouts when the platform is busy

If you use sf env create scratch, use the sf env resume command to resume the operation.

What about sandboxes?

For sandboxes, there is a pair of commands in Beta — sf env create sandbox and sf env resume sandbox — that work similarly to the operations that we described for scratch orgs.

Try it out and send us your feedback

We want to hear from you! We built this new feature to help you better manage the scratch org/sandbox creation process. If you encounter issues using this command, or have other types of feedback, please file an issue in the GitHub repo.

About the authors

Shane McLaughlin is an engineer on the Salesforce CLI team. You can follow Shane on twitter @mshanemc and explore his open-source projects via his GitHub handle @mshanemc.

Mohith Shrivastava is a Developer Advocate at Salesforce. He has a decade of experience building enterprise-scale products on the Salesforce Platform. Mohith is currently among the lead contributors on Salesforce Stack Exchange, a developer forum where Salesforce developers can ask questions and share knowledge. He is presently focusing on Salesforce developer tools, Platform services, and Lightning Web Components at Salesforce. You can follow him on Twitter @msrivastav13.