stmo-cli 0.9.0

Turn Claude Code into a data analyst on sql.telemetry.mozilla.org
Documentation

stmo-cli

How it works

stmo-cli is a CLI that Claude Code calls on your behalf. Install it, set your API key, and Claude Code can:

  • Explore — discover data sources, find existing queries, browse schemas
  • Write — create new Redash queries with proper BigQuery SQL
  • Deploy — push queries, charts, and dashboards to STMO
  • Execute — run queries and inspect results
  • Analyze — export data for deeper analysis with other tools

For example, ask Claude Code to:

  • "Find queries about Firefox DAU"
  • "Write a query to track [metric] over time"
  • "Fetch and run query #12345"
  • "Explore what telemetry tables are available"

Pair it with the mozdata plugin for telemetry expertise and probe discovery.

Prerequisites

Installation

For people who already have the Firefox source stored locally

cd /path/to/your/firefox/source/folder
./mach bootstrap

For anyone else

Install cargo-binstall.

cargo binstall stmo-cli

Build from source:

cargo build --release
# The binary will be at ./target/release/stmo-cli

Setup

  1. Get your Redash API key from your user profile

  2. Set environment variables:

export REDASH_API_KEY="your-api-key-here"
export REDASH_URL="https://sql.telemetry.mozilla.org"  # optional, this is the default

For Mozilla, the key can be accessed via the following URL: https://sql.telemetry.mozilla.org/users/me

  1. Create directories:
stmo-cli init
  1. Discover available queries:
stmo-cli discover                          # List your own queries
stmo-cli discover --search "firefox dau"   # Full-text search queries + dashboards
  1. Fetch specific queries:
stmo-cli fetch 123 456 789

Usage

Fetch Queries from Redash

stmo-cli fetch --all                       # Fetch all tracked queries
stmo-cli fetch 123 456 789                 # Fetch specific queries
stmo-cli discover                          # List your own queries
stmo-cli discover --search "firefox dau"   # Full-text search queries + dashboards (--limit, default 50)

This creates/updates:

  • queries/{id}-{slug}.sql - Query SQL
  • queries/{id}-{slug}.yaml - Query metadata (parameters, visualizations, etc.)

Deploy to Redash

stmo-cli deploy       # Deploy changed queries (detected via git status)
stmo-cli deploy --all # Deploy all queries

Warning: This force overwrites the queries in Redash. Git is the source of truth.

Execute Queries

stmo-cli execute 123                                       # Run query 123 (deploys local changes first, if any)
stmo-cli execute 123 --param start_date=2026-06-15
stmo-cli execute 123 --param channels='["release","beta"]' # Multi-value enum as JSON
stmo-cli data-sources                                      # List data sources
echo 'SELECT 1' | stmo-cli execute --data-source 321       # Run arbitrary SQL against a data source
stmo-cli execute --data-source 321 --file scratch.sql

execute ID deploys the local .sql/.yaml first if it differs from what's stored on the server (SQL, name, data source, or parameters), so it never silently runs a stale copy — then it always runs the up-to-date server-stored query.

execute --data-source ID runs ad-hoc SQL directly against a data source without creating a tracked query — useful for one-off exploration. It has no parameter schema, so multi-value parameters can't be expanded for you — inline the values directly in the SQL (e.g. IN ('release', 'beta')).

Parameters are passed as --param name=value (repeatable). Values are parsed as JSON when possible, anything that isn't valid JSON is treated as a plain string.

Manage Query Snippets

stmo-cli snippets list                     # List query snippets from Redash
stmo-cli snippets fetch 31 42              # Fetch specific snippets
stmo-cli snippets fetch --all              # Fetch all tracked snippets
stmo-cli snippets deploy                   # Deploy changed snippets (detected via git status)
stmo-cli snippets deploy --all             # Deploy all snippets
stmo-cli snippets delete 31 42             # Delete snippets in Redash and remove local files

Snippets don't have an archive concept in Redash — snippets delete removes the snippet on the server and deletes the local files in one step; there's no separate --cleanup flag.

File Structure

queries/
├── 123-mobile-crashes.sql
└── 123-mobile-crashes.yaml
dashboards/
└── 456-my-dashboard.yaml
snippets/
├── 31-reviewbot_e2e_action_ctcs.sql
└── 31-reviewbot_e2e_action_ctcs.yaml

Query IDs are embedded in filenames ({id}-{slug}.{ext}), so no separate config file is needed. Snippet filenames use {id}-{trigger}.{ext} (Redash snippets are keyed by trigger, not name).

Development

Pre-commit Hooks

The project uses clippy in pedantic mode:

cargo clippy --all-targets --all-features -- -W clippy::pedantic -D warnings

Install pre-commit hooks:

pip install pre-commit
pre-commit install

Building for Release

cargo build --release
./target/release/stmo-cli --help

Architecture

See CLAUDE.md for detailed architecture documentation.