dmc

Cross-platform, developer cli tool for Salesforce

Usage no npm install needed!

<script type="module">
  import dmc from 'https://cdn.skypack.dev/dmc';
</script>

README

dmc

Build Status npm version

dmc is a cross-platform, CLI developer tool for Salesforce.com. dmc aims to provide a CLI interface to salesforce.com development that abstracts the complexities of dealing with API's and metadata into a simple tool that makes everything feel like local and remote file system operations. Basically, the goal is to create a tool that is as intuitive to use as normal file system tools like cp and rsync.

dmc was built to be used on the command line but it's modules are exposed in a way that make it able to be used as a regular node modules in your programs. This means it can be integrated into build tools like grunt and gulp, or even into more complex systems like CI.

Installation

npm install -g dmc

Getting Started

Entering dmc on the command line with no command argument will print usage information.

λ: dmc

  Usage: dmc [options] [command]


  Commands:

    init                             initialize a project for dmc
    config [options]                 show the resolved dmc configuration
    config:set [options] [items...]  set configuration variables
    logins                           list your salesforce logins
    login [options] <org>            login to a Salesforce organization
    logout [org]                     logout of a Salesforce organization
    use [options] <org>              quickly set your default org in your configuration
    index [options] [org]            indexes metadata for a target org
    open [org]                       open the target org in a browser window
    identity [options]               show the identity for the specified org
    deploy [options] [globs...]      deploy metadata to target org
    test [options] [globs...]        run test classes
    retrieve [options] [globs...]    retrieve metadata from target org
    watch [options] [globs...]       watch files and deploy metadata to target org
    anon [options] [code]            execute anonymous apex [code]
    resources [options]              list all of the available api resources
    get [options] <url>              get a REST API url

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    --verbose      use verbose logging
    --silent       skip logging

To view the usage info on any particular command, enter the dmc command and add the --help or -h flag. Example:

$ dmc config:set --help

  Usage: config:set [options] [items...]

  set configuration variables

  Options:

    -h, --help    output usage information
    -g, --global  Set the global config variable. Otherwise, local variable set

Core Concepts

Authentication

dmc uses a global authentication system. This means that org credentials aren't stored on a project-by-project basis. Rather, dmc stores centrally stores credentials that can be used wherever and whenever you need to. This also comes in handy when you're working in a project but need to deploy it to multiple targets.

Globbing Patterns

One of the most powerful features of dmc is the ability to perform operations on metadata like deploy and retrieve using filesystem globbing patterns. The same globbing patterns you use for deploying will work for retrieving, and vice versa. The best way to understand this is to look at some examples:

$ dmc deploy src/classes/*            # deploy all classes
$ dmc retrieve src/{classes,pages}/*  # retrieve all classes and pages
$ dmc deploy src/**/*                 # deploy everything in src dir
$ dmc retrieve src/**/*               # retrieve all metadata (there will be a lot)

Globbing patterns are powerful. Here's some advanced examples.

$ dmc deploy src/{classes,pages}/Foo*  # would match FooClass.cls FooPage.page

dmc also supports multiple globs for deploys/retrieves.

$ dmc deploy src/classes/*_test.cls src/classes/MyClass* src/pages/MyPage*

More info on globbing pattens can be found here.

Important Note on Globbing and Shells

On *nix system shells, globbing patterns are automatically processed by your shell before the executable is called. This is fine for deploys but retrieves require a bit of additional thought.

For example, let's say that you want to retrieve all classes but several of those classes don't yet exist in your local src/classes directory. Running this command would not really work...

$ dmc retrieve src/classes/*

This isn't reliable because the glob pattern will actually be processed by your shell before the patterns are sent to dmc. Therefore, the only files that would be retrieved would be the files that currently reside on your local filesystem.

The good news is that this is easily fixed by wrapping the glob pattern(s) in quotes.

$ dmc retrieve 'src/classes/*'  # this will get all remote classes

Watching Files

dmc has a watch command that let's you listen to file changes and deploy when files change. This gives you compile-on-save functionality while using any editor or IDE that you like. It's easy...

$ dmc watch src/**/*  # watch files and deploy to your default org

$ dmc watch src/**/* --org myorg  # deploy to a specific org

.dmcignore

You can add a .dmcignore file to the root directory of your projects. It should reside in the same directory as your src/ folder. This file can be used to automatically exclude files from deploy and retrieve calls. This is handy for excluding files like mm.log files from MavensMate.

.dmcignore file:

# exclude log files
*mm.log

# exclude all pages starting with foo
src/pages/Foo*

Configuration

dmc has a configuration system that allow a developer to set global configuration options as well as override those at a project level. Setting up project-level configuration is completely optional.

$ dmc config:set api_version=36 # set Salesforce API version to use for this project

Contributing

CURRENTLY SEEKING WINDOWS TESTERS/CONTRIBUTORS

You're welcome and encouraged to contribute to dmc. Please just keep in mind the following guidelines before submitting a PR.

  • API Additions: Undoubtedly, the API will be expanding over time adding new commands and functionality. This needs to be done carefully though. It's easy for a tool like this to become a grab bag of commands. It's highly advised that if you want to contribute and API addition/change, that you first submit a proposal in the form of an issue to this repo. That way, we as a community can determine whether or not it should be a part of the project before you spend a bunch of your free time on building it.
  • PR Format: When submitting a PR, please make sure of the following:
    • Include only a single commit. You can squash multiple commits with a rebase prior to submitting the PR.
    • Ensure your commit is rebased from the target branch.
    • Reference any issue numbers that the PR resolves
  • Tests: Whenever possible, include unit tests with your PR.
  • Clean Builds: There is a very simple gulp build included with this project that runs jshint and unit tests. You are encouraged to run this before submitting

Roadmap

  • Anon script arguments
  • Test Execution
  • Lots of other stuff