Move from sfdx (v7) to sf (v2)

npm

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

macOS or Windows Installers

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

TAR Files

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

Update Your Continuous Integration (CI) Scripts

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

When updating your CI script, if it includes this command to install sfdx (v7), you must remove it:

1npm install sfdx-cli --global

If you keep both commands, the command to install sf (v2) returns an error and your script fails.

Warning

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.

After You Move to sf (v2)

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.

Why Should You Move?

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

Troubleshoot npm Error: code EEXIST

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

Return to sfdx (v7)

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.