Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Development
Develop Against Any Org (Beta)
Create a Lightning App and Components
Create an Apex Class
Create an Apex Trigger
Testing
View Apex Debug Logs
Apex Debugger
Build and Release Your App
First-Generation Managed Packages
Unlocked Packages (Generally Available) and Second-Generation Managed Packages (Beta)
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Develop Against Any Org (Beta)

Regardless of the development model you're using, you eventually test and validate your changes in a non-source-tracked org. For those of you who don’t use scratch orgs, we provide a similar experience for developing and unit testing in other environments, such as sandboxes.

As a beta feature, the Salesforce CLI non-source-tracked org commands are a preview and aren’t part of the “Services” under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature. You can provide feedback and suggestions for this feature in the Salesforce DX group in the Trailblazer Community.

Note

Imagine if you could use the Salesforce CLI to retrieve and deploy metadata to non-source-tracked orgs with the ease of pushing and pulling source to and from scratch orgs. And best of all, no extra conversion steps are required! After you retrieve the metadata, you don't have to convert it to source format. When you're ready to deploy it back to the org, you don't have to convert it to metadata format. If you’re new to Salesforce CLI, Salesforce DX Project Structure and Source File Format explains the difference between source format and metadata format.

The force:source:deploy, force:source:retrieve, and force:source:delete commands work on sandboxes, Developer Edition orgs, and trial orgs, but not production orgs. For production orgs, continue to use force:mdapi:deploy and force:mdapi:retrieve.

Note

Using force:source:retrieve, you can retrieve the metadata you need in source format to your local file system (DX project). Once you're ready to test, you can use force:source:deploy to deploy your local files directly to a non-source-tracked org.

So, how do these source commands differ from the scratch org commands, source:push and source:pull? Because the changes aren't tracked, you retrieve or deploy all the specified metadata instead of only what's changed. The source you retrieve or deploy overwrites what’s you have locally or in your org, respectively.

Not sure what metadata types are supported or which metadata types support wild cards in package.xml? See Metadata Types in the Metadata API Developer Guide.

Before You Begin

Before you begin, don't forget to:
  • Create a Salesforce DX project.
  • Authorize your non-source-tracked org. If connecting to a sandbox, edit your sfdx-project.json file to set sfdcLoginUrl to https://test.salesforce.com before you authorize the org. Don't forget to create aliases for your non-source-tracked orgs.

Metadata Names That Require Encoding on the Command Line

When retrieving or deploying metadata using the --metadata option, commas in metadata names require encoding to work properly.

Don’t: sfdx force:source:deploy -m "Profile:Standard User,Layout:Page,Console"

Do: sfdx force:source:deploy -m "Profile:Standard User,Layout:Page%2CConsole"

Retrieve Source from a Non-Source-Tracked Org

Use the force:source:retrieve command to retrieve source from orgs that don’t have source tracking, such as sandboxes. If you already have the source code and metadata in a VCS, you might be able to skip this step. If you're starting anew, you retrieve the metadata associated with the feature, project, or customization you're working on.

The source:retrieve command works differently from source:pull for scratch orgs. This command doesn’t notify you if there’s a conflict. Instead, the source you retrieve overwrites the corresponding source files in your local project. To retrieve metadata that’s in the metadata format, use force:mdapi:retrieve.

Note

You can retrieve metadata in source format using these methods:
  • Specify a package.xml that lists the components to retrieve.
  • Specify a comma-separated list of metadata component names.
  • Specify a comma-separated list of source file paths to retrieve. You can use the source path option when source exists locally, for example, after you've done an initial retrieve.

If the comma-separated list you’re supplying contains spaces, enclose the entire comma-separated list in one set of double quotes.

To Retrieve: Command Example
All metadata components listed in a manifest sfdx force:source:retrieve -x path/to/package.xml
Source files in a directory sfdx force:source:retrieve -p path/to/source
A specific Apex class and the objects whose source is in a directory sfdx force:source:retrieve -p path/to/apex/classes/MyClass.cls,path/to/source/objects
Source files in a comma-separated list that contains spaces sfdx force:source:retrieve -p "path/to/objects/MyCustomObject/fields/MyField.field-meta.xml, path/to/apex/classes"
All Apex classes sfdx force:source:retrieve -m ApexClass
A specific Apex class sfdx force:source:retrieve -m ApexClass:MyApexClass
A layout name that contains a comma (Layout: Page, Console) sfdx force:source:retrieve -m "Layout:Page%2C Console"

Deploy Source to a Non-Source-Tracked Org

Use the force:source:deploy command to deploy source to orgs that don’t have source tracking, such as a sandbox.

The source:deploy command works differently from source:push for scratch orgs. The source you deploy overwrites the corresponding metadata in your org, similar to running source:push with the --force option. To deploy metadata that’s in the metadata format, use force:mdapi:deploy.

Note

You can deploy metadata in source format using these methods:

  • Specify a package.xml that lists the components to deploy
  • Specify a comma-separated list of metadata component names
  • Specify a comma-separated list of source file paths to deploy

If the comma-separated list you’re supplying contains spaces, enclose the entire comma-separated list in one set of double quotes.

To Deploy: Command Example
All components listed in a manifest sfdx force:source:deploy -x path/to/package.xml
Source files in a directory sfdx force:source:deploy -p path/to/source
A specific Apex class and the objects whose source is in a directory sfdx force:source:deploy -p path/to/apex/classes/MyClass.cls,path/to/source/objects
Source files in a comma-separated list that contains spaces sfdx force:source:deploy -p "path/to/objects/MyCustomObject/fields/MyField.field-meta.xml, path/to/apex/classes"
All Apex classes sfdx force:source:deploy -m ApexClass
A specific Apex class sfdx force:source:deploy -m ApexClass:MyApexClass
All custom objects and Apex classes sfdx force:source:deploy -m CustomObject,ApexClass
All Apex classes and a profile that has a space in its name sfdx force:source:deploy -m "ApexClass, Profile:Content Experience Profile"

Delete Non-Tracked Source

Use the force:source:delete command to delete components from orgs that don’t have source tracking, such as a sandbox.

Run this command from within a Salesforce DX project. To remove deleted items from scratch orgs, which have change tracking, use force:source:push.

Note

You can delete metadata in source format by specifying the path to the source or by listing individual metadata components, once the source exists locally in a Salesforce DX project. If the comma-separated list you’re supplying contains spaces, enclose the entire comma-separated list in one set of double quotes.

To Delete: Command Example
Source files in a directory sfdx force:source:delete -p path/to/source
A specific component, such as a FlexiPage sfdx force:source:delete -m FlexiPage:Broker_Record_Page

Do You Want to Retain the Generated Metadata?

Normally, when you run some CLI commands, a temporary directory with all the metadata is created then deleted upon successful completion of the command. However, retaining these files can be useful for several reasons. You can debug problems that occur during command execution. You can use the generated package.xml when running subsequent commands, or as a starting point for creating a manifest that includes all the metadata you care about.

To retain all the metadata in a specified directory path when you run these commands, set the SFDX_MDAPI_TEMP_DIR environment variable:

  • force:source:deploy
  • force:source:retrieve
  • force:source:delete
  • force:source:push
  • force:source:pull
  • force:source:convert
  • force:org:create (if your scratch org definition contains scratch org settings, not org preferences)

Example: