---
name: mcli
description: >
  Query the Mantle Core API using the mcli CLI tool. Use this skill when the user asks to
  look up, query, list, get, or investigate data from the Mantle platform — customers,
  subscriptions, metrics (MRR, ARR, churn, etc.), apps, plans, deals, contacts, usage events,
  charges, transactions, affiliates, tickets, meetings, email campaigns, email deliveries,
  or any other Mantle resource.
  Triggers on: "look up customer", "check MRR", "find subscription", "get metrics",
  "query usage events", "list deals", "search entities", "list email campaigns",
  "check email deliveries", or any request to read data from the Core API.
  This skill is READ-ONLY — never use mcli to create, update, or delete data.
---

# mcli — Mantle Core API CLI

Query Mantle data via the `mcli` command. This skill covers **read-only** operations only.

## Key Rules

- **Read-only**: Only use `list`, `get`, `search`, `timeline`, and `metrics` subcommands. Never use `create`, `update`, `delete`, `add-*`, `remove-*`, or any mutating command.
- **Always use `--json`** when you need to parse or analyze the output programmatically.
- **Pagination**: Most list commands default to 25 items. Use `--take` to get more (up to 100) and `--cursor` or `--page` for pagination.
- The CLI is pre-authenticated. Run `mcli whoami` if you need to confirm the current profile.

## Quick Patterns

### Look up a customer
```bash
mcli customers list --search "acme" --json
mcli customers get <id> --json
mcli customers get <id> --includes subscriptions --json
mcli customers timeline <id> --json
```

### Check metrics
```bash
mcli metrics mrr --date-range last_30_days --json
mcli metrics arr --app-id <id> --json
mcli metrics revenue-churn --date-range this_month --json
mcli metrics sales --json
```

### Find subscriptions
```bash
mcli subscriptions list --customer-id <id> --json
mcli subscriptions get <id> --json
```

### Search across contacts and customers
```bash
mcli entities search --search "john@example.com" --json
```

### View app events / usage
```bash
mcli apps list-events --app-id <id> --take 50 --json
mcli usage-events list --customer-id <id> --event-name "page_view" --json
mcli metrics usage-event --app-id <id> --event-name "api_call" --date-range last_7_days --json
```

### Deals and pipeline
```bash
mcli deals list --status open --json
mcli deals get <id> --json
mcli deals timeline <id> --json
```

### Charges and transactions
```bash
mcli charges list --customer-id <id> --json
mcli transactions list --customer-id <id> --app-id <id> --json
```

## Full Command Reference

See [references/commands.md](references/commands.md) for the complete list of read-only commands and their options.

## Tips

- Use `mcli <resource> help <subcommand>` to see all options for any command.
- Pipe `--json` output to `jq` for filtering: `mcli customers list --json | jq '.customers[] | .name'`
- Date ranges accept presets (`last_30_days`, `this_year`, etc.) or custom ISO 8601 dates via `--start-date` / `--end-date`.
- When investigating a customer, start with `entities search` to find them, then drill into `customers get`, `subscriptions list`, `charges list`, etc.

### Email campaigns and deliveries
```bash
mcli email-campaigns list --status active --json
mcli email-campaigns get <id> --json
mcli email-campaigns preview <id> --customer-id <cust_id> --json
mcli email-deliveries list --email-id <campaign_id> --json
mcli email-deliveries get <id> --json
mcli email-layouts list --json
mcli email-senders list --json
```