From 939f91630ebe25915dfdc590a0920c6bc7621899 Mon Sep 17 00:00:00 2001
From: Kevin Wang <kenwang3333@gmail.com>
Date: Sun, 2 Aug 2026 14:41:51 -0700
Subject: [PATCH] feat: add cross-device OAuth login

---
 CHANGELOG.md                      |  17 ++
 README.md                         |   7 +-
 __tests__/auth.test.ts            | 125 ++++++++-
 __tests__/bundled-skills.test.ts  |   4 +
 __tests__/connect.test.ts         |  68 ++++-
 __tests__/login.test.ts           | 415 ++++++++++++++++++++++++++++++
 package-lock.json                 |   4 +-
 package.json                      |   2 +-
 skills/anyapi-onboarding/SKILL.md |  21 +-
 src/api.ts                        |  24 +-
 src/auth.ts                       |  48 +++-
 src/commands.ts                   |  41 ++-
 src/connect.ts                    | 131 ++--------
 src/constants.ts                  |   1 +
 src/index.ts                      |   7 +-
 src/login.ts                      | 163 ++++++++++++
 src/oauth.ts                      | 153 +++++++++++
 src/types.ts                      |  15 +-
 18 files changed, 1105 insertions(+), 141 deletions(-)
 create mode 100644 __tests__/login.test.ts
 create mode 100644 src/login.ts
 create mode 100644 src/oauth.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e2fcab..1ea2c04 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.5.0 - 2026-08-02
+
+### Added
+
+- `anyapi login` now starts the RFC 8628 OAuth device flow when no manual key is
+  supplied. It prints the verification URL and user code, opens the complete URL
+  best-effort, follows the server polling interval and `slow_down`, and stores the
+  same access token, refresh token, expiry, and scope fields as `anyapi connect`.
+  Account sessions refresh automatically before the one-hour access token expires.
+
+### Changed
+
+- `anyapi login --api-key aa_live_...` remains the manual-key compatibility path
+  and clears any unrelated OAuth or trial state before selecting that key.
+- `login` is the immediate cross-device account sign-in path; `connect` remains
+  the Authorization Code + PKCE loopback path for upgrading a free trial.
+
 ## 0.3.3
 
 ### Changed
diff --git a/README.md b/README.md
index 7227429..afe89cd 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,8 @@ anyapi run reddit.search --input '{"query":"anyapi","limit":5}'
 
 - `anyapi signup [--label <label>] [--show-key]` - mint a free trial key and save it locally. The secret is not printed unless you pass `--show-key`.
 - `anyapi connect` - upgrade past the free trial via a one-URL OAuth 2.1 approval (Authorization Code + PKCE over a loopback callback). Prints a single consent URL for a human to open; on approval the CLI stores the access token and keeps working.
-- `anyapi login --api-key aa_live_...` - store an existing dashboard key locally.
+- `anyapi login` - sign in to an AnyAPI account immediately with the OAuth 2.0 device flow. The CLI prints a verification URL and user code, opens the complete URL when possible, and waits without binding a localhost callback.
+- `anyapi login --api-key aa_live_...` - manual-key compatibility path: store an existing dashboard key locally without starting OAuth.
 - `anyapi search <query>` - search the public catalog and print SKU, name, and USD price terms.
 - `anyapi list [--category <cat>]` - list catalog APIs.
 - `anyapi describe <sku>` - print the authenticated API definition, including opaque schemas and gateway-published USD pricing, lane order, and failover metadata.
@@ -43,6 +44,10 @@ anyapi run reddit.search --input '{"query":"anyapi","limit":5}'
 
 Auth resolution order is `--api-key`, then `ANYAPI_API_KEY`, then `~/.anyapi/config.json`, then trial self-signup. When the trial budget is spent, runs return HTTP 402 `trial_cap_reached`; run `anyapi connect` to continue.
 
+Use `login` for immediate account-backed OAuth on any device. Use `connect` to
+upgrade and continue an existing free trial while preserving its trial receipt.
+OAuth access tokens refresh automatically from the saved session before expiry.
+
 ## Gateway and CLI responsibilities
 
 The AnyAPI gateway owns input validation, provider normalization, pricing, lane order,
diff --git a/__tests__/auth.test.ts b/__tests__/auth.test.ts
index 1c38924..b991113 100644
--- a/__tests__/auth.test.ts
+++ b/__tests__/auth.test.ts
@@ -3,7 +3,11 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import { resolveApiKey } from '../src/auth.js';
-import { getConfigPath, writeConfig } from '../src/config.js';
+import { getConfigPath, readConfig, writeConfig } from '../src/config.js';
+import type { FetchLike } from '../src/types.js';
+
+const METADATA_URL = 'https://api.getanyapi.com/.well-known/oauth-authorization-server';
+const TOKEN_URL = 'https://auth.example.test/token';
 
 const tempDirs: string[] = [];
 
@@ -42,6 +46,125 @@ describe('auth resolution', () => {
     const auth = await resolveApiKey({ env: {} as NodeJS.ProcessEnv, configPath: getConfigPath(dir) });
     expect(auth).toMatchObject({ source: 'missing' });
   });
+
+  it('rotates an expiring OAuth access token before returning config auth', async () => {
+    const dir = await tempDir();
+    const configPath = getConfigPath(dir);
+    await writeConfig({
+      apiKey: 'aa_at_old',
+      refreshToken: 'aa_rt_old',
+      oauthClientId: 'aa_client_login',
+      accessTokenExpiresAt: '2026-08-02T12:00:30.000Z',
+      scope: 'run balance:read',
+    }, configPath);
+    const requests: Array<{ url: string; init?: RequestInit }> = [];
+    const fetchImpl: FetchLike = async (input, init) => {
+      const url = String(input);
+      requests.push({ url, init });
+      if (url === METADATA_URL) {
+        return Response.json({
+          authorization_endpoint: 'https://auth.example.test/authorize',
+          token_endpoint: TOKEN_URL,
+        });
+      }
+      if (url === TOKEN_URL) {
+        return Response.json({
+          access_token: 'aa_at_new',
+          token_type: 'Bearer',
+          expires_in: 3600,
+          refresh_token: 'aa_rt_new',
+          scope: 'run balance:read',
+        });
+      }
+      throw new Error(`Unexpected URL: ${url}`);
+    };
+
+    const auth = await resolveApiKey({
+      env: {} as NodeJS.ProcessEnv,
+      configPath,
+      fetchImpl,
+      now: () => Date.parse('2026-08-02T12:00:00.000Z'),
+    });
+
+    expect(auth.apiKey).toBe('aa_at_new');
+    expect(requests.map((request) => request.url)).toEqual([METADATA_URL, TOKEN_URL]);
+    expect(Object.fromEntries(new URLSearchParams(String(requests[1].init?.body)))).toEqual({
+      grant_type: 'refresh_token',
+      refresh_token: 'aa_rt_old',
+      client_id: 'aa_client_login',
+    });
+    expect(await readConfig(configPath)).toMatchObject({
+      apiKey: 'aa_at_new',
+      refreshToken: 'aa_rt_new',
+      oauthClientId: 'aa_client_login',
+      accessTokenExpiresAt: '2026-08-02T13:00:00.000Z',
+    });
+  });
+
+  it('does not refresh a config OAuth token outside the refresh window', async () => {
+    const dir = await tempDir();
+    const configPath = getConfigPath(dir);
+    await writeConfig({
+      apiKey: 'aa_at_current',
+      refreshToken: 'aa_rt_current',
+      oauthClientId: 'aa_client_login',
+      accessTokenExpiresAt: '2026-08-02T12:05:00.000Z',
+    }, configPath);
+
+    const auth = await resolveApiKey({
+      env: {} as NodeJS.ProcessEnv,
+      configPath,
+      fetchImpl: async () => { throw new Error('refresh should not run'); },
+      now: () => Date.parse('2026-08-02T12:00:00.000Z'),
+    });
+
+    expect(auth.apiKey).toBe('aa_at_current');
+  });
+
+  it.each([
+    [{ clientId: 'aa_client_trial', cliClientId: 'aa_client_cli' }, 'aa_client_trial'],
+    [{ cliClientId: 'aa_client_cli' }, 'aa_client_cli'],
+  ])('migrates legacy OAuth client provenance before refreshing', async (legacyClients, expectedClientId) => {
+    const dir = await tempDir();
+    const configPath = getConfigPath(dir);
+    await writeConfig({
+      apiKey: 'aa_at_old',
+      refreshToken: 'aa_rt_old',
+      accessTokenExpiresAt: '2026-08-02T12:00:00.000Z',
+      ...legacyClients,
+    }, configPath);
+    let refreshClientId: string | undefined;
+    const fetchImpl: FetchLike = async (input, init) => {
+      const url = String(input);
+      if (url === METADATA_URL) {
+        return Response.json({
+          authorization_endpoint: 'https://auth.example.test/authorize',
+          token_endpoint: TOKEN_URL,
+        });
+      }
+      if (url === TOKEN_URL) {
+        refreshClientId = new URLSearchParams(String(init?.body)).get('client_id') ?? undefined;
+        return Response.json({
+          access_token: 'aa_at_new',
+          token_type: 'Bearer',
+          expires_in: 3600,
+          refresh_token: 'aa_rt_new',
+          scope: 'run balance:read',
+        });
+      }
+      throw new Error(`Unexpected URL: ${url}`);
+    };
+
+    await resolveApiKey({
+      env: {} as NodeJS.ProcessEnv,
+      configPath,
+      fetchImpl,
+      now: () => Date.parse('2026-08-02T12:00:00.000Z'),
+    });
+
+    expect(refreshClientId).toBe(expectedClientId);
+    expect(await readConfig(configPath)).toMatchObject({ oauthClientId: expectedClientId });
+  });
 });
 
 async function configWithKey(apiKey: string): Promise<string> {
diff --git a/__tests__/bundled-skills.test.ts b/__tests__/bundled-skills.test.ts
index e0ae619..04b2171 100644
--- a/__tests__/bundled-skills.test.ts
+++ b/__tests__/bundled-skills.test.ts
@@ -25,6 +25,10 @@ describe('bundled agent skills', () => {
     expect(onboarding).toContain('npx -y anyapi-cli@latest init');
     expect(onboarding).toContain('anyapi signup --label agent');
     expect(onboarding).toContain('anyapi connect');
+    expect(onboarding).toContain('anyapi login');
+    expect(onboarding).toContain('OAuth device flow');
+    expect(onboarding).toContain('does not bind a localhost callback');
+    expect(onboarding).toContain('anyapi login --api-key aa_live_...');
 
     const run = readSkill('anyapi-run');
     expect(run).toContain('anyapi run reddit.search --input');
diff --git a/__tests__/connect.test.ts b/__tests__/connect.test.ts
index 1232e36..da55fb0 100644
--- a/__tests__/connect.test.ts
+++ b/__tests__/connect.test.ts
@@ -5,6 +5,13 @@ import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import { AnyApiClient } from '../src/api.js';
 import { connectionConfigFromToken, resolveClientId } from '../src/connect.js';
+import {
+  OAUTH_AUTHORIZE_URL,
+  OAUTH_DEVICE_AUTHORIZATION_URL,
+  OAUTH_REGISTER_URL,
+  OAUTH_TOKEN_URL,
+} from '../src/constants.js';
+import { resolveOAuthEndpoints } from '../src/oauth.js';
 import { buildAuthorizeUrl, createPkce, randomState } from '../src/pkce.js';
 import type { AnyApiConfig, FetchLike, TokenResponse } from '../src/types.js';
 
@@ -68,18 +75,52 @@ describe('connectionConfigFromToken', () => {
 
   it('maps the access token onto apiKey and stores the refresh fields', () => {
     const now = new Date('2026-07-10T00:00:00.000Z');
-    expect(connectionConfigFromToken(token, now)).toEqual({
+    expect(connectionConfigFromToken(token, now, 'aa_client_active')).toEqual({
       apiKey: 'aa_at_access',
       refreshToken: 'aa_rt_refresh',
+      oauthClientId: 'aa_client_active',
       scope: 'run balance:read',
       accessTokenExpiresAt: '2026-07-10T01:00:00.000Z',
     });
   });
 
   it('omits the expiry when expires_in is missing', () => {
-    const patch = connectionConfigFromToken({ ...token, expires_in: undefined as unknown as number });
-    expect(patch.accessTokenExpiresAt).toBeUndefined();
-    expect(patch.apiKey).toBe('aa_at_access');
+    expect(() => connectionConfigFromToken({ ...token, expires_in: undefined as unknown as number }))
+      .toThrow('invalid response');
+  });
+
+  it('rejects a non-Bearer or empty access token response', () => {
+    expect(() => connectionConfigFromToken({ ...token, token_type: 'MAC' })).toThrow('invalid response');
+    expect(() => connectionConfigFromToken({ ...token, access_token: '' })).toThrow('invalid response');
+  });
+});
+
+describe('OAuth endpoint discovery', () => {
+  it('uses endpoint-specific fallbacks when optional metadata fields are omitted', async () => {
+    const client = new AnyApiClient({
+      fetchImpl: async () => Response.json({
+        authorization_endpoint: 'https://auth.example.test/authorize',
+        token_endpoint: 'https://auth.example.test/token',
+      }),
+    });
+
+    await expect(resolveOAuthEndpoints(client)).resolves.toEqual({
+      authorizationEndpoint: 'https://auth.example.test/authorize',
+      deviceAuthorizationEndpoint: OAUTH_DEVICE_AUTHORIZATION_URL,
+      tokenEndpoint: 'https://auth.example.test/token',
+      registrationEndpoint: OAUTH_REGISTER_URL,
+    });
+  });
+
+  it('uses all hardcoded endpoints when metadata discovery fails', async () => {
+    const client = new AnyApiClient({ fetchImpl: async () => { throw new Error('offline'); } });
+
+    await expect(resolveOAuthEndpoints(client)).resolves.toEqual({
+      authorizationEndpoint: OAUTH_AUTHORIZE_URL,
+      deviceAuthorizationEndpoint: OAUTH_DEVICE_AUTHORIZATION_URL,
+      tokenEndpoint: OAUTH_TOKEN_URL,
+      registrationEndpoint: OAUTH_REGISTER_URL,
+    });
   });
 });
 
@@ -160,4 +201,23 @@ describe('resolveClientId', () => {
     const persisted = JSON.parse(await readFile(configPath, 'utf8')) as AnyApiConfig;
     expect(persisted.cliClientId).toBe('aa_client_new');
   });
+
+  it('wraps DCR failures with the command context', async () => {
+    const client = new AnyApiClient({
+      fetchImpl: async () => new Response(JSON.stringify({ error: 'rate_limited' }), { status: 429 }),
+    });
+    const configPath = await makeConfigPath();
+
+    await expect(resolveClientId({}, client, REGISTRATION_ENDPOINT, configPath, {
+      commandName: 'anyapi login',
+    })).rejects.toThrow('Could not register an OAuth client for anyapi login: rate_limited');
+  });
+
+  it('rejects a successful DCR response with an empty client id', async () => {
+    const client = new AnyApiClient({ fetchImpl: async () => Response.json({ client_id: '  ' }) });
+    const configPath = await makeConfigPath();
+
+    await expect(resolveClientId({}, client, REGISTRATION_ENDPOINT, configPath))
+      .rejects.toThrow('did not return a client_id');
+  });
 });
diff --git a/__tests__/login.test.ts b/__tests__/login.test.ts
new file mode 100644
index 0000000..924323a
--- /dev/null
+++ b/__tests__/login.test.ts
@@ -0,0 +1,415 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { PassThrough } from 'node:stream';
+import { afterEach, describe, expect, it } from 'vitest';
+import { loginCommand, signupCommand } from '../src/commands.js';
+import { getConfigPath, readConfig, writeConfig } from '../src/config.js';
+import type { CommandContext } from '../src/io.js';
+import type { FetchLike } from '../src/types.js';
+
+const METADATA_URL = 'https://api.getanyapi.com/.well-known/oauth-authorization-server';
+const REGISTER_URL = 'https://auth.example.test/register';
+const DEVICE_URL = 'https://auth.example.test/device';
+const TOKEN_URL = 'https://auth.example.test/token';
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+describe('login command routing', () => {
+  it('preserves --api-key as the manual compatibility path without OAuth requests', async () => {
+    const homeDir = await tempDir();
+    await writeConfig({
+      refreshToken: 'remove-me',
+      accessTokenExpiresAt: '2026-08-02T12:00:00.000Z',
+      oauthClientId: 'aa_client_old',
+      scope: 'run balance:read',
+      keyId: 'key_old_trial',
+      capUsd: 0.15,
+      expiresAt: '2026-08-09T12:00:00.000Z',
+      verificationStatus: 'unverified',
+      clientId: 'aa_client_old_trial',
+    }, getConfigPath(homeDir));
+    let fetchCalls = 0;
+    const ctx = commandContext(homeDir, async () => {
+      fetchCalls += 1;
+      throw new Error('manual login must not fetch');
+    });
+
+    await loginCommand(ctx, { apiKey: 'aa_live_manual' });
+
+    expect(fetchCalls).toBe(0);
+    expect(await readConfig(getConfigPath(homeDir))).toEqual({ apiKey: 'aa_live_manual' });
+    expect(output(ctx)).toContain('AnyAPI key saved');
+  });
+
+  it('routes a keyless login through device OAuth, polls pending to success, and persists OAuth config', async () => {
+    const homeDir = await tempDir();
+    const requests: Array<{ url: string; init?: RequestInit }> = [];
+    let tokenPolls = 0;
+    const fetchImpl: FetchLike = async (input, init) => {
+      const url = String(input);
+      requests.push({ url, init });
+      if (url === METADATA_URL) return json(metadata());
+      if (url === REGISTER_URL) return json({ client_id: 'aa_client_device' });
+      if (url === DEVICE_URL) return json(deviceAuthorization({ interval: 5 }));
+      if (url === TOKEN_URL) {
+        tokenPolls += 1;
+        return tokenPolls === 1
+          ? json({ error: 'authorization_pending' }, 400)
+          : json(tokenResponse());
+      }
+      throw new Error(`Unexpected URL: ${url}`);
+    };
+    const ctx = commandContext(homeDir, fetchImpl);
+    const opened: string[] = [];
+    const clock = fakeClock();
+
+    await loginCommand(ctx, {}, { ...clock.dependencies, openUrl: (url) => opened.push(url) });
+
+    expect(clock.sleeps).toEqual([5000, 5000]);
+    expect(opened).toEqual(['https://getanyapi.com/dashboard/authorize?user_code=ABCD-EFGH']);
+    expect(requests.map((request) => request.url)).toEqual([
+      METADATA_URL,
+      REGISTER_URL,
+      DEVICE_URL,
+      TOKEN_URL,
+      TOKEN_URL,
+    ]);
+
+    const deviceRequest = requests[2];
+    expect(deviceRequest.init?.method).toBe('POST');
+    expect(new Headers(deviceRequest.init?.headers).get('Content-Type')).toBe('application/x-www-form-urlencoded');
+    expect(form(deviceRequest)).toEqual({
+      client_id: 'aa_client_device',
+      scope: 'run balance:read',
+    });
+
+    for (const tokenRequest of requests.slice(3)) {
+      expect(form(tokenRequest)).toEqual({
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        device_code: 'device-secret',
+        client_id: 'aa_client_device',
+      });
+    }
+
+    expect(await readConfig(getConfigPath(homeDir))).toEqual({
+      cliClientId: 'aa_client_device',
+      apiKey: 'aa_at_access',
+      refreshToken: 'aa_rt_refresh',
+      oauthClientId: 'aa_client_device',
+      scope: 'run balance:read',
+      accessTokenExpiresAt: '1970-01-01T01:00:10.000Z',
+    });
+    const stdout = output(ctx);
+    expect(stdout).toContain('https://getanyapi.com/dashboard/authorize');
+    expect(stdout).toContain('Code: ABCD-EFGH');
+    expect(stdout).toContain('Logged in. Account-backed AnyAPI OAuth is ready.');
+  });
+
+  it('uses the reusable CLI client instead of a saved trial-upgrade client', async () => {
+    const homeDir = await tempDir();
+    await writeConfig({
+      clientId: 'aa_client_trial_upgrade',
+      cliClientId: 'aa_client_account_login',
+    }, getConfigPath(homeDir));
+    const requests: Array<{ url: string; init?: RequestInit }> = [];
+    const fetchImpl: FetchLike = async (input, init) => {
+      const url = String(input);
+      requests.push({ url, init });
+      if (url === METADATA_URL) return json(metadata());
+      if (url === DEVICE_URL) return json(deviceAuthorization());
+      if (url === TOKEN_URL) return json(tokenResponse());
+      throw new Error(`Unexpected URL: ${url}`);
+    };
+    const ctx = commandContext(homeDir, fetchImpl);
+    const clock = fakeClock();
+
+    await loginCommand(ctx, {}, {
+      ...clock.dependencies,
+      openUrl: () => undefined,
+    });
+
+    expect(requests.map((request) => request.url)).toEqual([
+      METADATA_URL,
+      DEVICE_URL,
+      TOKEN_URL,
+    ]);
+    expect(form(requests[1])).toMatchObject({
+      client_id: 'aa_client_account_login',
+    });
+    expect(form(requests[2])).toMatchObject({
+      client_id: 'aa_client_account_login',
+    });
+  });
+});
+
+describe('credential selection', () => {
+  it('clears an old OAuth session when signup selects a new trial key', async () => {
+    const homeDir = await tempDir();
+    await writeConfig({
+      apiKey: 'aa_at_old',
+      refreshToken: 'aa_rt_old',
+      accessTokenExpiresAt: '2026-08-02T12:00:00.000Z',
+      oauthClientId: 'aa_client_old',
+      scope: 'run balance:read',
+    }, getConfigPath(homeDir));
+    const ctx = commandContext(homeDir, async () => json({
+      secret: 'aa_live_trial',
+      keyId: 'key_trial',
+      capUsd: 0.15,
+      verificationStatus: 'unverified',
+      expiresAt: '2026-08-09T12:00:00.000Z',
+      clientId: 'aa_client_trial',
+    }));
+
+    await signupCommand(ctx, {});
+
+    expect(await readConfig(getConfigPath(homeDir))).toEqual({
+      apiKey: 'aa_live_trial',
+      keyId: 'key_trial',
+      capUsd: 0.15,
+      verificationStatus: 'unverified',
+      expiresAt: '2026-08-09T12:00:00.000Z',
+      clientId: 'aa_client_trial',
+    });
+  });
+});
+
+describe('device token polling', () => {
+  it('adds five seconds to the polling interval after slow_down', async () => {
+    const homeDir = await configuredHome();
+    let tokenPolls = 0;
+    const ctx = commandContext(homeDir, flowFetch(() => {
+      tokenPolls += 1;
+      return tokenPolls === 1 ? json({ error: 'slow_down' }, 400) : json(tokenResponse());
+    }, { interval: 2 }));
+    const clock = fakeClock();
+
+    await loginCommand(ctx, {}, {
+      ...clock.dependencies,
+      openUrl: () => { throw new Error('no browser available'); },
+    });
+
+    expect(clock.sleeps).toEqual([2000, 7000]);
+    expect(tokenPolls).toBe(2);
+  });
+
+  it('uses the five-second default when the server omits interval', async () => {
+    const homeDir = await configuredHome();
+    const ctx = commandContext(homeDir, flowFetch(() => json(tokenResponse()), { interval: undefined }));
+    const clock = fakeClock();
+
+    await loginCommand(ctx, {}, { ...clock.dependencies, openUrl: () => undefined });
+
+    expect(clock.sleeps).toEqual([5000]);
+  });
+
+  it('stops immediately when the human denies authorization', async () => {
+    const homeDir = await configuredHome();
+    let tokenPolls = 0;
+    const ctx = commandContext(homeDir, flowFetch(() => {
+      tokenPolls += 1;
+      return json({ error: 'access_denied' }, 400);
+    }));
+    const clock = fakeClock();
+
+    await expect(loginCommand(ctx, {}, { ...clock.dependencies, openUrl: () => undefined }))
+      .rejects.toThrow('AnyAPI sign-in was denied');
+    expect(tokenPolls).toBe(1);
+    expect(clock.sleeps).toEqual([5000]);
+  });
+
+  it('reports a server-expired device code', async () => {
+    const homeDir = await configuredHome();
+    const ctx = commandContext(homeDir, flowFetch(() => json({ error: 'expired_token' }, 400)));
+    const clock = fakeClock();
+
+    await expect(loginCommand(ctx, {}, { ...clock.dependencies, openUrl: () => undefined }))
+      .rejects.toThrow('sign-in code expired');
+  });
+
+  it('rejects a malformed device authorization response before polling', async () => {
+    const homeDir = await configuredHome();
+    const fetchImpl: FetchLike = async (input) => {
+      const url = String(input);
+      if (url === METADATA_URL) return json(metadata());
+      if (url === DEVICE_URL) return json({ user_code: 'ABCD-EFGH', expires_in: 600 });
+      throw new Error(`Unexpected URL: ${url}`);
+    };
+    const ctx = commandContext(homeDir, fetchImpl);
+
+    await expect(loginCommand(ctx, {}, { ...fakeClock().dependencies, openUrl: () => undefined }))
+      .rejects.toThrow('invalid response');
+  });
+
+  it('accepts a device response without optional verification_uri_complete', async () => {
+    const homeDir = await configuredHome();
+    const ctx = commandContext(homeDir, flowFetch(() => json(tokenResponse()), {
+      verification_uri_complete: undefined,
+    }));
+    const opened: string[] = [];
+
+    await loginCommand(ctx, {}, { ...fakeClock().dependencies, openUrl: (url) => opened.push(url) });
+
+    expect(opened).toEqual([]);
+    expect(output(ctx)).toContain('https://getanyapi.com/dashboard/authorize');
+  });
+
+  it('rejects a malformed successful token response without overwriting config', async () => {
+    const homeDir = await configuredHome();
+    await writeConfig({
+      apiKey: 'aa_live_existing',
+      cliClientId: 'aa_client_existing',
+    }, getConfigPath(homeDir));
+    const ctx = commandContext(homeDir, flowFetch(() => json({ token_type: 'Bearer' })));
+
+    await expect(loginCommand(ctx, {}, { ...fakeClock().dependencies, openUrl: () => undefined }))
+      .rejects.toThrow('invalid response');
+    expect(await readConfig(getConfigPath(homeDir))).toEqual({
+      apiKey: 'aa_live_existing',
+      cliClientId: 'aa_client_existing',
+    });
+  });
+
+  it('bounds polling by expires_in without using real timers', async () => {
+    const homeDir = await configuredHome();
+    let tokenPolls = 0;
+    const ctx = commandContext(homeDir, flowFetch(() => {
+      tokenPolls += 1;
+      return json({ error: 'authorization_pending' }, 400);
+    }, { expires_in: 5, interval: 3 }));
+    const clock = fakeClock();
+
+    await expect(loginCommand(ctx, {}, { ...clock.dependencies, openUrl: () => undefined }))
+      .rejects.toThrow('Timed out waiting for AnyAPI sign-in');
+    expect(tokenPolls).toBe(1);
+    expect(clock.sleeps).toEqual([3000, 2000]);
+  });
+
+  it('aborts a token request that hangs past the device-code deadline', async () => {
+    const homeDir = await configuredHome();
+    let signalAborted = false;
+    const fetchImpl: FetchLike = async (input, init) => {
+      const url = String(input);
+      if (url === METADATA_URL) return json(metadata());
+      if (url === DEVICE_URL) {
+        return json(deviceAuthorization({ expires_in: 0.03, interval: 0.001 }));
+      }
+      if (url === TOKEN_URL) {
+        return new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener('abort', () => {
+            signalAborted = true;
+            reject(new Error('aborted'));
+          }, { once: true });
+        });
+      }
+      throw new Error(`Unexpected URL: ${url}`);
+    };
+    const ctx = commandContext(homeDir, fetchImpl);
+
+    await expect(loginCommand(ctx, {}, { ...fakeClock().dependencies, openUrl: () => undefined }))
+      .rejects.toThrow('Timed out waiting for AnyAPI sign-in');
+    expect(signalAborted).toBe(true);
+  });
+});
+
+function metadata(): Record<string, string> {
+  return {
+    authorization_endpoint: 'https://auth.example.test/authorize',
+    device_authorization_endpoint: DEVICE_URL,
+    token_endpoint: TOKEN_URL,
+    registration_endpoint: REGISTER_URL,
+  };
+}
+
+type DeviceOverrides = Partial<Record<'expires_in' | 'interval', number | undefined>> & {
+  verification_uri_complete?: string | undefined;
+};
+
+function deviceAuthorization(overrides: DeviceOverrides = {}): Record<string, unknown> {
+  return {
+    device_code: 'device-secret',
+    user_code: 'ABCD-EFGH',
+    verification_uri: 'https://getanyapi.com/dashboard/authorize',
+    verification_uri_complete: 'https://getanyapi.com/dashboard/authorize?user_code=ABCD-EFGH',
+    expires_in: 600,
+    interval: 5,
+    ...overrides,
+  };
+}
+
+function tokenResponse(): Record<string, unknown> {
+  return {
+    access_token: 'aa_at_access',
+    token_type: 'Bearer',
+    expires_in: 3600,
+    refresh_token: 'aa_rt_refresh',
+    scope: 'run balance:read',
+  };
+}
+
+function flowFetch(tokenResponseFactory: () => Response, overrides: DeviceOverrides = {}): FetchLike {
+  return async (input) => {
+    const url = String(input);
+    if (url === METADATA_URL) return json(metadata());
+    if (url === DEVICE_URL) return json(deviceAuthorization(overrides));
+    if (url === TOKEN_URL) return tokenResponseFactory();
+    throw new Error(`Unexpected URL: ${url}`);
+  };
+}
+
+async function configuredHome(): Promise<string> {
+  const homeDir = await tempDir();
+  await writeConfig({ cliClientId: 'aa_client_existing' }, getConfigPath(homeDir));
+  return homeDir;
+}
+
+function fakeClock(): {
+  sleeps: number[];
+  dependencies: { now: () => number; sleep: (milliseconds: number) => Promise<void> };
+} {
+  let currentTime = 0;
+  const sleeps: number[] = [];
+  return {
+    sleeps,
+    dependencies: {
+      now: () => currentTime,
+      sleep: async (milliseconds) => {
+        sleeps.push(milliseconds);
+        currentTime += milliseconds;
+      },
+    },
+  };
+}
+
+function commandContext(homeDir: string, fetchImpl: FetchLike): CommandContext {
+  return {
+    cwd: homeDir,
+    homeDir,
+    env: {},
+    stdin: new PassThrough(),
+    stdout: new PassThrough(),
+    stderr: new PassThrough(),
+    fetchImpl,
+  };
+}
+
+function output(ctx: CommandContext): string {
+  return ctx.stdout.read()?.toString() ?? '';
+}
+
+function form(request: { init?: RequestInit }): Record<string, string> {
+  return Object.fromEntries(new URLSearchParams(String(request.init?.body)).entries());
+}
+
+function json(body: unknown, status = 200): Response {
+  return Response.json(body, { status });
+}
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(`${tmpdir()}/anyapi-login-`);
+  tempDirs.push(dir);
+  return dir;
+}
diff --git a/package-lock.json b/package-lock.json
index 8485251..0a95453 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "anyapi-cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "anyapi-cli",
-      "version": "0.4.1",
+      "version": "0.5.0",
       "license": "MIT",
       "dependencies": {
         "commander": "^12.1.0",
diff --git a/package.json b/package.json
index 1841a5c..fcc6379 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "anyapi-cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Official CLI for AnyAPI, a unified marketplace for scraping and data APIs.",
   "type": "module",
   "bin": {
diff --git a/skills/anyapi-onboarding/SKILL.md b/skills/anyapi-onboarding/SKILL.md
index 3383d96..2cc89cd 100644
--- a/skills/anyapi-onboarding/SKILL.md
+++ b/skills/anyapi-onboarding/SKILL.md
@@ -44,7 +44,26 @@ anyapi connect
 
 `anyapi connect` (anyapi-cli >= 0.3.0) starts an OAuth flow with a localhost callback and prints a single consent URL. Hand that one URL to your human. They sign in or sign up, see a receipt of what you accomplished on the trial, set a spend limit, and approve. The CLI then holds the access token and keeps working - there is no key to swap by hand.
 
-## Dashboard key (secondary path)
+Use `connect` specifically to upgrade and continue a trial. It preserves the
+trial receipt and uses Authorization Code + PKCE with a loopback callback.
+
+## Immediate account sign-in (cross-device)
+
+To sign in to an AnyAPI account immediately instead of starting or upgrading a
+trial, run:
+
+```sh
+anyapi login
+```
+
+The CLI starts the OAuth device flow: it prints a verification URL and user code,
+opens the complete URL when possible, and waits for approval. The human can use
+any browser or device; the CLI does not bind a localhost callback. On approval,
+the account-backed access and refresh tokens are saved to
+`~/.anyapi/config.json`; the CLI refreshes the account session automatically
+before the access token expires.
+
+## Dashboard key (manual compatibility path)
 
 A human who is already signed in at https://getanyapi.com can create a full, non-expiring key at https://getanyapi.com/dashboard/keys and hand it to you:
 
diff --git a/src/api.ts b/src/api.ts
index 94cdf66..94b3e68 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -5,6 +5,7 @@ import type {
   CatalogApi,
   CatalogResponse,
   ClientRegistrationResponse,
+  DeviceAuthorizationResponse,
   FetchLike,
   OAuthMetadata,
   RunResult,
@@ -80,15 +81,34 @@ export class AnyApiClient {
     );
   }
 
+  async authorizeDevice(
+    deviceAuthorizationEndpoint: string,
+    params: { client_id: string; scope?: string; resource?: string },
+  ): Promise<DeviceAuthorizationResponse> {
+    return this.requestJson<DeviceAuthorizationResponse>(
+      deviceAuthorizationEndpoint,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams(compactObject(params)).toString(),
+      },
+    );
+  }
+
   // exchangeToken posts to the OAuth token endpoint as a public client (no secret):
-  // application/x-www-form-urlencoded, used for the authorization_code grant.
-  async exchangeToken(tokenUrl: string, params: Record<string, string>): Promise<TokenResponse> {
+  // application/x-www-form-urlencoded, used for authorization_code and device_code grants.
+  async exchangeToken(
+    tokenUrl: string,
+    params: Record<string, string>,
+    signal?: AbortSignal,
+  ): Promise<TokenResponse> {
     return this.requestJson<TokenResponse>(
       tokenUrl,
       {
         method: 'POST',
         headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams(params).toString(),
+        signal,
       },
     );
   }
diff --git a/src/auth.ts b/src/auth.ts
index 9e6bb70..eab06e2 100644
--- a/src/auth.ts
+++ b/src/auth.ts
@@ -1,6 +1,10 @@
+import { AnyApiClient } from './api.js';
 import { API_KEY_ENV } from './constants.js';
-import { readConfig } from './config.js';
-import type { AnyApiConfig } from './types.js';
+import { mergeConfig, readConfig } from './config.js';
+import { connectionConfigFromToken, resolveOAuthEndpoints } from './oauth.js';
+import type { AnyApiConfig, FetchLike } from './types.js';
+
+const REFRESH_WINDOW_MS = 60_000;
 
 export type AuthSource = 'flag' | 'env' | 'config' | 'missing';
 
@@ -14,6 +18,8 @@ export interface ResolveAuthOptions {
   apiKey?: string;
   env?: NodeJS.ProcessEnv;
   configPath?: string;
+  fetchImpl?: FetchLike;
+  now?: () => number;
 }
 
 export async function resolveApiKey(options: ResolveAuthOptions = {}): Promise<AuthResolution> {
@@ -27,15 +33,49 @@ export async function resolveApiKey(options: ResolveAuthOptions = {}): Promise<A
     return { apiKey: envKey, source: 'env', config: {} };
   }
 
-  const config = await readConfig(options.configPath);
-  const configKey = cleanKey(config.apiKey);
+  let config = await readConfig(options.configPath);
+  let configKey = cleanKey(config.apiKey);
   if (configKey) {
+    const refreshToken = cleanKey(config.refreshToken);
+    const oauthClientId = cleanKey(config.oauthClientId)
+      ?? (configKey.startsWith('aa_at_')
+        ? cleanKey(config.clientId) ?? cleanKey(config.cliClientId)
+        : undefined);
+    const expiresAt = parseExpiry(config.accessTokenExpiresAt);
+    const now = options.now?.() ?? Date.now();
+    if (
+      refreshToken
+      && oauthClientId
+      && expiresAt !== undefined
+      && expiresAt <= now + REFRESH_WINDOW_MS
+    ) {
+      const client = new AnyApiClient({ fetchImpl: options.fetchImpl });
+      const endpoints = await resolveOAuthEndpoints(client);
+      const token = await client.exchangeToken(endpoints.tokenEndpoint, {
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: oauthClientId,
+      });
+      config = await mergeConfig(
+        connectionConfigFromToken(token, new Date(now), oauthClientId),
+        options.configPath,
+      );
+      configKey = cleanKey(config.apiKey);
+    }
     return { apiKey: configKey, source: 'config', config };
   }
 
   return { source: 'missing', config };
 }
 
+function parseExpiry(value: unknown): number | undefined {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
 function cleanKey(value: unknown): string | undefined {
   if (typeof value !== 'string') {
     return undefined;
diff --git a/src/commands.ts b/src/commands.ts
index fe94e53..724ef9b 100644
--- a/src/commands.ts
+++ b/src/commands.ts
@@ -23,6 +23,7 @@ import { hasShapeFlags, shapeAndJq, type ShapeRequest } from './shape.js';
 import { resolveLastFile } from './view.js';
 import { configureMcp, detectAgents, installSkillsForAgents, printAgentDetection } from './init.js';
 import { promptYesNo, writeLine, type CommandContext } from './io.js';
+import { deviceLoginCommand, type DeviceLoginDependencies } from './login.js';
 import type { AnyApiConfig, CatalogApi, RunResult, SignupResponse } from './types.js';
 
 interface ShapeCliOptions {
@@ -53,11 +54,27 @@ export async function signupCommand(ctx: CommandContext, options: { label?: stri
   }
 }
 
-export async function loginCommand(ctx: CommandContext, options: { apiKey?: string }): Promise<void> {
+export async function loginCommand(
+  ctx: CommandContext,
+  options: { apiKey?: string },
+  dependencies: DeviceLoginDependencies = {},
+): Promise<void> {
   if (!options.apiKey) {
-    throw new CliError('Missing --api-key aa_live_...');
+    await deviceLoginCommand(ctx, dependencies);
+    return;
   }
-  await mergeConfig({ apiKey: options.apiKey }, getConfigPath(ctx.homeDir));
+  await mergeConfig({
+    apiKey: options.apiKey,
+    refreshToken: undefined,
+    accessTokenExpiresAt: undefined,
+    oauthClientId: undefined,
+    scope: undefined,
+    keyId: undefined,
+    capUsd: undefined,
+    expiresAt: undefined,
+    verificationStatus: undefined,
+    clientId: undefined,
+  }, getConfigPath(ctx.homeDir));
   writeLine(ctx.stdout, 'AnyAPI key saved to ~/.anyapi/config.json.');
 }
 
@@ -165,7 +182,12 @@ export async function balanceCommand(ctx: CommandContext, global: GlobalOptions)
 }
 
 export async function initCommand(ctx: CommandContext, global: GlobalOptions, options: { all?: boolean; yes?: boolean }): Promise<void> {
-  const auth = await resolveApiKey({ apiKey: global.apiKey, env: ctx.env, configPath: getConfigPath(ctx.homeDir) });
+  const auth = await resolveApiKey({
+    apiKey: global.apiKey,
+    env: ctx.env,
+    configPath: getConfigPath(ctx.homeDir),
+    fetchImpl: ctx.fetchImpl,
+  });
   if (auth.source === 'missing') {
     await maybeSignup(ctx, true);
   }
@@ -199,7 +221,12 @@ export async function setupSkillsCommand(ctx: CommandContext, options: { all?: b
 }
 
 async function requireApiKey(ctx: CommandContext, global: GlobalOptions): Promise<{ apiKey: string; config: AnyApiConfig }> {
-  const auth = await resolveApiKey({ apiKey: global.apiKey, env: ctx.env, configPath: getConfigPath(ctx.homeDir) });
+  const auth = await resolveApiKey({
+    apiKey: global.apiKey,
+    env: ctx.env,
+    configPath: getConfigPath(ctx.homeDir),
+    fetchImpl: ctx.fetchImpl,
+  });
   if (auth.apiKey) {
     return { apiKey: auth.apiKey, config: auth.config };
   }
@@ -235,6 +262,10 @@ async function saveSignup(ctx: CommandContext, signup: SignupResponse): Promise<
       clientId: signup.clientId,
       expiresAt: signup.expiresAt,
       verificationStatus: signup.verificationStatus,
+      refreshToken: undefined,
+      accessTokenExpiresAt: undefined,
+      oauthClientId: undefined,
+      scope: undefined,
     },
     getConfigPath(ctx.homeDir),
   );
diff --git a/src/connect.ts b/src/connect.ts
index 602d560..b548d43 100644
--- a/src/connect.ts
+++ b/src/connect.ts
@@ -1,33 +1,22 @@
-import { execFile } from 'node:child_process';
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
 import { AnyApiClient } from './api.js';
 import { getConfigPath, mergeConfig, readConfig } from './config.js';
-import {
-  OAUTH_AUTHORIZE_URL,
-  OAUTH_METADATA_URL,
-  OAUTH_REGISTER_URL,
-  OAUTH_SCOPE,
-  OAUTH_TOKEN_URL,
-} from './constants.js';
+import { OAUTH_SCOPE } from './constants.js';
 import { CliError } from './errors.js';
 import { writeLine, type CommandContext } from './io.js';
+import {
+  connectionConfigFromToken,
+  openBrowser,
+  resolveClientId,
+  resolveOAuthEndpoints,
+} from './oauth.js';
 import { buildAuthorizeUrl, createPkce, randomState } from './pkce.js';
-import type { AnyApiConfig, TokenResponse } from './types.js';
+import type { TokenResponse } from './types.js';
+
+export { connectionConfigFromToken, resolveClientId } from './oauth.js';
 
 const CALLBACK_PATH = '/callback';
 const CONNECT_TIMEOUT_MS = 5 * 60 * 1000;
-const CLI_CLIENT_NAME = 'AnyAPI CLI';
-// Portless loopback redirect URIs registered for the CLI's public client. The
-// server matches ports flexibly at authorize time, so registering portless is
-// correct and lets each run bind an ephemeral loopback port.
-const LOOPBACK_REDIRECT_URIS = ['http://127.0.0.1/callback', 'http://localhost/callback'];
-
-interface Endpoints {
-  authorizationEndpoint: string;
-  tokenEndpoint: string;
-  registrationEndpoint: string;
-}
-
 // connectCommand connects an AnyAPI wallet with a one-URL OAuth 2.1 Authorization
 // Code + PKCE approval over a loopback callback. It resolves an OAuth client id
 // (trial client, a previously registered CLI client, or a fresh Dynamic Client
@@ -38,8 +27,11 @@ export async function connectCommand(ctx: CommandContext): Promise<void> {
   const config = await readConfig(configPath);
 
   const client = new AnyApiClient({ fetchImpl: ctx.fetchImpl });
-  const endpoints = await resolveEndpoints(client);
-  const clientId = await resolveClientId(config, client, endpoints.registrationEndpoint, configPath);
+  const endpoints = await resolveOAuthEndpoints(client);
+  const clientId = await resolveClientId(config, client, endpoints.registrationEndpoint, configPath, {
+    includeTrialClient: true,
+    commandName: 'anyapi connect',
+  });
   const pkce = createPkce();
   const state = randomState();
 
@@ -58,85 +50,10 @@ export async function connectCommand(ctx: CommandContext): Promise<void> {
     code_verifier: pkce.verifier,
   });
 
-  await mergeConfig(connectionConfigFromToken(token), configPath);
+  await mergeConfig(connectionConfigFromToken(token, new Date(), clientId), configPath);
   printConnected(ctx, token);
 }
 
-// connectionConfigFromToken maps a token response onto the config patch. The
-// access token becomes the active apiKey (used as Authorization: Bearer exactly
-// like a key); the refresh token, expiry, and scope are stored alongside it.
-export function connectionConfigFromToken(token: TokenResponse, now: Date = new Date()): AnyApiConfig {
-  const patch: AnyApiConfig = {
-    apiKey: token.access_token,
-    refreshToken: token.refresh_token,
-    scope: token.scope,
-  };
-  if (typeof token.expires_in === 'number' && Number.isFinite(token.expires_in)) {
-    patch.accessTokenExpiresAt = new Date(now.getTime() + token.expires_in * 1000).toISOString();
-  }
-  return patch;
-}
-
-// resolveClientId picks the OAuth client id in priority order: the per-trial
-// client from signup/init (preserves the trial-upgrade receipt), else a CLI
-// client previously registered via Dynamic Client Registration, else a fresh DCR
-// whose client id is persisted so the rate-limited endpoint is hit at most once.
-export async function resolveClientId(
-  config: AnyApiConfig,
-  client: AnyApiClient,
-  registrationEndpoint: string,
-  configPath: string,
-): Promise<string> {
-  const trialClientId = config.clientId?.trim();
-  if (trialClientId) {
-    return trialClientId;
-  }
-  const cliClientId = config.cliClientId?.trim();
-  if (cliClientId) {
-    return cliClientId;
-  }
-
-  let registered;
-  try {
-    registered = await client.registerClient(registrationEndpoint, {
-      clientName: CLI_CLIENT_NAME,
-      redirectUris: LOOPBACK_REDIRECT_URIS,
-    });
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new CliError(`Could not register an OAuth client for anyapi connect: ${detail}`);
-  }
-
-  const clientId = registered.client_id?.trim();
-  if (!clientId) {
-    throw new CliError('OAuth client registration did not return a client_id.');
-  }
-  await mergeConfig({ cliClientId: clientId }, configPath);
-  return clientId;
-}
-
-// resolveEndpoints prefers the RFC 8414 metadata document and falls back to the
-// hardcoded gateway endpoints when discovery fails or omits an endpoint.
-async function resolveEndpoints(client: AnyApiClient): Promise<Endpoints> {
-  try {
-    const meta = await client.oauthMetadata(OAUTH_METADATA_URL);
-    if (meta.authorization_endpoint && meta.token_endpoint) {
-      return {
-        authorizationEndpoint: meta.authorization_endpoint,
-        tokenEndpoint: meta.token_endpoint,
-        registrationEndpoint: meta.registration_endpoint ?? OAUTH_REGISTER_URL,
-      };
-    }
-  } catch {
-    // Discovery is best-effort; fall through to the hardcoded endpoints.
-  }
-  return {
-    authorizationEndpoint: OAUTH_AUTHORIZE_URL,
-    tokenEndpoint: OAUTH_TOKEN_URL,
-    registrationEndpoint: OAUTH_REGISTER_URL,
-  };
-}
-
 interface LoopbackParams {
   authorizationEndpoint: string;
   clientId: string;
@@ -231,22 +148,6 @@ function respondHtml(res: ServerResponse, status: number, message: string): void
   res.end(html);
 }
 
-// openBrowser launches the default browser best-effort; failures are ignored so
-// the printed consent URL remains the reliable path.
-function openBrowser(url: string): void {
-  const launch: { command: string; args: string[] } =
-    process.platform === 'darwin'
-      ? { command: 'open', args: [url] }
-      : process.platform === 'win32'
-        ? { command: 'cmd', args: ['/c', 'start', '', url] }
-        : { command: 'xdg-open', args: [url] };
-  try {
-    execFile(launch.command, launch.args, () => undefined);
-  } catch {
-    // Best-effort only.
-  }
-}
-
 function printConsentUrl(ctx: CommandContext, url: string): void {
   writeLine(ctx.stdout, 'Hand this URL to your human to approve continued spend:');
   writeLine(ctx.stdout, url);
diff --git a/src/constants.ts b/src/constants.ts
index 91f339a..f66807b 100644
--- a/src/constants.ts
+++ b/src/constants.ts
@@ -8,6 +8,7 @@ export const SIGNUP_URL = `${API_BASE_URL}/agent/signup`;
 export const MCP_URL = `${API_BASE_URL}/mcp`;
 export const OAUTH_METADATA_URL = `${API_BASE_URL}/.well-known/oauth-authorization-server`;
 export const OAUTH_AUTHORIZE_URL = `${API_BASE_URL}/oauth/authorize`;
+export const OAUTH_DEVICE_AUTHORIZATION_URL = `${API_BASE_URL}/oauth/device_authorization`;
 export const OAUTH_TOKEN_URL = `${API_BASE_URL}/oauth/token`;
 export const OAUTH_REGISTER_URL = `${API_BASE_URL}/oauth/register`;
 export const OAUTH_SCOPE = 'run balance:read';
diff --git a/src/index.ts b/src/index.ts
index f889813..bce73f0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -24,7 +24,7 @@ program
   .name('anyapi')
   .description('Official CLI for AnyAPI.')
   .option('--api-key <apiKey>', 'AnyAPI API key. Overrides ANYAPI_API_KEY and local config.')
-  .version('0.3.3');
+  .version('0.5.0');
 
 program
   .command('signup')
@@ -35,8 +35,9 @@ program
 
 program
   .command('login')
-  .description('Store an existing AnyAPI key locally. Pass the key with the global --api-key flag.')
-  .action(() => run(() => loginCommand(ctx, globalOptions())));
+  .description('Sign in with cross-device OAuth, or store an existing key with --api-key.')
+  .option('--api-key <apiKey>', 'Store an existing AnyAPI API key instead of starting OAuth.')
+  .action((options) => run(() => loginCommand(ctx, { apiKey: options.apiKey ?? globalOptions().apiKey })));
 
 program
   .command('search')
diff --git a/src/login.ts b/src/login.ts
new file mode 100644
index 0000000..d6186fd
--- /dev/null
+++ b/src/login.ts
@@ -0,0 +1,163 @@
+import { AnyApiClient } from './api.js';
+import { getConfigPath, mergeConfig, readConfig } from './config.js';
+import { OAUTH_SCOPE } from './constants.js';
+import { ApiError, CliError } from './errors.js';
+import { writeLine, type CommandContext } from './io.js';
+import {
+  connectionConfigFromToken,
+  openBrowser,
+  resolveClientId,
+  resolveOAuthEndpoints,
+} from './oauth.js';
+import type { DeviceAuthorizationResponse, TokenResponse } from './types.js';
+
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const SLOW_DOWN_SECONDS = 5;
+const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+
+export interface DeviceLoginDependencies {
+  now?: () => number;
+  sleep?: (milliseconds: number) => Promise<void>;
+  openUrl?: (url: string) => void;
+}
+
+export async function deviceLoginCommand(
+  ctx: CommandContext,
+  dependencies: DeviceLoginDependencies = {},
+): Promise<void> {
+  const now = dependencies.now ?? Date.now;
+  const sleep = dependencies.sleep ?? defaultSleep;
+  const openUrl = dependencies.openUrl ?? openBrowser;
+  const configPath = getConfigPath(ctx.homeDir);
+  const config = await readConfig(configPath);
+  const client = new AnyApiClient({ fetchImpl: ctx.fetchImpl });
+  const endpoints = await resolveOAuthEndpoints(client);
+  const clientId = await resolveClientId(config, client, endpoints.registrationEndpoint, configPath, {
+    includeTrialClient: false,
+    commandName: 'anyapi login',
+  });
+
+  const authorization = await client.authorizeDevice(endpoints.deviceAuthorizationEndpoint, {
+    client_id: clientId,
+    scope: OAUTH_SCOPE,
+  });
+  validateAuthorization(authorization);
+  printDeviceInstructions(ctx, authorization);
+  if (authorization.verification_uri_complete) {
+    try {
+      openUrl(authorization.verification_uri_complete);
+    } catch {
+      // Best-effort only; the verification URL and user code are already printed.
+    }
+  }
+
+  const token = await pollForToken(client, endpoints.tokenEndpoint, clientId, authorization, { now, sleep });
+  await mergeConfig(connectionConfigFromToken(token, new Date(now()), clientId), configPath);
+  printLoggedIn(ctx, token);
+}
+
+interface PollClock {
+  now: () => number;
+  sleep: (milliseconds: number) => Promise<void>;
+}
+
+export async function pollForToken(
+  client: AnyApiClient,
+  tokenEndpoint: string,
+  clientId: string,
+  authorization: DeviceAuthorizationResponse,
+  clock: PollClock,
+): Promise<TokenResponse> {
+  const deadline = clock.now() + authorization.expires_in * 1000;
+  let intervalMs = (authorization.interval ?? DEFAULT_POLL_INTERVAL_SECONDS) * 1000;
+
+  while (true) {
+    const remainingMs = deadline - clock.now();
+    if (remainingMs <= 0) {
+      throw timeoutError();
+    }
+    await clock.sleep(Math.min(intervalMs, remainingMs));
+    if (clock.now() >= deadline) {
+      throw timeoutError();
+    }
+
+    const controller = new AbortController();
+    const requestTimeout = setTimeout(
+      () => controller.abort(),
+      Math.max(1, deadline - clock.now()),
+    );
+    try {
+      return await client.exchangeToken(tokenEndpoint, {
+        grant_type: DEVICE_CODE_GRANT,
+        device_code: authorization.device_code,
+        client_id: clientId,
+      }, controller.signal);
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw timeoutError();
+      }
+      const code = oauthErrorCode(error);
+      if (code === 'authorization_pending') {
+        continue;
+      }
+      if (code === 'slow_down') {
+        intervalMs += SLOW_DOWN_SECONDS * 1000;
+        continue;
+      }
+      if (code === 'access_denied') {
+        throw new CliError('AnyAPI sign-in was denied. Re-run anyapi login to try again.');
+      }
+      if (code === 'expired_token') {
+        throw new CliError('The AnyAPI sign-in code expired. Re-run anyapi login to get a new code.');
+      }
+      throw error;
+    } finally {
+      clearTimeout(requestTimeout);
+    }
+  }
+}
+
+function validateAuthorization(value: DeviceAuthorizationResponse): void {
+  if (
+    !value.device_code
+    || !value.user_code
+    || !value.verification_uri
+    || !Number.isFinite(value.expires_in)
+    || value.expires_in <= 0
+    || (value.interval !== undefined && (!Number.isFinite(value.interval) || value.interval <= 0))
+  ) {
+    throw new CliError('Device authorization returned an invalid response. Re-run anyapi login.');
+  }
+}
+
+function oauthErrorCode(error: unknown): string | undefined {
+  if (!(error instanceof ApiError) || !isRecord(error.body)) {
+    return undefined;
+  }
+  return typeof error.body.error === 'string' ? error.body.error : undefined;
+}
+
+function timeoutError(): CliError {
+  return new CliError('Timed out waiting for AnyAPI sign-in. Re-run anyapi login to get a new code.');
+}
+
+function printDeviceInstructions(ctx: CommandContext, authorization: DeviceAuthorizationResponse): void {
+  writeLine(ctx.stdout, 'Sign in to AnyAPI on any device:');
+  writeLine(ctx.stdout, authorization.verification_uri);
+  writeLine(ctx.stdout, `Code: ${authorization.user_code}`);
+  writeLine(ctx.stdout, 'Opening the sign-in page in your browser when possible. Waiting for approval...');
+}
+
+function printLoggedIn(ctx: CommandContext, token: TokenResponse): void {
+  writeLine(ctx.stdout, 'Logged in. Account-backed AnyAPI OAuth is ready.');
+  writeLine(ctx.stdout, `Scope: ${token.scope}`);
+  writeLine(ctx.stdout, 'Access token saved to ~/.anyapi/config.json.');
+}
+
+function defaultSleep(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
diff --git a/src/oauth.ts b/src/oauth.ts
new file mode 100644
index 0000000..8e76f34
--- /dev/null
+++ b/src/oauth.ts
@@ -0,0 +1,153 @@
+import { execFile } from 'node:child_process';
+import { AnyApiClient } from './api.js';
+import { mergeConfig } from './config.js';
+import {
+  OAUTH_AUTHORIZE_URL,
+  OAUTH_DEVICE_AUTHORIZATION_URL,
+  OAUTH_METADATA_URL,
+  OAUTH_REGISTER_URL,
+  OAUTH_TOKEN_URL,
+} from './constants.js';
+import { CliError } from './errors.js';
+import type { AnyApiConfig, TokenResponse } from './types.js';
+
+const CLI_CLIENT_NAME = 'AnyAPI CLI';
+// Register one reusable public CLI client that can support both the loopback
+// authorization-code flow and the device flow.
+const LOOPBACK_REDIRECT_URIS = ['http://127.0.0.1/callback', 'http://localhost/callback'];
+
+export interface OAuthEndpoints {
+  authorizationEndpoint: string;
+  deviceAuthorizationEndpoint: string;
+  tokenEndpoint: string;
+  registrationEndpoint: string;
+}
+
+export interface ResolveClientIdOptions {
+  includeTrialClient?: boolean;
+  commandName?: string;
+}
+
+// resolveOAuthEndpoints prefers RFC 8414 metadata and shares connect's existing
+// hardcoded fallback behavior with device login.
+export async function resolveOAuthEndpoints(client: AnyApiClient): Promise<OAuthEndpoints> {
+  try {
+    const meta = await client.oauthMetadata(OAUTH_METADATA_URL);
+    // Preserve connect's existing all-or-fallback behavior for its required
+    // authorization and token endpoints.
+    if (meta.authorization_endpoint && meta.token_endpoint) {
+      return {
+        authorizationEndpoint: meta.authorization_endpoint,
+        deviceAuthorizationEndpoint: meta.device_authorization_endpoint || OAUTH_DEVICE_AUTHORIZATION_URL,
+        tokenEndpoint: meta.token_endpoint,
+        registrationEndpoint: meta.registration_endpoint || OAUTH_REGISTER_URL,
+      };
+    }
+  } catch {
+    // Discovery is best-effort; fall through to the hardcoded endpoints.
+  }
+  return fallbackEndpoints();
+}
+
+// resolveClientId preserves connect's trial-client priority when requested.
+// Device login deliberately uses the reusable non-trial CLI client so it starts
+// an account-backed sign-in instead of taking ownership of a trial upgrade.
+export async function resolveClientId(
+  config: AnyApiConfig,
+  client: AnyApiClient,
+  registrationEndpoint: string,
+  configPath: string,
+  options: ResolveClientIdOptions = {},
+): Promise<string> {
+  if (options.includeTrialClient !== false) {
+    const trialClientId = config.clientId?.trim();
+    if (trialClientId) {
+      return trialClientId;
+    }
+  }
+
+  const cliClientId = config.cliClientId?.trim();
+  if (cliClientId) {
+    return cliClientId;
+  }
+
+  let registered;
+  try {
+    registered = await client.registerClient(registrationEndpoint, {
+      clientName: CLI_CLIENT_NAME,
+      redirectUris: LOOPBACK_REDIRECT_URIS,
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new CliError(`Could not register an OAuth client for ${options.commandName ?? 'AnyAPI CLI'}: ${detail}`);
+  }
+
+  const clientId = registered.client_id?.trim();
+  if (!clientId) {
+    throw new CliError('OAuth client registration did not return a client_id.');
+  }
+  await mergeConfig({ cliClientId: clientId }, configPath);
+  return clientId;
+}
+
+// connectionConfigFromToken maps either OAuth grant's response onto the same
+// persisted config fields.
+export function connectionConfigFromToken(
+  token: TokenResponse,
+  now: Date = new Date(),
+  oauthClientId?: string,
+): AnyApiConfig {
+  validateTokenResponse(token);
+  const patch: AnyApiConfig = {
+    apiKey: token.access_token,
+    refreshToken: token.refresh_token,
+    ...(oauthClientId ? { oauthClientId } : {}),
+    scope: token.scope,
+  };
+  if (typeof token.expires_in === 'number' && Number.isFinite(token.expires_in)) {
+    patch.accessTokenExpiresAt = new Date(now.getTime() + token.expires_in * 1000).toISOString();
+  }
+  return patch;
+}
+
+export function validateTokenResponse(token: TokenResponse): void {
+  if (
+    !token
+    || typeof token.access_token !== 'string'
+    || token.access_token.trim().length === 0
+    || typeof token.token_type !== 'string'
+    || token.token_type.toLowerCase() !== 'bearer'
+    || !Number.isFinite(token.expires_in)
+    || token.expires_in <= 0
+    || typeof token.refresh_token !== 'string'
+    || token.refresh_token.trim().length === 0
+    || typeof token.scope !== 'string'
+  ) {
+    throw new CliError('OAuth token endpoint returned an invalid response. Sign in again.');
+  }
+}
+
+// openBrowser launches the default browser best-effort; the printed URL and
+// code remain the reliable cross-device path when launching is unavailable.
+export function openBrowser(url: string): void {
+  const launch: { command: string; args: string[] } =
+    process.platform === 'darwin'
+      ? { command: 'open', args: [url] }
+      : process.platform === 'win32'
+        ? { command: 'cmd', args: ['/c', 'start', '', url] }
+        : { command: 'xdg-open', args: [url] };
+  try {
+    execFile(launch.command, launch.args, () => undefined);
+  } catch {
+    // Best-effort only.
+  }
+}
+
+function fallbackEndpoints(): OAuthEndpoints {
+  return {
+    authorizationEndpoint: OAUTH_AUTHORIZE_URL,
+    deviceAuthorizationEndpoint: OAUTH_DEVICE_AUTHORIZATION_URL,
+    tokenEndpoint: OAUTH_TOKEN_URL,
+    registrationEndpoint: OAUTH_REGISTER_URL,
+  };
+}
diff --git a/src/types.ts b/src/types.ts
index ead7817..920c2b6 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -8,6 +8,7 @@ export interface AnyApiConfig {
   cliClientId?: string;
   refreshToken?: string;
   accessTokenExpiresAt?: string;
+  oauthClientId?: string;
   scope?: string;
 }
 
@@ -29,14 +30,24 @@ export interface SignupResponse {
 }
 
 export interface OAuthMetadata {
-  authorization_endpoint: string;
-  token_endpoint: string;
+  authorization_endpoint?: string;
+  device_authorization_endpoint?: string;
+  token_endpoint?: string;
   registration_endpoint?: string;
   code_challenge_methods_supported?: string[];
   token_endpoint_auth_methods_supported?: string[];
   scopes_supported?: string[];
 }
 
+export interface DeviceAuthorizationResponse {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  verification_uri_complete?: string;
+  expires_in: number;
+  interval?: number;
+}
+
 // ClientRegistrationRequest is the OAuth 2.1 Dynamic Client Registration body.
 // token_endpoint_auth_method MUST be 'none' (public client) or the server 400s.
 export interface ClientRegistrationRequest {