telemetrydeck-analytics

Files (13)

• SKILL.md
• reference.md
• tdq.py
• aggregators.md · tql/
• dimensions.md · tql/
• filters.md · tql/
• funnel.md · tql/
• granularity.md · tql/
• index.md · tql/
• intervals.md · tql/
• query-types.md · tql/
• recipes.md · tql/
• retention.md · tql/

SKILL.md (first lines)

# TelemetryDeck Analytics

Answers product-analytics questions against the TelemetryDeck v3 API via the bundled `tdq` CLI. Stdlib-only, cross-platform, OS-native secret storage, no `.env`, no repo-local files.

This skill ships as part of the `telemetrydeck-analytics` Claude plugin. While the plugin is enabled, the `tdq` wrapper is on `PATH`, so you can call it directly as `tdq <subcommand>`. If the wrapper isn't available (e.g. running outside Claude Code), fall back to `python3 "$SKILL_DIR/tdq.py" <subcommand>`.

## User-invokable slash skills

The plugin exposes focused slash commands for common tasks — prefer them when the user's intent maps cleanly to one:

| Slash command | What it does |
|---|---|
| `/telemetrydeck-analytics:setup` | First-run login + app picker. |
| `/telemetrydeck-analytics:doctor` | End-to-end health check. |
| `/telemetrydeck-analytics:apps [list\|use\|add\|remove\|refresh]` | Manage registered apps. |
| `/telemetrydeck-analytics:dau [args]` | Daily active users. |
| `/telemetrydeck-analytics:mau [args]` | Monthly active users. |
| `/telemetrydeck-analytics:groupby <dim> [args]` | Breakdown by a dimension. |
| `/telemetrydeck-analytics:events` | Schema discovery (7d + 30d event counts). |
| `/telemetrydeck-analytics:signals [args]` | Top-N events, raw pipeline triage. |
| `/telemetrydeck-analytics:query <file or TQL>` | Run raw TQL. |
| `/telemetrydeck-analytics:report <question>` | Generate a markdown analytics report. |

This main skill handles the ambient / conversational case ("is the Pro share growing?", "why aren't signals arriving?") — it's model-invoked when a question needs analytics but doesn't match a slash command exactly.

## First-run setup (once per machine)

```bash
tdq login
```

Prompts for email and password, mints a bearer, then **lists the apps on your TelemetryDeck account and asks you to pick one**. No need to know the app UUID up front. If the listing endpoint isn't exposed for your account, the CLI falls back to a manual UUID prompt.

Secrets (password + bearer) go into the OS-native store:
- **macOS** — Keychain via `security` (service `telemetrydeck-cli`).
- **Linux** — libsecret via `secret-tool` if installed (GNOME Keyring, KWallet-libsecret, etc.).
- **Windows / Linux without `secret-tool`** — file fallback at `<config-dir>/secrets.json` mode 0600, with a one-time stderr warning. Install `libsecret-tools` on Linux (`apt install libsecret-tools`) for a proper keyring.

Non-secret state (email, registered apps, token expiry) lives in a platform-appropriate config directory:
- macOS: `~/Library/Application Support/TelemetryDeckCLI/config.json`
- Linux: `$XDG_CONFIG_HOME/TelemetryDeckCLI/config.json` (or `~/.config/...`)
- Windows: `%APPDATA%\TelemetryDeckCLI\config.json`

After setup, every subcommand auto-refreshes the bearer on expiry or HTTP 401.

`$SKILL_DIR` = the absolute directory of this SKILL.md (inside the plugin at `skills/analytics/`). Use it to read bundled reference files (`tql/index.md`, `reference.md`); prefer the `tdq` PATH wrapper for invocations when it is available, otherwise fall back to `python3 "$SKILL_DIR/tdq.py"` as noted above.

Verify setup:

```bash
tdq doctor
```

Reports pass/fail for platform (+ which secret backend is active), config, secret store, auth, and a trivial query round-trip with remediation hints.

## Managing multiple apps

If your TelemetryDeck account has more than one app, the CLI registers them all at `login` time. Switch between them, add more, or remove entries with the `apps` subcommand:

```bash
tdq apps                       # list registered apps, * marks current
tdq apps use MyApp             # switch by display name
tdq apps use <uuid>            # switch by UUID
tdq apps use 2                 # switch by 1-based index from `apps`
tdq apps add <uuid> --name "New App" [--set-current]
tdq apps remove <uuid-or-name-or-index>
tdq apps refresh               # re-pull the list from the API
```

Every query command also accepts a one-off `--app-id <UUID>` flag that bypasses the current-app setting for a single invocation.

## Subcommands

| Command | Purpose |
|---|---|
| `login [--app-id UUID] [--reset]` | Email/password prompt, mint bearer, interactive app picker. `--app-id` skips the picker. |
| `apps [list\|use\|add\|remove\|refresh]` | Manage the registered apps and switch the current one. Bare `apps` = list. |
| `logout` | Wipe stored secrets and config file. |
| `whoami` | Show user/org info (raw JSON). |
| `doctor` | End-to-end setup check. Fails if the round-trip returns zero rows. |
| `test` | Runs 3 known-good queries (timeseries, topN, groupBy), prints raw post-unwrap JSON + parsed row counts. Use when results look suspicious or after an API change. |
| `dau [--interval S\|--days N] [--event E]` | Daily active users (cardinality of `clientUser` per day). |
| `mau [--interval S\|--months N] [--event E]` | Monthly active users. |
| `groupby <dim> [--event E] [--interval S\|--days N] [--metric count\|users]` | Break down event count or user count by any dimension. |
| `events [--top N]` | Schema discovery: merged 7-day + 30-day event list with counts. |
| `signals [--days N] [--top N]` | Top-N event names — raw pipeline triage. |
| `insights` / `insight <id> [--days N]` | List / run saved dashboard insights. |
| `query <file\|-> [--include-test-mode]` | Run raw TQL from file or stdin. |

All query-producing commands share `--format table|csv|json` (default: `table` — markdown-ready for direct paste into a report), `--app-id <UUID>`, and `--raw`.

**`--raw` / `TDQ_RAW=1`**: prints the raw (post-envelope-unwrap) TelemetryDeck response to **stderr** before the formatted output. Reach for this the moment the formatted table says `(no rows)` — if the raw blob is non-empty, the parser dropped data (file a bug or re-check `_flatten_result`); if the raw blob itself is empty or a success-envelope with `"rows": []`, the query is genuinely empty and you need to widen the window or fix the filter.

**Named intervals** (`--interval`) accepted by `dau`, `mau`, `groupby`:
`last-Nd` for any N (e.g. `last-7d`, `last-30d`, `last-90d`), plus calendar-aware windows
`last-week`, `this-week`, `last-month`, `this-month`, `last-year`, `this-year`,
with aliases `wtd`, `mtd`, `ytd`. `--interval` wins over `--days` / `--months` when both are set.

**Period comparison** (`--compare prior-period`) on `dau`, `mau`, `groupby`: runs the same query against the immediately prior period, joins on the dimension (for `topN` / `groupBy`) or sums metrics (for `timeseries`), and emits one row per key with `current`, `prior`, `delta`, `pct` columns. For `last-Nd`, prior = the preceding N days. For `last-week`/`last-month`/`last-year`, prior = the completed period before that. For `this-X` to-date intervals, prior = the full last-X calendar period (note: this compares partial-to-full, which is usually what you want for "trending up?" questions but may understate growth early in a period — call this out in reports).

The `query` subcommand auto-injects the mandatory `appID` + `isTestMode=false` filter when the TQL has no `filter` key or sets it to the sentinel `{ "__auto_app_and_test_mode_filter__": true }`. If you write your own `filter`, include both selectors yourself — otherwise the result mixes other apps in the tenant and test-mode traffic.

## Worked example — "Is license mix shifting?"

```
User: "Has our Pro share grown month-over-month?"
```

Claude runs:

```bash
tdq groupby license --event App_launched \
  --interval last-30d --compare prior-period
```

Output:

```
| license | count_current | count_prior | delta | pct     |

From agenkin/telemetrydeck-analytics, MIT.

More from agenkin/telemetrydeck-analytics