I have been reading some mixed comments about the difference between force:source vs force:mdapi. So far my assumption is that force:source is used for scratch org and force:mdapi is used for sandbox/dev/prod org.

Q1) force:source vs force:mdapi

  • What is the difference between force:source vs force:mdapi?

Q2) force:source:pull/push vs force:source:deploy/retrieve

  • I do not completely understand the difference between force:source:pull/push vs force:source:deploy/retrieve. I understand when a code change is done either locally or on scratch org pull/push can sync in both environments, but when will I need to use force:source:deploy/retrieve?

Q3) force:mdapi:deploy/retrieve vs force:source:deploy/retrieve

  • What is the difference between force:mdapi:deploy/retrieve vs force:source: deploy/retrieve and when should they each be used?

Goal: My ultimate goal is to retrieve from production, do my development in scratch org, and deploy changes to development.

  • 2
    Have you had a chance to look through the Salesforce DX Extensions User Guide? While it's phrased mostly in terms of the UI commands, it explores all of the permutations. There are also excellent Trailhead modules on both Org and Package Development Models.
    – David Reed
    Jul 17, 2019 at 22:06
  • 1
    Thanks, but for some reason they never mention force:mdapi in that page. I am trying to implement CI so therefore I need a clear understanding of the CLI
    – Nino Y
    Jul 17, 2019 at 23:23

1 Answer 1


What is the difference between force:source vs force:mdapi?

The file and directory structures are different. force:source refers to the new "source" format, while force:mdapi refers to the old "metadata" format. As an example of the changes, in metadata format, a custom object is a single file, while in source format, an object has a core metadata file for the object itself, a folder full of files that represent each field, another folder for list views, etc.

... but when will I need to use force:source:deploy/retrieve?

For anything that is not a Scratch Org (including Production, Sandbox, and Developer Edition orgs). The difference here is that Scratch Orgs "track" changes, allowing developers to upload and download a delta (i.e. just the changes). Other orgs do not have this extra feature, and so you can only download and upload specified files, regardless if there has been any change. This means that it will typically take longer to upload and download changes, and it can be easier to miss changes.

What is the difference between force:mdapi:deploy/retrieve vs force:source: deploy/retrieve and when should they each be used?

If you have metadata formatted files, use force:mdapi. If you have source formatted files, use force:source. If you have neither, use the source format, as it is easier to work with.

The mdapi commands are to allow migration from existing source code repos to the newer format over time. You should prefer to use the force:source commands whenever possible, and use the force:mdapi commands only when dealing with legacy code repositories that have not yet been converted to "source" format.

Migrating to source format also means you'll get the advantage of 2GP (Second generation packages), which allows you to create versions, dependencies, etc, so you can just install packages instead of uploading metadata every time. This greatly reduces deployment times and grants additional features, like the ability to delete an obsolete field by removing it from a package.

You can get your goals done with nothing other than force:source (and optionally force:package) command(s). You can use a Developer Edition org, or you might even decide to eventually migrate to Scratch Orgs.

  • 4
    Should probably mention that SFDX has a myriad of bugs and that nowhere close to everything can be deployed through packages.
    – rzr
    Jul 19, 2019 at 22:20
  • @rzr Is this speaking from recent experience, or has it been a while? I remember trying to migrate to DX last year and I had a ton of problems, but as of Summer '19, I've been able to start migrating our org to scratch orgs and unlocked packages, and we have a lot of metadata. Unless you've got a super-complicated org, DX should be relatively painless.
    – sfdcfox
    Jul 20, 2019 at 0:37
  • 3
    I'm working with it right now on a fairly large project (although still a young one). My experience is that there's still a ton of issues with metadata support and change tracking in the CLI which makes us resort to MDAPI and ad-hoc powershell scripts to keep CI going and developers unblocked.
    – rzr
    Jul 20, 2019 at 22:16

Not the answer you're looking for? Browse other questions tagged .