feat: add anonymous CLI telemetry via PostHog by felipefreitag · Pull Request #123 · resend/resend-cli

felipefreitag · 2026-03-17T16:52:26Z

Fire-and-forget usage tracking (command name, OS, arch, CLI version). No PII collected.
Opt out with DO_NOT_TRACK=1 or RESEND_TELEMETRY_DISABLED=1.
Anonymous ID stored at ~/.config/resend/telemetry-id.

src/lib/telemetry.ts

jpvalery · 2026-03-17T17:03:17Z

src/lib/update-check.ts

+  if (full.startsWith('brew')) {
+    return 'homebrew';
+  }
+  return 'install-script';


Do we want an event for this?

It's a property on the event, not a separate event. The goal is to understand the distribution channel split (npm vs homebrew vs install script). It's a nice-to-have.

cubic-dev-ai

6 issues found across 4 files

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/cli.ts">

<violation number="1" location="src/cli.ts:164">
P2: Exclude the internal `telemetry flush` subprocess from the post-command update check. Right now every tracked command triggers a second `checkForUpdates()` run in the telemetry child.</violation>
</file>

<file name="tests/lib/telemetry.test.ts">

<violation number="1" location="tests/lib/telemetry.test.ts:158">
P2: Don't hardcode `macOS` here; this test will fail on Linux and Windows runners.</violation>

<violation number="2" location="tests/lib/telemetry.test.ts:159">
P2: This assertion codifies the missing `arch` field instead of testing the telemetry contract.</violation>
</file>

<file name="src/lib/telemetry.ts">

<violation number="1" location="src/lib/telemetry.ts:76">
P2: Don't print the telemetry notice during JSON/non-interactive runs; the first invocation currently writes to stderr in machine mode.</violation>

<violation number="2" location="src/lib/telemetry.ts:102">
P2: This argv construction breaks telemetry flushing for native binary installs because `process.argv[1]` is the user's command there, not a script path.</violation>

<violation number="3" location="src/lib/telemetry.ts:124">
P1: Validate the flush path before deleting it; this hidden command currently unlinks any readable file path the caller supplies.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

src/lib/telemetry.ts

src/cli.ts

tests/lib/telemetry.test.ts

src/lib/telemetry.ts

cubic-dev-ai

1 issue found across 7 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/build.mjs">

<violation number="1" location="scripts/build.mjs:10">
P2: The custom `.env` loader keeps surrounding quotes, so quoted `POSTHOG_PUBLIC_KEY` values are embedded incorrectly and telemetry requests use an invalid API key.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

scripts/build.mjs

cubic-dev-ai

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/workflows/test-telemetry-windows.yml">

<violation number="1" location=".github/workflows/test-telemetry-windows.yml:3">
P2: This workflow is effectively branch-locked to `feat-telemetry`, so telemetry CI checks won't run for normal PRs/mainline after this branch lifecycle ends.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

.github/workflows/test-telemetry-windows.yml

cubic-dev-ai

2 issues found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/workflows/test-telemetry-windows.yml">

<violation number="1" location=".github/workflows/test-telemetry-windows.yml:37">
P2: The test only fails when telemetry files remain, but it never asserts that a telemetry temp file was created. If telemetry doesn’t write a file at all, `remaining` stays 0 and the step still passes, masking regressions. Add a creation check before the consumption check.</violation>
</file>

<file name="src/lib/telemetry.ts">

<violation number="1" location="src/lib/telemetry.ts:65">
P2: The notice marker is written even when `interactive` is false, so a first non-interactive run suppresses the notice permanently. If the intent is to only skip output in non-interactive mode, the marker should only be written when the notice is actually shown.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

.github/workflows/test-telemetry-windows.yml

src/lib/telemetry.ts

cubic-dev-ai

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/workflows/test-telemetry-windows.yml">

<violation number="1" location=".github/workflows/test-telemetry-windows.yml:54">
P1: `fi` is invalid in this PowerShell script and will break the workflow step. Close the `if` block with `}` instead.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

.github/workflows/test-telemetry-windows.yml

Fire-and-forget usage tracking (command name, OS, arch, CLI version). No PII collected. Opt out with DO_NOT_TRACK=1 or RESEND_TELEMETRY_DISABLED=1. Anonymous ID stored at ~/.config/resend/telemetry-id.

Single boolean: isInteractive() && !opts.json Covers TTY, CI, piped, and --json/--quiet cases.

Spawn `resend telemetry flush <payload>` as a detached child process instead of calling fetch() inline, which either blocks exit or never completes. The child process POSTs to PostHog independently, adding no latency to the parent CLI command.

- Pass payload via temp file instead of CLI arg to avoid ps visibility - Validate JSON in flushPayload before sending - Use Commander public API for hidden command instead of _hidden - Skip tracking when no command was matched (bare `resend` invocation) - Replace os/arch with friendly os name (macOS, Windows, Linux) - Change detectInstallMethodName fallback to 'other'

Replace hardcoded API key with process.env.POSTHOG_PUBLIC_KEY, injected at bundle time through a build script using esbuild's define option. The key is sourced from .env (local) or env vars (CI). Telemetry silently no-ops when the key is absent. A verify-bundle script in prepack ensures the key is present before publishing. A preflight job in the release workflow catches missing secrets early.

Record which flags users pass (names only, never values) to understand feature usage and interactive-vs-explicit preference. Uses Commander's getOptionValueSource to capture only CLI-provided flags, split into command-specific `flags` and program-level `global_flags` arrays.

pkg-compiled binaries fail to spawn themselves without clearing PKG_EXECPATH. Also adds .env-based build-time key injection, flag tracking, and removes debug logging.

- Skip telemetry child from update check and re-tracking - Suppress first-run notice in non-interactive/JSON mode - Validate flush path is in tmpdir with expected naming pattern - Remove stale arch assertion from tests

- Skip telemetry child from update check and re-tracking - Suppress first-run notice in non-interactive/JSON mode - Validate flush path is in tmpdir with expected naming pattern - Add full spawn test for Windows CI

felipefreitag force-pushed the feat-telemetry branch from 116d27c to 21b6702 Compare March 17, 2026 16:55

jpvalery reviewed Mar 17, 2026

View reviewed changes

felipefreitag force-pushed the feat-telemetry branch from 7880617 to fb03736 Compare March 19, 2026 14:01

felipefreitag marked this pull request as ready for review March 19, 2026 14:01

cubic-dev-ai bot reviewed Mar 19, 2026

View reviewed changes

felipefreitag force-pushed the feat-telemetry branch from fb03736 to 5626301 Compare March 19, 2026 14:21

cubic-dev-ai bot reviewed Mar 19, 2026

View reviewed changes

scripts/build.mjs Outdated Show resolved Hide resolved

cubic-dev-ai bot reviewed Mar 19, 2026

View reviewed changes

.github/workflows/test-telemetry-windows.yml Outdated Show resolved Hide resolved

cubic-dev-ai bot reviewed Mar 19, 2026

View reviewed changes

.github/workflows/test-telemetry-windows.yml Outdated Show resolved Hide resolved

src/lib/telemetry.ts Outdated Show resolved Hide resolved

felipefreitag requested review from jpvalery and vcapretz March 19, 2026 19:55

cubic-dev-ai bot reviewed Mar 19, 2026

View reviewed changes

.github/workflows/test-telemetry-windows.yml Outdated Show resolved Hide resolved

vcapretz approved these changes Mar 19, 2026

View reviewed changes

felipefreitag added 17 commits March 19, 2026 17:20

feat: add anonymous CLI telemetry via PostHog

648a73a

Fire-and-forget usage tracking (command name, OS, arch, CLI version). No PII collected. Opt out with DO_NOT_TRACK=1 or RESEND_TELEMETRY_DISABLED=1. Anonymous ID stored at ~/.config/resend/telemetry-id.

refactor: rename telemetry event to cli.used

35c3b86

refactor: replace is_ci/json_mode with interactive flag

da96118

Single boolean: isInteractive() && !opts.json Covers TTY, CI, piped, and --json/--quiet cases.

fix: make telemetry test OS-agnostic for CI compatibility

94c4be5

fix: handle pkg compiled binary in telemetry self-invocation

580fe1d

fix: set PKG_EXECPATH for pkg binary self-invocation

714b701

pkg-compiled binaries fail to spawn themselves without clearing PKG_EXECPATH. Also adds .env-based build-time key injection, flag tracking, and removes debug logging.

ci: add Windows telemetry smoke test workflow

239c95b

fix: harden telemetry against review findings

2b7b54e

- Skip telemetry child from update check and re-tracking - Suppress first-run notice in non-interactive/JSON mode - Validate flush path is in tmpdir with expected naming pattern - Remove stale arch assertion from tests

fix: harden telemetry against review findings

c0d91a1

- Skip telemetry child from update check and re-tracking - Suppress first-run notice in non-interactive/JSON mode - Validate flush path is in tmpdir with expected naming pattern - Add full spawn test for Windows CI

ci: fix Windows telemetry test with PowerShell

f2c1f52

fix: strip surrounding quotes from .env values in build script

5ba457b

ci: verify temp file creation before checking consumption

c0ad46b

fix: only write notice marker when notice is actually shown

589b5e2

felipefreitag added 3 commits March 19, 2026 17:20

ci: fix PowerShell syntax in Windows telemetry test

6d36159

ci: remove push trigger from Windows telemetry test

b244f42

refactor: distinguish install-script from manual installs in detection

d36410d

felipefreitag force-pushed the feat-telemetry branch from f77a26f to d36410d Compare March 19, 2026 20:20

felipefreitag merged commit 1aa0f16 into main Mar 20, 2026
6 checks passed

felipefreitag deleted the feat-telemetry branch March 20, 2026 12:32

felipefreitag mentioned this pull request Mar 20, 2026

Add telemetry to track most used commands #38

Closed

Conversation

felipefreitag commented Mar 17, 2026

Uh oh!

Uh oh!

Uh oh!

jpvalery Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

felipefreitag Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants