mixpanel-cli

Human-friendly CLI for querying Mixpanel events and users from the terminal.

mixpanel-cli is a TypeScript command-line tool for:

• authenticating with Mixpanel service accounts
• exporting raw events
• running event queries for counts, uniques, top events, and breakdowns
• listing user profiles and inspecting user activity
• switching between named Mixpanel profiles

By default, commands print readable ASCII tables. Add --json to get machine-friendly output for scripts and pipelines.

Requirements

• Node.js >= 22
• A Mixpanel service account with access to the project you want to query
• macOS, Linux, or Windows with local keychain/credential storage support for keytar

Installation

After publishing to npm:

npm install -g mixpanel-cli

For local development:

npm install
npm run build
node dist/index.js --help

Authentication

The CLI stores profile metadata locally and keeps secrets in the OS credential store through keytar.

Create a profile:

mixpanel auth login \
  --profile prod \
  --region us \
  --username YOUR_SERVICE_ACCOUNT_USERNAME \
  --secret YOUR_SERVICE_ACCOUNT_SECRET

List profiles:

mixpanel auth list-profiles

Switch the active profile:

mixpanel auth use-profile prod

Validate the active profile:

mixpanel auth whoami

Remove the stored secret for the active profile:

mixpanel auth logout

Auth notes

• Supported regions are us and eu.
• The current auth login flow requires --secret, so your shell may retain it in history. Use care when running it on shared machines.
• Runtime commands can also use environment overrides:
  • MIXPANEL_SERVICE_ACCOUNT_USERNAME
  • MIXPANEL_SERVICE_ACCOUNT_SECRET
  • MIXPANEL_REGION
  • MIXPANEL_PROFILE

Commands

Raw event export

Export raw event rows over a date range:

mixpanel events export \
  --from 2026-03-01 \
  --to 2026-03-03 \
  --event "Signed Up" "Purchase" \
  --where 'properties["plan"] == "pro"'

JSON output:

mixpanel events export \
  --from 2026-03-01 \
  --to 2026-03-03 \
  --json

Event queries

Counts over time:

mixpanel events query counts \
  --from 2026-03-01 \
  --to 2026-03-07 \
  --event "Signed Up" \
  --interval day

Unique users over time:

mixpanel events query uniques \
  --from 2026-03-01 \
  --to 2026-03-07 \
  --event "Signed Up" \
  --interval week \
  --where 'properties["plan"] == "pro"' \
  --json

Top events over a date range:

mixpanel events query top \
  --from 2026-03-01 \
  --to 2026-03-07 \
  --limit 10

Break down an event by property:

mixpanel events query breakdown \
  --from 2026-03-01 \
  --to 2026-03-07 \
  --event "Signed Up" \
  --by plan \
  --limit 5

Users

List user profiles:

mixpanel users list \
  --selector 'properties["plan"] == "pro"' \
  --page 1 \
  --limit 50 \
  --sort '$last_seen'

Project only selected fields:

mixpanel users list \
  --selector 'properties["$email"] == "alex@example.com"' \
  --project '$email' plan \
  --json

Inspect user activity:

mixpanel users activity \
  --distinct-id user-123 \
  --since 2026-03-01 \
  --limit 25

Output modes

Default output is table-oriented and intended for terminal use.

Example:

date       | value
-----------+------
2026-03-01 | 4
2026-03-02 | 7

Add --json to print structured output:

mixpanel events query top --from 2026-03-01 --to 2026-03-07 --json

How event queries work

• counts and uniques use Mixpanel aggregate event queries over a date range.
• top is implemented by aggregating event totals over the requested date range and sorting them descending.
• breakdown uses Mixpanel event property queries and totals each property value across the requested window.

Development

Install dependencies:

npm install

Run the CLI directly in development:

npm run dev -- --help

Run tests:

npm test

Run typecheck:

npm run typecheck

Build:

npm run build

Run coverage:

npm test -- --coverage

Status

This repo is ready for public iteration, but it is still early-stage:

• the core auth, export, event query, and users flows are implemented
• test, typecheck, build, and coverage all run successfully in the current repo
• interactive secret prompting and richer profile management can still be improved