mParticle Command Line Interface

Overview

The mParticle Command Line Interface (CLI) can be used to communicate with various mParticle services and functions through simple terminal commands.

Through the CLI, an engineer can directly interface with many of mParticle’s services without needing to make requests directly, (such as commands via cUrl or Postman). Also, many of these requests can be integrated in any Continuous Integration/Continuous Deployment (CI/CD) systems.

Installation

The CLI installs as a simple npm package. Simply install globally and then type mp once installed.

$ npm install -g @mparticle/cli
$ mp [COMMAND]
running command...
$ mp (-v|--version|version)
@mparticle/cli/1.0.3 darwin-x64 node-v10.15.3
$ mp --help [COMMAND]
USAGE
  $ mp COMMAND

Verifying installation

To verify your installation and version, use the mp --version

$ mp --version
@mparticle/cli/1.0.3 darwin-x64 node-v10.15.3

Getting Started

Simply use mp help to view a list of the available commands.

$ mp help
mParticle Command Line Interface

VERSION
  @mparticle/cli/1.0.3 darwin-x64 node-v10.15.3

USAGE
  $ mp [COMMAND]

COMMANDS
  autocomplete  display autocomplete installation instructions
  help          display help for mp
  planning      Manages Data Planning

Setting up autocomplete

As a convenience, we provide a simple autocomplete feature, where you can type in part of a command, then press <TAB> to autocomplete a command.

Simply type mp autocomplete for instructions on configuring this feature.

Staying up to date

Simply use npm install -g @mparticle/cli to upgrade to the latest version.

Workflow

At its core, the CLI exposes services in a manner that is consistent with our REST APIs. Each command will offer a unique set of sub commands, as well as arguments and flags.

The CLI also provides universal command flags for global functions, such as --help or --outfile.

The CLI command structure is as follows:

mp [COMMAND]:[SUBCOMMAND]:[subcommand] --[flag]=[value][args...]

By default, every command will output to the CLI’s standard out. By adding a flag of --outFile=/path, the user can output the response to a log file (or json file) depending on the use case.

The CLI provides a --help flag which reveals all acceptable parameters and flags for a command, as well as a list of commands. Furthermore, top level commands will reveal their respective sub commands upon execution.

Authentication

Any CLI command that requires any mParticle HTTP API resources allows two options for authentication. You can pass credentials via either 1. command line or 2. an mp.config.json file in the root of your project.

Both of these methods will internally generate a bearer token on your behalf, as describe in Platform API Authentication.

Credentials Required:

via CLI

Simply pass your authentication credentials via the following CLI flags:

$ mp [COMMAND]:[SUBCOMMAND] --workspaceID=XXXX --clientId=XXXXX --clientSecret=XXXXXX

via Configuration File

To integrate with various services, we recommend adding an mp.config.json file to the root of your project. This will allow you to set various properties related to your mParticle account as well as other project settings, such as your data plan directory.

For more information on mp.config.json.

For example, to authenticate, make sure the following is in your mp.config.json file:

// mp.config.json
{
    "global": {
        "workspaceId": "XXXXX",
        "clientId": "XXXXXX",
        "clientSecret": "XXXXXXXXX"
    }
}

Services

Data Planning

For customers subscribed to Data Master, the CLI exposes commands to allow for Creating, Fetching, Updating, and Deleting data plans, as well as validating your events against a downloaded Data Plan.

Please be aware that all of these services require Platform API authentication credentials via ‘mp.config.jsonor via CLI arguments:clientId,clientSecretandworkspaceId` as well as Data Planning access.

Fetching Data Plans and Data Plan Versions

Fetching a Data Plan requires that a data plan exists on the server. Simply pass the dataPlanId as a flag to fetch this resource.

The Resource must exist on the server, otherwise this will fail.

$ mp planning:data-plans:fetch --dataPlanId=XXXXXX

To fetch a Data Plan Version, simply use mp planning:data-plan-versions:fetch and pass a dataPlanId and versionNumber.

Creating a Data Plan and Data Plan Versions

Use the following command to create a Data Plan Resource (or Data Plan Version) on the server.

$ mp planning:data-plans:create --dataPlan="{ // Data plan as string //}"

You can also replace dataPlan with dataPlanFile to use a path to a locally stored data plan if that is more convenient.

For example:

$ mp planning:data-plans:create --dataPlanFile=/path/to/dataplan/file.json

To create a Data Plan Version, simply use mp planning:data-plan-versions:create and pass a dataPlanId as a secondary flag.

Editing a Data Plan and Data Plan Versions

To edit an existing Data Plan (or Data Plan Version) on the server, use the following:

$ mp planning:data-plans:update --dataPlanId=XXXX --dataPlan="{ // Data plan as string //}"

You can also replace dataPlan with dataPlanFile to use a path to a locally stored data plan if that is more convenient.

For example:

$ mp planning:data-plans:update --dataPlanId=XXXXX --dataPlanFile=/path/to/dataplan/file

To create a Data Plan Version, simply use mp planning:data-plan-versions:update and pass a dataPlanId as a secondary flag.

Deleting a Data Plan and Data Plan Versions

To delete a data plan, simply pass the dataPlanId into the delete command.

$ mp planning:data-plans:delete --dataPlanId=XXXX

Deleting a Data Plan version is similar, only requiring an additional flag of versionNumber

$ mp planning:data-plans:delete --dataPlanId=XXXXX --versionNumber=XX

Validating agasint a Data Plan

Validating an Event Batch is a more complex task and the CLI provides flexibility by allowing validation to be done either locally or via the server, depending on your needs. Running a validation locally does not make a request on our servers, and as such is faster and ideal for a CI/CD environment.

$ mp planning:batches:validate --batch="{ // batch as string}" --dataPlanVersion="{ // data plan version as string }"

This will locally run your batch against a data plan version and return any validation results to the console.

This command also supports an --outfile flag that will write the validation results to a file in your local directory, in case you’d like to save the results for future use.

Both batch and dataPlanVersion support a batchFile and dataPlanVersionFile parameter (as well as dataPlan/dataPlanFile and versionNumber) options for less verbose validation commands.

Was this page helpful?