feat: add anonymous CLI telemetry via PostHog

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.

Author: felipefreitag

src/cli.ts

@@ -20,9 +20,12 @@ import { updateCommand } from './commands/update';
 import { webhooksCommand } from './commands/webhooks/index';
 import { whoamiCommand } from './commands/whoami';
 import { errorMessage, outputError } from './lib/output';
+import { trackCommand } from './lib/telemetry';
 import { checkForUpdates } from './lib/update-check';
 import { PACKAGE_NAME, VERSION } from './lib/version';
 
+let lastCommandName = '';
+
 const program = new Command()
   .name('resend')
   .description('Resend CLI — email for developers')
@@ -50,6 +53,16 @@ const program = new Command()
     'Save API key as plaintext instead of secure storage',
   )
   .hook('preAction', (thisCommand, actionCommand) => {
+    const parts: string[] = [];
+    for (
+      let cmd = actionCommand;
+      cmd?.parent;
+      cmd = cmd.parent as typeof actionCommand
+    ) {
+      parts.unshift(cmd.name());
+    }
+    lastCommandName = parts.join(' ');
+
     if (actionCommand.optsWithGlobals().quiet) {
       thisCommand.setOptionValue('json', true);
     }
@@ -116,6 +129,9 @@ program
     if (ran === 'update') {
       return;
     }
+
+    trackCommand(lastCommandName, program.opts());
+
     return checkForUpdates().catch(() => {});
   })
   .catch((err) => {

src/lib/telemetry.ts

@@ -0,0 +1,87 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getConfigDir } from './config';
+import { detectInstallMethodName } from './update-check';
+import { VERSION } from './version';
+
+const POSTHOG_API_KEY = 'phc_REPLACE_ME';
+const POSTHOG_HOST = 'https://us.i.posthog.com/capture/';
+
+export function isDisabled(): boolean {
+  return (
+    process.env.DO_NOT_TRACK === '1' ||
+    process.env.RESEND_TELEMETRY_DISABLED === '1'
+  );
+}
+
+export function getOrCreateAnonymousId(): string {
+  const configDir = getConfigDir();
+  const idPath = join(configDir, 'telemetry-id');
+
+  try {
+    const existing = readFileSync(idPath, 'utf-8').trim();
+    if (existing) {
+      return existing;
+    }
+  } catch {}
+
+  const id = crypto.randomUUID();
+  mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  writeFileSync(idPath, id, { mode: 0o600 });
+  return id;
+}
+
+function showFirstRunNotice(): void {
+  const configDir = getConfigDir();
+  const markerPath = join(configDir, 'telemetry-notice-shown');
+
+  if (existsSync(markerPath)) {
+    return;
+  }
+
+  mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  writeFileSync(markerPath, '', { mode: 0o600 });
+
+  process.stderr.write(
+    '\nResend collects anonymous CLI usage data to improve the tool.\n' +
+      'To opt out: export RESEND_TELEMETRY_DISABLED=1\n\n',
+  );
+}
+
+export function trackCommand(command: string, opts: { json?: boolean }): void {
+  if (isDisabled()) {
+    return;
+  }
+
+  try {
+    showFirstRunNotice();
+
+    const distinctId = getOrCreateAnonymousId();
+
+    const payload = {
+      api_key: POSTHOG_API_KEY,
+      distinct_id: distinctId,
+      event: 'cli_command',
+      properties: {
+        command,
+        cli_version: VERSION,
+        os: process.platform,
+        arch: process.arch,
+        node_version: process.version,
+        is_ci:
+          process.env.CI === 'true' ||
+          process.env.CI === '1' ||
+          !!process.env.GITHUB_ACTIONS,
+        json_mode: !!opts.json,
+        install_method: detectInstallMethodName(),
+      },
+    };
+
+    fetch(POSTHOG_HOST, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(3000),
+    }).catch(() => {});
+  } catch {}
+}

src/lib/update-check.ts

@@ -89,6 +89,17 @@ function shouldSkipCheck(): boolean {
   return false;
 }
 
+export function detectInstallMethodName(): string {
+  const full = detectInstallMethod();
+  if (full.startsWith('npm')) {
+    return 'npm';
+  }
+  if (full.startsWith('brew')) {
+    return 'homebrew';
+  }
+  return 'install-script';
+}
+
 export function detectInstallMethod(): string {
   const execPath = process.execPath || process.argv[0] || '';
   const scriptPath = process.argv[1] || '';

tests/lib/telemetry.test.ts

@@ -0,0 +1,156 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  type MockInstance,
+  test,
+  vi,
+} from 'vitest';
+import {
+  getOrCreateAnonymousId,
+  isDisabled,
+  trackCommand,
+} from '../../src/lib/telemetry';
+import { captureTestEnv } from '../helpers';
+
+const testConfigDir = join(tmpdir(), `resend-telemetry-test-${process.pid}`);
+const testResendDir = join(testConfigDir, 'resend');
+
+describe('isDisabled', () => {
+  const restoreEnv = captureTestEnv();
+
+  afterEach(() => {
+    restoreEnv();
+  });
+
+  test('returns true when DO_NOT_TRACK=1', () => {
+    process.env.DO_NOT_TRACK = '1';
+    delete process.env.RESEND_TELEMETRY_DISABLED;
+    expect(isDisabled()).toBe(true);
+  });
+
+  test('returns true when RESEND_TELEMETRY_DISABLED=1', () => {
+    delete process.env.DO_NOT_TRACK;
+    process.env.RESEND_TELEMETRY_DISABLED = '1';
+    expect(isDisabled()).toBe(true);
+  });
+
+  test('returns false when neither env var set', () => {
+    delete process.env.DO_NOT_TRACK;
+    delete process.env.RESEND_TELEMETRY_DISABLED;
+    expect(isDisabled()).toBe(false);
+  });
+});
+
+describe('getOrCreateAnonymousId', () => {
+  const restoreEnv = captureTestEnv();
+
+  beforeEach(() => {
+    mkdirSync(testResendDir, { recursive: true });
+    process.env.XDG_CONFIG_HOME = testConfigDir;
+  });
+
+  afterEach(() => {
+    restoreEnv();
+    if (existsSync(testConfigDir)) {
+      rmSync(testConfigDir, { recursive: true, force: true });
+    }
+  });
+
+  test('creates and persists a UUID', () => {
+    const id = getOrCreateAnonymousId();
+    expect(id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+
+    const stored = readFileSync(join(testResendDir, 'telemetry-id'), 'utf-8');
+    expect(stored).toBe(id);
+  });
+
+  test('returns same ID on subsequent calls', () => {
+    const first = getOrCreateAnonymousId();
+    const second = getOrCreateAnonymousId();
+    expect(first).toBe(second);
+  });
+});
+
+describe('trackCommand', () => {
+  const restoreEnv = captureTestEnv();
+  let fetchSpy: MockInstance;
+  let stderrSpy: MockInstance;
+
+  beforeEach(() => {
+    mkdirSync(testResendDir, { recursive: true });
+    process.env.XDG_CONFIG_HOME = testConfigDir;
+    delete process.env.DO_NOT_TRACK;
+    delete process.env.RESEND_TELEMETRY_DISABLED;
+
+    fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+      ok: true,
+    } as Response);
+
+    stderrSpy = vi
+      .spyOn(process.stderr, 'write')
+      .mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+    stderrSpy.mockRestore();
+    restoreEnv();
+    if (existsSync(testConfigDir)) {
+      rmSync(testConfigDir, { recursive: true, force: true });
+    }
+  });
+
+  test('sends correct payload to PostHog endpoint', () => {
+    trackCommand('emails send', { json: true });
+
+    expect(fetchSpy).toHaveBeenCalledOnce();
+    const [url, options] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('https://us.i.posthog.com/capture/');
+    expect(options.method).toBe('POST');
+
+    const body = JSON.parse(options.body as string);
+    expect(body.event).toBe('cli_command');
+    expect(body.properties.command).toBe('emails send');
+    expect(body.properties.json_mode).toBe(true);
+    expect(body.properties.os).toBe(process.platform);
+    expect(body.properties.arch).toBe(process.arch);
+    expect(body.properties.node_version).toBe(process.version);
+    expect(body.api_key).toBeTruthy();
+    expect(body.distinct_id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+  });
+
+  test('does nothing when disabled', () => {
+    process.env.RESEND_TELEMETRY_DISABLED = '1';
+    trackCommand('emails send', {});
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  test('handles fetch failures gracefully', () => {
+    fetchSpy.mockRejectedValue(new Error('network error'));
+    expect(() => trackCommand('emails send', {})).not.toThrow();
+  });
+
+  test('shows first-run notice only once', () => {
+    trackCommand('emails send', {});
+    const notice1 = stderrSpy.mock.calls.length;
+
+    trackCommand('domains list', {});
+    const notice2 = stderrSpy.mock.calls.length;
+
+    expect(notice1).toBe(1);
+    expect(notice2).toBe(1);
+
+    expect(existsSync(join(testResendDir, 'telemetry-notice-shown'))).toBe(
+      true,
+    );
+  });
+});