feat: attribute web signups to the CLI via UTM parameters

[eze-githits]

Tags the OAuth authorization URL the CLI opens with the five standard utm_* parameters, so PostHog can attribute web signups to githits login and githits init.

No new dependencies, no network calls from the CLI, no analytics SDK bundled.

Parameters

Parameter	Value
utm_source	githits-cli
utm_medium	cli
utm_campaign	cli-login or cli-init
utm_content	CLI version

Only the five standard slots are used, because that is the exact set posthog-js auto-captures (CAMPAIGN_PARAMS) under the current frontend config. A custom name would need custom_campaign_params on the frontend and would capture nothing until that shipped.

Scope — please read before interpreting any number

This measures auth-page arrival → OAuth completion. It does not measure command execution → completion.

A UTM only exists once a browser requests the URL, so anyone who runs the command and never reaches the auth page produces no signal and is absent from the denominator. Numbers from this are a lower bound, not a conversion rate.

Signup vs sign-in does not come from the UTM. The URL is built before the user authenticates, so at tagging time it is not yet known whether an account will be created. The UTM carries origin only; the outcome comes from the frontend's own signup event, joined on the person at query time.

The frontend runs posthog-js with cookieless_mode: "on_reject", under which users who reject cookies have no $anon_distinct_id to link to their signup, and users who never answer the banner have their events dropped entirely. Treat the result as directional and comparative (cli-init vs cli-login, movement across releases) rather than absolute.

Full analysis, with citations to posthog-js source: docs/superpowers/specs/2026-07-27-cli-utm-attribution-design.md.

Notes on the implementation

• The URL is tagged once, immediately after buildAuthUrl, and the tagged value is used in all three places it is consumed: the browser open, the --no-browser printout, and the "browser did not open" fallback. Tagging only the browser path would drop attribution for SSH users and for anyone whose browser failed to launch — the segments most likely to abandon, which would bias the funnel upward.
• Tagging sits above buildAuthUrl rather than inside it. OAuth parameters are correctness-critical while attribution is best-effort; they should not share a failure mode. withUtm never throws and returns the URL unchanged if it does not parse.
• The CLI hardcodes no login URL. It discovers the authorization endpoint via OAuth metadata, so the parameters are appended to whatever discovery returns.

Blocking verification before this measures anything

The CLI side is complete but inert until confirmed, and none of it is verifiable from this repo:

1. The authorization endpoint preserves the query string through its redirect chain.
2. PostHog is initialised on a page the flow actually reaches.
3. The frontend signup event fires with identify() so the anonymous visit links to the account.

Two-minute check, no deploy needed: run githits login --no-browser, open the printed URL, and watch the address bar. If it passes through a frontend page with the utm_* still present, client-side capture works. If it jumps straight to github.com/login/oauth/authorize, the attribution has to be recorded server-side instead.

Worth inspecting first: the frontend already detects initial CLI install. If that works off a URL parameter, the UTMs should ride alongside it rather than duplicate it.

Testing

• src/shared/utm.test.ts — 5 unit tests (idempotency, unparseable input, parameter preservation, optional content)
• src/commands/login.test.ts — 4 tests covering both the opened and the printed URL, and that OAuth parameters survive tagging
• src/commands/init/init.test.ts — 1 test asserting cli-init on the printed URL

bun test on the touched suites: 186 pass. bun run build, bun run typecheck and bun run smoke:cli pass.

One unrelated pre-existing failure remains on main: exec-service.test.ts > rejects with error for non-existent command, verified to fail with this branch stashed.

🤖 Generated with Claude Code