overlord-cli 0.2606081020.0 → 0.2606081442.0

package/README.md

@@ -38,15 +38,36 @@ overlord help
 ### Auth
 
 ```bash
+# No account yet? Create one entirely from the terminal with just an email.
+ovld auth signup --email agent@example.com --name "Build Agent" # emails an 8-digit code, then mints a durable oat_ agent token by default
+ovld onboard --email agent@example.com --project-name Repo       # same signup, plus org/project/cwd setup
+
 # Repair shared credentials first when a session already exists
 ovld auth repair # mirror and chmod shared Desktop/CLI credentials when possible
 
 # Login to Overlord if repair does not restore access
 ovld auth login #opens a browser when possible and also prints a verification URL/code so login can be completed from another machine over SSH.
+ovld auth login --email agent@example.com # log back in after logout with an emailed code (no browser)
 ovld auth status # show current login status (use --verbose for redacted diagnostics)
 ovld auth logout # remove stored credentials
 ```
 
+#### Terminal-native account creation
+
+`ovld auth signup` creates an Overlord account without a browser: it emails an
+8-digit confirmation code, you enter it in the terminal, and the CLI stores valid
+credentials. Pass `--password` to set a password-manager-generated password;
+without one, signup is passwordless and you log back in later with
+`ovld auth login --email`. By default a durable `oat_…` agent token is minted and
+saved for headless use — pass `--no-agent-token` to skip it. For agents that read
+email out of band, the split flow is available:
+
+```bash
+ovld auth signup request --email agent@example.com --name "Build Agent" --json
+ovld auth signup verify  --email agent@example.com --code 12345678 --json
+ovld onboard --use-current-auth --project-name Repo --directory "$PWD" --yes
+```
+
 Desktop-installed wrappers default `OVERLORD_URL` to `https://www.ovld.ai` unless you override it explicitly.
 For local dev against the web app on port 3000, export the override before running auth or protocol commands:
 

package/bin/_cli/auth.mjs

@@ -726,7 +726,14 @@ export async function runAuthCommand(subcommand, args = []) {
     console.log(`ovld auth <subcommand>
 
 Subcommands:
+  signup   Create a new Overlord account from the terminal (email + confirmation code)
+             --email <email>          Email to create the account with.
+             --name <name>            Display name.
+             --password <password>    Optional password-manager password.
+             --no-agent-token         Skip minting a durable oat_ token.
+           Run \`ovld auth signup help\` for request/verify split flow.
   login    Authorize the CLI via browser (works locally or over SSH)
+             --email <email>          Log in with an emailed code instead of a browser.
              --token <oat_…>          Persist an agent token from Settings → Agents & MCP.
                                       Skips the browser flow; token never expires.
              --organization-id <id>   Optional. Validated against your membership but
@@ -740,7 +747,29 @@ Subcommands:
     return;
   }
 
+  if (subcommand === 'signup') {
+    const { runAuthSignupCommand } = await import('./signup.mjs');
+    await runAuthSignupCommand(args);
+    return;
+  }
+
   if (subcommand === 'login') {
+    const [maybeSub, ...rest] = args;
+    if (maybeSub === 'request') {
+      const { runEmailLoginRequest } = await import('./signup.mjs');
+      await runEmailLoginRequest(rest);
+      return;
+    }
+    if (maybeSub === 'verify') {
+      const { runEmailLoginVerify } = await import('./signup.mjs');
+      await runEmailLoginVerify(rest);
+      return;
+    }
+    if (args.some(arg => arg === '--email' || arg.startsWith('--email='))) {
+      const { runEmailLogin } = await import('./signup.mjs');
+      await runEmailLogin(args);
+      return;
+    }
     await authLogin(args);
     return;
   }

package/bin/_cli/credentials.mjs

@@ -785,6 +785,57 @@ export async function searchTicketsAcrossOrganizations(auth, body, options = {})
   return { tickets, count: tickets.length };
 }
 
+/**
+ * Resolve a fresh Supabase access token (JWT) from stored credentials, refreshing
+ * via the stored refresh token when the cached access token is stale.
+ *
+ * Unlike {@link resolveAuth}, this never returns an `oat_…` agent token: it is for
+ * callers that must present a real Supabase user JWT (e.g. `/api/auth/cli-onboarding`
+ * and `/api/auth/agent-token`, which validate the session with `auth.getUser`).
+ *
+ * @returns {Promise<{ accessToken: string, platformUrl: string, localSecret: string }>}
+ */
+export async function resolveStoredSupabaseAccessToken() {
+  const selected = selectStoredCredentials();
+  const creds = selected?.credentials ?? migrateLegacyCredentials();
+  const platformUrl =
+    normalizePlatformUrl(process.env.OVERLORD_URL) ??
+    normalizeStoredPlatformUrl(creds?.platform_url) ??
+    getDefaultOverlordUrl();
+  const runtime = isLocalhostUrl(platformUrl) ? loadRuntime(platformUrl) : null;
+  const localSecret =
+    runtime?.local_secret && runtime.platform_url === platformUrl ? runtime.local_secret : '';
+
+  if (!creds) {
+    throw new Error('No stored Overlord credentials. Run `ovld auth signup` or `ovld auth login` first.');
+  }
+
+  if (creds.access_token && isAccessTokenFresh(creds)) {
+    return { accessToken: creds.access_token, platformUrl, localSecret };
+  }
+
+  if (creds.refresh_token) {
+    const refreshed = await refreshOAuthAccessToken(platformUrl, creds.refresh_token, localSecret);
+    if (!refreshed.access_token) {
+      throw new Error('Failed to refresh the stored Supabase session. Run `ovld auth login --email` again.');
+    }
+    saveCredentialsToSource(
+      {
+        ...creds,
+        access_token: refreshed.access_token,
+        access_token_expires_at: refreshed.access_token_expires_at,
+        refresh_token: refreshed.refresh_token || creds.refresh_token
+      },
+      selected?.source
+    );
+    return { accessToken: refreshed.access_token, platformUrl, localSecret };
+  }
+
+  throw new Error(
+    'Stored credentials have no Supabase session. Run `ovld auth login --email` to obtain one.'
+  );
+}
+
 export async function getAuthStatus() {
   const creds = loadCredentials();
   let resolved;

package/bin/_cli/index.mjs

@@ -59,7 +59,8 @@ Agents:
   Key protocol commands: auth-status, discover-project, create, prompt, attach, connect, load-context, heartbeat.
 
 Auth:
-  ${primaryCommand} auth login               Authorize CLI via browser or --token <oat_…>
+  ${primaryCommand} auth signup              Create an account from the terminal (--email <email>)
+  ${primaryCommand} auth login               Authorize CLI via browser, --email <email>, or --token <oat_…>
   ${primaryCommand} auth status              Show login status
   ${primaryCommand} auth repair              Repair shared Desktop/CLI credentials
   ${primaryCommand} auth logout              Remove stored credentials

package/bin/_cli/onboard.mjs

@@ -11,6 +11,7 @@ import {
   buildAuthHeaders,
   loadCredentials,
   loadRuntime,
+  resolveStoredSupabaseAccessToken,
   saveCredentials
 } from './credentials.mjs';
 import { upsertLocalOverlordConfig } from './local-config.mjs';
@@ -150,18 +151,87 @@ function buildWebProjectUrl(platformUrl, result) {
   return `${platformUrl}/projects/${projectId}`;
 }
 
+/**
+ * Resolve the credentials onboarding will use, based on the chosen auth mode:
+ *  - `--use-current-auth`: reuse the already signed-in Supabase session.
+ *  - `--email`: create the account entirely in the terminal (email + code).
+ *  - default: browser device-authorization flow.
+ *
+ * Returns the Supabase access token to call `cli-onboarding` with, the resolved
+ * platform URL and local secret, and (only for the browser flow) the freshly
+ * issued session that still needs persisting.
+ */
+async function resolveOnboardingAuth({ flags, name, inviteToken }) {
+  const useCurrentAuth = flags['use-current-auth'] === true || flags['use-current-auth'] === 'true';
+  const email = trimFlag(flags, 'email');
+
+  if (useCurrentAuth) {
+    const { accessToken, platformUrl, localSecret } = await resolveStoredSupabaseAccessToken();
+    return { accessToken, platformUrl, localSecret, sessionToPersist: null };
+  }
+
+  if (email) {
+    const { runCliSignupFlow } = await import('./signup.mjs');
+    const { session, platformUrl, localSecret } = await runCliSignupFlow({
+      email,
+      name,
+      password: trimFlag(flags, 'password') || undefined,
+      invite: inviteToken || undefined,
+      'no-agent-token': flags['no-agent-token'] === true
+    });
+    return {
+      accessToken: session.access_token,
+      platformUrl: session.platform_url ?? platformUrl,
+      localSecret,
+      sessionToPersist: null
+    };
+  }
+
+  const storedCredentials = loadCredentials();
+  const platformUrl = resolveLoginPlatformUrl(null, storedCredentials?.platform_url ?? null);
+  const runtime = loadRuntime(platformUrl);
+  const localSecret = runtime?.local_secret ?? process.env.OVERLORD_LOCAL_SECRET ?? '';
+
+  console.log('\nStarting Overlord onboarding in your browser.');
+  console.log('Create an account or sign in, then approve the CLI authorization request.\n');
+
+  const credentials = await authLoginViaDeviceFlow(platformUrl, localSecret, {
+    browserOpener: verificationUri => {
+      const signupUrl = buildSignupUrl(platformUrl, verificationUri, name, inviteToken);
+      console.log(`  Signup URL: ${signupUrl}`);
+      openBrowser(signupUrl);
+    }
+  });
+
+  return {
+    accessToken: credentials.access_token,
+    platformUrl: credentials.platform_url ?? platformUrl,
+    localSecret,
+    sessionToPersist: credentials
+  };
+}
+
 export async function runOnboardCommand(args) {
   const flags = parseFlags(args);
 
   if (flags.help === true || flags.h === true || args[0] === 'help') {
-    console.log(`Usage: ovld onboard [--name <name>] [--organization-name <name>] [--project-name <name>] [--directory <path>] [--invite <token|url>] [--yes] [--no-desktop]
+    console.log(`Usage: ovld onboard [--name <name>] [--organization-name <name>] [--project-name <name>] [--directory <path>] [--invite <token|url>] [--email <email>] [--password <password>] [--use-current-auth] [--yes] [--no-desktop]
 
 Creates an Overlord account setup from the terminal:
   1. collects your name, organization, project, and repository directory
-  2. opens browser signup/login and authorizes the CLI
+  2. authorizes the CLI (browser by default; terminal-only with --email)
   3. creates the organization/project, links this directory, and creates the first onboarding ticket
   4. opens the Desktop download page, or the web project when --no-desktop is used
 
+Authorization modes:
+  (default)            Browser signup/login + device authorization.
+  --email <email>      Create the account entirely in the terminal: an 8-digit
+                       confirmation code is emailed and entered here. Add
+                       --password <password> to set a password-manager password;
+                       otherwise future login uses \`ovld auth login --email\`.
+  --use-current-auth   Skip auth and provision using the already signed-in session
+                       (e.g. right after \`ovld auth signup\`).
+
 With --invite <token>, joins the inviting organization (from an invite email)
 with the invited role instead of creating a new organization; the organization
 prompt is skipped. Accepts a bare token or a full /invite/<token> URL.
@@ -190,42 +260,43 @@ Run this from the repository you want Overlord agents to work in.`);
     throw new Error('Organization name is required (or pass --invite <token> to join an org).');
   }
 
-  const storedCredentials = loadCredentials();
-  const platformUrl = resolveLoginPlatformUrl(null, storedCredentials?.platform_url ?? null);
-  const runtime = loadRuntime(platformUrl);
-  const localSecret = runtime?.local_secret ?? process.env.OVERLORD_LOCAL_SECRET ?? '';
-
-  console.log('\nStarting Overlord onboarding in your browser.');
-  console.log('Create an account or sign in, then approve the CLI authorization request.\n');
-
-  const credentials = await authLoginViaDeviceFlow(platformUrl, localSecret, {
-    browserOpener: verificationUri => {
-      const signupUrl = buildSignupUrl(platformUrl, verificationUri, name, inviteToken);
-      console.log(`  Signup URL: ${signupUrl}`);
-      openBrowser(signupUrl);
-    }
-  });
+  const {
+    accessToken,
+    platformUrl: resolvedPlatformUrl,
+    localSecret,
+    sessionToPersist
+  } = await resolveOnboardingAuth({ flags, name, inviteToken });
 
-  const resolvedPlatformUrl = credentials.platform_url ?? platformUrl;
   const deviceFingerprint = readOrCreateDeviceFingerprint(flags);
-  const result = await completeCliOnboarding(resolvedPlatformUrl, localSecret, credentials, {
-    name,
-    ...(organizationName ? { organizationName } : {}),
-    projectName,
-    directoryPath,
-    deviceFingerprint,
-    deviceHostname: os.hostname(),
-    devicePlatform: process.platform,
-    ...(inviteToken ? { inviteToken } : {})
-  });
-
-  saveCredentials({
-    access_token: credentials.access_token,
-    access_token_expires_at: credentials.access_token_expires_at ?? undefined,
-    refresh_token: credentials.refresh_token,
-    organization_id: result.organization.organizationId,
-    platform_url: resolvedPlatformUrl
-  });
+  const result = await completeCliOnboarding(
+    resolvedPlatformUrl,
+    localSecret,
+    { access_token: accessToken },
+    {
+      name,
+      ...(organizationName ? { organizationName } : {}),
+      projectName,
+      directoryPath,
+      deviceFingerprint,
+      deviceHostname: os.hostname(),
+      devicePlatform: process.platform,
+      ...(inviteToken ? { inviteToken } : {})
+    }
+  );
+
+  // The browser device-auth flow returns a session that hasn't been stored yet;
+  // persist it (with the resolved org). The --email and --use-current-auth paths
+  // already saved credentials (including any minted agent token), so we leave the
+  // stored credential — and its durable agent token — untouched.
+  if (sessionToPersist) {
+    saveCredentials({
+      access_token: sessionToPersist.access_token,
+      access_token_expires_at: sessionToPersist.access_token_expires_at ?? undefined,
+      refresh_token: sessionToPersist.refresh_token,
+      organization_id: result.organization.organizationId,
+      platform_url: resolvedPlatformUrl
+    });
+  }
 
   try {
     const localConfig = await upsertLocalOverlordConfig({

package/bin/_cli/protocol.mjs

@@ -3203,6 +3203,30 @@ Use this for ticket lifecycle work from an agent runtime: create a standalone
 draft with \`ovld protocol create\`, create-and-attach with \`ovld protocol prompt\`,
 or attach to an existing ticket with \`ovld protocol attach --ticket-id <ticket_id>\`.
 
+Account creation & onboarding:
+  No Overlord account or credentials yet? If you have an email address you can
+  create an account and set up a workspace entirely from the terminal — no
+  browser needed. Run these (outside \`ovld protocol\`) before attaching:
+
+    ovld auth signup --email <email> --name <name>
+                                   Create an account from the terminal: an 8-digit
+                                   code is emailed and entered here. Mints and
+                                   stores a durable oat_ agent token by default.
+    ovld onboard --email <email>   Same terminal-first signup, then also create an
+                                   organization + project and link this directory.
+    ovld onboard                   Browser-based account + workspace setup.
+    ovld onboard --invite <token>  Join an organization you were invited to
+                                   instead of creating a new one.
+    ovld auth login --email <email>
+                                   Log back in after logout with an emailed code.
+    ovld auth login                Authorize an existing account (browser flow,
+                                   or --token <oat_…> to persist a durable,
+                                   never-expiring agent token for headless use).
+    ovld auth status               Show current login status and organizations.
+
+  To check credentials machine-readably from a script, use
+  \`ovld protocol auth-status\` (returns ok=true|false).
+
 Project discovery:
   When prompting or creating tickets, the CLI automatically resolves the correct
   project by matching your current working directory against your configured

package/bin/_cli/runner.mjs

@@ -1,13 +1,11 @@
 #!/usr/bin/env node
 
 import { execFileSync, spawn } from 'node:child_process';
-import crypto from 'node:crypto';
-import fs from 'node:fs';
 import os from 'node:os';
-import path from 'node:path';
+
+import { readOrCreateCanonicalDeviceFingerprintSync } from '../../../../lib/overlord/device-identity.mjs';
 
 const OVLD_ENTRY = process.argv[1];
-const DEVICE_FILE = path.join(os.homedir(), '.ovld', 'device.json');
 const DEFAULT_TMUX_COMMAND = 'tmux new-session bash {script}';
 
 /** @internal Test-only overrides for protocol/launch subprocess calls. */
@@ -65,22 +63,7 @@ export function readOrCreateDeviceFingerprint(flags) {
     typeof flags['device-fingerprint'] === 'string'
       ? flags['device-fingerprint'].trim()
       : process.env.OVERLORD_DEVICE_FINGERPRINT?.trim();
-  if (explicit) return explicit;
-
-  try {
-    const raw = fs.readFileSync(DEVICE_FILE, 'utf8');
-    const parsed = JSON.parse(raw);
-    if (typeof parsed.deviceFingerprint === 'string' && parsed.deviceFingerprint.trim()) {
-      return parsed.deviceFingerprint.trim();
-    }
-  } catch {
-    // Create below.
-  }
-
-  const deviceFingerprint = crypto.randomUUID();
-  fs.mkdirSync(path.dirname(DEVICE_FILE), { recursive: true });
-  fs.writeFileSync(DEVICE_FILE, `${JSON.stringify({ deviceFingerprint }, null, 2)}\n`, 'utf8');
-  return deviceFingerprint;
+  return readOrCreateCanonicalDeviceFingerprintSync({ explicitFingerprint: explicit });
 }
 
 function runOvld(args, env = {}) {

package/bin/_cli/signup.mjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+/* global console, fetch, process, URL */
+
+import os from 'node:os';
+import readline from 'node:readline';
+import { stdin as input, stdout as output } from 'node:process';
+
+import { resolveLoginPlatformUrl } from './auth.mjs';
+import { buildAuthHeaders, loadCredentials, loadRuntime, saveCredentials } from './credentials.mjs';
+
+// ---------------------------------------------------------------------------
+// Small parsing / prompting helpers
+// ---------------------------------------------------------------------------
+
+export function parseSignupFlags(args = []) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) continue;
+    const eq = arg.indexOf('=');
+    if (eq !== -1) {
+      flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      continue;
+    }
+    const key = arg.slice(2);
+    if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+      flags[key] = args[i + 1];
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+  return flags;
+}
+
+function flagString(flags, name) {
+  const value = flags[name];
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+async function promptForValue(question, defaultValue = '') {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return defaultValue;
+  const rl = readline.createInterface({ input, output });
+  try {
+    return await new Promise(resolve => {
+      const suffix = defaultValue ? ` (${defaultValue})` : '';
+      rl.question(`${question}${suffix}: `, answer => resolve(answer.trim() || defaultValue));
+    });
+  } finally {
+    rl.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Network helpers
+// ---------------------------------------------------------------------------
+
+function resolveSignupContext() {
+  const storedCredentials = loadCredentials();
+  const platformUrl = resolveLoginPlatformUrl(null, storedCredentials?.platform_url ?? null);
+  const runtime = loadRuntime(platformUrl);
+  const localSecret = runtime?.local_secret ?? process.env.OVERLORD_LOCAL_SECRET ?? '';
+  return { platformUrl, localSecret };
+}
+
+async function postJson(platformUrl, pathName, localSecret, body, accessToken = '') {
+  let res;
+  try {
+    res = await fetch(`${platformUrl}${pathName}`, {
+      method: 'POST',
+      headers: {
+        ...buildAuthHeaders(accessToken, localSecret),
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    const cause = error?.cause;
+    const detail = [cause?.code, cause?.message].filter(Boolean).join(': ');
+    throw new Error(`Request to ${pathName} failed: ${detail || (error?.message ?? error)}`);
+  }
+
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const message = data.error ?? `${pathName} failed (${res.status})`;
+    const err = new Error(message);
+    err.status = res.status;
+    err.code = data.code;
+    throw err;
+  }
+  return data;
+}
+
+export function requestCliSignup(platformUrl, localSecret, { email, name, password, inviteToken }) {
+  return postJson(platformUrl, '/api/auth/cli-signup/request', localSecret, {
+    email,
+    name,
+    ...(password ? { password } : {}),
+    ...(inviteToken ? { inviteToken } : {})
+  });
+}
+
+export function verifyCliSignup(platformUrl, localSecret, { email, token, password }) {
+  return postJson(platformUrl, '/api/auth/cli-signup/verify', localSecret, {
+    email,
+    token,
+    ...(password ? { password } : {})
+  });
+}
+
+export function requestCliLogin(platformUrl, localSecret, { email }) {
+  return postJson(platformUrl, '/api/auth/cli-login/request', localSecret, { email });
+}
+
+export function verifyCliLogin(platformUrl, localSecret, { email, token }) {
+  return postJson(platformUrl, '/api/auth/cli-login/verify', localSecret, { email, token });
+}
+
+export function mintAgentToken(platformUrl, localSecret, accessToken, label) {
+  return postJson(platformUrl, '/api/auth/agent-token', localSecret, { label }, accessToken);
+}
+
+// ---------------------------------------------------------------------------
+// Credential persistence after a verified session
+// ---------------------------------------------------------------------------
+
+function defaultAgentTokenLabel() {
+  const host = os.hostname() || 'cli';
+  return `CLI: ${host}`.slice(0, 80);
+}
+
+/**
+ * Persist a verified Supabase session and, unless suppressed, mint and store a
+ * durable `oat_…` agent token as the preferred future credential.
+ *
+ * @returns {Promise<{ agentToken: string | null }>}
+ */
+export async function persistVerifiedSession(
+  platformUrl,
+  localSecret,
+  session,
+  { mintToken = true, label = defaultAgentTokenLabel(), logger = console } = {}
+) {
+  const resolvedPlatformUrl = session.platform_url ?? platformUrl;
+  let agentToken = null;
+
+  if (mintToken) {
+    try {
+      const minted = await mintAgentToken(
+        resolvedPlatformUrl,
+        localSecret,
+        session.access_token,
+        label
+      );
+      agentToken = typeof minted.token === 'string' ? minted.token : null;
+    } catch (error) {
+      logger.log(
+        `\nWarning: could not mint a durable agent token (${error instanceof Error ? error.message : error}).`
+      );
+      logger.log('Saved the Supabase session instead; re-run `ovld auth login --email` to retry.');
+    }
+  }
+
+  saveCredentials({
+    ...(agentToken ? { agent_token: agentToken } : {}),
+    access_token: session.access_token,
+    access_token_expires_at: session.access_token_expires_at ?? undefined,
+    refresh_token: session.refresh_token,
+    platform_url: resolvedPlatformUrl,
+    ...(session.email ? { user_email: session.email } : {})
+  });
+
+  return { agentToken };
+}
+
+// ---------------------------------------------------------------------------
+// Full interactive signup flow (shared with `ovld onboard --email`)
+// ---------------------------------------------------------------------------
+
+/**
+ * Run CLI account creation end to end: request a confirmation email, collect the
+ * code, verify it, then persist the session (and an agent token by default).
+ * Returns the verified session so callers (e.g. onboarding) can keep using the
+ * Supabase access token for follow-up provisioning.
+ */
+export async function runCliSignupFlow(
+  flags,
+  { logger = console, mintToken = !(flags['no-agent-token'] === true) } = {}
+) {
+  const email = flagString(flags, 'email') || (await promptForValue('Email'));
+  if (!email) throw new Error('An email address is required (--email).');
+
+  const inferredName = os.userInfo().username || 'Agent';
+  const name = flagString(flags, 'name') || (await promptForValue('Your name', inferredName));
+  if (!name) throw new Error('A name is required (--name).');
+
+  const password = flagString(flags, 'password') || undefined;
+  const inviteToken = flagString(flags, 'invite') || flagString(flags, 'invite-code') || undefined;
+
+  const { platformUrl, localSecret } = resolveSignupContext();
+
+  logger.log(`\nCreating your Overlord account for ${email}...`);
+  const requested = await requestCliSignup(platformUrl, localSecret, {
+    email,
+    name,
+    password,
+    inviteToken
+  });
+
+  logger.log(`We sent an 8-digit confirmation code to ${email}.`);
+  const code = flagString(flags, 'code') || (await promptForValue('Enter confirmation code'));
+  if (!code) throw new Error('A confirmation code is required to finish signup.');
+
+  const session = await verifyCliSignup(platformUrl, localSecret, { email, token: code, password });
+
+  const { agentToken } = await persistVerifiedSession(platformUrl, localSecret, session, {
+    mintToken,
+    logger
+  });
+
+  return { session, agentToken, platformUrl, localSecret, passwordless: requested.passwordless };
+}
+
+// ---------------------------------------------------------------------------
+// Command handlers
+// ---------------------------------------------------------------------------
+
+function printSignupHelp() {
+  console.log(`ovld auth signup — create an Overlord account from the terminal
+
+Usage:
+  ovld auth signup --email <email> [--name <name>] [--password <password>]
+  ovld auth signup request --email <email> --name <name> [--password <password>] [--json]
+  ovld auth signup verify --email <email> --code <code> [--password <password>] [--json]
+
+Flags:
+  --email <email>       Email to create the account with (prompted if omitted).
+  --name <name>         Display name (prompted if omitted).
+  --password <password> Optional. Recommended: a password-manager-generated password.
+                        Without one, signup uses an email code and future login is
+                        via \`ovld auth login --email\`.
+  --no-agent-token      Do not mint/store a durable oat_ agent token after signup.
+  --code <code>         Provide the emailed code non-interactively (single-shot flow).
+  --json                Machine-readable output (request/verify subcommands).
+
+Creates the account only. To also create an organization, project, and link this
+directory, use \`ovld onboard --email <email>\`.`);
+}
+
+async function runSignupRequest(flags) {
+  const email = flagString(flags, 'email');
+  const name = flagString(flags, 'name');
+  if (!email || !name) {
+    throw new Error('`ovld auth signup request` requires --email and --name.');
+  }
+  const password = flagString(flags, 'password') || undefined;
+  const inviteToken = flagString(flags, 'invite') || flagString(flags, 'invite-code') || undefined;
+  const { platformUrl, localSecret } = resolveSignupContext();
+  const result = await requestCliSignup(platformUrl, localSecret, {
+    email,
+    name,
+    password,
+    inviteToken
+  });
+
+  if (flags.json === true) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  console.log(`Confirmation code sent to ${email}.`);
+  console.log('Finish with: ovld auth signup verify --email ' + email + ' --code <code>');
+}
+
+async function runSignupVerify(flags) {
+  const email = flagString(flags, 'email');
+  const token = flagString(flags, 'code') || flagString(flags, 'token');
+  if (!email || !token) {
+    throw new Error('`ovld auth signup verify` requires --email and --code.');
+  }
+  const password = flagString(flags, 'password') || undefined;
+  const { platformUrl, localSecret } = resolveSignupContext();
+  const session = await verifyCliSignup(platformUrl, localSecret, { email, token, password });
+  const mintToken = !(flags['no-agent-token'] === true);
+  const { agentToken } = await persistVerifiedSession(platformUrl, localSecret, session, {
+    mintToken
+  });
+
+  if (flags.json === true) {
+    console.log(JSON.stringify({ ok: true, email, agentTokenMinted: Boolean(agentToken) }));
+    return;
+  }
+  console.log('Account confirmed and credentials saved.');
+  if (agentToken) console.log('A durable agent token was minted and stored for headless use.');
+}
+
+export async function runAuthSignupCommand(args = []) {
+  const [maybeSub, ...rest] = args;
+
+  if (maybeSub === 'help' || maybeSub === '--help' || maybeSub === '-h') {
+    printSignupHelp();
+    return;
+  }
+
+  if (maybeSub === 'request') {
+    await runSignupRequest(parseSignupFlags(rest));
+    return;
+  }
+  if (maybeSub === 'verify') {
+    await runSignupVerify(parseSignupFlags(rest));
+    return;
+  }
+
+  // Single-shot interactive flow: `ovld auth signup --email ...`
+  const flags = parseSignupFlags(args);
+  const { agentToken, passwordless } = await runCliSignupFlow(flags);
+
+  console.log('\nOverlord account created.');
+  if (agentToken) {
+    console.log('A durable agent token was minted and stored for headless use.');
+  }
+  if (passwordless) {
+    console.log('No password was set — log back in later with `ovld auth login --email`.');
+  }
+  console.log('\nNext: run `ovld onboard --use-current-auth` to create a project in this directory.');
+}
+
+/**
+ * `ovld auth login --email <email>`: send a fresh email OTP for an existing
+ * account, verify it, and persist credentials (minting an agent token by default).
+ */
+export async function runEmailLogin(args = []) {
+  const flags = parseSignupFlags(args);
+  const email = flagString(flags, 'email') || (await promptForValue('Email'));
+  if (!email) throw new Error('An email address is required (--email).');
+
+  const { platformUrl, localSecret } = resolveSignupContext();
+
+  // Split sub-flow support: `login request` / `login verify` are handled by the
+  // caller; this entry point runs the interactive request+verify together.
+  console.log(`\nSending a login code to ${email}...`);
+  await requestCliLogin(platformUrl, localSecret, { email });
+
+  const code =
+    flagString(flags, 'code') ||
+    flagString(flags, 'token') ||
+    (await promptForValue('Enter login code'));
+  if (!code) throw new Error('A login code is required.');
+
+  const session = await verifyCliLogin(platformUrl, localSecret, { email, token: code });
+  const mintToken = !(flags['no-agent-token'] === true);
+  const { agentToken } = await persistVerifiedSession(platformUrl, localSecret, session, {
+    mintToken
+  });
+
+  console.log('Logged in successfully.');
+  if (agentToken) console.log('A durable agent token was minted and stored for headless use.');
+}
+
+/** Split login helpers for agents that pause between request and verify. */
+export async function runEmailLoginRequest(args = []) {
+  const flags = parseSignupFlags(args);
+  const email = flagString(flags, 'email');
+  if (!email) throw new Error('`ovld auth login request` requires --email.');
+  const { platformUrl, localSecret } = resolveSignupContext();
+  const result = await requestCliLogin(platformUrl, localSecret, { email });
+  if (flags.json === true) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  console.log(`Login code sent to ${email}.`);
+}
+
+export async function runEmailLoginVerify(args = []) {
+  const flags = parseSignupFlags(args);
+  const email = flagString(flags, 'email');
+  const token = flagString(flags, 'code') || flagString(flags, 'token');
+  if (!email || !token) {
+    throw new Error('`ovld auth login verify` requires --email and --code.');
+  }
+  const { platformUrl, localSecret } = resolveSignupContext();
+  const session = await verifyCliLogin(platformUrl, localSecret, { email, token });
+  const mintToken = !(flags['no-agent-token'] === true);
+  const { agentToken } = await persistVerifiedSession(platformUrl, localSecret, session, {
+    mintToken
+  });
+  if (flags.json === true) {
+    console.log(JSON.stringify({ ok: true, email, agentTokenMinted: Boolean(agentToken) }));
+    return;
+  }
+  console.log('Logged in successfully.');
+  if (agentToken) console.log('A durable agent token was minted and stored for headless use.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2606081020.0",
+  "version": "0.2606081442.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "homepage": "https://www.ovld.ai/docs/",
   "type": "module",