I am new to salesforce development and have been reading the manual, but I am kind of stuck. I have pulled and converted the metadata api source from the scratch org, but now I am wanting to deploy it up to the primary salesforce account. Suggestions, pointers... just not wanting to brick our current salesforce instance if I do something wrong

  • sfdx force:mdapi:deploy -d mdapi_output_dir/ -u "username" Commented Apr 26, 2018 at 16:47

1 Answer 1


Well, the sfdx command that you included in your comment is the correct one to use. If you're worried about messing up your production environment, why not use sfdx to deploy to a sandbox first?

Any sandbox will work, but using a full copy or partial copy sandbox would make it easier because you'd have some amount of "real" data that you could play around with to make sure, for example, that you haven't broken any customizations to Opportunity.


Also, there is a difference in terminology to pay attention to:

  • "Source form" is what most people will store in version control, this is what sfdx uses to push/pull from a scratch org. This is the form where you can put things into almost any folder that you want.
  • "Metadata API form" is the traditional form of code/objects/validation/etc..., and is what the Metadata API uses. The layout and structure of this code is more strict.

General flow

The general sfdx flow from a scratch org into a sandbox or production org is:

  1. Convert from source form to metadata api form
    • sfdx force:source:convert -d <target directory>
  2. Use the metadata api to deploy
    • sfdx force:mdapi:deploy -d <same directory as step 1> -u <username or alias>

+edit 2019-1-27

There is (and has been for a couple of releases, I think) a beta program that allows you to use force:source:push (and pull) with sandbox orgs. There's also an extension on the VSCode marketplace (also in beta at time of writing)


Having an alias for your target org is nice, you can use sfdx force:org:list to enumerate the orgs that you've authorized sfdx to use. If the alias column isn't blank, you can use that alias for the -u parameter. Otherwise, you can simply use the username.

You can set an alias for an org by using the -a parameter for the sfdx force:auth commands. If you didn't do that, you can set an alias for an org that you've already authenticated with by using force:alias:set.

sfdx force:alias:set <alias to use>=<username>

If I have a "derek" sandbox, and my username for that sandbox is "[email protected]", setting an alias would be

sfdx force:alias:set [email protected]

Other tips

If you're still worried about bricking prod, you can consider using sfdx force:mdapi:retrieve -k <path to your package.xml> -d <destination directory> -u <username or alias of your target org> to pull a copy of the files involved in your project from your production org prior to deploying your code.

Converting to metadata api form also generates a package.xml file. Using that should mean you retrieve the current production version of the things you're about to change. If things go south, you can simply do another deploy to restore the known-good version.

// pull the current metadata, and store in a "prodBackup" folder
sfdx force:mdapi:retrieve -k deployPrepared/package.xml -r prodBackup -u production

// If things go poorly in a deployment, restore from backup
// the mdapi:retrieve gives you results in the metadata api form, so no need to convert
sfdx force:mdapi:deploy -d prodBackup -u production`

Also, in the past, if you were using changesets or the force.com migration tool (w/ANT) there was an option to do a "validate" or "check only" deployment, where only tests were run (even if all tests succeeded, the deployment would not actually deploy the changes).

SFDX allows you to do the same thing with the -c option

sfdx force:mdapi:deploy -c -d myDeploymentDirectory -u ProductionAlias
  • 7
    +1, but I would also recommend mentioning -c to check the deployment without committing it.
    – sfdcfox
    Commented Apr 27, 2018 at 1:42

You must log in to answer this question.

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