Salesforce CLI is Salesforce's official command-line tool for building on the platform. With one command, sf, you log in to orgs, create scratch orgs, deploy and retrieve metadata, run Apex tests, query and load data and create packages. The current version is sf (v2). The older sfdx (v7) receives no updates, and the old force:source and force:mdapi commands were removed in 2024.
This guide was first published in 2021 as "What is Salesforce CLI? | Salesforce DX CLI". It has been rewritten for 2026 for the sf (v2) CLI, with the command changes that broke many older scripts.
What is Salesforce CLI?
Salesforce CLI is Salesforce's free, open-source command-line tool for every Salesforce DX task, from logging in to deploying and testing. Salesforce CLI is a free, open-source tool that talks to Salesforce's APIs for you. It is the engine behind source-driven development (often called Salesforce DX): you keep your org's metadata as files in Git, change them locally, and push them to orgs with commands that can also run unattended in a pipeline. The Salesforce extensions for Visual Studio Code use it under the hood, so even developers who never open a terminal depend on it.
Salesforce unified its two executables into sf (v2), which reached general availability in July 2023, according to the official CLI repository. The same page notes that sf (v2) "is smart enough to understand both sfdx and sf commands" and is faster to install and update.
sfdx vs sf: what changed and why it matters
sf (v2) replaced sfdx (v7); sfdx gets no updates, and scripts that use removed force: commands now fail.
| sfdx (v7) | sf (v2) | |
|---|---|---|
| Status | Deprecated; npm marks sfdx-cli as deprecated with "no updates planned" | Current; new stable release every week |
| Command style | sfdx force:source:deploy (colons, force: namespace) | sf project deploy start (spaces, grouped by topic) |
| npm package | sfdx-cli | @salesforce/cli |
Typing sfdx | Runs v7 | Still works: sfdx is an alias for sf |
The change that catches teams out: in release 2.65.8 (6 November 2024) Salesforce removed more than twenty deprecated commands, including force:source:deploy, force:source:retrieve, force:source:push, force:source:pull and every force:mdapi command, as announced in the CLI release notes. Any CI script still calling them fails on a current CLI. The npm package page for @salesforce/cli is the one to install.
How to install Salesforce CLI
Install Salesforce CLI with the installer for your operating system, or with npm on any system. Salesforce's install guide offers four routes:
- macOS: a .pkg installer (choose the Apple silicon or Intel build).
- Windows: an .exe installer (x64 or ARM64). Salesforce recommends the native command prompt or PowerShell.
- Linux (and others): TAR archives.
- npm, on any system:
npm install --global @salesforce/cli. This needs Node.js; Salesforce recommends the Active LTS version and advises against using sudo. The current release in the npm registry requires Node.js 22 or later.
The installers bundle their own Node.js, so they are the simplest choice for most people. Check the install with sf version (it should start with @salesforce/cli/2) and list everything available with sf commands.
Moving from sfdx to sf, step by step
Moving to sf is an uninstall of sfdx followed by a clean install of sf, plus a review of your scripts. Salesforce's migration page describes the move as an uninstall followed by an install:
- Run
sfdx version. If it starts withsfdx-cli/7, you have the old CLI. - Uninstall sfdx (v7) with the same method you used to install it. If you used an installer, this removes both sfdx (v7) and sf (v1).
- Run
sfdx versionagain; it should now fail. - Install sf (v2) with an installer or npm. Installing over v7 without removing it causes an error.
- In CI, replace any
npm install sfdx-cliline withnpm install @salesforce/cli --global. - Rewrite removed
force:sourceandforce:mdapicalls using the table below, and refresh autocomplete withsf autocomplete --refresh-cache.
Old sfdx commands and their sf replacements
Every common sfdx command has an sf equivalent grouped by topic, such as org, project, apex and data.
| Task | Old sfdx command | Current sf command |
|---|---|---|
| Log in through the browser | force:auth:web:login | sf org login web |
| Log in from CI with a certificate | force:auth:jwt:grant | sf org login jwt |
| Create a project | force:project:create | sf project generate |
| Create a scratch org | force:org:create | sf org create scratch |
| Deploy metadata | force:source:deploy, force:source:push, force:mdapi:deploy (removed) | sf project deploy start |
| Retrieve metadata | force:source:retrieve, force:source:pull (removed) | sf project retrieve start |
| Run Apex tests | force:apex:test:run | sf apex run test |
| Run a SOQL query | force:data:soql:query | sf data query |
| Open an org | force:org:open | sf org open |
| Assign a permission set | force user permset assign (removal announced for 1 March 2027) | sf org assign permset |
| Generate a user password | force user password generate (removal announced for 1 March 2027) | sf org generate password |
Command names and aliases are taken from the current sf command reference on GitHub. Commands that were not removed, such as the data query, still accept their old names as aliases, but new scripts should use the sf names.
The Salesforce CLI commands you will use most
Ten commands cover most daily work: logging in, listing orgs, creating projects and scratch orgs, deploying, retrieving, testing and querying.
sf org login web --alias dev --set-default: log in to an org in the browser and make it the default target.sf org list: show every org the CLI is connected to.sf project generate --name myproject: create a new Salesforce DX project.sf project retrieve start --metadata ApexClass: pull components from an org into your project.sf project deploy start --source-dir force-app --target-org dev: deploy local source to an org. Add--dry-runto validate and run tests without saving, and--test-level RunLocalTeststo choose which tests run.sf apex run test --target-org dev: run Apex tests.sf data query --query "SELECT Id, Name FROM Account LIMIT 10": run SOQL.sf data import bulk --file accounts.csv --sobject Account: load a large CSV through Bulk API 2.0.sf org create scratch --target-dev-hub hub --definition-file config/project-scratch-def.json: create a scratch org from a Dev Hub. A free Developer Edition org can act as your Dev Hub while you learn.sf doctor: collect diagnostics when something goes wrong.
Every command accepts --json for machine-readable output in scripts, and sf COMMAND --help shows its flags.
Release channels and keeping the CLI current
Salesforce CLI has three channels, stable, release candidate and nightly, and the stable version changes every week. Salesforce publishes a new stable version every Wednesday, a release candidate at the same time, and nightly builds, according to the release notes; as of 10 November 2026 the latest stable release is 2.157.8, published on 4 November 2026. Update with sf update stable (installer or TAR) or npm install @salesforce/cli@latest --global (npm). In CI, pin a version so a weekly release cannot change a pipeline without warning, and upgrade on purpose.
Common Salesforce CLI problems
Most CLI errors after an upgrade come from removed commands, the source-tracking rule or a leftover sfdx install.
- "Command not found" after an upgrade: the script still calls a removed
force:sourceorforce:mdapicommand. Switch to the sf command in the table above. - Deploy or retrieve refuses to run without metadata: since December 2025,
project deploy startandproject retrieve startneed either a source-tracked org or an explicit--source-dir,--metadataor--manifest, as the release notes explain. - Deprecation warnings on user commands: the release candidate published on 4 November 2026 warns that
force user password generate,force user permset assignandforce user permsetlicense assignwill be removed on 1 March 2027; switch to theirsf orgreplacements now. - Install error over an old version: sfdx (v7) is still installed. Uninstall it first.
- Permission errors with npm: fix npm's global folder permissions rather than using sudo, as Salesforce advises.
- Tests that pass locally fail on deploy: check which test level the deploy uses and Apex coverage, and see our guide to governor limits.
Deploy to a sandbox before production, and if you are new to metadata, our guide to Salesforce metadata explains what the CLI is moving. For one-off data fixes and queries without a terminal, see our Workbench guide; for bulk loads with a desktop app, see Data Loader. For release management on top of the CLI, read our Salesforce DevOps guide.
Getting help
Moving a team from change sets or old sfdx scripts to a clean sf-based pipeline is mostly about getting the project structure, test levels and environments right once. Techila is a Salesforce Summit Partner; our Salesforce development services team sets up and runs source-driven delivery for Salesforce orgs. Talk to us about your release process.
Frequently asked questions
What is Salesforce CLI used for?
It lets developers and admins work with Salesforce orgs from a terminal or script: log in, create scratch orgs and sandboxes, deploy and retrieve metadata, run Apex tests, query and load data, and build packages. It is also what the Salesforce extensions for VS Code and most CI pipelines run underneath.
What is the difference between sfdx and sf?
sfdx (v7) is the old executable and no longer receives updates. sf (v2), generally available since July 2023, is the current Salesforce CLI. It understands both sf-style and sfdx-style commands, but many old force:source and force:mdapi commands were removed in November 2024, so scripts should use the sf commands.
How do I install Salesforce CLI?
Download the installer for macOS (.pkg) or Windows (.exe), use a TAR file on Linux, or run npm install --global @salesforce/cli if you have Node.js. Uninstall sfdx (v7) first if it is on your machine, then check the install with sf version.
How do I update Salesforce CLI?
If you used an installer or TAR file, run sf update stable. If you used npm, run npm install @salesforce/cli@latest --global. Salesforce publishes a new stable version every Wednesday.
What replaced sfdx force:source:deploy?
sf project deploy start, which replaces force:source:deploy, force:source:push and force:mdapi:deploy. For retrieving, use sf project retrieve start. The old force:source and force:mdapi commands were removed from Salesforce CLI in version 2.65.8 (November 2024).