Guides

MCM CLI

MCM Command Line Interface tool

Introduction

MCM CLI is a command-line tool for operating a Moloco Commerce Media platform from a terminal or script. It wraps the Management, Decision, Event, and User Event APIs so platform owners and operators can manage ad accounts, users, wallets, campaigns, and reports, and prototype Decision API calls without writing custom HTTP requests.

📘

Note

This guide covers mcm_cli v1.9.0. Run mcm version any time to confirm the version installed in your environment.

Prerequisites

You need the following before using MCM CLI:

  • Python 3.10 or newer.
  • pip or uv for installation.
  • Network access to your platform’s Management, Decision, and Event API hostnames.
  • A Moloco user account with the appropriate role for the actions you want to perform.

Some commands depend on your assigned role. For example, the admin command group assumes PLATFORM_OWNER access.

Requirements

The MCM CLI tool requires Python and PIP please review the documentation links for installation and configuration.

Github

Download the MCM CLI tool from Moloco’s GitHub repository. https://github.com/moloco-mcm/mcm-cli

What you can do with MCM CLI

MCM CLI currently exposes these command groups:

  • version: print the installed CLI version.
  • config: initialize and manage CLI profiles.
  • auth: fetch a fresh JWT bearer token.
  • account: list, create, and manage ad accounts and ad account users.
  • admin: run platform-level admin operations such as listing users, campaigns, items, balances, generating sample data, and blocking items.
  • campaign: list, read, update, and archive campaigns, and manage campaign items.
  • decision: prototype Decision API requests for products, items, and creatives.
  • report: retrieve platform-wide and ad-account reporting output.
  • wallet: view balances and deposit or withdraw funds.

In practice, most users rely on the CLI for a few common workflows: checking platform and ad account state, troubleshooting with --to-curl, previewing Decision API requests, inspecting wallet balances, and retrieving report output for a specific time window.

Install MCM CLI

Install with pip

$ pip install --upgrade mcm-cli
mcm version

Install with uv

uv init my-mcm-project && cd my-mcm-project
uv add mcm-cli
uv run mcm version

If you install with pip, use mcm ....

If you install in a uv project, use uv run mcm ....

The two forms are interchangeable aside from the prefix.

Set up your CLI profile

The first time you use the CLI, initialize a profile:

mcm config init

This creates ~/.mcm/config.toml and prompts for the core settings, including your platform ID, Campaign Manager email and password, timezone, currency, and API hostnames and keys.

To create another profile, such as production:

mcm config init --profile prod

To list configured profiles:

mcm config list-profiles
🚧

Security Note

The config file stores your password and API keys in plaintext, so restrict access to the file and never commit it to version control. Output from --to-curl may also include credentials inline, so treat it as sensitive.

Common tasks

# Check your installed version
mcm version

# List ad accounts
mcm account list-accounts

# Show one ad account wallet balance
mcm wallet balance --account-id 10017

# List campaigns for an ad account
mcm campaign list-campaigns --account-id A001399

# Read one campaign
mcm campaign read-campaign --account-id A001399 --campaign-id Eexr1DxUXJtLS6yU

# Preview a Decision API request without sending it
mcm decision decide-products --inventory-id HOME --num-ads 3 --to-curl

# Run a platform report
mcm report platform-summary --start-date 2026-05-01 --end-date 2026-05-13 --group-by DATE

Important behaviors to know

--profile placement

--profile is a per-subcommand option, not a top-level flag. Use this form:

mcm account list-accounts --profile prod

Not this form:

mcm --profile prod account list-accounts

Dry-run with --to-curl

You can add --to-curl to many commands to print the equivalent HTTP request without sending it. This is especially useful before running mutating commands such as wallet deposits, withdrawals, campaign archive operations, or item blocking.

Output formats

Depending on the command, MCM CLI can return human-readable text, CSV, pretty-printed JSON, compact JSON, or a generated curl command. Many list-style commands default to CSV-like output, while report commands return JSON.

Many read commands support --to-json to print raw JSON instead of the default human-readable or CSV output. Report commands are an exception: they already return JSON, so there is no --to-json flag there.

Money units

Some JSON responses include amount_micro, which represents one-millionth of the configured currency unit. Human-readable output usually converts this automatically, but raw JSON preserves the micro-unit value.

For example, if you inspect wallet or campaign budget data in JSON, the numeric value may look much larger than the amount shown in human-readable output because it is expressed in micro-units.

Authentication behavior

Authenticated subcommands automatically obtain a fresh bearer token using the email and password stored in the selected profile. You only need mcm auth get-token when you explicitly want the token itself.

Reporting output

Report commands use YYYY-MM-DD dates, and --group-by accepts DATE, AD_ACCOUNT, or CAMPAIGN only. The timezone used for date bucketing comes from the active profile.

SSO caveat

If SSO is enforced for a customer email domain, accounts under that domain can no longer use email/password authentication for tools such as the Bulk Ops Tool and MCM CLI. In that case, use an API key or a separate non-SSO account for CLI and automation workflows.

Error handling

If the CLI prints ERROR: ..., do not assume the process exited non-zero. In many cases, the CLI still exits with status 0, so scripts should check command output for the ERROR: prefix instead of relying only on shell exit codes.

Limitations in v1.9.0

The current CLI version has a few notable limitations:

  • Some campaign and admin list commands can fail with a pydantic ValidationError on ad accounts that contain legacy field shapes. The workaround is to call the underlying API directly via --to-curl until a fix is rolled out.
  • Use PRE_PAID rather than PREPAID as fund type.
  • mcm admin generate-sample-data is restricted to dedicated test platforms and fails on non-test platforms.

Additional information

  • Every command and subcommand supports --help.
  • Browse the MCM API reference at mcm-docs.moloco.com/reference.
  • For support, contact your Moloco account team.