Home

Get Started With sf

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:

1. Install sf.
2. Run Through the Dreamhouse Example.
3. 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 for all Salesforce development. The new executable, sf, is bundled with Salesforce CLI so you can keep using the sfdx commands you know and love. But you can also start using the new sf commands that are designed for cross-cloud app development and deployment. The two executables are fully aware of each other, so, for example, you can start using sf commands on orgs you've already created or authorized with sfdx commands.

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

If you aren't currently using sfdx, install sf using operating system-specific installers such as *.pkg on macOS. We've updated all Salesforce CLI installers to include both the sfdx and sf executables. See Install Salesforce CLI for details. After you install, run sfdx update to start using sf.

To install using npm, run this command:

npm install @salesforce/cli --global

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.

1. 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

2. Change to the dreamhouse-lwc project directory.

   cd dreamhouse-lwc

3. 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.

4. 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.

5. 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.

6. Deploy the Salesforce app, whose source is located in the force-app directory, to the scratch org.

   sf deploy metadata --source-dir force-app

7. Assign the dreamhouse permission set to the default user.

   sfdx force:user:permset:assign -n dreamhouse

8. Import sample data into the scratch org.

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

9. Run Apex tests.

   sfdx force:apex:test:run --resultformat human

10. Open the scratch org and view the pushed metadata under Most Recently Used.

    sf env open --target-env my-scratch-org

11. 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.

12. Optionally, in the App Launcher, find and open Dreamhouse.

13. 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.