Add opt-in telemetry for CLI command usage tracking

[mayashavin]

Summary

Add lightweight, opt-in telemetry to track CLI command usage patterns. This helps prioritize features, identify common workflows, and understand how users configure Polira — without collecting any content or personal data.

Privacy principles

• Opt-in only: telemetry is off by default, users must explicitly enable it
• No content collection: never send markdown content, file paths, API keys, or generated text
• Anonymous: no user identifiers, emails, or IP tracking
• Transparent: users can see exactly what is collected before opting in
• Revocable: users can opt out at any time

What to collect

• Command name (e.g. analyze, seo, review, fix, cover, prepare)
• Command flags used (e.g. --apply, --mode strong, --json)
• Polira version
• Node.js version
• OS platform (darwin, linux, win32)
• Config: which provider/storage type is configured (not values, just the type)
• Execution outcome (success / error code, not error message)
• Execution duration (ms)

What NOT to collect

• File paths or file content
• API keys or credentials
• AI model responses or suggestions
• Generated image data
• User identity or machine identifiers
• IP addresses

User experience

Opt-in via config init

Add a telemetry prompt to polira config init:

? Enable anonymous usage telemetry? (helps improve Polira) No

Opt-in via config

export default {
  telemetry: {
    enabled: true,
  },
};

Opt-in via CLI

polira config telemetry --enable
polira config telemetry --disable
polira config telemetry --status     # Show current setting and what is collected

Environment variable override

POLIRA_TELEMETRY=0  # Disable regardless of config

First-run notice

On first command run (when telemetry is not explicitly set), display a one-time notice:

Polira can collect anonymous usage data to help improve the tool.
Run "polira config telemetry --enable" to opt in.
This message will not appear again.

Implementation approach

Config changes

Add telemetry section to PoliraConfig:

telemetry?: {
  enabled: boolean;
};

Architecture

• Create src/core/telemetry.ts — telemetry client with event batching
• Events are queued in memory during command execution
• Batch is sent asynchronously after command completes (non-blocking)
• Failed sends are silently dropped (never affect CLI behavior)
• A local file within the project (/.config/polira/.telemetry-notice) tracks whether the first-run notice has been shown

Backend

• Use a lightweight analytics endpoint (e.g. PostHog, Mixpanel, or a simple custom API)
• Consider a self-hosted option for full data control

Task list

• Add telemetry section to PoliraConfig type and schema
• Create src/core/telemetry.ts with event collection and sending
• Add telemetry prompt to polira config init
• Add polira config telemetry subcommand (--enable, --disable, --status)
• Instrument all CLI commands to emit telemetry events
• Add first-run notice logic
• Support POLIRA_TELEMETRY=0 environment variable override
• Add documentation explaining what is collected
• Choose and integrate analytics backend
• Add tests for telemetry collection (mocked sender)