Salesforce CLI Setup Guide

Release Notes
Before You Begin
Move from sfdx (v7) to sf (v2)
Install Salesforce CLI
Install the CLI on macOS
Install the CLI on Windows
Install the CLI with a TAR File
Install the CLI with npm
Install the CLI Release Candidate or Nightly
Install Older Versions of Salesforce CLI
Verify Your Installation And Get Version Information
Update Salesforce CLI
Salesforce CLI Configuration and Tips
Uninstall Salesforce CLI or Plugins
Run Salesforce CLI Using a Docker Image
Salesforce CLI Plugins
Troubleshoot Salesforce CLI
CLI Deprecation Policy
Next Steps
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Install Salesforce CLI

Install Salesforce CLI on your computer using operating system-specific artifacts, such as .pkg on macOS, TAR files, or with npm.

Choose one method to install on your computer. For example, don’t install on macOs with both a .pkg file and npm. Installing it both ways can lead to confusing path issues on your computer, sometimes without an explicit error and thus difficult to diagnose.

Install the CLI on macOS

Install Salesforce CLI on macOS with a .pkg file.
  1. Download the .pkg file.
  2. Run the .pkg file, such as double-clicking it from Finder, and answer all the prompts.
  3. After the installation completes, restart your Terminal windows or IDEs to make sure Salesforce CLI is available.

Install the CLI on Windows

Install Salesforce CLI on Windows with an .exe file.
  1. Download the .exe file.
  2. Run the .exe file, such as double-clicking it from Windows Explorer, and answer all the prompts.
  3. After the installation completes, restart your command prompts, PowerShell windows, or IDE to make sure Salesforce CLI is available.

Salesforce CLI works best within the native Windows command prompt (cmd.exe) and the Microsoft Windows PowerShell. We don’t recommend using Salesforce CLI with a Linux terminal emulator, such as Windows 10 Subsystem for Linux, cygwin, or MinGW, because support for bugs is limited.

Warning

Install the CLI with a TAR File

Salesforce CLI distributes TAR files that you can install on all supported operating systems.

Use this table to find the unversioned URLs for the TAR file (.tar.gz or .tar.xz ) for your operating system. When we release a new version of Salesforce CLI every week, we also update these URLs so they point to the most up-to-date version. Unversioned URLs are especially useful for CI use cases. The table also includes manifest URLs that show the versioned URL for each file.

Operating System Tar Files Manifest
Linux
macOS
Windows

We highly recommended that you use the installers or npm to install Salesforce CLI on Windows. If, however, you decide to use the Windows TAR files, you must first install a separate program, such as 7Zip, to extract the file contents.

Important

In these examples it’s assumed that you’re installing Salesforce CLI on Linux and in the cli/sf subdirectory of your home directory.

  1. Download or wget one of these TAR files. 
    1wget https://developer.salesforce.com/media/salesforce-cli/sf/channels/stable/sf-linux-x64.tar.xz
  2. Create the directory where you want to install Salesforce CLI. 
    1mkdir ~/cli/sf
  3. Unpack the contents for your TAR file: 
    1tar xJf sf-linux-x64.tar.xz -C ~/cli/sf --strip-components 1

    -C unpacks the contents in the ~/cli/sf directory, while --strip-components 1 removes the root path component.

    This example shows just one possible set of flags for the tar command on Linux. For other options on your operating system, refer to the tar documentation.

    Note

  4. Update your PATH environment variable to include the Salesforce CLI bin directory. For example, to set it for your current terminal session: 
    1export PATH=~/cli/sf/bin:$PATH

    To update your PATH permanently, add the appropriate entry to your shell’s configuration file. For example, if you use the Bash shell, add this line to your ~/.bashrc or ~/.bash_profile file:

    1PATH=~/cli/sf/bin:$PATH

Install the CLI with npm

If you've installed Node.js on your computer, you can use npm to install Salesforce CLI. This method lets you install Salesforce CLI from the command line and can be especially useful for continuous integration (CI) use cases.

This installation method is a good option if you don’t have administrator permissions on your workstation, or if group policy blocks CLI installation and updates. Installing Salesforce CLI with npm doesn’t require root permissions.

  1. Ensure that the long-term support (Active LTS) version of Node.js is installed on your computer. To install the LTS version, go to https://nodejs.org/en/download/. To check your version number, run: 
    1node --version
  2. Run this command to install Salesforce CLI: 
    1npm install @salesforce/cli --global

    If you receive a permission error when installing the CLI using npm, we recommend not using sudo. See Fixing npm permissions.

Install the CLI Release Candidate or Nightly

We release a new version of the CLI weekly. At the same time we also publish a release candidate of the CLI that contains changes that we plan to include in the next weekly release. Think of the release candidate as the CLI-version of the Salesforce sandbox preview. You can install a release candidate if you want to check out upcoming features. Or stay on the current and official release. Or go back and forth. It’s up to you!

We also release nightly builds every day. Nightly builds include the latest versions of all our libraries and plugins. If you want to try out a fix that was merged just a day ago, try installing a nightly build. Similar to the release candidate, the nightly builds help improve the stability of Salesforce CLI by catching issues before they make it to the stable release. 

While the latest (stable) release is the most reliable, we encourage users to also test the release candidates and nightly builds and report issues to our GitHub issues repository. We recommend you run your continuous integration (CI) jobs against both the current release and the release candidate to identify potential breaking changes before they happen.

Run this command to display the version of your installed Salesforce CLI. The version doesn’t indicate if it’s a release candidate or nightly build, so check the release notes for the current version numbers. 

1sf version

Install Using Installers

Installers use the tags stable for the current release, stable-rc for the release candidate, and nightly for the nightly builds.

If you’ve already installed Salesforce CLI and are using the current release, run this command to switch to the release candidate.

1sf update stable-rc

Similarly, run this command to install the nightly build.

1sf update nightly

To uninstall the release candidate or nightly build and return to the current version, run this command.

1sf update stable

Install Using npm

Npm installs use the tags latest for the current release, latest-rc for the release candidate, and nightly for the nightly builds.

Run this command to install the release candidate using npm.

1npm install --global @salesforce/cli@latest-rc

Similarly, run this command to install the nightly build.

1npm install --global @salesforce/cli@nightly

To uninstall the release candidate or nightly build and return to the current version, run this command. 

1npm install --global @salesforce/cli@latest

Run this command to view the Salesforce CLI versions that are currently associated with the npm tags. 

1npm view @salesforce/cli dist-tags --json

Install from a TAR File

Salesforce CLI distributes TAR files for the release candidate and nightly builds that you can install on all supported operating systems. The download URLs are similar to the URLs for installing the current release, but use the stable-rc or nightly channel rather than the stable channel.

For example, to wget the Linux TAR file for the release candidate, run this command, which downloads from the stable-rc channel.

1wget https://developer.salesforce.com/media/salesforce-cli/sf/channels/stable-rc/sf-linux-x64.tar.xz

This command downloads a nightly build.

1wget https://developer.salesforce.com/media/salesforce-cli/sf/channels/nightly/sf-linux-x64.tar.xz

Other than using a different channel, the instructions for installing the release candidate or nightly build from a TAR file are the same as the instructions for installing the current release.

Install Older Versions of Salesforce CLI

We recommend that you always use the latest version or release candidate of Salesforce CLI. However, we also understand that sometimes you want an older version of the CLI.

Installers

If you installed Salesforce CLI with the installers, update to an older version with the --version flag. For example, run this command to update to version 2.0.1.

1sf update --version 2.0.1

Use the --available flag to list all available older versions to which you can update. The output also shows whether you already have a local copy or if it must be downloaded. 

1sf update --available

Use --interactive to choose a version interactively.

Use this command to return to the current version.

1sf update stable

npm

To update to an older version of Salesforce CLI using npm, specify the version using @<version> after the @salesforce/cli package name. For example, run this command to update to version 2.0.1.

1npm install @salesforce/cli@2.0.1 --global

Use this command to return to the current version.

1npm install @salesforce/cli --global

See the Salesforce CLI npmjs.com page for a list of all versions. We keep all old versions of the @salesforce/cli and sfdx-cli (deprecated) npm packages.

TAR Files

We publish JSON files that list the download URLs for recent versions of the installers and TAR files for each supported operating system. We continually add new versions to the lists; versions remain on the list for 20 weeks. We keep the TAR and installer files themselves for 40 weeks minimum.

sf (v2)

Operating System File Type TAR Compression Type Link to JSON File
Linux ARM TAR gz sf-linux-arm-tar-gz.json
Linux ARM TAR xz sf-linux-arm-tar-xz.json
Linux 64 TAR gz sf-linux-x64-tar-gz.json
Linux 64 TAR xz sf-linux-x64-tar-xz.json
Windows 64 TAR gz sf-win32-x64-tar-gz.json
Windows 64 TAR xz sf-win32-x64-tar-xz.json
Windows x86 TAR gz sf-win32-x86-tar-gz.json
Windows x86 TAR xz sf-win32-x86-tar-xz.json
macOS (Intel CPU) TAR gz sf-darwin-x64-tar-gz.json
macOS (Intel CPU) TAR xz sf-darwin-x64-tar-xz.json
macOS (Apple Silicon) TAR gz sf-darwin-arm64-tar-gz.json
macOS (Apple Silicon) TAR xz sf-darwin-arm64-tar-xz.json
Windows 64 Installer sf-x64-exe.json
Windows x86 Installer sf-x86-exe.json
macOS (Intel CPU) Installer sf-x64-pkg.json
macOS (Apple Silicon) Installer sf-arm64-pkg.json

sfdx (v7) - Deprecated

As of July 12, 2023, we no longer update sfdx (v7). We keep these old versions for historical reasons only.

Note

Operating System File Type TAR Compression Type Link to JSON File
Linux ARM TAR gz sfdx-linux-arm-tar-gz.json
Linux ARM TAR xz sfdx-linux-arm-tar-xz.json
Linux 64 TAR gz sfdx-linux-x64-tar-gz.json
Linux 64 TAR xz sfdx-linux-x64-tar-xz.json
Windows 64 TAR gz sfdx-win32-x64-tar-gz.json
Windows 64 TAR xz sfdx-win32-x64-tar-xz.json
Windows x86 TAR gz sfdx-win32-x86-tar-gz.json
Windows x86 TAR xz sfdx-win32-x86-tar-xz.json
macOS (Intel CPU) TAR gz sfdx-darwin-x64-tar-gz.json
macOS (Intel CPU) TAR xz sfdx-darwin-x64-tar-xz.json
macOS (Apple Silicon) TAR gz sfdx-darwin-arm64-tar-gz.json
macOS (Apple Silicon) TAR xz sfdx-darwin-arm64-tar-xz.json
Windows 64 Installer sfdx-x64-exe.json
Windows x86 Installer sfdx-x86-exe.json
macOS (Intel CPU) Installer sfdx-x64-pkg.json
macOS (Apple Silicon) Installer sfdx-arm64-pkg.json

Verify Your Installation And Get Version Information

Verify your Salesforce CLI installation to ensure you’ve installed it correctly.
Run this command to verify the Salesforce CLI version:
1sf --version
2@salesforce/cli/2.1.0 darwin-arm64 node-v16.17.0

Run this command to view the installed core plugins and their versions:

1sf plugins --core
2@oclif/plugin-autocomplete 2.2.0 (core)
3@oclif/plugin-commands 2.2.15 (core)
4@oclif/plugin-help 5.2.9 (core)
5@oclif/plugin-not-found 2.3.24 (core)
6@oclif/plugin-plugins 3.1.2 (core)
7@oclif/plugin-search 0.0.17 (core)
8@oclif/plugin-update 3.1.16 (core)
9@oclif/plugin-version 1.3.4 (core)
10@oclif/plugin-warn-if-update-available 2.0.37 (core)
11@oclif/plugin-which 2.2.21 (core)
12@salesforce/cli 2.0.0 (core)
13apex 2.2.22 (core)
14auth 2.7.17 (core)
15data 2.3.20 (core)
16deploy-retrieve 1.10.4 (core)
17info 2.6.16 (core)
18limits 2.3.17 (core)
19login 1.2.11 (core)
20org 2.9.2 (core)
21schema 2.3.10 (core)
22settings 1.4.10 (core)
23sobject 0.1.22 (core)
24source 2.10.10 (core)
25telemetry 2.2.0 (core)
26templates 55.4.18 (core)
27trust 2.4.20 (core)
28user 2.3.14 (core)

Run this command to view all available Salesforce CLI commands:

1sf commands

The list of commands includes aliased commands, such as force:apex:execute, the sfdx-style command that’s aliased to apex run.

Run this command to display the release notes for the version of Salesforce CLI that’s currently installed on your computer:

1sf whatsnew