Salesforce CLI Setup Guide

Release Notes
Before You Begin
Install Salesforce CLI
Install the CLI Release Candidate
Run Salesforce CLI Using a Docker Image
Update Salesforce CLI
Salesforce CLI Plug-ins
Salesforce CLI Configuration and Tips
Autocomplete CLI Commands, Parameters, and File Names
Use the Salesforce CLI from Behind a Company Firewall or Web Proxy
Windows Performance Suggestions
CLI Runtime Configuration Values
Environment Variables
How API Version and Source API Version Work in Salesforce CLI
CLI Parameter Resolution Order
Support for JSON Responses
Log Messages and Log Levels
Disable CLI Data Collection and Metrics
Uninstall Salesforce CLI or Plugins
Troubleshoot Salesforce CLI
CLI Deprecation Policy
Next Steps
Get Started with Salesforce CLI Unification
PDF

Newer Version Available

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

How API Version and Source API Version Work in Salesforce CLI

Salesforce CLI uses both the API version and source API version when deploying or retrieving metadata to or from an org. While they sound the same, and are often set to the same value, the two settings work differently.

For simplicity, let’s use the terms apiVersion and sourceApiVersion in this topic, and first define what each means.

apiVersion
The apiVersion value determines the shape of the HTTPS request or response.

Digging a little deeper, apiVersion refers to the core Metadata API version used to service an HTTPS request or response. When deploying metadata source to an org, Salesforce CLI sets the apiVersion value on the Connection object and uses the URL of the HTTPS request with either the SOAP or REST API. Because there’s currently no REST API for metadata retrievals, Salesforce CLI uses the apiVersion value set on the Connection object to create the URL for a SOAP endpoint.

sourceApiVersion
The sourceApiVersion value determines the shape of the metadata in the HTTPS request or response.

Salesforce CLI uses the sourceApiVersion value when setting the <version> element in the manifest file (package.xml). The package.xml file is included in the HTTPS request or response when deploying or retrieving, respectively.

These examples show how the two settings work together:
  • Retrieve: Let’s say that a new field was added to a metadata type in the Summer ‘22 release, which is API version 55.0. If you set sourceApiVersion to 54.0, and then execute the force:source:retrieve command, the retrieved metadata doesn’t include this new field. However, the same retrieve with sourceApiVersion set to 55.0 does return the metadata with the new field.
  • Deploy: Again assume that a new field was added to a metadata type in API version 55.0. If you set sourceApiVersion to 54.0 and try to deploy a local metadata file that includes this new field, the deploy fails. To successfully deploy metadata with the new field, you must set sourceApiVersion to 55.0 or greater.

Precedence of Salesforce CLI Settings

There are multiple ways to set apiVersion and sourceApiVersion, and multiple ways Salesforce CLI determines their values if you haven’t explicitly set them. Use the following prioritized lists to determine the value of the two settings in your environment. Settings higher on the list take precedence over lower ones. See the examples after this section to understand how this precedence affects metadata deploys and retrieves.

apiVersion: Order of Precedence
  1. --apiversion command flag.
  2. SFDX_API_VERSION environment variable.
  3. apiVersion local configuration variable.
  4. apiVersion global configuration variable.
  5. Highest API version supported by the target org.
sourceApiVersion: Order of Precedence
  1. <version> element in the manifest file ( package.xml).
  2. sourceApiVersion property in the sfdx-project.json file.
  3. --apiversion command flag.
  4. SFDX_API_VERSION environment variable.
  5. apiVersion local configuration variable.
  6. apiVersion global configuration variable.
  7. Highest API version supported by the target org.

Deploy Examples That Show Settings Precedence

These examples set up various use cases, and then show the result after you deploy. While the examples use force:source:deploy, the same applies to force:source:push and force:mdapi:deploy.

Settings: The apiVersion is set to 55.0 using the local configuration variable (sfdx config:set apiVersion=55.0). The sourceApiVersion is set to 54.0 in the sfdx-project.json file.
Command: sfdx force:source:deploy --sourcepath force-app

Result: Salesforce CLI sends the deploy request to an API version 55.0 endpoint. The <version> element in the manifest that’s sent with the request has a value of 54.0, which means the metadata source being deployed is in API version 54.0 shape.

Settings: The apiVersion is set to 55.0 using the local configuration variable. The sourceApiVersion is set to 54.0 in the sfdx-project.json file.
Command: sfdx force:source:deploy --sourcepath force-app --apiversion=56.0

Result: Salesforce CLI sends the deploy request to an API version 56.0 endpoint. The <version> element in the manifest that’s sent with the request has a value of 54.0, which means the metadata source being deployed is in API version 54.0 shape.

Settings: The apiVersion is set to 55.0 using the local configuration variable. The SFDX_API_VERSION environment variable is set to 56.0. The sourceApiVersion isn’t defined in sfdx-project.json.
Command: sfdx force:source:deploy --sourcepath force-app

Result: Salesforce CLI sends the deploy request to an API version 56.0 endpoint. The <version> element in the manifest that’s sent with the request has a value of 56.0, which means the metadata source being deployed is in API version 56.0 shape.

Settings: The apiVersion is set to 55.0 using the local configuration variable. The sourceApiVersion is set to 54.0 in the sfdx-project.json file. The <version> element in the manifest file is set to 53.0.
Command: sfdx force:source:deploy --manifest ./package.xml

Result: Salesforce CLI sends the deploy request to an API version 55.0 endpoint. The <version> element in the manifest that’s sent with the request has a value of 53.0, which means the metadata source being deployed is in API version 53.0 shape.

Settings: None. The maximum API version supported by the org is 56.0
Command: sfdx force:source:deploy --sourcepath force-app

Result: Salesforce CLI sends the deploy request to an API version 56.0 endpoint. The <version> element in the manifest that’s sent with the request has a value of 56.0, which means the metadata source being deployed is in API version 56.0 shape.

Retrieve Examples That Show Settings Precedence

These examples set up various use cases, and then show the result after you retrieve. While the examples use force:source:retrieve, the same applies to force:source:pull and force:mdapi:retrieve.

Settings: The apiVersion is set to 55.0 using the local configuration variable (sfdx config:set apiVersion=55.0). The sourceApiVersion is set to 54.0 in the sfdx-project.json file.
Command: sfdx force:source:retrieve --sourcepath force-app

Result: Salesforce CLI sends the retrieve request to an API version 55.0 SOAP endpoint. The <version> element in the manifest that’s sent with the request has a value of 54.0, which means the metadata source being retrieved is in API version 54.0 shape.

Settings: The apiVersion is set to 55.0 using the local configuration variable (sfdx config:set apiVersion=55.0). The sourceApiVersion is set to 54.0 in the sfdx-project.json file.
Command: sfdx force:source:retrieve --sourcepath force-app --apiversion 56.0

Result: Salesforce CLI sends the retrieve request to an API version 56.0 SOAP endpoint. The <version> element in the manifest that’s sent with the request has a value of 54.0, which means the metadata source being retrieved is in API version 54.0 shape.

Settings: The apiVersion is set to 55.0 using the local configuration variable. The SFDX_API_VERSION environment variable is set to 56.0. The sourceApiVersion isn’t defined in sfdx-project.json.
Command: sfdx force:source:retrieve --sourcepath force-app

Result: Salesforce CLI sends the retrieve request to an API version 56.0 SOAP endpoint. The <version> element in the manifest that’s sent with the request has a value of 56.0, which means the metadata source being retrieved is in API version 56.0 shape.

Settings: The apiVersion is set to 55.0 using the local configuration variable. The sourceApiVersion is set to 54.0 in the sfdx-project.json file. The <version> element in the manifest file is set to 53.0.
Command: sfdx force:source:retrieve --manifest ./package.xml

Result: Salesforce CLI sends the retrieve request to an API version 55.0 SOAP endpoint. The <version> element in the manifest that’s sent with the request has a value of 53.0, which means the metadata source being retrieved is in API version 53.0 shape.

Settings: None. The maximum API version supported by the org is 56.0
Command: sfdx force:source:retrieve --sourcepath force-app

Result: Salesforce CLI sends the retrieve request to an API version 56.0 SOAP endpoint. The <version> element in the manifest that’s sent with the request has a value of 56.0, which means the metadata source being retrieved is in API version 56.0 shape.