Metadata API Developer Guide

Introduction to Metadata API
Using Metadata API
Deploying and Retrieving Metadata
CRUD-Based Metadata Development
REST Resources
Deploy Metadata with Apex Testing Using REST
Deploy Metadata with REST API in Salesforce CLI
Error Handling
Reference
Appendices
Glossary
PDF

Newer Version Available

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

Deploy Metadata with REST API in Salesforce CLI

By default, Salesforce CLI commands use the Metadata SOAP API to deploy source to your org. These commands include force:source:push, force:mdapi:deploy, force:source:deploy, and commands that deploy source in the background, such as force:org:create. You can use the Metadata REST API instead by setting a CLI configuration value or environment variable. Compared with SOAP API, REST API offers faster deployment.

User Permissions Needed
To work with Metadata API from Salesforce CLI:

Modify Metadata Through Metadata API Functions

Or

Modify All Data

Use the restDeploy CLI runtime configuration value or SFDX_REST_DEPLOY environment variable to set REST API as the default. For more information, see the Salesforce DX Setup Guide.

This example uses the configuration value to set the default for your current project:

1sfdx config:set restDeploy=true

To set the default globally for all your projects, use the --global parameter:

1sfdx config:set restDeploy=true --global

Only commands that deploy source, such as force:mdapi:deploy and force:source:push, support REST API. Commands that retrieve source, such as force:mdapi:retrieve and force:source:pull, always use SOAP API.

Note

Here are the deploy limits.

Feature Limit
Maximum compressed .zip folder size1(SOAP API) Approximately 39 MB
Maximum uncompressed folder size2(SOAP API) Approximately 400 MB
Maximum number of files in AppExchange packages (REST and SOAP API)

30,000 (API version 47.0 and later)

22,000 (API version 46.0)

17,500 (API version 45.0)

12,500 (API version 43.0 and 44.0)

10,000 (API version 42.0 and earlier)
Maximum number of files in packages (REST and SOAP API) 10,000

1 Metadata API base-64 encodes components after they’re compressed. The resulting .zip file can't exceed 50 MB. Base-64 encoding increases the size of the payload by approximately 22%, so your compressed payload can't exceed approximately 39 MB before encoding.

2 When using the Ant Migration Tool to deploy an unzipped project, all files in the project are compressed first. The maximum size of uncompressed components in an uncompressed project is 400 MB or less, depending on the files’ compression ratio. If the files have a high compression ratio, you can migrate a total of approximately 400 MB because the compressed size would be under 39 MB. However, if the components can't be compressed much, like binary static resources, you can migrate less than 400 MB.