feat(cli): add browser-based login via device-code flow

Adds a `codetime login` command so users can authorize a machine by
signing in through their browser instead of copying the upload token
from the dashboard by hand.

The CLI calls /v3/agent/cli/link/start, opens <remote>/cli/auth?code=…
(or just prints it, for SSH/headless hosts), then polls /poll until the
user approves it in a signed-in tab. The upload token is never typed and
never travels in a URL; it is resolved server-side at approval time.

Author: Jannchie

packages/cli/src/cli.ts

@@ -35,14 +35,17 @@ import { DEFAULT_API_URL, DEFAULT_BACKFILL_BATCH_BYTES, DEFAULT_BACKFILL_BATCH_S
 import { isPlainObject, numberOption, stringOption, valuesOption } from './lib/fields.js'
 import { countDirectoryEntries, listJsonlFiles, pathExists, readJsonIfExists } from './lib/fs.js'
 import { logError } from './lib/logger.js'
+import { isHeadless, openBrowser, sleep } from './lib/login.js'
 import { ProgressBar } from './lib/progress.js'
 import {
   deleteMachine,
   deleteRollupsBySource,
   listMachines,
+  pollCliLink,
   postRollupBatch,
   renameMachine,
   resolveRemote,
+  startCliLink,
 } from './lib/remote.js'
 import { BACKFILL_STATE_SCHEMA_VERSION } from './lib/types.js'
 
@@ -172,9 +175,18 @@ function createCli(ctx: RunContext, registry: AdapterRegistry) {
     .option('--force', 'Force full re-import: clear watermark and re-process all files')
     .action((action, options) => backfillCommand({ ...normalizeOptions(options), action }, ctx, registry))
 
-  // `token` is the only path to set credentials — the agent CLI reuses
+  // Browser login (device-code flow): opens `<remote>/cli/auth?code=…`,
+  // polls until the user approves it there, then writes the upload token
+  // to config — the one-click alternative to `token set`. Works over SSH
+  // too: open the printed URL on any device. See lib/login.ts + remote.ts.
+  cli.command('login', 'Authorize this machine by signing in through your browser')
+    .option('--remote <url>', 'Override API base URL for this login')
+    .option('--no-browser', 'Print the login URL instead of opening a browser')
+    .action(options => loginCommand(normalizeOptions(options), ctx))
+
+  // `token` is the manual alternative to `login`: the agent CLI reuses
   // the user's existing upload_token (visible in the codetime
-  // dashboard's Settings page), so there is no device-flow login.
+  // dashboard's Settings page).
   //   token set <value>   write to ~/.codetime/config.json
   //   token show          print masked token + remoteUrl
   //   token clear         remove only the token (keep remoteUrl)
@@ -1320,6 +1332,91 @@ function maskToken(token: string): string {
   return `${token.slice(0, 3)}…${token.slice(-4)}`
 }
 
+// Hard ceiling on how long we keep polling, independent of the server's
+// advertised expiry, so a misbehaving server can't pin the CLI forever.
+const LOGIN_MAX_WAIT_MS = 15 * 60 * 1000
+
+async function loginCommand(options: ParsedArgs, ctx: RunContext): Promise<number> {
+  const home = resolveHome(options, ctx)
+  const remoteOverride = stringOption(options.remote) || stringOption(options['api-url'])
+  const existing = readConfig(home)
+  const baseUrl = (remoteOverride
+    || ctx.env.CODETIME_API_URL
+    || existing.remoteUrl
+    || DEFAULT_API_URL).replace(/\/$/, '')
+
+  const remote = resolveRemote({
+    apiUrl: baseUrl,
+    env: ctx.env,
+    fetch: ctx.fetch,
+    homeOverride: home,
+  })
+  if (!remote) {
+    write(ctx.stderr, 'No fetch implementation available.\n')
+    return 1
+  }
+
+  let link
+  try {
+    link = await startCliLink(remote)
+  }
+  catch (error) {
+    write(ctx.stderr, `${(error as Error).message}\n`)
+    return 1
+  }
+
+  // Build the browser URL from the CLI's own base URL rather than the
+  // server-advertised verificationUri, so it stays correct when the API
+  // host and the web origin differ (e.g. local dev on a non-default port).
+  const authUrl = `${baseUrl}/cli/auth?code=${encodeURIComponent(link.userCode)}`
+  const noBrowser = options.browser === false
+  const headless = isHeadless(ctx)
+
+  write(ctx.stdout, `\nTo sign in, visit:\n\n  ${authUrl}\n\nand confirm this code:  ${link.userCode}\n\n`)
+  if (!noBrowser && !headless) {
+    openBrowser(ctx, authUrl)
+  }
+  write(ctx.stdout, 'Waiting for authorization…\n')
+
+  const intervalMs = Math.max(1, link.interval || 4) * 1000
+  const deadline = Date.now() + Math.min(LOGIN_MAX_WAIT_MS, Math.max(1, link.expiresIn || 600) * 1000)
+  while (Date.now() < deadline) {
+    let poll
+    try {
+      poll = await pollCliLink(remote, link.deviceCode)
+    }
+    catch (error) {
+      // Transient network blip — wait and keep polling until the deadline.
+      void error
+      await sleep(intervalMs)
+      continue
+    }
+    if (poll.status === 'pending') {
+      await sleep(intervalMs)
+      continue
+    }
+    if (poll.status === 'expired') {
+      write(ctx.stderr, 'Login code expired before it was approved. Re-run `codetime login`.\n')
+      return 1
+    }
+    // Approved.
+    writeConfig({
+      ...existing,
+      token: poll.token,
+      ...(poll.userId == null ? {} : { userId: String(poll.userId) }),
+      // Persist the host only when explicitly overridden, matching
+      // `token set` so a default-host login never clobbers an earlier
+      // --remote choice.
+      ...(remoteOverride ? { remoteUrl: remoteOverride } : {}),
+    }, home)
+    write(ctx.stdout, `Logged in. Token saved (${maskToken(poll.token)}).\n`)
+    return 0
+  }
+
+  write(ctx.stderr, 'Timed out waiting for authorization. Re-run `codetime login`.\n')
+  return 1
+}
+
 async function tokenCommand(
   action: string | undefined,
   value: string | undefined,
@@ -1440,19 +1537,22 @@ Usage:
   codetime install [--target codex,claude,opencode,pi] [--all] [--dry-run] [--force] [--home <path>]
   codetime hook --agent <name>
   codetime backfill discover|plan|import|verify --source codex|claude-code|opencode|pi|all --dry-run [--json] [--batch-size <count>]
+  codetime login [--no-browser] [--remote <url>]
   codetime token set <token>
   codetime token show
   codetime token clear
 
 Setup:
-  Copy your upload token from https://codetime.dev/dashboard/settings,
-  then run: codetime token set <token>
+  Run: codetime login  (signs in through your browser)
+  Or copy your upload token from https://codetime.dev/dashboard/settings
+  and run: codetime token set <token>
 
 Commands:
   detect    Show supported local targets and install status.
   install   Install integration files into detected or requested targets.
   hook      Read agent hook JSON from stdin and report a throttled event.
   backfill  Discover local history and create metadata-only import plans.
+  login     Authorize this machine by signing in through your browser.
   token     Set, show, or clear the persisted API token.
   machine   List your machines (read-only).
   version   Print CLI version.

packages/cli/src/lib/login.ts

@@ -0,0 +1,54 @@
+// Helpers for the browser-based `codetime login` (device-code flow). The
+// orchestration — start, open browser, poll, persist — lives in
+// loginCommand (cli.ts); this module holds the side-effecting bits
+// (launching a browser, detecting headless hosts) plus a small sleep.
+// The server side is codetime-web-v3/server/routes/v3/agent/cli/link/.
+import type { RunContext } from './types.js'
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+// Best-effort launch of the user's default browser. Failures are
+// swallowed: `codetime login` always prints the URL too, so a missing
+// opener (headless box, locked-down container) just means the user
+// opens the printed link themselves.
+export function openBrowser(ctx: RunContext, url: string): void {
+  const { command, args } = browserCommand(ctx.env.CODETIME_OS ?? process.platform, url)
+  try {
+    const child = ctx.spawn(command, args, { detached: true, stdio: 'ignore' })
+    child.unref?.()
+  }
+  catch {
+    // Ignored — the printed URL is the fallback.
+  }
+}
+
+function browserCommand(platform: string, url: string): { command: string, args: string[] } {
+  if (platform === 'darwin') {
+    return { command: 'open', args: [url] }
+  }
+  if (platform === 'win32') {
+    // `start` is a cmd builtin; the empty "" is the window title cmd
+    // expects before the URL, otherwise a quoted URL becomes the title.
+    return { command: 'cmd', args: ['/c', 'start', '', url] }
+  }
+  return { command: 'xdg-open', args: [url] }
+}
+
+// A headless host (CI, SSH session without X) can't open a browser; the
+// caller skips the auto-open and tells the user to open the URL manually.
+// Device-code login still works there — the user opens the URL on any
+// other device — which is the main reason this flow exists.
+export function isHeadless(ctx: RunContext): boolean {
+  if (ctx.env.CODETIME_NO_BROWSER) {
+    return true
+  }
+  if (ctx.env.SSH_CONNECTION || ctx.env.SSH_TTY) {
+    return true
+  }
+  if (process.platform === 'linux') {
+    return !ctx.env.DISPLAY && !ctx.env.WAYLAND_DISPLAY
+  }
+  return false
+}

packages/cli/src/lib/remote.ts

@@ -119,9 +119,49 @@ export async function deleteRollupsBySource(
   return Number(body.deleted) || 0
 }
 
-// Device-link helpers (startCliLink/pollCliLink) were removed when the
-// CLI moved to reusing the user's upload_token via `codetime token
-// set <token>`. The server no longer exposes `/v3/agent/cli/link/*`.
+// ── Device-code login ──
+// Browser-based `codetime login`: /start mints a code pair, the user
+// approves it in a signed-in browser tab, and /poll returns the token
+// once approved. The server side lives in
+// codetime-web-v3/server/routes/v3/agent/cli/link/.
+
+export interface CliLinkStart {
+  deviceCode: string
+  userCode: string
+  verificationUri: string
+  verificationUriComplete: string
+  interval: number
+  expiresIn: number
+}
+
+export type CliLinkPoll
+  = | { status: 'pending' }
+  | { status: 'approved', token: string, userId?: number }
+  | { status: 'expired' }
+
+export async function startCliLink(remote: RemoteOptions): Promise<CliLinkStart> {
+  const response = await remote.fetchImpl(joinUrl(remote.baseUrl, '/v3/agent/cli/link/start'), {
+    method: 'POST',
+    headers: buildHeaders(),
+    body: '{}',
+  })
+  if (!response.ok) {
+    throw new Error(`Failed to start login: ${response.status}`)
+  }
+  return await response.json() as CliLinkStart
+}
+
+export async function pollCliLink(remote: RemoteOptions, deviceCode: string): Promise<CliLinkPoll> {
+  const response = await remote.fetchImpl(joinUrl(remote.baseUrl, '/v3/agent/cli/link/poll'), {
+    method: 'POST',
+    headers: buildHeaders(),
+    body: JSON.stringify({ deviceCode }),
+  })
+  if (!response.ok) {
+    throw new Error(`Login poll failed: ${response.status}`)
+  }
+  return await response.json() as CliLinkPoll
+}
 
 export interface MachineRow {
   id: string

packages/cli/test/cli.test.ts

@@ -1488,3 +1488,90 @@ test('XDG_DATA_HOME relocates OpenCode backfill source candidates', async () =>
     `expected XDG_DATA_HOME path among ${JSON.stringify(candidatePaths)}`,
   )
 })
+
+// Mock the device-code endpoints: /start hands back a fixed code pair,
+// /poll replays the supplied statuses in order (repeating the last).
+function linkFetch(pollStatuses: Array<Record<string, unknown>>) {
+  const requests: Array<{ url: string, body: string }> = []
+  let pollIdx = 0
+  const impl = (async (url: string, init?: { body?: string }) => {
+    const u = String(url)
+    requests.push({ url: u, body: typeof init?.body === 'string' ? init.body : '' })
+    if (u.endsWith('/v3/agent/cli/link/start')) {
+      return Response.json({
+        deviceCode: 'device-secret-1',
+        userCode: 'WXYZ2345',
+        verificationUri: 'https://codetime.dev/cli/auth',
+        verificationUriComplete: 'https://codetime.dev/cli/auth?code=WXYZ2345',
+        interval: 1,
+        expiresIn: 600,
+      })
+    }
+    if (u.endsWith('/v3/agent/cli/link/poll')) {
+      const status = pollStatuses[Math.min(pollIdx, pollStatuses.length - 1)]
+      pollIdx += 1
+      return Response.json(status)
+    }
+    throw new Error(`unexpected url ${u}`)
+  }) as unknown as RunContext['fetch']
+  return { impl, requests }
+}
+
+test('login polls the device-code endpoint and saves the approved token', async () => {
+  const home = await mkdtemp(path.join(tmpdir(), 'codetime-'))
+  let output = ''
+  const { impl, requests } = linkFetch([{ status: 'approved', token: 'upload_abc123', userId: 7 }])
+
+  const exitCode = await run(['login', '--no-browser', '--home', home], testContext({
+    env: { HOME: home },
+    fetch: impl,
+    stdout: { write: (text: string) => {
+      output += text
+    } },
+  }))
+
+  assert.equal(exitCode, 0)
+  // The printed URL + code let an SSH user open it on another device.
+  assert.match(output, /\/cli\/auth\?code=WXYZ2345/)
+  assert.match(output, /WXYZ2345/)
+  // start is POSTed before any poll.
+  assert.ok(requests[0].url.endsWith('/v3/agent/cli/link/start'))
+  assert.ok(requests.some(r => r.url.endsWith('/v3/agent/cli/link/poll') && r.body.includes('device-secret-1')))
+
+  const config = JSON.parse(await readFile(path.join(home, '.codetime', 'config.json'), 'utf8'))
+  assert.equal(config.token, 'upload_abc123')
+  assert.equal(config.userId, '7')
+})
+
+test('login keeps polling while pending, then saves on approval', async () => {
+  const home = await mkdtemp(path.join(tmpdir(), 'codetime-'))
+  const { impl } = linkFetch([
+    { status: 'pending' },
+    { status: 'approved', token: 'tok_2', userId: 9 },
+  ])
+
+  const exitCode = await run(['login', '--no-browser', '--home', home], testContext({
+    env: { HOME: home },
+    fetch: impl,
+    stdout: { write: () => {} },
+  }))
+
+  assert.equal(exitCode, 0)
+  const config = JSON.parse(await readFile(path.join(home, '.codetime', 'config.json'), 'utf8'))
+  assert.equal(config.token, 'tok_2')
+})
+
+test('login fails and writes no token when the code expires', async () => {
+  const home = await mkdtemp(path.join(tmpdir(), 'codetime-'))
+  const { impl } = linkFetch([{ status: 'expired' }])
+
+  const exitCode = await run(['login', '--no-browser', '--home', home], testContext({
+    env: { HOME: home },
+    fetch: impl,
+    stdout: { write: () => {} },
+    stderr: { write: () => {} },
+  }))
+
+  assert.equal(exitCode, 1)
+  await assert.rejects(readFile(path.join(home, '.codetime', 'config.json'), 'utf8'), { code: 'ENOENT' })
+})