@anyslate/cli 0.2.0 → 0.3.0

package/src/commands/doctor.mjs

@@ -26,6 +26,7 @@ import {
   requireToken,
 } from '../config.mjs';
 import { checkUrlShape, hasWriteScope, isValidTokenFormat, probeVerify, tokenPreview } from '../verify.mjs';
+import { hasOauthCredentials, isExpired, minutesUntilExpiry, resolveBearer } from '../auth.mjs';
 import { lastRunPath, readLastRun } from '../runlog.mjs';
 import { callTool } from '../mcp-client.mjs';
 import { VERSION, USER_AGENT } from '../version.mjs';
@@ -128,9 +129,21 @@ export async function runDoctor(argv = [], deps = {}) {
   }
 
   // ---- 2. Token present --------------------------------------------------
+  // "Present" now has three shapes: an env/static token, a live OAuth access
+  // token, or OAuth credentials whose access token has aged out but which carry
+  // a refresh token. The third is NOT a failure — the refresh happens further
+  // down, once the URL and reachability checks have cleared.
+  const oauthPresent = hasOauthCredentials(cfg.oauth);
   const tokenCheck = requireToken(cfg);
-  if (!tokenCheck.ok) {
+  if (!tokenCheck.ok && !oauthPresent) {
     add(FAIL, 'token-present', 'No MCP token configured.', tokenCheck.error);
+  } else if (!tokenCheck.ok) {
+    add(
+      WARN,
+      'token-present',
+      'OAuth access token has expired; a refresh is needed before the next call.',
+      'This is normal — access tokens live one hour. The refresh is exercised by the oauth-refresh check below.',
+    );
   } else {
     add(
       PASS,
@@ -139,6 +152,44 @@ export async function runDoctor(argv = [], deps = {}) {
     );
   }
 
+  // ---- 2a. Auth mode -----------------------------------------------------
+  // Pure config inspection, no network. Which credential the CLI would use is
+  // the first thing anyone debugging "capture stopped" needs to know, and it
+  // must be answerable even when the host is down.
+  if (cfg.sources.mcpToken === 'env' && cfg.mcpToken) {
+    add(PASS, 'auth-mode', 'Static token from ANYSLATE_MCP_TOKEN (env) — no refresh, never expires.');
+    if (oauthPresent) {
+      add(
+        WARN,
+        'auth-override',
+        'ANYSLATE_MCP_TOKEN is overriding a stored OAuth session.',
+        'Unset ANYSLATE_MCP_TOKEN to go back to the browser-issued credential.',
+      );
+    }
+  } else if (oauthPresent) {
+    const mins = minutesUntilExpiry(cfg.oauth);
+    const when =
+      mins == null
+        ? 'expiry unknown (no parseable expires_at)'
+        : mins >= 0
+          ? `expires in ${mins} min (${cfg.oauth.expires_at})`
+          : `expired ${Math.abs(mins)} min ago (${cfg.oauth.expires_at})`;
+    if (!cfg.oauth.refresh_token) {
+      add(
+        WARN,
+        'auth-mode',
+        `OAuth (browser sign-in), ${when}, no refresh token stored.`,
+        'Without a refresh token the session dies at expiry. Run `anyslate login` to get one.',
+      );
+    } else {
+      add(PASS, 'auth-mode', `OAuth (browser sign-in), ${when}, refresh token stored.`);
+    }
+  } else if (cfg.staticToken) {
+    add(PASS, 'auth-mode', `Static MCP token from ${cfg.sources.mcpToken} — no refresh, never expires.`);
+  } else {
+    add(SKIP, 'auth-mode', 'No credentials to classify.');
+  }
+
   // ---- 2b. Handle FORMAT — never gated behind a server round trip ---------
   // This is the exact live failure that produced a 100% invisible capture
   // loss: cli/README.md told users to export `ANYSLATE_HANDLE=h_xxx`, but real
@@ -171,6 +222,8 @@ export async function runDoctor(argv = [], deps = {}) {
         'Mint one in the desktop app at Avatar (top-right) → API Tokens → Create Token.',
       );
     }
+  } else if (oauthPresent) {
+    add(SKIP, 'token-format', 'OAuth access token is past its expiry; the format is checked after it is refreshed.');
   } else {
     add(SKIP, 'token-format', 'No token to check.');
   }
@@ -224,10 +277,49 @@ export async function runDoctor(argv = [], deps = {}) {
     add(SKIP, 'reachability', 'URL shape failed; not probing.');
   }
 
+  // ---- 5b. OAuth refresh -------------------------------------------------
+  // Deliberately AFTER url-shape and reachability. A refresh against an
+  // unreachable host fails for a reason that has nothing to do with the
+  // credential, and reporting that as "refresh is broken" sends the user
+  // hunting for the wrong bug.
+  let bearer = cfg.mcpToken;
+  if (shape.ok && reachable && oauthPresent && cfg.sources.mcpToken !== 'env') {
+    const wasStale = isExpired(cfg.oauth) || flags.refresh;
+    const resolved = await resolveBearer({ cfg, env, fetchImpl, force: flags.refresh });
+    if (resolved.ok) {
+      bearer = resolved.token;
+      if (resolved.refreshed) {
+        add(PASS, 'oauth-refresh', 'Refreshed the access token successfully; the rotated refresh token was persisted.');
+      } else if (wasStale) {
+        add(PASS, 'oauth-refresh', 'Access token was already renewed by another process; nothing to do.');
+      } else {
+        add(
+          PASS,
+          'oauth-refresh',
+          'Refresh token is stored and the access token is still valid — refresh not exercised.',
+          'Run `anyslate doctor --refresh` to force a real refresh round trip (it rotates the refresh token).',
+        );
+      }
+    } else {
+      add(
+        FAIL,
+        'oauth-refresh',
+        `OAuth refresh failed: ${String(resolved.message).replace(/^anyslate: /, '')}`,
+        'Run `anyslate login` to sign in again. Refresh tokens live 30 days and are single-use (rotated on every refresh).',
+      );
+    }
+  } else if (oauthPresent && cfg.sources.mcpToken === 'env') {
+    add(SKIP, 'oauth-refresh', 'ANYSLATE_MCP_TOKEN is in use; the stored OAuth session is not consulted.');
+  } else if (oauthPresent) {
+    add(SKIP, 'oauth-refresh', 'Skipped — the URL and reachability checks must pass before a refresh is meaningful.');
+  } else {
+    add(SKIP, 'oauth-refresh', 'Not an OAuth session.');
+  }
+
   // ---- 6. Token valid ----------------------------------------------------
   let verified = null;
-  if (shape.ok && tokenCheck.ok && reachable) {
-    verified = await probeVerify({ root, token: cfg.mcpToken, fetchImpl });
+  if (shape.ok && reachable && bearer) {
+    verified = await probeVerify({ root, token: bearer, fetchImpl });
     if (verified.ok) {
       add(PASS, 'token-valid', `${verified.message.replace(/^anyslate: /, '')}`);
     } else {
@@ -345,7 +437,7 @@ export async function runDoctor(argv = [], deps = {}) {
     if (verified?.ok) {
       const res = await callTool({
         apiUrl: root,
-        token: cfg.mcpToken,
+        token: bearer,
         toolName: 'activity_submit',
         args: {
           source: 'api',
@@ -513,9 +605,10 @@ function indent(block) {
 
 /** @param {string[]} argv */
 function parseFlags(argv) {
-  const out = { deep: false };
+  const out = { deep: false, refresh: false };
   for (const a of argv) {
     if (a === '--deep') out.deep = true;
+    else if (a === '--refresh') out.refresh = true;
   }
   return out;
 }

package/src/commands/hook.mjs

@@ -19,7 +19,8 @@
 // nothing and exited 0.
 
 import { loadConfig, requireToken, apiUrlNormalizationNotice, DISABLED_NOTICE } from '../config.mjs';
-import { callTool, formatCallFailure } from '../mcp-client.mjs';
+import { formatCallFailure } from '../mcp-client.mjs';
+import { callToolWithAuth, formatAuthFailure } from '../auth.mjs';
 import { buildHookSubmission, parseHookEvent } from '../hooks.mjs';
 import { readStdin, stdinTimeoutFromEnv } from '../stdin.mjs';
 import { recordRun, shouldEscalate, escalationPayload } from '../runlog.mjs';
@@ -65,9 +66,12 @@ export async function runHook(argv, deps = {}) {
   const notice = apiUrlNormalizationNotice(cfg);
   if (notice) err.write(notice);
 
-  const tokenCheck = requireToken(cfg);
-  if (!tokenCheck.ok) {
-    return fail(`${prefix}: ${tokenCheck.error}\n`);
+  // Credential PRESENCE only. An expired OAuth access token is not "missing" —
+  // callToolWithAuth refreshes it below — so gating on `cfg.mcpToken` here (as
+  // this did before OAuth) would turn every hour-old session into a silent
+  // no-capture with a misleading "no token configured" in the run log.
+  if (cfg.authMode === 'none') {
+    return fail(`${prefix}: ${requireToken({ mcpToken: null }).error}\n`);
   }
 
   let stdinRaw = '';
@@ -95,15 +99,18 @@ export async function runHook(argv, deps = {}) {
   if (submission.sessionIdHint) args.session_id_hint = submission.sessionIdHint;
 
   try {
-    const res = await callTool({
-      apiUrl: cfg.apiUrl,
-      token: cfg.mcpToken,
+    // Never opens a browser: this path runs unattended inside Claude Code.
+    // A refresh failure surfaces as an ordinary failure and still exits 0.
+    const res = await callToolWithAuth({
+      cfg,
+      env,
       toolName: 'activity_submit',
       args,
       fetchImpl: deps.fetchImpl,
     });
+    if (res.authWarning) err.write(`${res.authWarning}\n`);
     if (!res.ok) {
-      return fail(formatCallFailure(prefix, res), {
+      return fail(formatAuthFailure(prefix, res) ?? formatCallFailure(prefix, res), {
         status: res.status,
         isError: !!res.isError,
         networkError: !!res.networkError,

package/src/commands/login.mjs

@@ -1,65 +1,119 @@
-// `anyslate login` - validate credentials, then write `~/.anyslate/cli.json`.
+// `anyslate login` - two credential paths, one config file.
 //
-// Mint the token in the desktop app at Avatar (top-right) → API Tokens →
-// Create Token (available on every current tier). Then:
+//   anyslate login                        OAuth browser flow (default, humans)
+//   anyslate login --api-url <root>       ... against dev / a local wrangler
+//   anyslate login --token as_mcp_…       static token (CI, air-gapped, scripts)
 //
-//   anyslate login --token <BEARER>
-//   anyslate login --token <BEARER> --handle <HANDLE_ID>
-//   anyslate login --token <BEARER> --api-url https://anyslate-mcp-service-development.<workers-dev-url>
+// The static-token path is UNCHANGED and stays first-class. It is the only one
+// that works where no browser exists, and a long-lived token is the right shape
+// for a CI secret. `--token` is therefore the switch between the two paths: its
+// presence selects the static flow, its absence selects OAuth.
 //
-// The file is written with mode 0600 - only the current user can read it.
-//
-// W3: `login` used to perform ZERO network I/O — its imports were three
-// node: builtins. It accepted a token that is not a token and a hostname that
-// cannot resolve, printing success and exiting 0 for both. It now:
-//   1. checks token format,
-//   2. resolves URL shape (MUST precede any token verdict — a wrong URL 404s
-//      before auth middleware and masks the real answer),
-//   3. runs one live GET {root}/mcp/auth/verify,
-//   4. warns on a missing memory:write scope,
-//   5. writes the file ONLY on success.
+// Ordering in the static path is load-bearing and is preserved verbatim:
+//   1. token format,
+//   2. URL shape (MUST precede any token verdict — a wrong URL 404s before auth
+//      middleware and masks the real answer),
+//   3. one live GET {root}/mcp/auth/verify,
+//   4. scope warning,
+//   5. write ONLY on success.
 // `--force` writes anyway; `--no-verify` skips the probe (air-gapped setup).
+//
+// The OAuth path ends at the same place — one `/mcp/auth/verify` probe, the same
+// printed verdict line — so "logged in" means exactly one thing regardless of
+// how the credential was obtained.
 
-import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DEFAULT_API_URL, anyslateDir, isCaptureDisabled, normalizeApiRoot } from '../config.mjs';
 import { checkUrlShape, isValidTokenFormat, probeVerify, scopeWarning, tokenPreview } from '../verify.mjs';
+import { readConfigFile, writeConfigFile } from '../credentials.mjs';
+import {
+  DEFAULT_CALLBACK_TIMEOUT_S,
+  REGISTERED_REDIRECT_URI,
+  buildAuthorizeUrl,
+  discover,
+  exchangeCode,
+  generatePkce,
+  generateState,
+  openBrowser,
+  registerClient,
+  startCallbackServer,
+} from '../oauth.mjs';
 import { makeIo } from '../io.mjs';
 
+export const USAGE =
+  'usage: anyslate login [--api-url <URL>] [--no-browser] [--timeout <seconds>] [--handle <ID>]\n' +
+  '       anyslate login --token <BEARER> [--handle <ID>] [--api-url <URL>] [--force] [--no-verify]\n' +
+  '\n' +
+  '  With no --token, `login` opens your browser and signs you in with OAuth.\n' +
+  '  --token keeps the static-token path for CI and air-gapped setups.';
+
 /**
  * @param {string[]} argv  arguments after `login`
- * @param {{fetchImpl?: typeof fetch, env?: NodeJS.ProcessEnv}} [deps]
+ * @param {{fetchImpl?: typeof fetch, env?: NodeJS.ProcessEnv,
+ *          openBrowserImpl?: typeof openBrowser,
+ *          onAuthorizeUrl?: (url: string, ctx: object) => unknown}} [deps]
  * @returns {Promise<number>}
  */
 export async function runLogin(argv, deps = {}) {
-  const env = deps.env ?? process.env;
-  const fetchImpl = deps.fetchImpl ?? fetch;
-  const { out, err } = makeIo(deps);
   const flags = parseFlags(argv);
-
-  if (!flags.token) {
-    err.write(
-      'usage: anyslate login --token <BEARER> [--handle <ID>] [--api-url <URL>] [--force] [--no-verify]\n',
-    );
+  if (flags.help) {
+    makeIo(deps).err.write(`${USAGE}\n`);
     return 2;
   }
+  return flags.token ? runTokenLogin(flags, deps) : runOauthLogin(flags, deps);
+}
+
+// ---------------------------------------------------------------------------
+// Shared
+// ---------------------------------------------------------------------------
 
-  if (isCaptureDisabled(env)) {
-    // login is setup, not capture — it still runs, but say so, because the
-    // shell it was run in will capture nothing afterwards.
-    err.write(
-      'anyslate: note — ANYSLATE_DISABLE is set, so capture is off in this shell. `login` still writes your config.\n',
+/**
+ * Resolve the service root exactly as the static path always has: an explicit
+ * --api-url wins, else the stored value is inherited AND re-normalized so a
+ * previously-broken `/mcp`-suffixed apiUrl cannot survive a re-login.
+ */
+function resolveRoot(flags, existing, io) {
+  const merged = flags.apiUrl ?? existing.apiUrl ?? existing.api_url ?? DEFAULT_API_URL;
+  const shape = checkUrlShape(merged);
+  const root = shape.ok ? shape.root : normalizeApiRoot(merged);
+  if (shape.ok && shape.normalized) {
+    io.out.write(
+      `anyslate: apiUrl "${shape.original}" ends in /mcp — the CLI wants the service ROOT and appends /mcp itself.\n` +
+        `anyslate: using "${root}". Run \`anyslate login --api-url ${root}\` to persist.\n`,
     );
   }
+  return { shape, root };
+}
+
+function noteIfCaptureDisabled(env, io) {
+  if (!isCaptureDisabled(env)) return;
+  io.err.write(
+    'anyslate: note — ANYSLATE_DISABLE is set, so capture is off in this shell. `login` still writes your config.\n',
+  );
+}
 
-  const dir = anyslateDir(env);
-  const path = join(dir, 'cli.json');
-  let existing = {};
+function hostOf(root) {
   try {
-    existing = JSON.parse(readFileSync(path, 'utf8')) || {};
+    return new URL(root).host;
   } catch {
-    existing = {};
+    return root;
   }
+}
+
+// ---------------------------------------------------------------------------
+// Static token path (behaviour unchanged)
+// ---------------------------------------------------------------------------
+
+async function runTokenLogin(flags, deps) {
+  const env = deps.env ?? process.env;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const io = makeIo(deps);
+  const { out, err } = io;
+
+  noteIfCaptureDisabled(env, io);
+
+  const path = join(anyslateDir(env), 'cli.json');
+  const existing = readConfigFile(env);
 
   // --- 1. Token format ----------------------------------------------------
   if (!isValidTokenFormat(flags.token)) {
@@ -75,24 +129,12 @@ export async function runLogin(argv, deps = {}) {
   }
 
   // --- 2. URL shape (MUST precede any token verdict) ----------------------
-  // Preserve the merge semantics — `login --token <new>` alone keeps the
-  // stored apiUrl — but re-normalize the merged value so a previously-bad
-  // apiUrl cannot survive a re-login.
-  const mergedUrl = flags.apiUrl ?? existing.apiUrl ?? existing.api_url ?? DEFAULT_API_URL;
-  const shape = checkUrlShape(mergedUrl);
+  const { shape, root } = resolveRoot(flags, existing, io);
   if (!shape.ok) {
     err.write(`${shape.message}\n`);
     if (!flags.force) return 1;
     err.write('anyslate: --force given — writing anyway.\n');
   }
-  const root = shape.ok ? shape.root : normalizeApiRoot(mergedUrl);
-
-  if (shape.ok && shape.normalized) {
-    out.write(
-      `anyslate: apiUrl "${shape.original}" ends in /mcp — the CLI wants the service ROOT and appends /mcp itself.\n` +
-        `anyslate: using "${root}". Run \`anyslate login --api-url ${root}\` to persist.\n`,
-    );
-  }
 
   // --- 3. Live probe ------------------------------------------------------
   let verified = null;
@@ -127,8 +169,7 @@ export async function runLogin(argv, deps = {}) {
   delete next.api_url; // collapse the legacy alias so only one key can drift
 
   try {
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    writeFileSync(path, JSON.stringify(next, null, 2), { mode: 0o600 });
+    writeConfigFile(next, env);
   } catch (e) {
     err.write(`anyslate login: write failed (${e?.message ?? e})\n`);
     return 1;
@@ -144,9 +185,205 @@ export async function runLogin(argv, deps = {}) {
   return 0;
 }
 
+// ---------------------------------------------------------------------------
+// OAuth browser path
+// ---------------------------------------------------------------------------
+
+async function runOauthLogin(flags, deps) {
+  const env = deps.env ?? process.env;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const io = makeIo(deps);
+  const { out, err } = io;
+
+  if (flags.timeoutInvalid) {
+    err.write('anyslate: --timeout takes a positive number of seconds.\n');
+    return 2;
+  }
+
+  noteIfCaptureDisabled(env, io);
+
+  const existing = readConfigFile(env);
+  const { shape, root } = resolveRoot(flags, existing, io);
+  if (!shape.ok) {
+    err.write(`${shape.message}\n`);
+    return 1;
+  }
+  const host = hostOf(root);
+
+  // --- 1. Discovery. No guessed endpoint paths, ever. ---------------------
+  const discovery = await discover({ root, fetchImpl });
+  if (!discovery.ok) {
+    err.write(`${discovery.message}\n`);
+    return 1;
+  }
+
+  // --- 2. Client id: cached per root, because DCR is 10/hour --------------
+  const clients = existing.oauth_clients && typeof existing.oauth_clients === 'object' ? existing.oauth_clients : {};
+  let clientId = typeof clients[root] === 'string' && clients[root] ? clients[root] : null;
+  let registered = false;
+  if (clientId) {
+    out.write(`anyslate: reusing this CLI's registered OAuth client for ${host}.\n`);
+  } else {
+    const reg = await registerClient({
+      registrationEndpoint: discovery.registrationEndpoint,
+      redirectUri: REGISTERED_REDIRECT_URI,
+      fetchImpl,
+    });
+    if (!reg.ok) {
+      err.write(`${reg.message}\n`);
+      return 1;
+    }
+    clientId = reg.clientId;
+    registered = true;
+    // Persist immediately, BEFORE the browser round trip. A user who closes the
+    // consent tab must not burn a second registration on their next attempt.
+    try {
+      writeConfigFile({ ...readConfigFile(env), oauth_clients: { ...clients, [root]: clientId } }, env);
+    } catch {
+      err.write('anyslate: warning — could not cache the client registration; the next login will register again.\n');
+    }
+  }
+
+  // --- 3. PKCE + state ----------------------------------------------------
+  const pkce = generatePkce();
+  const state = generateState();
+
+  // --- 4. Loopback listener on an ephemeral port --------------------------
+  const timeoutMs = (flags.timeout ?? DEFAULT_CALLBACK_TIMEOUT_S) * 1000;
+  let listener;
+  try {
+    listener = await startCallbackServer({ state, timeoutMs });
+  } catch (e) {
+    err.write(`anyslate: could not bind a loopback port for the OAuth callback (${e?.message ?? e}).\n`);
+    return 1;
+  }
+
+  try {
+    const authorizeUrl = buildAuthorizeUrl({
+      authorizationEndpoint: discovery.authorizationEndpoint,
+      clientId,
+      redirectUri: listener.redirectUri,
+      codeChallenge: pkce.challenge,
+      state,
+      resource: discovery.resource,
+    });
+
+    // --- 5. Browser -------------------------------------------------------
+    out.write(`anyslate: signing in to ${host}${registered ? ' (registered this CLI)' : ''}.\n`);
+    if (flags.noBrowser) {
+      out.write('anyslate: --no-browser given. Open this URL to authorize:\n');
+    } else {
+      const opened = (deps.openBrowserImpl ?? openBrowser)(authorizeUrl);
+      out.write(
+        opened.ok
+          ? 'anyslate: opened your browser. If nothing appeared, open this URL:\n'
+          : `anyslate: could not launch a browser (${opened.error ?? 'unknown error'}). Open this URL:\n`,
+      );
+    }
+    // Printed on BOTH paths. A browser that reported success but silently failed
+    // to appear would otherwise leave the user at a hung prompt with no way in.
+    out.write(`\n  ${authorizeUrl}\n\n`);
+    out.write(`anyslate: waiting up to ${Math.round(timeoutMs / 1000)}s for the callback on ${listener.redirectUri} …\n`);
+
+    await deps.onAuthorizeUrl?.(authorizeUrl, { redirectUri: listener.redirectUri, state, root });
+
+    // --- 6. Callback (state validated inside the listener) ----------------
+    const callback = await listener.waitForResult();
+    if (!callback.ok) {
+      err.write(`${callback.message}\n`);
+      return 1;
+    }
+
+    // --- 7. Token exchange ------------------------------------------------
+    const exchanged = await exchangeCode({
+      tokenEndpoint: discovery.tokenEndpoint,
+      code: callback.code,
+      redirectUri: listener.redirectUri,
+      codeVerifier: pkce.verifier,
+      clientId,
+      resource: discovery.resource,
+      fetchImpl,
+    });
+    if (!exchanged.ok) {
+      err.write(`${exchanged.message}\n`);
+      return 1;
+    }
+
+    const oauth = {
+      client_id: clientId,
+      access_token: exchanged.tokens.access_token,
+      refresh_token: exchanged.tokens.refresh_token,
+      expires_at: exchanged.tokens.expires_at,
+      // Cached so an unattended refresh costs one request rather than three.
+      // Bound to `root` so switching environments re-discovers instead of
+      // reusing dev's token endpoint against prod.
+      token_endpoint: discovery.tokenEndpoint,
+      resource: discovery.resource,
+      root,
+    };
+
+    // --- 8. Verify, exactly as the static path does -----------------------
+    let verified = null;
+    if (flags.noVerify) {
+      err.write('anyslate: --no-verify given — skipping the live connection check.\n');
+    } else {
+      verified = await probeVerify({ root, token: oauth.access_token, fetchImpl });
+      if (verified.ok) {
+        out.write(`${verified.message}\n`);
+        const warning = scopeWarning(verified.scopes);
+        if (warning) err.write(`${warning}\n`);
+      } else {
+        err.write(`${verified.message}\n`);
+        if (!flags.force) {
+          err.write('anyslate: nothing was written. Re-run `anyslate login`, or pass --force to write anyway.\n');
+          return 1;
+        }
+        err.write('anyslate: --force given — writing anyway.\n');
+      }
+    }
+
+    // --- 9. Persist -------------------------------------------------------
+    const path = join(anyslateDir(env), 'cli.json');
+    let handle = null;
+    try {
+      const current = readConfigFile(env);
+      handle = flags.handle ?? current.handle ?? null;
+      const next = {
+        ...current,
+        apiUrl: root,
+        handle,
+        oauth_clients: { ...(current.oauth_clients ?? {}), [root]: clientId },
+        oauth,
+      };
+      delete next.api_url;
+      writeConfigFile(next, env);
+    } catch (e) {
+      err.write(`anyslate login: write failed (${e?.message ?? e})\n`);
+      return 1;
+    }
+
+    out.write(`anyslate: wrote ${path}\n`);
+    out.write(`  apiUrl: ${root}\n`);
+    out.write('  auth:   oauth (browser)\n');
+    out.write(`  handle: ${handle ?? '(none — bearer token only)'}\n`);
+    out.write(
+      `  access token expires ${oauth.expires_at}${
+        oauth.refresh_token ? '; it refreshes automatically' : ' (no refresh token issued)'
+      }\n`,
+    );
+    if (verified?.ok && verified.defaultHandleId) {
+      out.write(`  token is bound to handle: ${verified.defaultHandleId} (server-side scope)\n`);
+    }
+    out.write('anyslate: run `anyslate doctor` to verify the full setup.\n');
+    return 0;
+  } finally {
+    await listener.close();
+  }
+}
+
 /** @param {string[]} argv */
 function parseFlags(argv) {
-  const out = { force: false, noVerify: false };
+  const out = { force: false, noVerify: false, noBrowser: false, help: false };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--token' && argv[i + 1]) out.token = argv[++i];
@@ -154,6 +391,14 @@ function parseFlags(argv) {
     else if ((a === '--api-url' || a === '--api_url') && argv[i + 1]) out.apiUrl = argv[++i];
     else if (a === '--force') out.force = true;
     else if (a === '--no-verify' || a === '--skip-verify') out.noVerify = true;
+    else if (a === '--no-browser') out.noBrowser = true;
+    else if (a === '--timeout' && argv[i + 1]) {
+      const seconds = Number(argv[++i]);
+      if (Number.isFinite(seconds) && seconds > 0) out.timeout = seconds;
+      else out.timeoutInvalid = true;
+    } else if (a === '--help' || a === '-h') out.help = true;
   }
   return out;
 }
+
+export const __testing = { parseFlags };