feat: telemetry opt-out command + first-run notice

[nicknisi]

Summary

Gives users a first-class, reversible way to opt out of CLI telemetry (collection stays on by default) plus a one-time notice that it's happening. Closes the trust/norms gap left by the always-on telemetry added in #122 — until now the only control was the undocumented WORKOS_TELEMETRY=false env var.

What's included

• workos telemetry opt-out / opt-in / status — reversible commands. status reports the effective state and its source (env var / saved preference / default), with human and JSON output.
• Persisted preference at a plain ~/.workos/preferences.json (mirrors the non-secret device-id file pattern — no keyring, no insecure-fallback warning). Folded into the single Analytics.isEnabled() gate so opt-out suppresses all event types (session.start, command, crash).
• Env precedence — WORKOS_TELEMETRY overrides the saved preference in both directions for that invocation. Replaced the import-time WORKOS_TELEMETRY_ENABLED const (which conflated "unset" with "true") with a call-time tri-state isTelemetryEnabled() resolver.
• First-run notice — one-time, stderr-only box (human/interactive mode only; suppressed in --json/non-TTY/CI and when already opted out), backed by a persisted noticeShownAt timestamp. Marked shown only when actually displayed, so a human eventually sees it even if early runs are scripted.
• telemetry is skip-listed so managing your preference never itself emits telemetry; registered in the help-json command tree.
• debug integration — debug state surfaces telemetry enabled/optedOut/source/noticeShown + the preferences path; debug reset clears preferences alongside config.
• Box rendering fix — renderStderrBox was single-line-only and broke its border when a message exceeded the terminal width. Now wraps (ANSI-aware), fixing the notice on narrow terminals and benefiting the unclaimed-env warning/provision boxes too.

Testing

• pnpm test — 2028 tests pass (new specs for the preferences store, the telemetry command, the first-run notice gates, the box wrapping, and debug integration).
• Integration spec proves opt-out emits zero events and that env precedence holds both directions.
• pnpm typecheck and pnpm build pass; changed files pass oxfmt --check.

Manual

workos telemetry status            # enabled, source: default
workos telemetry opt-out
workos telemetry status            # disabled, source: saved preference
WORKOS_TELEMETRY=true workos telemetry status   # enabled, source: env var

Notes

• Two local-only files were intentionally left out of this PR: scripts/test-local-telemetry.sh (contains a hardcoded local-dev API key) and scripts/datadog-cli-dashboard.json. Flag if either should be tracked (the script needs the key removed first).

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR adds first-class, reversible telemetry opt-out to the WorkOS CLI. It introduces a preferences.json store (~/.workos/preferences.json), three new workos telemetry subcommands (opt-out, opt-in, status), a one-time first-run notice on stderr, a fix to the box renderer for narrow terminals, and replaces the import-time WORKOS_TELEMETRY_ENABLED constant with a call-time isTelemetryEnabled() resolver that correctly interprets the env var as a tri-state override.

• src/lib/preferences.ts — New store with an async prewarm (loadPreferences), a synchronous cached accessor (getPreferences), a read-modify-write save that preserves unrelated fields, and a clearPreferences used by debug reset.
• src/lib/telemetry-notice.ts — First-run stderr notice with per-session and persistent guards; correctly sets shownThisSession only after a successful render and marks the disk only after render, so a write failure retries rather than silently suppressing.
• src/utils/box.ts — renderStderrBox now wraps ANSI-aware on narrow terminals instead of letting the border break; the token regex treats each self-closing chalk span as an atomic unit.

Confidence Score: 5/5

Safe to merge — all changed paths are additive, non-breaking, and backed by comprehensive unit and integration tests.

The preferences store, notice gating, box renderer, and telemetry resolver are all correctly implemented with no observable defects. The most subtle invariants — render-then-persist ordering in the notice, truthy-empty-object sentinel after clearPreferences, and the tri-state env resolver — are each verified by dedicated tests. The shift from an import-time constant to a call-time isTelemetryEnabled() is backward-compatible and correctly prewarmed before any events fire.

No files require special attention.

Important Files Changed

Filename	Overview
src/lib/preferences.ts	New preferences store with async prewarm, synchronous cached fallback, read-modify-write save, and clearPreferences. Cache logic is correct: empty-object sentinel (truthy) is used after clearPreferences so subsequent reads skip disk. Deep merge of the telemetry sub-object correctly preserves unrelated fields like noticeShownAt when only optedOut changes.
src/lib/telemetry-notice.ts	First-run notice gates (json mode, opted-out, already shown, per-session flag) are ordered correctly. shownThisSession and markNoticeShown are set only after a successful render, so a render or write failure retries on the next call within the session.
src/utils/box.ts	wrapAnsiAware tokenizes colored spans as atomic units so chalk color doesn't bleed across wrap boundaries. renderStderrBox fast-path is unchanged; wrap-path correctly snugs the border to the longest wrapped line. Documented limitation on stacked SGR styles is acceptable given current callers use only single-layer chalk colors.
src/utils/analytics.ts	isEnabled() now delegates to isTelemetryEnabled() (call-time resolver) instead of the import-time WORKOS_TELEMETRY_ENABLED constant. Since loadPreferences() is awaited in bin.ts before initForNonInstaller(), the cache is warm before any events fire.
src/commands/telemetry.ts	New opt-out/opt-in/status commands. persistOptedOut wraps the write and surfaces a CliExit on failure so users see a clear error rather than a silent no-op. Status command correctly exposes the tri-state source via describeSource.
src/bin.ts	loadPreferences() is correctly awaited before analytics.initForNonInstaller(). Telemetry middleware skips the notice for command === 'telemetry' and command === '' (bare help/version). The WORKOS_TELEMETRY_ENABLED import is cleanly removed.
src/bin-command-telemetry.integration.spec.ts	New integration tests cover opted-out preference suppressing all events, env=true overriding an opt-out, and env=false suppressing events on a fresh install. WORKOS_TELEMETRY='' (empty string) correctly falls through to the preference in the tri-state resolver. pendingDir ENOENT is now handled with try/catch.
src/commands/debug.ts	debug state now reports telemetry enabled/optedOut/source/noticeShown and the preferences path. debug reset clears preferences alongside config (clearPrefs = clearConf) — consistent with the 'preferences ride with config' design decision.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[bin.ts startup] --> B[await loadPreferences]
    B --> C[analytics.initForNonInstaller]
    C --> D[yargs middleware]
    D --> E{command === 'telemetry' or empty?}
    E -- yes --> F[skip notice]
    E -- no --> G[maybeShowTelemetryNotice]
    G --> H{isJsonMode?}
    H -- yes --> I[suppress]
    H -- no --> J{isTelemetryOptedOut?}
    J -- yes --> I
    J -- no --> K{isNoticeShown?}
    K -- yes --> I
    K -- no --> L[renderStderrBox]
    L --> M[shownThisSession = true]
    M --> N[markNoticeShown — persist noticeShownAt]

    O[workos telemetry opt-out] --> P[persistOptedOut true]
    P --> Q[savePreferences — read-modify-write]
    Q --> R[cached = merged]

    S[isTelemetryEnabled] --> T{envTelemetryOverride?}
    T -- true/false --> U[return env value]
    T -- undefined --> V{isTelemetryOptedOut?}
    V -- true --> W[return false]
    V -- false --> X[return true — default on]

    Y[analytics.isEnabled] --> S

Loading

_{Reviews (2): Last reviewed commit: "chore(telemetry): drop unused savePrefer..." | Re-trigger Greptile}

[devin-ai-integration]

Devin Review found 1 potential issue.

View 6 additional findings in Devin Review.

[nicknisi]

Addressed review feedback in f969135:

• telemetry-notice (devin): opt-out command now rendered via formatWorkOSCommand('telemetry opt-out'), so npx users get the working invocation instead of a hardcoded workos .... Added a regression test.
• telemetry-notice (greptile): shownThisSession/markNoticeShown now run only after a successful render, so a render failure lets a later command retry instead of suppressing the notice for the rest of the session.
• preferences getTelemetrySource (greptile): returns default (not preference) when optedOut === false, matching isTelemetryEnabled()'s precedence — an opted-in state is indistinguishable from a fresh install. Updated the corresponding test.
• preferences (greptile): removed the unused mkdir import.
• box wrapping (greptile): documented the single-level-SGR assumption (stacked/adjacent spans not guaranteed atomic) and the long atomic-token overflow caveat (e.g. the npx command form on very narrow terminals). Did not change the regex — a multi-layer pattern would mis-group adjacent spans and regress color for no current caller.

pnpm test (2029), typecheck, build, and oxfmt --check all pass.