Sunday 26 June 2016

Force CLI Part 2 - Extracting Metadata

Force CLI Part 2 - Extracting Metadata



In Part 1 of this series, Getting Started, I covered downloading and installing the Force CLI, and logging in to Salesforce. This post covers extracting metadata from your Salesforce org.

Why do I need the Metadata?

This is a very good question - a lot of the time the answer is that you don’t. If you do, its highly likely that your IDE of choice will handle this for you - pulling down the metadata components that you are working on and uploading the changes when you save or deploy. The classic use case for this is to make a backup of your implementation, typically on a regular schedule in an unattended fashion.


At first glance, this looks about as straightforward as it could be. Executing force help shows there is a command that looks tailor made:

export    Export metadata to a local directory

By default, this command dumps the metadata to a subdirectory of your current directory named (fittingly enough) metadata, although you can supply a different location for the output as an additional parameter.

After logging in, I can export the metadata by executing the following command:

force export

However, at the time of writing this doesn’t quite bring everything back. Here’s the contents of my metadata directory- spot the deliberate mistake: 

analyticSnapshots	homePageComponents	quickActions
applications		homePageLayouts		remoteSiteSettings
approvalProcesses	labels			reportTypes
assignmentRules		layouts			roles
autoResponseRules	networks		samlssoconfigs
callCenters		objectTranslations	scontrols
classes			objects			sharingRules
communities		package.xml		sites
components		pages			staticresources
connectedApps		permissionsets		tabs
dataSources		portals			translations
flows			profiles		triggers
groups			queues			workflows

Spotters Badge for those eagle-eyed readers that wondered where the Lightning Components metadata directory(aka aura) is.

There’s currently no way to influence the metadata elements that are included by the export command, but luckily there is a mechanism to extract individual metadata component types.

Fetch! Good boy!

The fetch subcommand provides granularity around metadata extraction, not just down to a single type of metadata, but as far as a single metadata component. I’m not going down to that level, but if you are interested then execute force help fetch which gives full details of the options.

The fetch command takes a -t switch to identify which metadata type you want to extract. For all types you can specify the name of the metadata type as detailed in the Metadata API Developer’s Guide, so to extract the Sites metadata, for example, you would execute:

force fetch -t CustomSite

The metadata name for Lightning Components is AuraDefinitionBundle, but you can also specify Aura as the type, which will extract the Lightning Component metadata via the REST API - I tend to use the latter version as I find it is slightly faster than the metadata route.


force fetch -t Aura

extracts the Lightning Components to the metadata directory, and the entire Salesforce configuration is now in one place:

analyticSnapshots	homePageComponents	remoteSiteSettings
applications		homePageLayouts		reportTypes
approvalProcesses	labels			roles
assignmentRules		layouts			samlssoconfigs
aura			networks		scontrols
autoResponseRules	objectTranslations	sharingRules
callCenters		objects			sites
classes			package.xml		staticresources
communities		pages			tabs
components		permissionsets		translations
connectedApps		portals			triggers
dataSources		profiles		workflows
flows			queues
groups			quickActions

Putting these commands together in a bash script, with a dash of compression, gives me a handy backup file containing my metadata:

force login
force export
force fetch -t Aura
zip -r metadata >

Note - if you run the above commands directly from the command line, ignore the first one. That tells the OS which command to use to execute the script, which makes no sense for individual commands.

Version Control to Major Tom

Where this can be particularly powerful is if you integrate with version control.  You can use a script to periodically extract the latest metadata and merge into your Git repository for example.

Related Posts



  1. Hi Bob. Have you used the CLI in Windows7 (64bit) before? I am having trouble with the "push" param
    When I type this:
    C:\sfdc\force push -t ApexClass -n myClass -l NoTestRun
    I get this...
    Validating and deploying push...

    But then it just hangs and the file is never actually pushed to my target sandbox org.

    Any ideas?

    1. Sorry, we are a Mac outfit so I've only used it on that.

  2. Thank you for your post! This is way better that the ANT script that I've implemented to do basically the same thing. Here's how I added source control (I welcome any feedback):

    #clone backup repo into the folder 'metadata'
    git clone[user/group account]/[repo name].git metadata

    #export will dump into the 'metadata' folder automatically
    force export
    force fetch -t Aura

    #create variable '$NOW' to store the current date time
    NOW=$(date +"%Y-%m-%d %H:%M:%S")

    #copy the backupscript to the metadata folder for script versioning
    cp ./metadata/

    #get into the right directory
    cd metadata

    #update a log file so that there is always something to check-in
    echo "Last Updated: $NOW" > update.log

    #add any changes that were made (update/add/delete) to git for staging
    git add .
    #commit changes to the local git repo
    git commit -m "$NOW Daily Data Backup using Automated Script"
    #push the changes out to the remote that was associated in the 'clone' above
    git push origin master

    #move up a directory
    cd ..
    #remove the metadata folder as cleanup
    rm -rf ./metadata

  3. I have the same problem as Mark, but I am on a Mac. If I open a terminal and cd to one level above the "metadata" folder, and then I:

    force push -t ApexClass -f metadata/classes/ -l NoTestRun


    force push -t ApexClass -f metadata/classes/

    The command just hangs forever. Nothing happens.

  4. Can you provide us the link for restoring the metadata

  5. I wouldn’t use the force CLI now that the Salesforce CLI is here.