Project

mpql

0.0
No release in over 3 years
mpqltomorrowkey/mpqlHomepageDocumentationSource CodeBug TrackerWiki
A command-line tool to execute MixPanel Query API requests. Designed for both human users and AI agents.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
650
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.2.2
Total releases
3
First release
1980-01-02
Latest release
1980-01-02
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-03-09
Reverse Dependencies
0

 Dependencies

Runtime

terminal-table
~> 3.0
thor
~> 1.3
 Project Readme

mpql

A command-line tool to execute MixPanel Query API requests. Designed for both human users and AI agents.

Installation

gem install mpql

Configuration

Create ~/.mpql.yml:

username: your-service-account-username
secret: your-service-account-secret

Or use environment variables:

MIXPANEL_USERNAME=your-service-account-username
MIXPANEL_SECRET=your-service-account-secret

Usage

Segmentation

mpql segmentation --project-id 123456 --event "Signed Up" --from 7d --to today
mpql segmentation --project-id 123456 --event "Page View" --from 2026-03-01 --to 2026-03-09 --on "properties.$browser" --unit day
mpql segmentation --project-id 123456 --event "Purchase" --from 1m --to today --type unique --format tsv

Funnels

mpql funnels --project-id 123456 --funnel-id 12345 --from 7d --to today
mpql funnels --project-id 123456 --funnel-id 12345 --from 2026-03-01 --to 2026-03-09 --on "properties.$os"

Retention

mpql retention --project-id 123456 --from 30d --to today
mpql retention --project-id 123456 --from 2026-02-01 --to 2026-03-09 --born-event "Signed Up" --event "Login"

Insights

mpql insights --project-id 123456 --bookmark-id 67890

Cohorts

mpql cohorts --project-id 123456
mpql cohorts --project-id 123456 --format table

Export (Raw Event Data)

mpql export --project-id 123456 --event "ScreenView" --from 7d --to today
mpql export --project-id 123456 --event "Signed Up" --from 2026-03-01 --to 2026-03-09

Engage (User Profiles)

mpql engage --project-id 123456
mpql engage --project-id 123456 --where 'properties["$email"] == "test@example.com"'
mpql engage --project-id 123456 --distinct-id "user123"
mpql engage --project-id 123456 --distinct-id "user123" "user456" "user789"

Date Formats

  • yyyy-mm-dd (e.g., 2026-03-01)
  • today, yesterday
  • Nd - N days ago (e.g., 7d)
  • Nw - N weeks ago (e.g., 2w)
  • Nm - N months ago (e.g., 1m)

Output Formats

  • --format json (default) - JSON output
  • --format tsv - Tab-separated values
  • --format table - ASCII table
  • --raw - Raw JSON without pretty-printing

Global Options

  • --project-id - MixPanel project ID (required)
  • --region - MixPanel region (us, eu, in). Defaults to us

Release

  1. Update the version number in lib/mpql/version.rb
  2. Commit the changes
  3. Run rake release

This will create a git tag, build the gem, and push it to rubygems.org.

License

MIT License. See LICENSE.txt for details.