CLI

This guide explains the basic usage of Monte Carlo's CLI, installed with pip install montecarlodata. For the new CLI built on the REST API v2, see New CLI.

You can find the CLI reference guide (documentation on all commands, options, and arguments) here.

Requirements

The CLI requires Python 3.10 or greater.

Installing or updating the CLI

To install or update the CLI, please run:

pip install -U montecarlodata

Then, verify the installation using:

montecarlo --version

Setting up the CLI

To configure your CLI, please run:

montecarlo configure

You will be prompted to choose an authentication type — API key or OAuth — and then to enter the corresponding credentials. See API Authentication for how to create each type of credential.

❗️

Careful!

You are only able to see the secret (API key secret or OAuth client secret) once! Save it in a safe place.

Configure with an API key

To skip the prompt and configure an API key non-interactively, pass --api-key:

montecarlo configure --api-key --mcd-id <KEY_ID> --mcd-token <SECRET>

You can create an API key from the API settings page.

Configure with OAuth

To configure OAuth client credentials, pass --oauth. In addition to the client ID and secret, OAuth requires your deployment's instance ID (e.g. us1, eu1), shown under Account Information → Instance ID in the app:

montecarlo configure --oauth \
  --mcd-oauth-client-id <CLIENT_ID> \
  --mcd-oauth-client-secret <CLIENT_SECRET> \
  --mcd-instance-id <INSTANCE_ID>

Omit the flags to be prompted for each value. The CLI handles the OAuth token exchange for you on each call; there is nothing else to configure.

After configuring you can validate your connection with:

montecarlo validate

Documentation

Documentation for commands, options, and arguments can be found here.

Otherwise, to get high-level help, please run:

montecarlo --help

Similarly, you can get help for a specific set of commands:

montecarlo integrations --help

To retrieve documentation (help text) on all commands, subcommands and options:

montecarlo help

As an example, this is how you would list all active integrations:

montecarlo integrations list

See here for additional details and examples.

New CLI

A new CLI, built on the REST API v2, manages an account's setup from a terminal or script: deployments, collection agents and data stores, credentials, warehouses and connections. It is a single binary with no Python requirement. Its reference has a page for every command, plus guides to setting up credentials, deploying a collection agent and connecting a warehouse.

🚧

Beta

The new CLI is versioned 0.x, and a new minor version may carry breaking changes. In CI or scripts, pin the version you install.

Installing the new CLI

On macOS and Linux:

curl -fsSL https://github.com/monte-carlo-data/mc-cli/releases/latest/download/install.sh | sh

On Windows, in PowerShell:

irm https://github.com/monte-carlo-data/mc-cli/releases/latest/download/install.ps1 | iex

The project README covers pinning a version, verifying the installer before running it, and other install methods.

Using it alongside the Python CLI

Both CLIs install a command named montecarlo. The new CLI's installer does not replace the Python CLI: it stops if the Python CLI is where it would install, and warns if the Python CLI is elsewhere on your PATH. To keep both, install the new CLI under another name:

curl -fsSL https://github.com/monte-carlo-data/mc-cli/releases/latest/download/install.sh | MONTECARLO_BIN_NAME=mc sh

If both keep the name montecarlo, whichever comes first on your PATH runs; which -a montecarlo lists them in that order.

Setting up the new CLI

montecarlo configure
montecarlo whoami

configure asks whether you use an OAuth client or an API key, checks the credentials with Monte Carlo, and saves them as a profile. Profiles live in ~/.mcd/profiles.ini, the same file the Python CLI writes, so both CLIs can use credentials set up by either. For scripts and CI, see the credentials guides in the reference.