mdapi Commands

Help for force:mdapi:convert

Converts metadata retrieved via Metadata API into the source format used in Salesforce DX projects.

To use Salesforce CLI to work with components that you retrieved via Metadata API, first convert your files from the metadata format to the source format using "sfdx force:mdapi:convert".

To convert files from the source format back to the metadata format, so that you can deploy them using "sfdx force:mdapi:deploy", run "sfdx force:source:convert".

Examples for force:mdapi:convert

1sfdx force:mdapi:convert -r path/to/metadata

1sfdx force:mdapi:convert -r path/to/metadata -d path/to/outputdir

Command Syntax

sfdx force:mdapi:convert

[--json]

[--loglevel LOGLEVEL]

-r ROOTDIR

[-d OUTPUTDIR]

[-x MANIFEST]

[-p METADATAPATH]

[-m METADATA]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-r | --rootdir ROOTDIR

Required

The root directory that contains the metadata you retrieved using Metadata API.

Type: directory

-d | --outputdir OUTPUTDIR

Optional

The directory to store your files in after they’re converted to the source format. Can be an absolute or relative path.

Type: directory

-x | --manifest MANIFEST

Optional

The complete path to the manifest (package.xml) file that specifies the metadata types to convert.

If you specify this parameter, don’t specify --metadata or --sourcepath.

Type: string

-p | --metadatapath METADATAPATH

Optional

A comma-separated list of paths to the local metadata files to convert. The supplied paths can be to a single file (in which case the operation is applied to only one file) or to a folder (in which case the operation is applied to all metadata types in the directory and its sub-directories).

If you specify this parameter, don’t specify --manifest or --metadata. If the comma-separated list you’re supplying contains spaces, enclose the entire comma-separated list in one set of double quotes.

Type: array

-m | --metadata METADATA

Optional

A comma-separated list of metadata component names to convert.

Type: array

Aliases for force:mdapi:convert

1force:mdapi:beta:convert

Examples for force:mdapi:deploy

Return a job ID you can use to check the deploy status:

1sfdx force:mdapi:deploy -d some/path

Deploy and poll for 1000 minutes:

1sfdx force:mdapi:deploy -d some/path -w 1000

Deploy a ZIP file:

1sfdx force:mdapi:deploy -f stuff.zip

Validate a deployment so the ID can be used for a quick deploy:

1sfdx force:mdapi:deploy -d some/path -w 1000 -c --testlevel RunAllTestsInOrg

Quick deploy using a previously validated deployment:

1sfdx force:mdapi:deploy -q MyValidatedId

Command Syntax

sfdx force:mdapi:deploy

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[--apiversion APIVERSION]

[-c]

[-d DEPLOYDIR]

[-w WAIT]

[-l TESTLEVEL]

[-r RUNTESTS]

[-o]

[-g]

[-q VALIDATEDDEPLOYREQUESTID]

[--verbose]

[-f ZIPFILE]

[-s]

[--soapdeploy]

[--purgeondelete]

[--concise]

[--resultsdir RESULTSDIR]

[--coverageformatters COVERAGEFORMATTERS]

[--junit]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

--apiversion APIVERSION

Optional

Override the API version used for API requests made by this command.

Type: string

-c | --checkonly

Optional

IMPORTANT: Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Validates the deployed metadata and runs all Apex tests, but prevents the deployment from being saved to the org.

If you change a field type from Master-Detail to Lookup or vice versa, that change isn’t supported when using the --checkonly parameter to test a deployment (validation). This kind of change isn’t supported for test deployments to avoid the risk of data loss or corruption. If a change that isn’t supported for test deployments is included in a deployment package, the test deployment fails and issues an error.

If your deployment package changes a field type from Master-Detail to Lookup or vice versa, you can still validate the changes prior to deploying to Production by performing a full deployment to another test Sandbox. A full deployment includes a validation of the changes as part of the deployment process.

Note: A Metadata API deployment that includes Master-Detail relationships deletes all detail records in the Recycle Bin in the following cases.

1. For a deployment with a new Master-Detail field, soft delete (send to the Recycle Bin) all detail records before proceeding to deploy the Master-Detail field, or the deployment fails. During the deployment, detail records are permanently deleted from the Recycle Bin and cannot be recovered.

2. For a deployment that converts a Lookup field relationship to a Master-Detail relationship, detail records must reference a master record or be soft-deleted (sent to the Recycle Bin) for the deployment to succeed. However, a successful deployment permanently deletes any detail records in the Recycle Bin.

Type: boolean

-d | --deploydir DEPLOYDIR

Optional

The root of the directory tree that contains the files to deploy. The root must contain a valid package.xml file describing the entities in the directory structure. Required to initiate a deployment if you don’t use --zipfile. If you specify both --zipfile and --deploydir, a zip file of the contents of the --deploydir directory is written to the location specified by --zipfile.

Type: directory

-w | --wait WAIT

Optional

The number of minutes to wait for the command to complete. The default is 0 (returns immediately). 0

Type: minutes

Default value: 0 minutes

-l | --testlevel TESTLEVEL

Optional

Specifies which level of deployment tests to run. Valid values are:

NoTestRun—No tests are run. This test level applies only to deployments to development environments, such as sandbox, Developer Edition, or trial orgs. This test level is the default for development environments.

RunSpecifiedTests—Runs only the tests that you specify in the --runtests option. Code coverage requirements differ from the default coverage requirements when using this test level. Executed tests must comprise a minimum of 75% code coverage for each class and trigger in the deployment package. This coverage is computed for each class and trigger individually and is different than the overall coverage percentage.

RunLocalTests—All tests in your org are run, except the ones that originate from installed managed and unlocked packages. This test level is the default for production deployments that include Apex classes or triggers.

RunAllTestsInOrg—All tests in your org are run, including tests of managed packages.

If you don’t specify a test level, the default behavior depends on the contents of your deployment package. For more information, see “Running Tests in a Deployment” in the Metadata API Developer Guide.

Type: enum

Permissible values are: NoTestRun, RunSpecifiedTests, RunLocalTests, RunAllTestsInOrg

-r | --runtests RUNTESTS

Optional

Lists the Apex classes containing the deployment tests to run. Use this parameter when you set --testlevel to RunSpecifiedTests.

Type: array

-o | --ignoreerrors

Optional

Ignores the deploy errors, and continues with the deploy operation. The default is false. Keep this parameter set to false when deploying to a production org. If set to true, components without errors are deployed, and components with errors are skipped.

Type: boolean

-g | --ignorewarnings

Optional

If a warning occurs and ignoreWarnings is set to true, the success field in DeployMessage is true. When ignoreWarnings is set to false, success is set to false, and the warning is treated like an error.

This field is available in API version 18.0 and later. Prior to version 18.0, there was no distinction between warnings and errors. All problems were treated as errors and prevented a successful deployment.

Type: boolean

-q | --validateddeployrequestid VALIDATEDDEPLOYREQUESTID

Optional

Specifies the ID of a package with recently validated components to run a Quick Deploy. Deploying a validation helps you shorten your deployment time because tests aren’t rerun. If you have a recent successful validation, you can deploy the validated components without running tests. A validation doesn’t save any components in the org. You use a validation only to check the success or failure messages that you would receive with an actual deployment. To validate your components, add the -c | --checkonly flag when you run 'sfdx force:mdapi:deploy'. This flag sets the checkOnly='true' parameter for your deployment. Before deploying a recent validation, ensure that the following requirements are met:

1. The components have been validated successfully for the target environment within the last 10 days.

2. As part of the validation, Apex tests in the target org have passed.

3. Code coverage requirements are met.

- If all tests in the org or all local tests are run, overall code coverage is at least 75%, and Apex triggers have some coverage.

- If specific tests are run with the RunSpecifiedTests test level, each class and trigger that was deployed is covered by at least 75% individually.

Type: id

--verbose

Optional

Indicates that you want verbose output from the deploy operation.

Type: boolean

-f | --zipfile ZIPFILE

Optional

The path to the .zip file of metadata files to deploy. You must indicate this option or --deploydir.If you specify both --zipfile and --deploydir, a .zip file of the contents of the deploy directory is created at the path specified for the .zip file.

Type: filepath

-s | --singlepackage

Optional

Indicates that the specified .zip file points to a directory structure for a single package. By default, the CLI assumes the directory is structured for a set of packages.

Type: boolean

--soapdeploy

Optional

Deploy metadata with SOAP API instead of the default REST API. Because SOAP API has a lower .ZIP file size limit (400 MB uncompressed, 39 MB compressed), Salesforce recommends REST API deployment. This flag provides backwards compatibility with API version 50.0 and earlier when deploy used SOAP API by default.

Type: boolean

--purgeondelete

Optional

Specify that deleted components in the destructive changes manifest file are immediately eligible for deletion rather than being stored in the Recycle Bin.

Type: boolean

--concise

Optional

Emit brief command output to stdout.

Type: boolean

--resultsdir RESULTSDIR

Optional

Output directory for code coverage and JUnit results; defaults to the deploy ID.

Type: directory

--coverageformatters COVERAGEFORMATTERS

Optional

Format of the code coverage results.

Type: array

--junit

Optional

Output JUnit test results.

Type: boolean

Aliases for force:mdapi:deploy

1force:mdapi:beta:deploy

Help for force:mdapi:deploy:cancel

Use this command to cancel a specified asynchronous metadata deployment. You can also specify a wait time (in minutes) to check for updates to the canceled deploy status.

Examples for force:mdapi:deploy:cancel

Deploy a directory of files to the org

1sfdx force:mdapi:deploy -d <directory>

Now cancel this deployment and wait two minutes

1sfdx force:mdapi:deploy:cancel -w 2

If you have multiple deployments in progress and want to cancel a specific one, specify the job ID

1sfdx force:mdapi:deploy:cancel -i <jobid>

Check the status of the cancel job

1sfdx force:mdapi:deploy:report

Command Syntax

sfdx force:mdapi:deploy:cancel

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[--apiversion APIVERSION]

[-w WAIT]

[-i JOBID]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

--apiversion APIVERSION

Optional

Override the API version used for API requests made by this command.

Type: string

-w | --wait WAIT

Optional

Number of minutes to wait for the command to complete and display results to the terminal window. If the command continues to run after the wait period, the CLI returns control of the terminal window to you. The default is 33 minutes.

Type: minutes

Default value: 33 minutes

-i | --jobid JOBID

Optional

Job ID of the deployment you want to cancel; defaults to your most recent CLI deployment if not specified.

Type: id

Examples for force:mdapi:deploy:report

Check the status of the most recent deployment

1sfdx force:mdapi:deploy:report

Check the status of a deploy with job ID 1234 and wait for 10 minutes for the result:

1sfdx force:mdapi:deploy:report -i 1234 -w 10

Command Syntax

sfdx force:mdapi:deploy:report

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[--apiversion APIVERSION]

[-w WAIT]

[-i JOBID]

[--verbose]

[--concise]

[--resultsdir RESULTSDIR]

[--coverageformatters COVERAGEFORMATTERS]

[--junit]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

--apiversion APIVERSION

Optional

Override the API version used for API requests made by this command.

Type: string

-w | --wait WAIT

Optional

The number of minutes to wait for the command to complete. The default is –1 (no limit).

Type: minutes

Default value: 0 minutes

-i | --jobid JOBID

Optional

The job ID (id field value for AsyncResult) of the deployment you want to check. The job ID is required if you haven’t previously deployed using Salesforce CLI. If you deploy using Salesforce CLI and don’t specify a job ID, we use the ID of the most recent metadata deployment.

Type: id

--verbose

Optional

Indicates that you want verbose output for deploy results.

Type: boolean

--concise

Optional

Emit brief command output to stdout.

Type: boolean

--resultsdir RESULTSDIR

Optional

Output directory for code coverage and JUnit results; defaults to the deploy ID.

Type: directory

--coverageformatters COVERAGEFORMATTERS

Optional

Format of the code coverage results.

Type: array

--junit

Optional

Output JUnit test results.

Type: boolean

Aliases for force:mdapi:deploy:report

1force:mdapi:beta:deploy:report

Help for force:mdapi:describemetadata

Use this information to identify the syntax needed for a <name> element in package.xml. The most recent API version is the default, or you can specify an older version.

The default target username is the admin user for the default scratch org. The username must have the Modify All Data permission or the Modify Metadata permission (Beta). For more information about permissions, see Salesforce Help.

Examples for force:mdapi:describemetadata

1sfdx force:mdapi:describemetadata -a 43.0

1sfdx force:mdapi:describemetadata -u me@example.com

1sfdx force:mdapi:describemetadata -f /path/to/outputfilename.txt

1sfdx force:mdapi:describemetadata -u me@example.com -f /path/to/outputfilename.txt

Command Syntax

sfdx force:mdapi:describemetadata

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[-a APIVERSION]

[-f RESULTFILE]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

-a | --apiversion APIVERSION

Optional

The API version to use. The default is the latest API version

Type: string

-f | --resultfile RESULTFILE

Optional

The path to the file where the results of the command are stored. Directing the output to a file makes it easier to extract relevant information for your package.xml manifest file. The default output destination is the console.

Type: filepath

Help for force:mdapi:legacy:convert

To use Salesforce CLI to work with components that you retrieved via Metadata API, first convert your files from the metadata format to the source format using "sfdx force:mdapi:legacy:convert".

To convert files from the source format back to the metadata format, so that you can deploy them using "sfdx force:mdapi:legacy:deploy", run "sfdx force:source:convert".

Examples:

1sfdx force:mdapi:legacy:convert -r path/to/metadata

1sfdx force:mdapi:legacy:convert -r path/to/metadata -d path/to/outputdir

Command Syntax

sfdx force:mdapi:legacy:convert

[--json]

[--loglevel LOGLEVEL]

-r ROOTDIR

[-d OUTPUTDIR]

[-x MANIFEST]

[-m METADATA]

[-p METADATAPATH]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-r | --rootdir ROOTDIR

Required

The root directory that contains the metadata you retrieved using Metadata API.

Type: directory

-d | --outputdir OUTPUTDIR

Optional

The directory to store your files in after they’re converted to the source format. Can be an absolute or relative path.

Type: directory

-x | --manifest MANIFEST

Optional

The complete path to the manifest (package.xml) file that specifies the metadata types to convert.

If you specify this parameter, don’t specify --metadata or --sourcepath.

Type: string

-m | --metadata METADATA

Optional

A comma-separated list of metadata component names to convert.

Type: array

-p | --metadatapath METADATAPATH

Optional

A comma-separated list of paths to the local source files to convert. The supplied paths can be to a single file (in which case the operation is applied to only one file) or to a folder (in which case the operation is applied to all metadata types in the directory and its sub-directories).

If you specify this parameter, don’t specify --manifest or --metadata.If the comma-separated list you’re supplying contains spaces, enclose the entire comma-separated list in one set of double quotes.

Type: array

Help for force:mdapi:legacy:deploy

IMPORTANT: Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Specify the location of the files to deploy as a .zip file or by the root of the directory tree containing the files. To check the status of a deployment, specify its job ID. To run quick deploy of a recently validated package, use --validateddeployrequestid with the validated ID.

To wait for the command to finish running no matter how long the deployment takes, set --wait to -1: "sfdx force mdapi:deploy -w -1 ...".

If you don’t specify --wait, the command returns immediately and the metadata deploys asynchronously. Run force:mdapi:legacy: deploy:report to check the status of the deploy.

Command Syntax

sfdx force:mdapi:legacy:deploy

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[--apiversion APIVERSION]

[-c]

[-d DEPLOYDIR]

[-w WAIT]

[-l TESTLEVEL]

[-r RUNTESTS]

[-o]

[-g]

[-q VALIDATEDDEPLOYREQUESTID]

[--verbose]

[-f ZIPFILE]

[-s]

[--soapdeploy]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

--apiversion APIVERSION

Optional

Override the API version used for API requests made by this command.

Type: string

-c | --checkonly

Optional

Validates the deployed metadata and runs all Apex tests, but prevents the deployment from being saved to the org.

If you change a field type from Master-Detail to Lookup or vice versa, that change isn’t supported when using the --checkonly parameter to test a deployment (validation). This kind of change isn’t supported for test deployments to avoid the risk of data loss or corruption. If a change that isn’t supported for test deployments is included in a deployment package, the test deployment fails and issues an error.

If your deployment package changes a field type from Master-Detail to Lookup or vice versa, you can still validate the changes prior to deploying to Production by performing a full deployment to another test Sandbox. A full deployment includes a validation of the changes as part of the deployment process.

Note: A Metadata API deployment that includes Master-Detail relationships deletes all detail records in the Recycle Bin in the following cases.

1. For a deployment with a new Master-Detail field, soft delete (send to the Recycle Bin) all detail records before proceeding to deploy the Master-Detail field, or the deployment fails. During the deployment, detail records are permanently deleted from the Recycle Bin and cannot be recovered.

2. For a deployment that converts a Lookup field relationship to a Master-Detail relationship, detail records must reference a master record or be soft-deleted (sent to the Recycle Bin) for the deployment to succeed. However, a successful deployment permanently deletes any detail records in the Recycle Bin.

Type: boolean

-d | --deploydir DEPLOYDIR

Optional

The root of the directory tree that contains the files to deploy. The root must contain a valid package.xml file describing the entities in the directory structure. Required to initiate a deployment if you don’t use --zipfile. If you specify both --zipfile and --deploydir, a zip file of the contents of the --deploydir directory is written to the location specified by --zipfile.

Type: directory

-w | --wait WAIT

Optional

The number of minutes to wait for the command to complete. The default is –1 (no limit). 0

Type: minutes

-l | --testlevel TESTLEVEL

Optional

Specifies which level of deployment tests to run. Valid values are:

NoTestRun—No tests are run. This test level applies only to deployments to development environments, such as sandbox, Developer Edition, or trial orgs. This test level is the default for development environments.

RunSpecifiedTests—Runs only the tests that you specify in the --runtests option. Code coverage requirements differ from the default coverage requirements when using this test level. Executed tests must comprise a minimum of 75% code coverage for each class and trigger in the deployment package. This coverage is computed for each class and trigger individually and is different than the overall coverage percentage.

RunLocalTests—All tests in your org are run, except the ones that originate from installed managed packages. This test level is the default for production deployments that include Apex classes or triggers.

RunAllTestsInOrg—All tests in your org are run, including tests of managed packages.

If you don’t specify a test level, the default behavior depends on the contents of your deployment package. For more information, see “Running Tests in a Deployment” in the Metadata API Developer Guide.

Type: enum

Permissible values are: NoTestRun, RunSpecifiedTests, RunLocalTests, RunAllTestsInOrg

-r | --runtests RUNTESTS

Optional

Lists the Apex classes containing the deployment tests to run. Use this parameter when you set --testlevel to RunSpecifiedTests.

Type: array

-o | --ignoreerrors

Optional

Ignores the deploy errors, and continues with the deploy operation. The default is false. Keep this parameter set to false when deploying to a production org. If set to true, components without errors are deployed, and components with errors are skipped.

Type: boolean

-g | --ignorewarnings

Optional

If a warning occurs and ignoreWarnings is set to true, the success field in DeployMessage is true. When ignoreWarnings is set to false, success is set to false, and the warning is treated like an error.

This field is available in API version 18.0 and later. Prior to version 18.0, there was no distinction between warnings and errors. All problems were treated as errors and prevented a successful deployment.

Type: boolean

-q | --validateddeployrequestid VALIDATEDDEPLOYREQUESTID

Optional

Specifies the ID of a package with recently validated components to run a Quick Deploy. Deploying a validation helps you shorten your deployment time because tests aren’t rerun. If you have a recent successful validation, you can deploy the validated components without running tests. A validation doesn’t save any components in the org. You use a validation only to check the success or failure messages that you would receive with an actual deployment. To validate your components, add the -c | --checkonly flag when you run "sfdx force:mdapi:legacy:deploy". This flag sets the checkOnly="true" parameter for your deployment. Before deploying a recent validation, ensure that the following requirements are met:

1. The components have been validated successfully for the target environment within the last 10 days.

2. As part of the validation, Apex tests in the target org have passed.

3. Code coverage requirements are met.

- If all tests in the org or all local tests are run, overall code coverage is at least 75%, and Apex triggers have some coverage.

- If specific tests are run with the RunSpecifiedTests test level, each class and trigger that was deployed is covered by at least 75% individually.

Type: id

--verbose

Optional

Indicates that you want verbose output from the deploy operation.

Type: boolean

-f | --zipfile ZIPFILE

Optional

The path to the .zip file of metadata files to deploy. You must indicate this option or --deploydir.If you specify both --zipfile and --deploydir, a .zip file of the contents of the deploy directory is created at the path specified for the .zip file.

Type: filepath

-s | --singlepackage

Optional

Indicates that the specified .zip file points to a directory structure for a single package. By default, the CLI assumes the directory is structured for a set of packages.

Type: boolean

--soapdeploy

Optional

Deploy metadata with SOAP API instead of the default REST API. Because SOAP API has a lower .ZIP file size limit (400 MB uncompressed, 39 MB compressed), Salesforce recommends REST API deployment. This flag provides backwards compatibility with API version 50.0 and earlier when deploy used SOAP API by default.

Type: boolean

Help for force:mdapi:legacy:deploy:report

Specify the job ID for the deploy you want to check. You can also specify a wait time (minutes) to check for updates to the deploy status.

Command Syntax

sfdx force:mdapi:legacy:deploy:report

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[--apiversion APIVERSION]

[-w WAIT]

[-i JOBID]

[--verbose]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

--apiversion APIVERSION

Optional

Override the API version used for API requests made by this command.

Type: string

-w | --wait WAIT

Optional

The number of minutes to wait for the command to complete. The default is –1 (no limit). 0

Type: minutes

-i | --jobid JOBID

Optional

The job ID (id field value for AsyncResult) of the deployment you want to check. The job ID is required if you haven’t previously deployed using Salesforce CLI. If you deploy using Salesforce CLI and don’t specify a job ID, we use the ID of the most recent metadata deployment.

Type: id

--verbose

Optional

Indicates that you want verbose output for deploy results.

Type: boolean

Help for force:mdapi:legacy:retrieve

The default target username is the admin user for the default scratch org. You can retrieve and deploy up to 10,000 files or 400 MB (39 MB compressed) at one time.

Command Syntax

sfdx force:mdapi:legacy:retrieve

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[-a APIVERSION]

[-w WAIT]

-r RETRIEVETARGETDIR

[-k UNPACKAGED]

[--verbose]

[-d SOURCEDIR]

[-p PACKAGENAMES]

[-s]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

-a | --apiversion APIVERSION

Optional

Use to override the default, which is the latest version supported by your CLI plug-in, with the version in your package.xml file.

Type: string

-w | --wait WAIT

Optional

The number of minutes to wait for the command to complete.

Type: minutes

-r | --retrievetargetdir RETRIEVETARGETDIR

Required

The root of the directory structure where the retrieved .zip or metadata files are put.

Type: directory

-k | --unpackaged UNPACKAGED

Optional

The complete path for the manifest file that specifies the components to retrieve.

Type: filepath

--verbose

Optional

Indicates that you want verbose output from the retrieve operation.

Type: boolean

-d | --sourcedir SOURCEDIR

Optional

The source directory to use instead of the default package directory specified in sfdx-project.json

Type: directory

-p | --packagenames PACKAGENAMES

Optional

A comma-separated list of package names to retrieve.

Type: array

-s | --singlepackage

Optional

Indicates that the specified .zip file points to a directory structure for a single package. By default, the CLI assumes the directory is structured for a set of packages.

Type: boolean

Help for force:mdapi:legacy:retrieve:report

Specify the job ID and a target directory for the retrieve you want to check. You can also specify a wait time (minutes) to check for updates to the deploy status. If the retrieve was successful, the resulting zip file will be saved to the location passed in with the retrieve target parameter.

Command Syntax

sfdx force:mdapi:legacy:retrieve:report

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[--apiversion APIVERSION]

[-w WAIT]

[-r RETRIEVETARGETDIR]

[--verbose]

[-i JOBID]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

--apiversion APIVERSION

Optional

Override the API version used for API requests made by this command.

Type: string

-w | --wait WAIT

Optional

The number of minutes to wait for the command to complete. -1

Type: minutes

-r | --retrievetargetdir RETRIEVETARGETDIR

Optional

The root of the directory structure where the retrieved .zip or metadata files are put.

Type: directory

--verbose

Optional

Indicates that you want verbose output from the retrieve operation.

Type: boolean

-i | --jobid JOBID

Optional

The job ID (asyncId) of the retrieve you want to check. If not specified, the default value is the ID of the most recent metadata retrieval you ran using Salesforce CLI. You must specify a --retrievetargetdir. Use with --wait to resume waiting.

Type: id

Help for force:mdapi:listmetadata

This command is useful when you want to identify individual components in your manifest file or if you want a high-level view of particular components in your organization. For example, you could use this target to return a list of names of all Layout components in your org, then use this information in a retrieve operation that returns a subset of these components.

Examples for force:mdapi:listmetadata

1sfdx force:mdapi:listmetadata -m CustomObject

1sfdx force:mdapi:listmetadata -m CustomObject -a 43.0

1sfdx force:mdapi:listmetadata -m CustomObject -u me@example.com

1sfdx force:mdapi:listmetadata -m CustomObject -f /path/to/outputfilename.txt

1sfdx force:mdapi:listmetadata -m Dashboard --folder foldername

1sfdx force:mdapi:listmetadata -m Dashboard --folder foldername -a 43.0

1sfdx force:mdapi:listmetadata -m Dashboard --folder foldername -u me@example.com

1sfdx force:mdapi:listmetadata -m Dashboard --folder foldername -f /path/to/outputfilename.txt

1sfdx force:mdapi:listmetadata -m CustomObject -u me@example.com -f /path/to/outputfilename.txt

Command Syntax

sfdx force:mdapi:listmetadata

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[-a APIVERSION]

[-f RESULTFILE]

-m METADATATYPE

[--folder FOLDER]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

-a | --apiversion APIVERSION

Optional

The API version to use. The default is the latest API version

Type: string

-f | --resultfile RESULTFILE

Optional

The path to the file where the results of the command are stored. The default output destination is the console.

Type: filepath

-m | --metadatatype METADATATYPE

Required

The metadata type to be retrieved, such as CustomObject or Report. The metadata type value is case-sensitive.

Type: string

--folder FOLDER

Optional

The folder associated with the component. This parameter is required for components that use folders, such as Dashboard, Document, EmailTemplate, or Report. The folder name value is case-sensitive.

Type: string

Help for force:mdapi:retrieve

Uses Metadata API to retrieve a .zip of XML files that represent metadata from the targeted org. The default target username is the admin user for the default scratch org. You can retrieve and deploy up to 10,000 files or 400 MB (39 MB compressed) at one time.

Examples for force:mdapi:retrieve

Retrieve metadata in the default project directory into the target directory:

1sfdx force:mdapi:retrieve -r path/to/retrieve/dir

Retrieve metadata defined in the specified manifest into the target directory:

1sfdx force:mdapi:retrieve -r path/to/retrieve/dir -k package.xml

Retrieve metadata defined by the specified directory, name the retrieved zipfile and extract all contents

1sfdx force:mdapi:retrieve -d path/to/apexClasses -r path/to/retrieve/dir --unzip --zipfilename apexClasses.zip

Enqueue a retrieve request but do not wait for the metadata to be retrieved:

1sfdx force:mdapi:retrieve -r path/to/retrieve/dir --wait 0

Command Syntax

sfdx force:mdapi:retrieve

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[-a APIVERSION]

-r RETRIEVETARGETDIR

[-k UNPACKAGED]

[-d SOURCEDIR]

[-p PACKAGENAMES]

[-s]

[-n ZIPFILENAME]

[-z]

[-w WAIT]

[--verbose]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

-a | --apiversion APIVERSION

Optional

Use to override the default, which is the latest version supported by your CLI plug-in, with the version in your package.xml file.

Type: string

-r | --retrievetargetdir RETRIEVETARGETDIR

Required

The root of the directory structure where the retrieved .zip or metadata files are put.

Type: directory

-k | --unpackaged UNPACKAGED

Optional

The complete path for the manifest file that specifies the components to retrieve.

Type: filepath

-d | --sourcedir SOURCEDIR

Optional

The source directory to use instead of the default package directory specified in sfdx-project.json

Type: directory

-p | --packagenames PACKAGENAMES

Optional

A comma-separated list of package names to retrieve.

Type: array

-s | --singlepackage

Optional

Indicates that the specified .zip file points to a directory structure for a single package. By default, the CLI assumes the directory is structured for a set of packages.

Type: boolean

-n | --zipfilename ZIPFILENAME

Optional

The file name to use for the retrieved zip file.

Type: string

-z | --unzip

Optional

Extract all files from the retrieved zip file.

Type: boolean

-w | --wait WAIT

Optional

The number of minutes to wait for the command to complete.

Type: minutes

Default value: 1440 minutes

--verbose

Optional

Indicates that you want verbose output from the retrieve operation.

Type: boolean

Aliases for force:mdapi:retrieve

1force:mdapi:beta:retrieve

Help for force:mdapi:retrieve:report

Specify the job ID and a target directory for the retrieve you want to check. You can also specify a wait time (minutes) to check for updates to the retrieve status. If the retrieve was successful, the resulting zip file will be saved to the location passed in with the retrieve target parameter.

Examples for force:mdapi:retrieve:report

Poll until the metadata is retrieved (or timeout is reached) using data from the last force:mdapi:retrieve command:

sfdx force:mdapi:retrieve:report

Report the current status of the last retrieve command. If the retrieve is complete the zip file of metadata is written to the target directoy:

sfdx force:mdapi:retrieve:report -r path/to/retrieve/dir -w 0

Poll until the metadata is retrieved (or timeout is reached) using the provided RetrieveID, naming the zip file and extracting all contents:

sfdx force:mdapi:retrieve:report -i retrieveId -r path/to/retrieve/dir --unzip --zipfilename apexClasses.zip

Command Syntax

sfdx force:mdapi:retrieve:report

[--json]

[--loglevel LOGLEVEL]

[-u TARGETUSERNAME]

[--apiversion APIVERSION]

[-r RETRIEVETARGETDIR]

[-i JOBID]

[-n ZIPFILENAME]

[-z]

[-w WAIT]

[--verbose]

Parameters

--json

Optional

Format output as JSON.

Type: boolean

--loglevel LOGLEVEL

Optional

The logging level for this command invocation. Logs are stored in $HOME/.sf/sf.log.

Type: enum

Permissible values are: trace, debug, info, warn, error, fatal, TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Default value: warn

-u | --targetusername TARGETUSERNAME

Optional

A username or alias for the target org. Overrides the default target org.

Type: string

--apiversion APIVERSION

Optional

Override the API version used for API requests made by this command.

Type: string

-r | --retrievetargetdir RETRIEVETARGETDIR

Optional

The root of the directory structure where the retrieved .zip or metadata files are put.

Type: directory

-i | --jobid JOBID

Optional

The job ID (asyncId) of the retrieve you want to check. If not specified, the default value is the ID of the most recent metadata retrieval you ran using Salesforce CLI. You must specify a --retrievetargetdir. Use with --wait to resume waiting.

Type: id

-n | --zipfilename ZIPFILENAME

Optional

The file name to use for the retrieved zip file.

Type: string

-z | --unzip

Optional

Extract all files from the retrieved zip file.

Type: boolean

-w | --wait WAIT

Optional

The number of minutes to wait for the command to complete.

Type: minutes

Default value: 1440 minutes

--verbose

Optional

Indicates that you want verbose output from the retrieve operation.

Type: boolean

Aliases for force:mdapi:retrieve:report

1force:mdapi:beta:retrieve:report