Home

Get Started with Salesforce CLI Unification

NOTE: This feature is a Beta Service. Customers may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at Agreements and Terms.

Quick Start

Want to dive right in and read the rest of the documentation later? Here you go:

Install sf.
Run through the Dreamhouse example.
Check the Issues tab for known issues with sf, and to enter one yourself if necessary.

What Is sf?

sf is a new Salesforce CLI executable that provides a single set of commands designed to develop and deploy applications across all Salesforce clouds. While this beta supports only Salesforce orgs, future sf releases will support Salesforce Functions, Mulesoft, Heroku, and more. Our goal: one CLI to rule them all!

Salesforce CLI is now a bundle of two executables: sf and sfdx. The sfdx executable is the one you know and love, and have used to build wonderful applications for the Salesforce Platform. The two executables are aware of each other and some of their commands are interoperable. For example, if you create a scratch org with an sfdx command, you can deploy metadata to it with an sf command. See How sf and sfdx Work Together for details.

But note that sf isn’t an sfdx plug-in, and while some commands interoperate between the two executables, the two executables aren’t generally interoperable. For example, if you install a plug-in into sfdx and use some of its commands, you don't also see those commands in sf. To use the commands in sf you must explicitly install the plug-in into sf.

How Is sf Different from sfdx?

sf is similar to sfdx in that it's a command-line interface that simplifies Salesforce development and build automation. But it also includes some key new features and design changes.

New and Improved Features and Design

The sf command hierarchy reflects a typical developer's workflow rather than Salesforce brands, products, or features.

For example, the top-level topics include configuring the CLI (sf config), logging into environments (sf login), deploying and retrieving (sf deploy and sf retrieve), and managing environments (sf env). Later sf releases will add top-level topics for creating scaffolded artifacts, running code, testing, and managing data.

As sf grows and embraces other Salesforce clouds, it will include their commands in this workflow-focused hierarchy instead of each product having its own command hierarchy. Because sf creates consistency across all these commands, it's easier and more intuitive to use, even when developing on a new cloud.
sf provides interactive commands that actively prompt you for required information rather than passively accepting flag values. Now you don't have to remember all the flag names or which are required, which in turn reduces errors. For example, sf deploy prompts you for the deployment environment and artifacts, level of testing, and so on.

Each interactive command has an environment-specific command for use in automated scripts. For example, sf deploy metadata has flags to specify the org you're deploying to, the metadata location, and so on.
Improved --help output:
- The short flag descriptions are grouped into logical groups for easier reading, which is especially useful when a command has many flags.
- All examples have brief explanations.
- The long flag descriptions are displayed at the end of the --help output. In sfdx, the long flag descriptions don’t display in the --help output at all, they’re documented only in the Salesforce CLI Command Reference.
The command output has been improved for readability and standardized.

Look Out: Differences Between sf and sfdx

The commands to deploy and retrieve org metadata (sf deploy|retrieve metadata) don't yet include source-tracking functionality. If you want to use source-tracking in scratch orgs or sandboxes, keep using the sfdx force:source:push|pull commands for now.
sf uses spaces between topics, commands, and subcommands rather than colons. For example, the sf command to get a configuration variable is sf config get; in sfdx it's sfdx config:get.
Where appropriate, we've renamed sfdx flags in sf to include dashes in its name for better readability. For example, --apiversion in sfdx is now --api-version in sf.
In sf, you have two ways to use flags that take multiple values:
- Specify the flag multiple times, with each flag taking a different single value. For example:
```
sf deploy metadata --metadata ApexClass \
                   --metadata CustomObject \
                   --metadata AnotherCustomObject
```
- Specify the flag one time, but separate all the values with a space:
```
sf deploy metadata --metadata ApexClass CustomObject AnotherCustomObject
```
- In sfdx you specify the flag one time and separate the values with commas:
```
sfdx force:source:deploy --metadata ApexClass,CustomObject,AnotherCustomObject
```
While equivalent sf and sfdx commands, such as sf config set and sfdx config:set, are interoperable and aware of each other, they produce different JSON output.

New and Changed Terminology

A quick word about these sf terms:

Environments: A general term for the thing you use the CLI to interact with, such as the org to which you deploy metadata. For beta, we support only environments that are Salesforce orgs. Future releases will include environments to which you deploy Salesforce Functions.

Commands for managing environments are grouped under the sf env topic, such as sf env list, which lists all the environments you've created or logged into.
Logging in: In sf you log into an environment, which authorizes the CLI to run other commands that interact with that environment. In sfdx we use the term authorize.
Flags: In sf we consistently use the term flag in the documentation, such as the --json flag of a command. In sfdx we use the terms parameter, flag, and option in the documentation, sometimes interchangeably.
Configuration variables: In sf, you use configuration variables to configure aspects of the CLI. In sfdx we call them configuration values.

How sf and sfdx Work Together

The sf and sfdx commands play nicely together.

Environments

In this beta release, the only environments you can interact with are Salesforce orgs (scratch orgs, Dev Hubs, production orgs, sandboxes, and so on). Org authorizations are interoperable between sf and sfdx.

In practice this means that when you create a scratch org, authorize an org, or log out of an org with sfdx, the sf commands respect these actions. The reverse is also true: if you log in or out of an environment in sf, the sfdx commands respect it.

For example, let's say you create a scratch org with sfdx force:org:create. When you run sf env list in the same project, the new scratch org is displayed.

Similarly, if you log into an org with sf login org, then run sfdx force:org:list, the org you logged into is displayed.

Aliases

Aliases are interoperable between sf and sfdx.

For example, if you run sfdx force:org:create --setalias MyScratchOrg, you can use this alias in sf, such as sf env open --target-env MyScratchOrg.

Similarly, if you run sf login org --alias MyDevHub, you can use this alias in sfdx, such as sfdx force:org:open --targetusername MyDevHub.

Configuration Variables

Configuration variables are interoperable between sf and sfdx. But we've made two important name changes:

defaultusername (sfdx) has been renamed target-org in sf.
defaultdevhubusername (sfdx) has been renamed target-dev-hub in sf.

Other than the preceding two configuration variables, the rest of the sfdx variables have the same name and work the same way in sf.

Let's run through a few use cases to see how the interoperability works, using target-org and defaultusername as examples. The same behavior applies to target-dev-hub and defaultdevhubusername, and the rest.

Here's the general rule: if you set target-org to a value, then defaultusername is also automatically set to the same value. And vice versa.

Action: Use this sfdx command to create a scratch org:

sfdx force:org:create --setdefaultusername -f config/project-scratch-def.json --setalias my-scratch-org

Then run sfdx config:list and sf config list.

Result: Both defaultusername and target-org are set to my-scratch-org.

Action: Use this sf command to set the target-org configuration variable to an org with alias uat-testing-org:

sf config set target-org=uat-testing-org

Then run sfdx config:list and sf config list.

Result: Both defaultusername and target-org are set to uat-testing-org.

Action: Use this sfdx command to set the defaultusername configuration variable to an org with alias production-org:

sfdx config:set defaultusername=production-org

Then run sfdx config:list and sf config list.

Result: Both defaultusername and target-org are set to production-org.

Action: Use this sf command to set defaultusername:

sf config set defaultusername=other-org

Result: Error, because you can't use sf commands to directly set defaultusername.

Action: Use this sfdx command to set target-org:

sfdx config:set target-org=other-org

Result: Error, because you can't use sfdx commands to directly set target-org.

To recap, this table lists all available configuration variables in both sf and sfdx.

sf Configuration Variable	Equivalent sfdx Configuration Value
`apiVersion`	`apiVersion`
`disableTelemetry`	`disableTelemetry`
`instanceUrl`	`instanceUrl`
`maxQueryLimit`	`maxQueryLimit`
`restDeploy`	`restDeploy`
`target-dev-hub`	`defaultdevhubusername`
`target-org`	`defaultusername`

Install an sfdx Plug-In into sf

Because both sf and sfdx are built on the open-source CLI framework (oclif), you can successfully install and use plug-ins originally built for sfdx in sf. However, you may notice a few discrepancies if the plug-in hasn't been explicitly updated for sf:

The --help content likely assumes you’re running the commands in sfdx. So the command examples show using sfdx instead of sf, use colon separators instead of spaces, and so on.
Similarly, the command output reflects the sfdx style. For example, if you install the @oclif/plugin-commands plug-in and then run sf commands, all the commands are correctly listed. However, the commands are displayed with colon separators and their description is the first line of the long command description rather than the short summary.

Install sf

If you've already installed Salesforce CLI and are currently using sfdx commands, update to the latest version of sfdx and you automatically get the sf executable:

sfdx update

We've updated the operating system-specific Salesforce CLI installers to include both the sfdx and sf executables. So if you haven't ever installed Salesforce CLI, install it now to get both executables. See Install Salesforce CLI for details. After you install, run sfdx update to start using sf.

If get errors using the preceding methods, install sf on its own, without sfdx:

npm: npm install @salesforce/cli --global
macOS installer: https://developer.salesforce.com/media/salesforce-cli/sf/channels/stable/sf.pkg
Windows installer: https://developer.salesforce.com/media/salesforce-cli/sf/channels/stable/sf-x64.exe

Run Through the Dreamhouse Example

The quickest way to get going with sf is to clone the dreamhouse-lwc GitHub repo. Use its configuration files and Salesforce application to try out some of the new sf commands and see how they work with sfdx.

Open a terminal or command prompt window, and clone the dreamhouse-lwc GitHub sample repo using HTTPS or SSH.

git clone https://github.com/trailheadapps/dreamhouse-lwc.git --or-- git clone [email protected]:trailheadapps/dreamhouse-lwc.git
Change to the dreamhouse-lwc project directory.

cd dreamhouse-lwc
Log in to your Developer Hub (Dev Hub) org to authorize it to create scratch orgs. Set it as your default Dev Hub and assign it an alias.

sf login org --set-default-dev-hub --alias DevHub

Enter your Dev Hub org credentials in the browser that opens. After you log in successfully, you can close the browser.
Create a scratch org using the config/project-scratch-def.json file, set the environment (org) as your default, and assign it an alias.

sfdx force:org:create --setdefaultusername -f config/project-scratch-def.json --setalias my-scratch-org

The sfdx command uses the default Dev Hub you set with the sf login command in a previous step.
View the environments (in this case, orgs) that you've either created or logged into.

sf env list

The displayed tables include the scratch org you created and the Dev Hub you logged into. The right-most Config column indicates the default scratch org and Dev Hub org with the target-org and target-dev-hub configuration variables, respectively.
Deploy the Salesforce app, whose source is located in the force-app directory, to the scratch org.

sf deploy metadata --source-dir force-app
Assign the dreamhouse permission set to the default user.

sfdx force:user:permset:assign -n dreamhouse
Import sample data into the scratch org.

sfdx force:data:tree:import -p data/sample-data-plan.json
Run Apex tests.

sfdx force:apex:test:run --resultformat human
Open the scratch org and view the pushed metadata under Most Recently Used.

sf env open --target-env my-scratch-org
In the Salesforce UI, make a small cosmetic change to an item. For example, update a comment in the GeocodingServiceTest Apex class. This step is to later show how you retrieve metadata from an org.
Optionally, in the App Launcher, find and open Dreamhouse.
Back in the terminal or command window, retrieve the small change you made in the org to your project.

sf retrieve metadata --source-dir force-app

Confirm that the small change you made in your org has been retrieved to your project by viewing the file force-app/main/default/classes/GeocodingServiceTest.cls.

List of sf Commands with sfdx Equivalents

This table shows the mapping between the currently available sf commands and their closest sfdx equivalent.

sf command	Similar sfdx command
`sf config get`	`sfdx config:get`
`sf config list`	`sfdx config:list`
`sf config set`	`sfdx config:set`
`sf config unset`	`sfdx config:unset`
`sf deploy` (interactive)	No equivalent.
`sf deploy metadata`	`sfdx force:source:deploy`
`sf env open`	`sfdx force:org:open
`sf env list`	`sfdx force:org:list`, `sfdx auth:list`
`sf env display`	`sfdx force:org:display`
`sf login` (interactive)	No equivalent.
`sf login org`	`sfdx auth:web:login`
`sf login org jwt`	`sfdx auth:jwt:grant`
`sf logout` (interactive)	No equivalent.
`sf logout org`	`sfdx auth:logout`
`sf retrieve metadata`	`sfdx force:source:retrieve`

Final Notes

We reserve the right to change the JSON output of sf commands between Beta and GA.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly