feat(auth): identify accounts and add structured login telemetry

Link a successful login (OAuth or API-key) to the account identity via
PostHog identify, disclose telemetry + identity linking on first run, and
emit structured started/completed/failed events per login attempt with
method and failure reason so login funnels are queryable by branch instead
of a generic command-complete event.

Author: miguel-heygen

README.md

@@ -190,7 +190,7 @@ heygen config list       # show all settings with sources
 
 ## Reporting bugs
 
-- **Quick signal (recommended for agents):** `heygen feedback --rating <1-5> --comment "..."`. Goes to private, anonymous analytics. Safe to run unattended.
+- **Quick signal (recommended for agents):** `heygen feedback --rating <1-5> --comment "..."`. Goes to private, anonymous analytics. Safe to run unattended. Usage telemetry is anonymous until you sign in: running `heygen auth login` links it to your account email or username. A one-time notice prints the first time analytics runs; opt out anytime with `HEYGEN_NO_ANALYTICS=1` (or `heygen config set analytics false`).
 - **Tracked bug a maintainer should see:** open a [GitHub issue](https://github.com/heygen-com/heygen-cli/issues). This repo is **public**, so review what you paste first and omit anything sensitive (API keys, prompts, internal URLs, personal data).
 
 **Agents:** do not open GitHub issues automatically. Use `heygen feedback` for bug signal; if something seems worth tracking, surface it to the user and let a human file the issue after reviewing it for sensitive content.

cmd/heygen/auth_login.go

@@ -12,6 +12,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/heygen-com/heygen-cli/internal/analytics"
 	"github.com/heygen-com/heygen-cli/internal/auth"
 	"github.com/heygen-com/heygen-cli/internal/auth/oauth"
 	clierrors "github.com/heygen-com/heygen-cli/internal/errors"
@@ -20,6 +21,35 @@ import (
 	"golang.org/x/term"
 )
 
+// loginAnalyticsClient is the subset of *analytics.Client this file calls,
+// factored out as an interface so tests can inject a spy without needing a
+// real PostHog capture client (internal/analytics's own stubCaptureClient
+// is the lower-level equivalent used in that package's tests).
+type loginAnalyticsClient interface {
+	IdentifyAccount(distinctId string)
+	AuthLoginStarted(method string)
+	AuthLoginCompleted(method string)
+	AuthLoginFailed(method, reason string)
+}
+
+// loginAnalytics is the process-wide analytics client login telemetry
+// calls into. main() sets it to the real client once at startup; left at
+// its inert zero value here so any test that builds the login commands
+// directly (bypassing main()) gets a no-op, matching analytics.New(_,
+// false)'s existing disabled-client contract.
+var loginAnalytics loginAnalyticsClient = &analytics.Client{}
+
+// identityKey picks the identity a successful login links analytics to:
+// email if present, otherwise username. Deliberately narrower than
+// UserInfo.DisplayName() (which also falls back to "first last") — this
+// links a PostHog person to a stable login handle, not a display string.
+func identityKey(userInfo auth.UserInfo) string {
+	if userInfo.Email != "" {
+		return userInfo.Email
+	}
+	return userInfo.Username
+}
+
 // oauthLoginConfig is overridable in tests so the login flow can be
 // driven against an httptest IdP without spawning a real browser.
 type oauthLoginConfig struct {
@@ -187,6 +217,8 @@ var runAuthLoginTestDeps *runAuthLoginDeps
 // override is in effect, else we default to the API-key flow.
 func runAuthLogin(cmd *cobra.Command, ctx *cmdContext, flags authLoginFlags) error {
 	if flags.deviceCodeMode {
+		loginAnalytics.AuthLoginStarted("device_code")
+		loginAnalytics.AuthLoginFailed("device_code", "device_code_unsupported")
 		return clierrors.NewUsage(
 			"--device-code is not yet supported; use the default browser flow or --api-key",
 		)
@@ -219,8 +251,10 @@ func runAuthLogin(cmd *cobra.Command, ctx *cmdContext, flags authLoginFlags) err
 
 	switch {
 	case flags.oauthMode:
+		loginAnalytics.AuthLoginStarted("oauth")
 		return deps.runOAuth(cmd, ctx)
 	case flags.apiKeyMode:
+		loginAnalytics.AuthLoginStarted("api_key")
 		return deps.runAPIKey(cmd, ctx)
 	}
 
@@ -230,6 +264,8 @@ func runAuthLogin(cmd *cobra.Command, ctx *cmdContext, flags authLoginFlags) err
 	// keystrokes), and only when nothing in the environment has asked
 	// us to behave non-interactively.
 	if deps.stdinIsTerminal() && deps.stdoutIsTerminal() && !deps.nonInteractive() {
+		// No AuthLoginStarted here — the picker hasn't resolved a method
+		// yet. A cancel below must emit no started/failed pair at all.
 		choice, err := deps.runPicker(cmd.Context(), cmd.InOrStdin(), cmd.ErrOrStderr())
 		if err != nil {
 			if errors.Is(err, pickerCanceledError{}) || errorsAsPickerCanceled(err) {
@@ -239,8 +275,10 @@ func runAuthLogin(cmd *cobra.Command, ctx *cmdContext, flags authLoginFlags) err
 		}
 		switch choice {
 		case loginChoiceOAuth:
+			loginAnalytics.AuthLoginStarted("oauth")
 			return deps.runOAuth(cmd, ctx)
 		case loginChoiceAPIKey:
+			loginAnalytics.AuthLoginStarted("api_key")
 			return deps.runAPIKey(cmd, ctx)
 		default:
 			return clierrors.New(fmt.Sprintf("unknown login choice: %d", choice))
@@ -251,6 +289,7 @@ func runAuthLogin(cmd *cobra.Command, ctx *cmdContext, flags authLoginFlags) err
 	// decision: agents and CI runners feed keys on stdin, and the
 	// browser-OAuth dance has nowhere to land its loopback callback
 	// when there's no human to click "Allow".
+	loginAnalytics.AuthLoginStarted("api_key")
 	return deps.runAPIKey(cmd, ctx)
 }
 
@@ -273,9 +312,11 @@ func errorsAsPickerCanceled(err error) bool {
 func runAPIKeyLogin(cmd *cobra.Command, ctx *cmdContext) error {
 	key, err := readAPIKey(cmd.InOrStdin(), cmd.ErrOrStderr())
 	if err != nil {
+		loginAnalytics.AuthLoginFailed("api_key", "api_key_aborted")
 		return err
 	}
 	if key == "" {
+		loginAnalytics.AuthLoginFailed("api_key", "api_key_invalid_input")
 		if stdinIsTerminalFunc() {
 			return clierrors.NewUsage(
 				"no API key entered — type your key after the prompt, or paste it.",
@@ -340,6 +381,9 @@ func runAPIKeyLogin(cmd *cobra.Command, ctx *cmdContext) error {
 		if saveErr := auth.SaveUserInfo(userInfo); saveErr != nil {
 			fmt.Fprintf(cmd.ErrOrStderr(), "(warning: could not persist user info: %v)\n", saveErr)
 		}
+		if id := identityKey(userInfo); id != "" {
+			loginAnalytics.IdentifyAccount(id)
+		}
 	} else if clearErr := auth.ClearUserInfo(); clearErr != nil {
 		// Probe failed but a stale user block from a prior login may
 		// still be on disk. Best-effort clear; a failure here is
@@ -372,6 +416,7 @@ func runAPIKeyLogin(cmd *cobra.Command, ctx *cmdContext) error {
 	if err != nil {
 		return clierrors.New(fmt.Sprintf("failed to encode response: %v", err))
 	}
+	loginAnalytics.AuthLoginCompleted("api_key")
 	if display := userInfo.DisplayName(); display != "" {
 		fmt.Fprintf(cmd.ErrOrStderr(), "Logged in as %s\n", display)
 	}
@@ -389,6 +434,7 @@ func runOAuthLogin(cmd *cobra.Command, ctx *cmdContext, cfg oauthLoginConfig) er
 	// guard when cfg.OpenBrowser is injected (test path drives the
 	// callback synthetically). (N1)
 	if cfg.OpenBrowser == nil && isHeadlessOAuthShell() {
+		loginAnalytics.AuthLoginFailed("oauth", "headless_shell")
 		return clierrors.NewUsage(
 			"cannot complete browser OAuth flow in a headless shell " +
 				"(no TTY and BROWSER=none / HEYGEN_NO_BROWSER=1).\n" +
@@ -446,18 +492,22 @@ func runOAuthLogin(cmd *cobra.Command, ctx *cmdContext, cfg oauthLoginConfig) er
 	var loopbackResult oauth.LoopbackResult
 	select {
 	case <-cmdCtx.Done():
+		loginAnalytics.AuthLoginFailed("oauth", "oauth_timeout")
 		return clierrors.New(fmt.Sprintf("oauth: timed out waiting for browser callback: %v", cmdCtx.Err()))
 	case loopbackResult = <-results:
 	}
 	if loopbackResult.Err != nil {
+		loginAnalytics.AuthLoginFailed("oauth", "oauth_flow_error")
 		return clierrors.New(loopbackResult.Err.Error())
 	}
 
 	tok, err := oc.ExchangeAuthorizationCode(cmdCtx, loopbackResult.Code, verifier, loopbackResult.RedirectURI)
 	if err != nil {
+		loginAnalytics.AuthLoginFailed("oauth", "token_exchange_failed")
 		return clierrors.New(fmt.Sprintf("oauth: token exchange failed: %v", err))
 	}
 	if tok.AccessToken == "" {
+		loginAnalytics.AuthLoginFailed("oauth", "token_exchange_failed")
 		return clierrors.New("oauth: token endpoint returned no access_token")
 	}
 
@@ -508,6 +558,9 @@ func runOAuthLogin(cmd *cobra.Command, ctx *cmdContext, cfg oauthLoginConfig) er
 		if saveErr := auth.SaveUserInfo(userInfo); saveErr != nil {
 			fmt.Fprintf(cmd.ErrOrStderr(), "(warning: could not persist user info: %v)\n", saveErr)
 		}
+		if id := identityKey(userInfo); id != "" {
+			loginAnalytics.IdentifyAccount(id)
+		}
 	} else if clearErr := auth.ClearUserInfo(); clearErr != nil {
 		// Probe failed AND the file might still hold a stale user block
 		// from a prior login (different account). Best-effort clear; a
@@ -546,6 +599,7 @@ func runOAuthLogin(cmd *cobra.Command, ctx *cmdContext, cfg oauthLoginConfig) er
 	if err != nil {
 		return clierrors.New(fmt.Sprintf("failed to encode response: %v", err))
 	}
+	loginAnalytics.AuthLoginCompleted("oauth")
 	if display := userInfo.DisplayName(); display != "" {
 		fmt.Fprintf(cmd.ErrOrStderr(), "Logged in as %s\n", display)
 	} else {

cmd/heygen/auth_login_dispatch_test.go

@@ -4,12 +4,67 @@ import (
 	"context"
 	"errors"
 	"io"
+	"slices"
 	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 )
 
+// loginAnalyticsSpy is a test double for loginAnalyticsClient (U3/U4): it
+// records every IdentifyAccount / AuthLoginStarted / AuthLoginCompleted /
+// AuthLoginFailed call in order so tests can assert both the exact call
+// and how it reconciles against the others.
+type loginAnalyticsSpy struct {
+	identifyCalls []string
+	started       []string
+	completed     []string
+	failed        []loginAnalyticsFailedCall
+}
+
+type loginAnalyticsFailedCall struct {
+	method string
+	reason string
+}
+
+func (s *loginAnalyticsSpy) IdentifyAccount(distinctId string) {
+	s.identifyCalls = append(s.identifyCalls, distinctId)
+}
+
+func (s *loginAnalyticsSpy) AuthLoginStarted(method string) {
+	s.started = append(s.started, method)
+}
+
+func (s *loginAnalyticsSpy) AuthLoginCompleted(method string) {
+	s.completed = append(s.completed, method)
+}
+
+func (s *loginAnalyticsSpy) AuthLoginFailed(method, reason string) {
+	s.failed = append(s.failed, loginAnalyticsFailedCall{method: method, reason: reason})
+}
+
+// withLoginAnalyticsSpy swaps the package-level loginAnalytics for a spy
+// for the duration of the test, restoring the previous value on cleanup.
+// Every entry point that fires login telemetry (the dispatcher, the two
+// runners, or a full cmd.Execute()) reads the same package var, so this
+// works regardless of how the test drives the login flow.
+func withLoginAnalyticsSpy(t *testing.T) *loginAnalyticsSpy {
+	t.Helper()
+	spy := &loginAnalyticsSpy{}
+	orig := loginAnalytics
+	loginAnalytics = spy
+	t.Cleanup(func() { loginAnalytics = orig })
+	return spy
+}
+
+// erroringReader always fails on Read, simulating an aborted stdin read
+// (e.g. Ctrl-C mid-input) for the api-key login flow.
+type erroringReader struct{}
+
+func (erroringReader) Read(_ []byte) (int, error) {
+	return 0, errors.New("input aborted")
+}
+
 // dispatchSpy records which runner runAuthLogin ended up invoking so
 // the table-driven dispatch tests can assert against a stable value
 // without spinning up the real OAuth / API-key flows.
@@ -264,3 +319,148 @@ func TestNonInteractiveEnvFunc_ParsesCommonShapes(t *testing.T) {
 		})
 	}
 }
+
+// U4: AuthLoginStarted fires once per dispatched attempt, after the
+// picker/flag resolves a method — using the same stubbed runOAuth/runAPIKey
+// as TestRunAuthLogin_Dispatch (so only Started is observable here; the
+// real runners' Completed/Failed calls are exercised separately in
+// auth_login_oauth_test.go where the real runOAuthLogin/runAPIKeyLogin run).
+func TestRunAuthLogin_TelemetryStarted(t *testing.T) {
+	cases := []struct {
+		name         string
+		flags        authLoginFlags
+		pickerChoice loginChoice
+		wantStarted  []string
+	}{
+		{
+			name:        "--oauth flag",
+			flags:       authLoginFlags{oauthMode: true},
+			wantStarted: []string{"oauth"},
+		},
+		{
+			name:        "--api-key flag",
+			flags:       authLoginFlags{apiKeyMode: true},
+			wantStarted: []string{"api_key"},
+		},
+		{
+			name:         "picker picks oauth",
+			pickerChoice: loginChoiceOAuth,
+			wantStarted:  []string{"oauth"},
+		},
+		{
+			name:         "picker picks api key",
+			pickerChoice: loginChoiceAPIKey,
+			wantStarted:  []string{"api_key"},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			spy := withLoginAnalyticsSpy(t)
+			dispatchTestSpy := &dispatchSpy{pickerChoice: tc.pickerChoice}
+			runAuthLoginTestDeps = dispatchTestSpy.deps()
+			t.Cleanup(func() { runAuthLoginTestDeps = nil })
+
+			cmd, ctx := makeDispatchCmd(t)
+			if err := runAuthLogin(cmd, ctx, tc.flags); err != nil {
+				t.Fatalf("runAuthLogin: %v", err)
+			}
+
+			if !slices.Equal(spy.started, tc.wantStarted) {
+				t.Errorf("started = %v, want %v", spy.started, tc.wantStarted)
+			}
+			// The stubbed runners never call Completed/Failed themselves —
+			// only the dispatcher's Started call is under test here.
+			if len(spy.completed) != 0 {
+				t.Errorf("completed = %v, want none (runner is stubbed)", spy.completed)
+			}
+			if len(spy.failed) != 0 {
+				t.Errorf("failed = %v, want none (runner is stubbed)", spy.failed)
+			}
+		})
+	}
+}
+
+// U4: a picker cancellation must emit no started/failed pair at all —
+// Started only fires after a method is chosen.
+func TestRunAuthLogin_PickerCancel_NoTelemetry(t *testing.T) {
+	spy := withLoginAnalyticsSpy(t)
+	dispatchTestSpy := &dispatchSpy{pickerErr: pickerCanceledError{}}
+	runAuthLoginTestDeps = dispatchTestSpy.deps()
+	t.Cleanup(func() { runAuthLoginTestDeps = nil })
+
+	cmd, ctx := makeDispatchCmd(t)
+	if err := runAuthLogin(cmd, ctx, authLoginFlags{}); err == nil {
+		t.Fatal("want canceled error, got nil")
+	}
+
+	if len(spy.started) != 0 || len(spy.completed) != 0 || len(spy.failed) != 0 {
+		t.Fatalf("expected no telemetry on picker cancel; started=%v completed=%v failed=%v",
+			spy.started, spy.completed, spy.failed)
+	}
+}
+
+// U4: --device-code emits started(device_code) then
+// failed(device_code, device_code_unsupported) — the reason is explicitly
+// named in the plan's enum, so this implementation instruments it rather
+// than silently dropping telemetry for the flag.
+func TestRunAuthLogin_DeviceCode_Telemetry(t *testing.T) {
+	spy := withLoginAnalyticsSpy(t)
+
+	cmd, ctx := makeDispatchCmd(t)
+	if err := runAuthLogin(cmd, ctx, authLoginFlags{deviceCodeMode: true}); err == nil {
+		t.Fatal("want usage error, got nil")
+	}
+
+	if got := spy.started; len(got) != 1 || got[0] != "device_code" {
+		t.Fatalf("started = %v, want [device_code]", got)
+	}
+	if got := spy.failed; len(got) != 1 || got[0] != (loginAnalyticsFailedCall{"device_code", "device_code_unsupported"}) {
+		t.Fatalf("failed = %v, want [{device_code device_code_unsupported}]", got)
+	}
+}
+
+// U4: --api-key with an aborted stdin read (Ctrl-C mid-input) emits
+// started(api_key) then failed(api_key, api_key_aborted).
+func TestRunAuthLogin_APIKeyAborted_Telemetry(t *testing.T) {
+	spy := withLoginAnalyticsSpy(t)
+	t.Setenv("HEYGEN_CONFIG_DIR", t.TempDir())
+
+	cmd, ctx := makeDispatchCmd(t)
+	cmd.SetIn(erroringReader{})
+
+	if err := runAuthLogin(cmd, ctx, authLoginFlags{apiKeyMode: true}); err == nil {
+		t.Fatal("want error, got nil")
+	}
+
+	if got := spy.started; len(got) != 1 || got[0] != "api_key" {
+		t.Fatalf("started = %v, want [api_key]", got)
+	}
+	if got := spy.failed; len(got) != 1 || got[0] != (loginAnalyticsFailedCall{"api_key", "api_key_aborted"}) {
+		t.Fatalf("failed = %v, want [{api_key api_key_aborted}]", got)
+	}
+	if len(spy.completed) != 0 {
+		t.Fatalf("completed = %v, want none", spy.completed)
+	}
+}
+
+// U4: --api-key with empty stdin emits started(api_key) then
+// failed(api_key, api_key_invalid_input).
+func TestRunAuthLogin_APIKeyEmptyInput_Telemetry(t *testing.T) {
+	spy := withLoginAnalyticsSpy(t)
+	t.Setenv("HEYGEN_CONFIG_DIR", t.TempDir())
+
+	cmd, ctx := makeDispatchCmd(t)
+	cmd.SetIn(strings.NewReader(""))
+
+	if err := runAuthLogin(cmd, ctx, authLoginFlags{apiKeyMode: true}); err == nil {
+		t.Fatal("want error, got nil")
+	}
+
+	if got := spy.started; len(got) != 1 || got[0] != "api_key" {
+		t.Fatalf("started = %v, want [api_key]", got)
+	}
+	if got := spy.failed; len(got) != 1 || got[0] != (loginAnalyticsFailedCall{"api_key", "api_key_invalid_input"}) {
+		t.Fatalf("failed = %v, want [{api_key api_key_invalid_input}]", got)
+	}
+}