Anonymous CLI usage analytics (telemetry)

[karava]

Measure real usage of the CLI tool itself — not website link clicks. Answer questions like: how many unique installs, daily/monthly actives, sessions started, which channels/modes are popular, which versions are in the wild.

What we already have

src/lib/listener.ts POSTs to devflow.fm/api/listeners every 15s during music playback, with a random per-session listenerId. So the server already sees music sessions — but:

• random per-session id ⇒ counts concurrent listeners, not unique installs/users;
• only fires when music plays (a --no-music timer session is invisible);
• the server tracks counts in memory (resets on deploy) — no durable history.

Proposal

• Persistent anonymous install id: generate a UUID once, store in ~/.config/devflow/config.json (or a sibling state file). Include it in pings.
• Start ping independent of music, so every devflow start is counted (channel, mode, --demo, client version, OS).
• Durable server store (e.g. NocoDB or a small DB) so uniques/DAU/MAU can be computed over time, not just live counts. Likely a dedicated /api/telemetry endpoint rather than overloading /api/listeners.

Privacy (decide deliberately)

• Anonymous only — no PII, no paths, no usernames.
• Disclose it — README + a one-line first-run note.
• Honor opt-out — config.telemetry = false, a --no-telemetry flag, and respect the DO_NOT_TRACK env var.

Acceptance

• Can report unique installs + DAU/MAU + popular channels/modes + version spread.
• Opt-out fully silences it; documented and disclosed.