Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Enable Dev Hub Features in Your Org
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Sandboxes
Development
Develop Against Any Org
Assign a Permission Set
Ways to Add Data to Your Org
Create Lightning Apps and Aura Components
Create Lightning Web 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
Second-Generation Managed Packages
Unlocked Packages
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

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.

You can use Salesforce CLI to retrieve and deploy metadata to non-source-tracked orgs with the same 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.

Using force:source:retrieve, you can retrieve the metadata you need in source format to your local file system (DX project). When your changes are ready for testing or production, 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 that includes a manifest (package.xml). Run force:project:create -n MyProject --manifest.
  • 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 a sandbox or your production org. 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 one of 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.
  • Specify a comma-separated list of package names.

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"
All the metadata related to a specific package or packages sfdx force:source:retrieve -n DreamHouse

You can specify only one scoping parameter when retrieving metadata: --metadata, --sourcepath, or --manifest. If you indicate --packagenames, you can include one additional scoping parameter.

1sfdx force:source:retrieve -n DreamHouse, -x manifest/package.xml

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 or production org.

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"
A recently validated set of components without running Apex tests (often referred to as a quick deploy) sfdx force:source:deploy -q VALIDATEDDEPLOYREQUESTID

You can run this option after you have run tests, passed code coverage requirements, and performed a check-only deployment using the -c | --checkonly option.
Even if the deployment contains warnings sfdx force:source:deploy -g
Regardless of whether the deployment contains errors (not recommended if deploying to a production org) sfdx force:source:deploy -o

Delete Non-Tracked Source

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

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

If the source exists locally in a DX project, you can delete metadata by specifying the path to the source or by listing individual metadata components. 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:

1SFDX_MDAPI_TEMP_DIR=/users/myName/myDXProject/metadata