Move from sfdx (v7) to sf (v2)

If you’re currently using sfdx (v7), we highly recommend that you move to sf (v2). The move is easy: you first uninstall sfdx (v7) and then install sf (v2). After you move, the CLI commands that you’ve been running in a terminal or continuous integration (CI) scripts continue to work as before.

1sfdx version
2sfdx-cli/7.208.10 darwin-arm64 node-v18.16.0

The sections in this document show how to move to sf (v2) for the three installation methods: npm, macOS or Windows installers, and TAR files. Pick the section that applies to your environment. If you’re not sure how you originally installed sfdx (v7), read this document. Are you using Docker? Read our updated Docker instructions to see how to get the sf (v2) image.

1. Open a terminal (macOS and Linux) or command prompt (Windows).

2. Uninstall sfdx (v7) with this command:

   1npm uninstall sfdx-cli --global

3. Verify that you’ve uninstalled sfdx (v7) by running the sfdx version command. If you uninstalled correctly, the command fails. For example, on macOS:

   1sfdx version
   2-bash: sfdx: command not found

4. Install sf (v2) with this command.

   1npm install @salesforce/cli --global

   If you already had sf (v1) installed, this command updates it to v2.

5. Verify that you’ve installed sf (v2) by running this command:

   1sf version
   2@salesforce/cli/2.0.1 darwin-arm64 node-v18.16.0

   The version starts with @salesforce/cli/2. The following command also returns the same version because sfdx is now aliased to sf:

   1sfdx version
   2@salesforce/cli/2.0.1 darwin-arm64 node-v18.16.0

Congrats, you successfully moved to sf (v2)!

Installers refer to the Windows .exe or macOS .pkg installer files.

1. Uninstall your current sfdx (v7) installation.

   As of October 2021, if you originally installed Salesforce CLI using the OS-specific installers, you actually got two interoperable CLIs (AKA executables) bundled together: sfdx (v7) and sf (v1). When you uninstall Salesforce CLI, it removes both executables.

2. Open a terminal (macOS) or command prompt (Windows).

3. Verify that you’ve uninstalled sfdx (v7) by running the sfdx version command. If you uninstalled correctly, the command fails. For example, on macOS:

   1sfdx version
   2-bash: sfdx: command not found

4. Install sf (v2) using these installer links:

   • macOS

     • Apple Silicon
     • Intel CPU

   • Windows

     • x64
     • x86

5. Verify that you’ve installed sf (v2) by running this command:

   1sf version
   2@salesforce/cli/2.0.1 darwin-arm64 node-v18.16.0

   The version starts with @salesforce/cli/2. The following command also returns the same version because sfdx is now aliased to sf:

   1sfdx version
   2@salesforce/cli/2.0.1 darwin-arm64 node-v18.16.0

Congrats, you successfully moved to sf (v2)!

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

1. Uninstall your current sfdx (v7) installation.

   As of October 2021, if you originally installed Salesforce CLI using TAR files, you actually got two interoperable CLIs (AKA executables) bundled together: sfdx (v7) and sf (v1). When you uninstall Salesforce CLI, it removes both executables.

2. Open a terminal (macOS and Linux) or command prompt (Windows).

3. Verify that you’ve uninstalled sfdx (v7) by running the sfdx version command. If you uninstalled correctly, the command fails. For example, on macOS:

   1sfdx version
   2-bash: sfdx: command not found

4. Install sf (v2).

5. Verify that you’ve installed sf (v2) by running this command:

   1sf version
   2@salesforce/cli/2.0.1 darwin-arm64 node-v18.16.0

   The version starts with @salesforce/cli/2. The following command also returns the same version because sfdx is now aliased to sf:

   1sfdx version
   2@salesforce/cli/2.0.1 darwin-arm64 node-v18.16.0

Congrats, you successfully moved to sf (v2)!

If you use Salesforce CLI in a continuous integration (CI) system, update your scripts to use sf (v2).

npm

If your CI scripts install Salesforce CLI with npm, update them to use this command to install sf (v2):

1npm install @salesforce/cli --global

1npm install sfdx-cli --global

TAR Files

If your CI scripts install Salesforce CLI with TAR files, update the download URLs to point to the sf (v2) downloads. For example, change this URL:

1https://developer.salesforce.com/media/salesforce-cli/sfdx/channels/stable/sfdx-linux-x64.tar.gz

To this URL:

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

See Install the CLI with a TAR file for the URLs for all operating systems.

Here are a few things to be aware of after you make the move.

• Regenerate your autocomplete cache by running this command in a terminal (macOS and Linux) or command prompt (Windows).

  1sf autocomplete --refresh-cache

  Open a new terminal for the change to take effect. Autocomplete doesn’t work correctly until you regenerate its cache.

• Every CLI command execution, VS Code invocation of Salesforce CLI, and CI script works the same in both sfdx (v7) and sf (v2). If you find a difference, open a GitHub issue.

• You can run commands with either sfdx or sf; they’re now the same. For example, these two command executions are the same.

  1sf project deploy start
  2sfdx project deploy start

  Everything that was in sfdx is available in sf, with the same names and flags.

sf (v2) became generally available on July 12, 2023. At that time we stopped publishing updates to sfdx (v7) and sf (v1). To get new Salesforce CLI features and bug fixes, you must use sf (v2).

Also, sfdx (v7) is twice the size of sf (v2) because it also includes sf (v1). To reduce the size of your Salesforce CLI installation and downloads, we recommend you move to sf (v2).

If you try to install sf (v2) using npm without first uninstalling sfdx (v7), you get this error:

1npm ERR! code EEXIST
2npm ERR! path /Users/user/.nvm/versions/node/v18.16.0/bin/sfdx
3npm ERR! EEXIST: file already exists
4npm ERR! File exists: /Users/user/.nvm/versions/node/v18.16.0/bin/sfdx
5npm ERR! Remove the existing file and try again, or run npm
6npm ERR! with --force to overwrite files recklessly.
7
8npm ERR! A complete log of this run can be found in:
9npm ERR!     /Users/user/.npm/_logs/2023-06-28T22_16_15_181Z-debug-0.log

You can also encounter this error in your continuous integration (CI) system when sf (v2) becomes generally available. If your CI scripts already use npm to install both sfdx (v7) and sf (v1), and you don’t update the script, the error can start happening automatically as of July 12, 2023.

To fix the problem, remove this command from your script.

1npm install sfdx-cli --global

Keep this command, which installs sf (v2).

1npm install @salesforce/cli --global

We don’t anticipate any reason for you to move back to sfdx (v7). However, if you must return, follow these steps.

1. Uninstall sf (v2).

2. Install sfdx (v7).

   For npm, run this command in a terminal (macOS and Linux) or command prompt (Windows).

   1npm install sfdx-cli --global

   For the installers and TAR files, refer to the sfdx (v7) JSON files that list the recent download URLs for each supported operating system. See this topic for details.

   As of July 12, 2023, the web page to download Salesforce CLI has been updated to download only sf (v2).

   Note

3. In your CI scripts, go back to the npm commands or TAR download URLs you were using before.

See Also

• Salesforce CLI Command Reference: Migrate sfdx-Style Commands to the New sf-Style

j

Quick Start

System Requirements

Move from sfdx (v7) to sf (v2)

Install Salesforce CLI

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

Release Notes

Previous PDF Versions