Salesforce CLI Command Reference

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
Salesforce CLI Command Reference
Release Notes
sf
Salesforce Functions (Retired)
sfdx (Deprecated)
Migrate sfdx-Style Commands to Their sf-Style Equivalents
force:source:* and force:mdapi:* Commands Migration
force:org:* Commands Migration
force:data:bulk:* Commands Migration
Configuration and Environment Variable Names Migration
Source Tracking in New sf-Style Commands
Mapping sfdx Commands to Their sf Equivalents
Mapping sf Commands to Their sfdx Equivalents
CLI Deprecation Policy
Discover Salesforce Plugins
PDF

force:source:* and force:mdapi:* Commands Migration

Migrating the force:source:* and force:mdapi:* commands is straightforward in most cases, although some scenarios require some rework.

If you’re still using version 7 of the sfdx executable of Salesforce CLI (also referred to as sfdx (v7)), move to version 2 of the sf executable (sf (v2)). See Move from sfdx (v7) to sf (v2) for details.

Note

We introduced two sf-style commands, project deploy start and project retrieve start, to replace these six deprecated force commands.

  • force:source:push
  • force:source:pull
  • force:source:deploy
  • force:source:retrieve
  • force:mdapi:deploy
  • force:mdapi:retrieve

It was often confusing to determine which force command to use because they all have similar functionality. For example, both force:source:push and force:source:deploy move source format files from your project to the org. Now it’s simple: use project deploy start to deploy metadata to your org and project retrieve start to retrieve metadata from your org.

By default, both new commands work with files in source format. If you want to deploy or retrieve in metadata format, use the --metadata-dir or --target-metadata-dir flags, respectively.

The project deploy|retrieve start commands support source tracking. However, because these two commands encapsulate the functionality of the six force commands, source tracking works a bit differently. For more information, see Source Tracking in New sf-Style Commands.

The table summarizes the mapping between the force:source:* and force:mdapi:* commands to their new sf-style equivalents. The usage notes indicate if the mapping is a simple one-to-one. If it is, you migrate them by replacing their command and flag names in your scripts. Some command migrations require changes beyond simple name replacements, or the functionality has changed, as described in the usage notes. For more guidance, see the examples after the table.

For all command migrations, refer to the reference pages for each force command in the Salesforce CLI Command Reference for details.

force:source|mdapi:* Command Equivalent sf-Style Command Usage Notes
force:mdapi:convert project convert mdapi One-to-one mapping
force:mdapi:deploy project deploy start The project deploy start command works with source and metadata format files. The default is source format. To deploy metadata format files, use the --metadata-dir flag.
force:mdapi:deploy:cancel project deploy cancel One-to-one mapping
force:mdapi:deploy:report project deploy report or project deploy resume The force:mdapi:deploy:report command does more than just report, it also resumes a deployment. We now provide two new commands for each task, which is more intuitive.

The project deploy resume command doesn’t include the --wait -1 flag, which means “wait forever.”Instead, specify a large number with the new commands to ensure enough time to complete the deployment.
force:mdapi:describemetadata org list metadata-types One-to-one mapping.

The new command is in the org topic.
force:mdapi:listmetadata org list metadata One-to-one mapping.

The new command is in the org topic.
force:mdapi:retrieve project retrieve start The project retrieve start command works with source and metadata format files. The default is source format. To retrieve metadata format files, use the --target-metadata-dir flag.
force:mdapi:retrieve:report No equivalent. We removed this command and provide no new equivalent because it’s not needed.
force:source:convert project convert source One-to-one mapping
force:source:delete project delete source One-to-one mapping
force:source:deploy project deploy start When deploying in source format, the project deploy start command always tracks your source if the org is enabled for source tracking. So there’s no new equivalent for the force:source --tracksource flag. If you don’t want to use source tracking, you have two options:

Instead of force:source:deploy --validateddeployrequestid, use the new project deploy validate and project deploy quick --job-id commands.
force:source:deploy:cancel project deploy cancel One-to-one mapping
force:source:deploy:report project deploy report or project deploy resume The force:source:deploy:report command does more than just report, it also resumes a deployment. We now provide two new commands for each task, which is more intuitive.
force:source:ignored:list project list ignored One-to-one mapping
force:source:manifest:create project generate manifest One-to-one mapping
force:source:open org open --source-file The force:source:open command is now the --source-file flag of the org open command. Also, you can now specify a browser with the --browser flag.
force:source:pull project retrieve start The new project retrieve start command has additional flags that you can use to fine-tune the retrieve.
force:source:push project deploy start The project deploy start command doesn’t support the pushPackageDirectoriesSequentially property of sfdx-project.json. The force:source:push command uses this property to deploy packages sequentially. If you must deploy packages sequentially, and in a specific order, use separate project deploy start commands in the desired order.

The new project deploy start command has additional flags that you can use to fine-tune the deploy.
force:source:retrieve project retrieve start When retrieving in source format, the project retrieve start command always tracks your source if the org is enabled for source tracking. So there’s no new equivalent for the force:source --tracksource flag. If you don’t want to use source tracking, you have two options:
force:source:status project deploy preview or project retrieve preview We now provide two separate commands to preview a deploy or a retrieve, which is more intuitive. These preview commands have flags that align with their non-preview commands, such as project deploy start. The force:source:status command shows local and remote changes.
force:source:tracking:clear project delete tracking One-to-one mapping
force:source:tracking:reset project reset tracking One-to-one mapping

A few examples can help you get started with these new commands.

To differentiate the examples, we preface sfdx-style commands with sfdx and sf-style commands with sf. However, you can indicate either sf or sfdx when running any CLI command.

Note

force:source Examples

This force command converts source-formatted files into metadata format.

sfdx force:source:convert --rootdir path/to/source --outputdir path/to/outputdir --packagename "My Package"

Here’s the sf-style equivalent.

sf project convert source --root-dir path/to/source --output-dir path/to/outputdir --package-name 'My Package'

This force command deploys multiple metadata types.

sfdx force:source:deploy --metadata "ApexClass,CustomObject" --testlevel RunSpecifiedTests --runtests MyTests --targetusername my-scratch

Here’s the sf-style equivalent in which the --metadata flag is specified multiple times.

sf project deploy start --metadata ApexClass --metadata CustomObject --test-level RunSpecifiedTests --tests MyTests --target-org my-scratch

This force command pushes (deploys) all the changes in your project to an org.

sfdx force:source:push --targetusername myscratch --forceoverwrite --wait 10

Here’s the sf-style equivalent.

sf project deploy start --target-org myscratch --ignore-conflicts --wait 10

This force command retrieves the source in the specified directories.

sfdx force:source:retrieve --sourcepath "path/to/objects/MyCustomObject/fields/MyField.field-meta.xml, path/to/apex/classes"

Here’s the sf-style equivalent in which the --source-dir flag is specified multiple times.

sf project retrieve start --source-dir path/to/objects/MyCustomObject/fields/MyField.field-meta.xml --source-dir path/to/apex/classes

This force command opens a metadata file in Lightning App Builder.

sfdx force:source:open --source-file force-app/main/default/flexipages/Hello.flexipage-meta.xml --urlonly --targetusername myscratch

Here’s the sf-style equivalent that uses the org open command.

sf org open --source-path force-app/main/default/flexipages/Hello.flexipage-meta.xml --url-only --target-org myscratch

This force command pulls (retrieves) all the changes in your org to your project.

sfdx force:source:pull --targetusername myscratch --forceoverwrite --wait 10

Here’s the sf-style equivalent.

sf project retrieve start --target-org myscratch --ignore-conflicts --wait 10

This force command shows how your local project differs from the org.

sfdx force:source:status --targetusername myscratch --local

Here’s the sf-style equivalent; the command requires that you specify what you want preview, in this case, with the --manifest flag.

sf project deploy preview --target-org myscratch --manifest package.xml

force:mdapi Examples

This force command deploys metadata format files in the specified directory.

sfdx force:mdapi:deploy --deploydir some/path --wait 1000 --checkonly --testlevel RunAllTestsInOrg --targetusername my-test-org

There are two sf-style equivalents.

sf project deploy start --dry-run --metadata-dir some/path --wait 1000 --test-level RunAllTestsInOrg --target-org my-test-org
sf project deploy validate --metadata-dir some/path --wait 1000 --test-level RunAllTestsInOrg --target-org my-test-org

This force command deploys a .zip file that contains metadata files.

sfdx force:mdapi:deploy sfdx force:mdapi:deploy --zipfile stuff.zip --resultsdir --junit

Here’s the sf-style equivalent.

sf project deploy start --metadata-dir stuff.zip --results-dir --junit

This force command retrieves metadata defined in a manifest file into the target directory.

sfdx force:mdapi:retrieve --retrievetargetdir path/to/retrieve/dir --unpackaged package.xml

Here’s the sf-style equivalent.

sf project retrieve start --target-metadata-dir path/to/retrieve/dir --manifest package.xml

Overview of New Commands and Functionality

In addition to the new project deploy start and project retrieve start, we introduced other commands and flags that improve the Salesforce CLI’s usability.

  • Preview a deployment to your org with the project deploy preview command.

    The command outputs a table that shows what happens when you run the project deploy start command. The table displays a preview of the metadata components that are deployed and deleted, and the current conflicts between your project and org. The table also lists the files that aren’t deployed because they’re included in your .forceignore file.

  • Similarly, preview a retrieve from your org with the project retrieve preview command.
  • Validate a deployment, and then quickly deploy it later, with the project deploy validate and project deploy quick command pair.

    Use project deploy validate to verify whether a deployment can succeed without actually deploying the metadata to your org. This command is similar to project deploy start, except that you’re required to run Apex tests, and the command returns a job ID rather than actually executing the deployment. If the validation succeeds, then you pass this job ID to the project deploy quick command to actually deploy the metadata. This type of deploy takes less time because it skips running Apex tests.

    You can also use the --dry-run flag of project deploy start to get a preview of a deploy. Use this preview method if you don’t plan to later do a quick deploy. This way of previewing provides more flexibility because you can use all the flags of the project deploy start command, such as making destructive changes with the --pre|post-destructive-changes flags. The project deploy validate provides just a subset of the full deployment flags.

  • These new deploy commands that take a job ID now also have the handy --use-most-recent flag to automatically use the job ID of the most recent deploy operation.
    • project deploy cancel
    • project deploy quick
    • project deploy report
    • project deploy resume
  • These new deploy commands have the --async flag to run the command asynchronously.
    • project deploy cancel
    • project deploy quick
    • project deploy resume
    • project deploy validate
  • Delete source from a non-source-tracked org with the project delete source command.