jesperkristensen/forcecmd

A command-line tool for the Salesforce metadata API

Command line tool for the Salesforce metadata API

This command line tool allows you to use the file based Salesforce metadata API to download and deploy your Org's configuration and code. The tool will automatically build the required package.xml file for you and work around some bugs and limitations in the metadata API.

Installation

1. Install Node.js from http://nodejs.org/.
2. Open a command prompt / terminal.
3. Run npm install --global forcecmd.

Set up an org

1. Create an empty directory for your org.

2. Create a new file in your org's directory named forcecmd.json with content like this:

    {
      "hostname": "login.salesforce.com",
      "username": "[email protected]"
    }
   

3. Create a new file in your home directory (~) named forcepw.json with content like this:

    {
      "passwords": {
        "login.salesforce.com:[email protected]": "YourPasswordYourSecirityToken"
      }
    }
   

Download an org

1. Navigate your command prompt to your org's directory.
2. Type forcecmd retrieve.

All metadata and all custom settings are downloaded by default. You can customize this in forcecmd.json like this:

{
  "apiVersion": "45.0",
  "hostname": "login.salesforce.com",
  "username": "[email protected]",
  "excludeDirs": ["documents"],
  "objects": {
    "MyCustomSetting__c": false,
    "Product2": true,
    "Pricebook2": ["Id", "Name", "IsActive"],
    "PricebookEntry": "select Product2Id, Pricebook2Id, UnitPrice from PricebookEntry where IsActive = true"
  }
}

Use forcecmd retrieve --verbose to see what values are available to customize, or to debug issues finding the right password.

Upon completion the tool will typically print a number of messages from the Metadata API indicating problems. This is normal. If the status is Succeeded, you can ignore the messages.

Deploy changes

1. Navigate your command prompt to our org's directory.
2. Type for example forcecmd deploy src/classes/MyClass.cls src/objects/Account.object.

Additional arguments:

• --destroy: Delete all the listed files instead of updating them.
• '--options={"rollbackOnError":true}': Specify deployment options as documented on http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_deploy.htm#deploy_options
• --save-test-result: Save test results (if tests are run) to a file named TEST-result.xml in JUnit format.
• --ignore-deploy-errors: By default the process exits with an error code when the deployment fails. Use this argument to always exit with success no matter if the deployment was successful or not.
• --timed: Show timestamps next to log messages.

Use with continous integration

You can use forcecmd together with a continuous integration tool and a version control system to backup and track changes to all your Salesforce organization's customizations (metadata), and to continously run all your Salesforce organization's unit tests.

See an example of how to set this up completely in the cloud using GitHub and Travis CI.

See an example of how to set this up completely in the cloud using Azure DevOps.

Developing forcecmd

To set up development environment:

1. Clone this repository.
2. From the root of the cloned repository, run npm install.
3. Replace forcecmd with node path/to/this/tool/cli.js when you use the tool.

License

MIT

forcecmd's Issues

Receiving should delete files for deleted components

When ListMetadata throws, display which call failed and what directories to exclude

Support installed packages

Currently managed Appexchange packages are ignored.

Allow retrieving only parts of an org

The forcecmd.json file should be able to exclude parts you don't want, and it should be possible to select individual components to download on the command line.

Add optional support for rollback on error

Currently all deployments are done without rollback on error, where a partial success will cause the successful components to be deployed. It should be possible to turn it on or off.

Allow not storing individual fields for stored objects

For example if a custom settings field contains a password for an integration.

Consider using a single XML library instead of two

Retrieve custom settings

It should be possible to retrieve data stored in custom settings, so we can put those under version control.

Selecting components to be deployed should be more flexible

You currently have to specify each individual file to be deployed on the command line. It should be possible to for example specify an entire group of components or do some kind of file name pattern matching, or integrate with git status.

Consider to avoid hardcoding invalid components

We currently hardcode "ApexTriggerCoupling" and "WorkflowActionFlow" because the API claims they are supported, but using them cause API calls to fail. The Eclipse plugin works around this by making an individual list request for each type and mark it as unsupported if the request fails. We should consider doing something similar, but then we probably need to cache the result for performance.

Try to remove rimraf dependency

This dependency is quite large (304 KB) compared to what it would take to implement it ourselves.

Only the first 1000 records of data are stored

Retrieve should use fewer API calls

It is possible to query up to 3 components in a single list request.

Deployment of lightning components

Seems you need to specify all the parts of a component as a unit when deploying.

Format status.json

We should write the status.json file in a nicely formatted way using multiple lines, so you can actually use the diff when version controlling the file.

Deployment error messages missing

In the Summer 14 release error messages are no longer shown in the deploy result. Can we work around this?

Cannot deploy folders

It is currently not possible to deploy Folders because they don't have a file that corresponds to the -meta.xml file.