How to Install Salesforce CLI with NPM

Reading Time: 6 min
Author: William Watson Published: November 21, 2023 Updated: February 11, 2026
#Development #SFDX #Deployment
Jump to section Current: Top of article

Why should I install Salesforce CLI with npm?

NPM gives you version control, CI/CD compatibility, and cross-platform consistency that standalone installers lack. If your team already uses Node.js, installing Salesforce CLI through npm keeps your toolchain unified and your builds reproducible.

The sfdx-cli package is deprecated and will block installation of the current CLI. If you have sfdx-cli installed, you must uninstall it before installing @salesforce/cli. See the migration section below.

npm uninstall sfdx-cli --global

Having installation issues? See our guide on How to Fix Salesforce CLI NPM Installation Errors for solutions to common problems like permission errors and command not found.

Why NPM?

NPM, integral to the Node.js ecosystem, brings numerous benefits to Salesforce CLI installation:

  • Version Management: Easily switch between CLI versions to meet project-specific requirements. For example, npm install @salesforce/cli@2.121.7 --global for a specific version.
  • Version Pinning for CI/CD: Lock your team to a specific CLI version for reproducible builds.
  • Ecosystem Compatibility: Seamlessly integrates with other Node.js tools, enhancing tooling and automation capabilities in Salesforce development.
  • Cross-Platform Consistency: Provides a consistent installation experience across different operating systems, reducing setup overhead.

Prerequisites

  • Node.js 24 (Active LTS) or Node.js 22 (Maintenance LTS). Node.js 20 has reached end of life. Visit Node.js for download and installation instructions.
  • Familiarity with basic command-line operations and NPM is assumed.

Recommended: Install Node.js via nvm (macOS/Linux) or nvm-windows (Windows) to avoid permission issues and switch Node versions easily.

You can check your Node.js and NPM versions by running the commands node --version and npm --version respectively.

Detailed Installation Steps

  1. Open your terminal: Use Terminal on macOS/Linux, or PowerShell on Windows.
  2. Install Salesforce CLI: Run the following command to install the CLI globally:
    npm install @salesforce/cli --global
  3. Verify the installation: Check that the CLI is installed correctly:
    sf --version
    You should see output like @salesforce/cli/2.121.7. Run sf doctor to check your environment for common configuration issues:
    sf doctor
  4. Keep the CLI updated: Salesforce releases weekly updates with new features and security patches:
    npm update @salesforce/cli --global
    You can also update using the CLI’s built-in command:
    sf update

Getting errors? Permission denied, command not found, or PowerShell policy errors are common. See How to Fix Salesforce CLI NPM Installation Errors for solutions.

How do I migrate from sfdx-cli to @salesforce/cli?

If you previously installed the old sfdx-cli package, you must fully remove it before installing @salesforce/cli. The new CLI will refuse to install if it detects sfdx-cli on your system.

  1. Check your current installation:

    npm list -g sfdx-cli

    If this returns a version number, you have the old package installed.

  2. Uninstall the old CLI:

    npm uninstall sfdx-cli --global

  3. Install the current CLI:

    npm install @salesforce/cli --global

  4. Verify the new installation:

    sf --version
sf doctor

  5. Update your scripts: The sfdx command still works as an alias, but Salesforce recommends updating scripts to use sf. Command syntax has changed — for example, sfdx force:org:list is now sf org list. See Salesforce’s command reference for the full mapping.

Note: If you see sfdx: command not found after installing @salesforce/cli, that is expected when the alias is not enabled. Use sf instead.

What are the best practices for managing Salesforce CLI with npm?

  • Use nvm (Recommended): Installing Node.js via nvm (macOS/Linux) or nvm-windows (Windows) avoids permission issues and makes switching Node versions simple. This is the approach Salesforce recommends.
  • Local Installation for CI/CD: For reproducible builds, install a specific version locally in your project:
    npm install @salesforce/cli@2.121.7 --save-dev
    Then run commands via npx sf instead of the global sf. For full CI/CD pipeline patterns including GitHub Actions and GitLab CI, see our Salesforce CLI DevOps Playbook.
  • sf vs sfdx Commands: Both commands work after installing @salesforce/cli. The sfdx command is an alias for backward compatibility. Salesforce recommends using sf for all new projects and scripts.
  • Run diagnostics with sf doctor: If something feels off after installation or an update, sf doctor checks your Node version, CLI version, plugin health, and environment configuration in one command.

Conclusion

Using NPM for Salesforce CLI installation provides version control, CI/CD compatibility, and cross-platform consistency that standalone installers lack. Install @salesforce/cli (not the deprecated sfdx-cli), use Node.js 24 or 22, and consider using nvm to avoid permission headaches. If you are migrating from the old sfdx-cli package, uninstall it first — the new CLI will not install alongside it.

If you run into installation problems, check out How to Fix Salesforce CLI NPM Installation Errors for step-by-step solutions to common issues.