Migrate sfdx-Style Commands to Their sf-Style Equivalents

Where is the Reference for sfdx-Style Commands?

We removed the reference information about sfdx-style commands from this guide on June 12, 2024. If you need the information, see the Spring ‘24 Salesforce CLI Command Reference.

Overview of Command and Usage Differences

The deprecated sfdx commands are different from the sf ones in these key ways. Other sections in this migration guide go into details.

• Some commands and flags have new names, but their behavior and JSON output is the same as their sfdx equivalents. To migrate, rename your existing commands and flags. For example, let’s say you have this command.
  force:apex:execute --targetusername <org> –--apexcodefile <file>

  Here’s its sf-style equivalent.

  apex run --target-org <org> --file <file>

• For other sfdx-style commands, we created sf commands that likely behave differently, so migrating to them requires a bit more effort. The inputs and JSON output for these new commands are also likely different from their sfdx equivalents. For example, force:org:create is now two commands: org create scratch and org create sandbox.

  In these cases the sfdx command is still available for backward compatibility.

• Configuration and environment variables have new names. For example, targetusername is now target-org, and SFDX_DEFAULTUSERNAME is now SF_TARGET_ORG.
• We no longer use the force topic, except for a handful of commands that we kept for backward compatibility.

Read these usage differences between the sfdx-style and sf-style commands, and apply them when necessary.

• When flags for new sf commands take multiple values, you specify the flag multiple times, with each flag taking a different single value. For example:
  sf project deploy start --metadata ApexClass:SampleDataController --metadata ApexClass:PropertyController

  Previously, with the deprecated sfdx-style commands, you specified the flag one time and separated the values with commas. For example:

  sfdx force:source:deploy --metadata ApexClass:SampleDataController,ApexClass:PropertyController

  You can continue using this comma-separated style with existing commands before you migrate. But when you migrate to the sf commands, make sure that you use this new style because new and future commands don’t support the comma-separated style. An example is specifying multiple Apex test classes and code coverage formats to the project deploy start command. If you continue using commas, the command doesn’t return an error, but the Apex tests probably didn’t all run.

  For example, use this syntax.

  sf project deploy start --metadata ApexClass --tests FirstTest --tests SecondTest --tests “Third Test” --coverage-formatters json --coverage-formatters html

  But don’t use this syntax.

  sf project deploy start --metadata ApexClass --tests FirstTest,SecondTest,“Third Test” --coverage-formatters json,html

• The sf commands accept either spaces or colons between topics, commands, and subcommands. For example, both of these command formats to get a configuration variable are valid.
  sf config get target-org
  sf config:get target-org

Run the dev convert script Command

Begin your migration by running the dev convert script command to update your CI scripts. The command replaces many of the sfdx commands and flags with their sf equivalents.

First, install the plugin-dev Salesforce CLI plugin, which contains the conversion command.

sfdx plugins install @salesforce/plugin-dev

Then pass your script file to the dev convert script command with the --script flag.

sfdx dev convert script --script ./myScript.yml

The command scans your script file, and each time it finds an sfdx command or flag, it prompts whether you want to replace it with the new sf equivalent. The command overwrites your original file.

While dev convert script can convert a large portion of your script, it likely can’t convert all of it because there’s not always a one-to-one mapping between the previous and new commands. In these cases, dev convert script doesn't replace the sfdx-style command but instead adds a comment that starts with #ERROR.

Migrate Scripts Manually

Because dev convert script typically can’t convert your entire script, you must migrate the remainder of the commands manually. You can update your entire script manually if you want.

The easiest way to find the sf-style equivalent of a sfdx command is to read the sfdx section of the Salesforce CLI Command Reference. Each deprecated sfdx command displays information about the new equivalent sf command and the new flag names.

You can also look at the deprecation warnings when you run an sfdx command. The warnings display the new sf-style equivalent command and flag names. To display help information about the new equivalent command along with examples, run the old command with the --help flag.

Most commands are a simple one-to-one mapping, including flag name changes. Let’s take auth:jwt:grant as an example. The reference tells you to use the new org login jwt command instead, and it lists how the flag names have changed. Here’s an example of the deprecated sfdx-style command.

sfdx auth:jwt:grant --username jdoe@example.org --jwtkeyfile /Users/jdoe/JWT/server.key --clientid 123456 --setdefaultdevhubusername

Here’s the sf-style equivalent.

sf org login jwt --username jdoe@example.org --jwt-key-file /Users/jdoe/JWT/server.key --client-id 123456 --set-default-dev-hub

The force:apex commands also have a one-to-one mapping to the new sf-style commands. Here’s an example of the force:apex:test:run command.

sfdx force:apex:test:run --suitenames "MySuite,MyOtherSuite" --codecoverage --detailedcoverage --targetusename my-scratch --outputdir tests/output"

Here’s the sf-style equivalent.

sf apex run test --suite-names "MySuite,MyOtherSuite" --code-coverage --detailed-coverage --target-org my-scratch --output-dir tests/output"

Some commands aren’t a direct one-to-one mapping, or their behavior changed, so migrating them requires more effort. For additional information about these commands, see these topics.

• force:source:* and force:mdapi:* Commands Migration
• force:org:* Commands Migration
• force:data:bulk:* Commands Migration

High-Level Overview of Common Flag Name Changes

This table provides an overview of common Salesforce CLI flag name changes.

For less common flags, the sf-style name is often similar to the sfdx-style one, but it has dashes to make it easier to read. We also standardized many of the flags across all topics and commands, such as using --output-dir consistently for the directory to write the results of a command. Here are a few more examples.

• project:create --outputdir is now project generate --output-dir.
• force:source:deploy --sourcepath is now project deploy start --source-dir.
• force:apex:class:create --classname is now apex generate class --name.
• force:package:create --errornotificationusername is now package create --error-notification-username.

As always, for command and flag name changes for a specific deprecated sfdx command, see its reference page in the Salesforce CLI Command Reference.