@runtypelabs/cli 2.30.1 → 2.31.0

package/dist/index.js

@@ -72,12 +72,35 @@ var init_credential_store = __esm({
           }
         }
       }
+      /**
+       * Replace the entire backing store in one file write. Conf's runtime has a
+       * `store` setter (used for exactly this whole-store replacement), but its
+       * published typings declare the property read-only, so the assignment needs
+       * a cast. Single-write replacement is load-bearing for claim completion:
+       * the server has already revoked the previous key, so a multi-write
+       * sequence could lose the only copy of the fresh credential.
+       */
+      replaceStore(data) {
+        ;
+        this.config.store = data;
+      }
       getMachineKey() {
         const hostname4 = os.hostname();
         const username = os.userInfo().username;
         return crypto3.createHash("sha256").update(`runtype-cli-${hostname4}-${username}`).digest("hex").substring(0, 32);
       }
-      async saveCredentials(credentials) {
+      /**
+       * Store credentials, optionally together with agent-auth claim state in the
+       * same write. Passing `claimState` here (rather than a follow-up
+       * `saveClaimState` call) keeps the temporary credential and its claim token
+       * atomic — a crash between two writes would otherwise orphan a pre-claim
+       * key that `auth status` then misreports as a full account.
+       *
+       * Storing credentials WITHOUT `claimState` invalidates any in-flight claim
+       * ceremony: every login path (api-key, browser, claim completion) must not
+       * leave stale claim state behind.
+       */
+      async saveCredentials(credentials, claimState) {
         const configData = {
           apiKey: this.encrypt(credentials.apiKey),
           userId: credentials.userId,
@@ -90,7 +113,21 @@ var init_credential_store = __esm({
         if (credentials.apiUrl !== void 0) {
           configData.apiUrl = credentials.apiUrl;
         }
-        this.config.set(configData);
+        if (claimState) {
+          Object.assign(configData, this.claimStateToConfig(claimState));
+        }
+        this.replaceStore(configData);
+      }
+      claimStateToConfig(state) {
+        const data = {
+          claimToken: this.encrypt(state.claimToken),
+          registrationId: state.registrationId
+        };
+        if (state.claimEmail !== void 0) data.claimEmail = state.claimEmail;
+        if (state.credentialExpires !== void 0) data.credentialExpires = state.credentialExpires;
+        if (state.claimTokenExpires !== void 0) data.claimTokenExpires = state.claimTokenExpires;
+        if (state.apiUrl !== void 0) data.claimApiUrl = state.apiUrl;
+        return data;
       }
       async getApiKey() {
         const encrypted = this.config.get("apiKey");
@@ -109,6 +146,39 @@ var init_credential_store = __esm({
       async clearCredentials() {
         this.config.clear();
       }
+      /**
+       * Persist agent-auth claim ceremony state alongside the pre-claim credential
+       * so `runtype auth claim` / `runtype auth verify` can run as separate
+       * invocations (the agent asks the user for their email and OTP in between).
+       * The claim token is encrypted like the API key — it can mint the
+       * post-claim credential, so it is a secret.
+       */
+      async saveClaimState(state) {
+        this.config.set(this.claimStateToConfig(state));
+      }
+      async getClaimState() {
+        const claimToken = this.config.get("claimToken");
+        const registrationId = this.config.get("registrationId");
+        if (!claimToken || !registrationId) return null;
+        return {
+          claimToken: this.decrypt(claimToken),
+          registrationId,
+          claimEmail: this.config.get("claimEmail"),
+          credentialExpires: this.config.get("credentialExpires"),
+          claimTokenExpires: this.config.get("claimTokenExpires"),
+          apiUrl: this.config.get("claimApiUrl")
+        };
+      }
+      async clearClaimState() {
+        const store = { ...this.config.store };
+        delete store.claimToken;
+        delete store.registrationId;
+        delete store.claimEmail;
+        delete store.credentialExpires;
+        delete store.claimTokenExpires;
+        delete store.claimApiUrl;
+        this.replaceStore(store);
+      }
       async hasCredentials() {
         return !!this.config.get("apiKey");
       }
@@ -159,7 +229,7 @@ function loadEnv(path20 = resolve(process.cwd(), ".env")) {
 
 // src/commands/auth.ts
 import { Command } from "commander";
-import chalk from "chalk";
+import chalk2 from "chalk";
 import React from "react";
 import { render } from "ink";
 import { useState as useState2, useEffect as useEffect3 } from "react";
@@ -38886,6 +38956,13 @@ var userProfileFeaturesSchema = external_exports.object({
   // until a rule enables it). Execution and tool listings are gated
   // server-side by the same flag.
   enableMassiveWebRender: external_exports.boolean(),
+  // Gates the agent voice configuration UI in the dashboard (the Voice tab in
+  // the agent editor). Driven by the `enable-voice` boolean flag (fail-closed
+  // in production until a rule enables it; non-prod defaults on, preserving
+  // the staging-first rollout the flag replaced). The voice API routes stay
+  // ungated: they already require per-agent `config.voice.enabled` opt-in,
+  // which production users can only set once this flag exposes the UI.
+  enableVoice: external_exports.boolean(),
   // Gates the workspace-model arms of the dashboard signup / switcher UI
   // (docs/features/planning/2026-07-07-workspace-model-migration.md). Driven by
   // the `enable-workspace-model` boolean flag (fail-closed in production until a
@@ -45920,7 +45997,18 @@ var ApiKeyManager = class {
     try {
       data = await client.get("/auth/me");
     } catch {
-      throw new Error("Failed to get user information");
+      try {
+        const profile = await client.get(
+          "/users/profile"
+        );
+        if (typeof profile.id === "string") {
+          data = { userId: profile.id, orgId: profile.orgId ?? null, email: profile.email };
+        }
+      } catch {
+      }
+      if (!data) {
+        throw new Error("Failed to get user information");
+      }
     }
     if (!isAuthMeResponse(data)) {
       throw new Error("Invalid user response format");
@@ -46167,23 +46255,418 @@ function MutationResult({
   return null;
 }
 
-// src/commands/auth.ts
-var authCommand = new Command("auth").description("Manage authentication");
-async function getBillingInfo(apiKey, apiUrl) {
+// src/commands/auth-agent.ts
+init_credential_store();
+
+// src/auth/agent-auth-client.ts
+var AgentAuthError = class extends Error {
+  constructor(code, status, message, hint) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.hint = hint;
+    this.name = "AgentAuthError";
+  }
+  code;
+  status;
+  hint;
+};
+var ERROR_HINTS = {
+  email_already_registered: "This email already has a Runtype account, so it cannot claim a new agent account. Ask the user to sign in at the dashboard, create an API key (Settings > API keys), and give it to you. Then run: runtype auth login --api-key <key> --no-tty",
+  invalid_claim_token: "The claim token is invalid or expired. Run: runtype auth register --force",
+  claim_expired: "The claim window expired. Run: runtype auth register --force",
+  credential_expired: "The temporary credential expired. Run: runtype auth register --force",
+  claimed_or_in_flight: "A claim is already in progress. Ask the user for the 6-digit code from their email, then run: runtype auth verify <code>. If the code expired, re-run: runtype auth claim <email>",
+  otp_invalid: "That code is not correct. Ask the user to re-check the 6-digit code from the most recent Runtype email and run: runtype auth verify <code>",
+  otp_expired: "The code expired. Re-send it with: runtype auth claim <email>",
+  previously_claimed: "This registration was already claimed. Run: runtype auth status to inspect stored credentials.",
+  email_send_failed: "The verification email could not be sent. Retry: runtype auth claim <email>",
+  rate_limited: "Too many attempts. Wait a minute, then retry the same command.",
+  service_disabled: "Agent registration is temporarily disabled. Try again later."
+};
+async function postJson(url2, body) {
+  let response;
   try {
-    const client = createCliClient(apiKey, apiUrl);
-    return await client.get("/billing/status");
+    response = await fetch(url2, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "user-agent": "runtype-cli"
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (error51) {
+    const message = error51 instanceof Error ? error51.message : String(error51);
+    throw new AgentAuthError(
+      "network_error",
+      0,
+      `Could not reach ${url2}: ${message}`,
+      "Check network access and the --api-url value, then retry the same command."
+    );
+  }
+  let data = {};
+  try {
+    data = await response.json();
   } catch {
-    return null;
   }
+  if (!response.ok) {
+    const code = typeof data.error === "string" ? data.error : `http_${response.status}`;
+    const message = typeof data.message === "string" ? data.message : `Request failed (${response.status})`;
+    throw new AgentAuthError(code, response.status, message, ERROR_HINTS[code]);
+  }
+  return { status: response.status, data };
 }
-authCommand.command("signup").description('Create a new Runtype account (alias for "auth login")').option("--api-url <url>", "Custom API URL").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
-  if (!isTTY(options)) {
+function requireString(data, key) {
+  const value = data[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new AgentAuthError(
+      "invalid_response",
+      0,
+      `Registration response is missing "${key}". The API may be an incompatible version.`
+    );
+  }
+  return value;
+}
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+async function registerAnonymousAgent(apiUrl) {
+  const base = apiUrl || getApiUrl();
+  const { data } = await postJson(`${base}/agent/auth`, {
+    // @snake-case-ok-start: auth.md protocol field names
+    type: "anonymous",
+    requested_credential_type: "api_key"
+    // @snake-case-ok-end
+  });
+  return {
+    // @snake-case-ok-start: auth.md protocol field names
+    registrationId: requireString(data, "registration_id"),
+    credential: requireString(data, "credential"),
+    credentialExpires: requireString(data, "credential_expires"),
+    scopes: stringArray(data.scopes),
+    claimToken: requireString(data, "claim_token"),
+    claimTokenExpires: requireString(data, "claim_token_expires"),
+    postClaimScopes: stringArray(data.post_claim_scopes)
+    // @snake-case-ok-end
+  };
+}
+async function initiateClaim(claimToken, email3, apiUrl) {
+  const base = apiUrl || getApiUrl();
+  const { data } = await postJson(`${base}/agent/auth/claim`, {
+    // @snake-case-ok-start: auth.md protocol field names
+    claim_token: claimToken,
+    email: email3
+    // @snake-case-ok-end
+  });
+  return {
+    // @snake-case-ok-start: auth.md protocol field names
+    registrationId: requireString(data, "registration_id"),
+    status: typeof data.status === "string" ? data.status : "initiated",
+    otpExpiresAt: requireString(data, "expires_at")
+    // @snake-case-ok-end
+  };
+}
+async function completeClaim(claimToken, otp, apiUrl) {
+  const base = apiUrl || getApiUrl();
+  const { data } = await postJson(`${base}/agent/auth/claim/complete`, {
+    // @snake-case-ok-start: auth.md protocol field names
+    claim_token: claimToken,
+    otp
+    // @snake-case-ok-end
+  });
+  return {
+    // @snake-case-ok-start: auth.md protocol field names
+    registrationId: requireString(data, "registration_id"),
+    credential: requireString(data, "credential"),
+    scopes: stringArray(data.scopes)
+    // @snake-case-ok-end
+  };
+}
+
+// src/lib/output.ts
+import chalk from "chalk";
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function printList(items, options) {
+  console.log(chalk.cyan(`${options.title}:`));
+  if (items.length === 0) {
+    console.log(chalk.gray(`  ${options.emptyMessage || "None found"}`));
+    return;
+  }
+  for (const item of items) {
+    const parts = [];
+    for (const col of options.columns) {
+      const value = item[col.key];
+      if (value === void 0 || value === null) continue;
+      const str = String(value);
+      const colorFn = col.color ? chalk[col.color] : (s) => s;
+      if (col.label) {
+        parts.push(`${col.label}: ${colorFn(str)}`);
+      } else {
+        parts.push(colorFn(str));
+      }
+    }
+    console.log(`  ${parts.join(" - ")}`);
+  }
+  if (options.total !== void 0) {
+    console.log(chalk.dim(`
+  Total: ${options.total}`));
+  }
+}
+function printDetail(title, fields) {
+  console.log(chalk.cyan(`${title}:`));
+  for (const field of fields) {
+    if (field.value === void 0 || field.value === null) continue;
+    const str = typeof field.value === "object" ? JSON.stringify(field.value) : String(field.value);
+    console.log(`  ${chalk.gray(field.label + ":")} ${str}`);
+  }
+}
+function getTotalCount(pagination) {
+  return pagination?.totalCount ?? pagination?.total ?? void 0;
+}
+function buildListParams(options, extra) {
+  const params = {};
+  if (options.limit) params.limit = options.limit;
+  if (options.cursor) params.cursor = options.cursor;
+  if (extra) {
+    for (const [key, value] of Object.entries(extra)) {
+      if (value !== void 0) params[key] = value;
+    }
+  }
+  return params;
+}
+function printNextCursorHint(commandPath, pagination) {
+  const hasMore = pagination?.hasMore ?? pagination?.hasNextPage ?? false;
+  const nextCursor = pagination?.nextCursor !== void 0 ? pagination.nextCursor : pagination?.cursor ?? null;
+  if (!hasMore || !nextCursor) return;
+  console.log(
+    chalk.yellow("\n  More results available \u2014 fetch the next page with:") + chalk.dim(`
+    ${commandPath} --cursor ${nextCursor}`)
+  );
+}
+
+// src/commands/auth-agent.ts
+var VERIFY_NEXT = "Ask the user for the 6-digit code from their email, then run: runtype auth verify <code>";
+function claimNext(email3) {
+  return email3 ? `Send the verification email with: runtype auth claim ${email3}` : "Ask the user for their email address, then run: runtype auth claim <email>";
+}
+function fail(payload) {
+  console.error(JSON.stringify(payload, null, 2));
+  process.exit(1);
+}
+function failFromError(error51, fallbackNext) {
+  if (error51 instanceof AgentAuthError) {
+    fail({
+      status: "error",
+      code: error51.code,
+      error: error51.message,
+      ...error51.hint || fallbackNext ? { next: error51.hint || fallbackNext } : {}
+    });
+  }
+  const message = error51 instanceof Error ? error51.message : String(error51);
+  fail({ status: "error", error: message, ...fallbackNext ? { next: fallbackNext } : {} });
+}
+async function fetchIdentity(apiKey, apiUrl) {
+  const client = createCliClient(apiKey, apiUrl);
+  const profile = await client.get(
+    "/users/profile"
+  );
+  return {
+    userId: typeof profile.id === "string" ? profile.id : "unknown",
+    orgId: typeof profile.orgId === "string" ? profile.orgId : void 0,
+    email: typeof profile.email === "string" ? profile.email : void 0
+  };
+}
+async function registerAction(options) {
+  const store = new CredentialStore();
+  const apiUrl = options.apiUrl || getApiUrl();
+  const existingClaim = await store.getClaimState();
+  const hasCredentials = await store.hasCredentials();
+  if (existingClaim && !options.force) {
+    const resumeDeadline = existingClaim.claimTokenExpires ?? existingClaim.credentialExpires;
+    const expired = resumeDeadline && new Date(resumeDeadline) < /* @__PURE__ */ new Date();
+    if (!expired) {
+      const payload = {
+        status: "registration_pending",
+        registrationId: existingClaim.registrationId,
+        credentialExpires: existingClaim.credentialExpires,
+        next: existingClaim.claimEmail ? VERIFY_NEXT : claimNext(options.email)
+      };
+      if (existingClaim.claimEmail) payload.claimEmail = existingClaim.claimEmail;
+      printJson(payload);
+      return;
+    }
+  }
+  if (hasCredentials && !existingClaim && !options.force) {
+    fail({
+      status: "error",
+      code: "already_authenticated",
+      error: "Credentials are already stored for a claimed account.",
+      next: "Run: runtype auth whoami --no-tty to confirm, or runtype auth logout first if the user wants a different account."
+    });
+  }
+  let registration;
+  try {
+    registration = await registerAnonymousAgent(apiUrl);
+  } catch (error51) {
+    failFromError(error51, "Retry: runtype auth register");
+  }
+  let identity = { userId: "unknown" };
+  try {
+    identity = await fetchIdentity(registration.credential, apiUrl);
+  } catch {
+  }
+  const claimState = {
+    claimToken: registration.claimToken,
+    registrationId: registration.registrationId,
+    credentialExpires: registration.credentialExpires,
+    claimTokenExpires: registration.claimTokenExpires,
+    apiUrl
+  };
+  await store.saveCredentials(
+    {
+      apiKey: registration.credential,
+      userId: identity.userId,
+      orgId: identity.orgId,
+      apiUrl
+    },
+    claimState
+  );
+  const base = {
+    status: "registered",
+    accountState: "temporary",
+    registrationId: registration.registrationId,
+    userId: identity.userId,
+    credentialExpires: registration.credentialExpires,
+    note: "A temporary account is active: CLI commands work now with limited models and quota. Verifying an email upgrades it to a full account and replaces the stored credential automatically."
+  };
+  if (options.email) {
+    try {
+      const claim = await initiateClaim(registration.claimToken, options.email, apiUrl);
+      await store.saveClaimState({ ...claimState, claimEmail: options.email });
+      printJson({
+        ...base,
+        status: "otp_sent",
+        claimEmail: options.email,
+        otpExpiresAt: claim.otpExpiresAt,
+        next: VERIFY_NEXT
+      });
+      return;
+    } catch (error51) {
+      if (error51 instanceof AgentAuthError) {
+        fail({
+          ...base,
+          status: "registered_claim_failed",
+          code: error51.code,
+          error: error51.message,
+          next: error51.hint || claimNext(options.email)
+        });
+      }
+      throw error51;
+    }
+  }
+  printJson({ ...base, next: claimNext() });
+}
+async function claimAction(email3, options) {
+  const store = new CredentialStore();
+  const claimState = await store.getClaimState();
+  const apiUrl = options.apiUrl || claimState?.apiUrl || (await store.getCredentials())?.apiUrl || getApiUrl();
+  if (!claimState) {
+    const hasCredentials = await store.hasCredentials();
+    fail({
+      status: "error",
+      code: "no_pending_registration",
+      error: hasCredentials ? "Stored credentials are already claimed; there is nothing to claim." : "No registration found.",
+      next: hasCredentials ? "Run: runtype auth whoami --no-tty" : `Run: runtype auth register --email ${email3}`
+    });
+  }
+  try {
+    const claim = await initiateClaim(claimState.claimToken, email3, apiUrl);
+    await store.saveClaimState({ ...claimState, claimEmail: email3 });
+    printJson({
+      status: "otp_sent",
+      registrationId: claim.registrationId,
+      claimEmail: email3,
+      otpExpiresAt: claim.otpExpiresAt,
+      next: VERIFY_NEXT
+    });
+  } catch (error51) {
+    failFromError(error51, `Retry: runtype auth claim ${email3}`);
+  }
+}
+async function verifyAction(code, options) {
+  const store = new CredentialStore();
+  const claimState = await store.getClaimState();
+  const apiUrl = options.apiUrl || claimState?.apiUrl || (await store.getCredentials())?.apiUrl || getApiUrl();
+  if (!claimState) {
+    fail({
+      status: "error",
+      code: "no_pending_registration",
+      error: "No claim in progress.",
+      next: "Run: runtype auth register --email <email> first."
+    });
+  }
+  if (!claimState.claimEmail) {
+    fail({
+      status: "error",
+      code: "claim_not_initiated",
+      error: "No verification email has been sent yet, so there is no code to verify.",
+      next: claimNext()
+    });
+  }
+  let completed;
+  try {
+    completed = await completeClaim(claimState.claimToken, code.trim(), apiUrl);
+  } catch (error51) {
+    failFromError(error51);
+  }
+  let identity = { userId: "unknown" };
+  try {
+    identity = await fetchIdentity(completed.credential, apiUrl);
+  } catch {
+  }
+  await store.saveCredentials({
+    apiKey: completed.credential,
+    userId: identity.userId,
+    orgId: identity.orgId,
+    apiUrl
+  });
+  await store.clearClaimState();
+  printJson({
+    status: "authenticated",
+    accountState: "full",
+    registrationId: completed.registrationId,
+    userId: identity.userId,
+    email: identity.email ?? claimState.claimEmail,
+    note: "The account is fully activated and the stored credential was rotated. All limits from the temporary account are removed.",
+    next: "Continue with setup: runtype install-mcp (then confirm with: runtype auth whoami --no-tty)"
+  });
+}
+function registerAgentAuthCommands(authCommand2) {
+  authCommand2.command("register").description("Create a Runtype account without a browser (agent signup, step 1 of 2)").option("--email <email>", "Also send the verification email in the same step").option("--force", "Register a new account even if one is stored or pending").option("--api-url <url>", "Custom API URL").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(registerAction);
+  authCommand2.command("claim <email>").description("Email the user a 6-digit code to attach the account to them").option("--api-url <url>", "Custom API URL").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(claimAction);
+  authCommand2.command("verify <code>").description("Complete signup with the 6-digit code from the verification email (step 2 of 2)").option("--api-url <url>", "Custom API URL").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(verifyAction);
+}
+
+// src/commands/auth.ts
+var authCommand = new Command("auth").description("Manage authentication");
+var NON_TTY_LOGIN_GUIDANCE = {
+  status: "error",
+  code: "tty_required",
+  error: "Browser login needs an interactive terminal, which this environment does not have.",
+  next: [
+    "New account (no browser needed): ask the user for their email, then run: runtype auth register --email <email> \u2014 a 6-digit code is emailed to them; finish with: runtype auth verify <code>",
+    "Existing account: ask the user for an API key from the dashboard (Settings > API keys), then run: runtype auth login --api-key <key>"
+  ]
+};
+function refuseForcedTtyLogin(options) {
+  if (options.tty === true && process.stdout.isTTY !== true) {
     console.error(
       JSON.stringify(
         {
-          status: "error",
-          error: "Browser login requires TTY mode. Use --api-key with auth login instead."
+          ...NON_TTY_LOGIN_GUIDANCE,
+          error: "Browser login needs a real interactive terminal. Forcing --tty from a non-terminal only changes output formatting; the browser OAuth callback still cannot complete here, so the command would hang."
         },
         null,
         2
@@ -46191,6 +46674,22 @@ authCommand.command("signup").description('Create a new Runtype account (alias f
     );
     process.exit(1);
   }
+  return false;
+}
+async function getBillingInfo(apiKey, apiUrl) {
+  try {
+    const client = createCliClient(apiKey, apiUrl);
+    return await client.get("/billing/status");
+  } catch {
+    return null;
+  }
+}
+authCommand.command("signup").description('Create a new Runtype account (alias for "auth login")').option("--api-url <url>", "Custom API URL").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
+  refuseForcedTtyLogin(options);
+  if (!isTTY(options)) {
+    console.error(JSON.stringify(NON_TTY_LOGIN_GUIDANCE, null, 2));
+    process.exit(1);
+  }
   const App = () => {
     const [loading, setLoading] = useState2(true);
     const [loadingLabel, setLoadingLabel] = useState2("Opening browser for authentication...");
@@ -46263,7 +46762,11 @@ async function loginAction(options) {
         });
         console.log(
           JSON.stringify(
-            { status: "authenticated", userId: userData.userId },
+            {
+              status: "authenticated",
+              userId: userData.userId,
+              next: "Continue with setup: runtype install-mcp (then confirm with: runtype auth whoami)"
+            },
             null,
             2
           )
@@ -46321,14 +46824,9 @@ async function loginAction(options) {
     await waitUntilExit2();
     return;
   }
+  refuseForcedTtyLogin(options);
   if (!isTTY(options)) {
-    console.error(
-      JSON.stringify(
-        { status: "error", error: "Browser login requires TTY mode. Use --api-key instead." },
-        null,
-        2
-      )
-    );
+    console.error(JSON.stringify(NON_TTY_LOGIN_GUIDANCE, null, 2));
     process.exit(1);
   }
   const App = () => {
@@ -46393,17 +46891,34 @@ authCommand.command("status").description("Show authentication status").option("
     try {
       const hasCredentials = await store.hasCredentials();
       if (!hasCredentials) {
-        console.log(JSON.stringify({ status: "unauthenticated" }, null, 2));
+        console.log(
+          JSON.stringify(
+            {
+              status: "unauthenticated",
+              next: "New account: runtype auth register --email <email>. Existing account: runtype auth login --api-key <key>."
+            },
+            null,
+            2
+          )
+        );
         return;
       }
       const credentials = await store.getCredentials();
+      const claimState = await store.getClaimState();
       console.log(
         JSON.stringify(
           {
             status: "authenticated",
+            accountState: claimState ? "temporary" : "full",
             userId: credentials?.userId,
             apiUrl: credentials?.apiUrl || "default",
-            orgId: credentials?.orgId || null
+            orgId: credentials?.orgId || null,
+            ...claimState ? {
+              registrationId: claimState.registrationId,
+              credentialExpires: claimState.credentialExpires,
+              claimEmail: claimState.claimEmail ?? null,
+              next: claimState.claimEmail ? "Finish signup: ask the user for the 6-digit code from their email, then run: runtype auth verify <code>" : "Finish signup: ask the user for their email, then run: runtype auth claim <email>"
+            } : {}
           },
           null,
           2
@@ -46486,6 +47001,7 @@ authCommand.command("export-key").description("Print the stored API key to stdou
   }
   process.stdout.write(apiKey);
 });
+registerAgentAuthCommands(authCommand);
 authCommand.command("logout").description("Remove stored credentials").option("--tty", "Force TTY mode").option("--no-tty", "Force non-TTY mode").action(async (options) => {
   const store = new CredentialStore();
   if (!isTTY(options)) {
@@ -46548,7 +47064,7 @@ authCommand.command("whoami").description("Display current user information").op
     if (!isTTY(options) || options.json) {
       console.log(JSON.stringify({ status: "unauthenticated" }, null, 2));
     } else {
-      console.log(chalk.yellow("Not logged in"));
+      console.log(chalk2.yellow("Not logged in"));
       console.log("Run: runtype auth login");
     }
     return;
@@ -46640,17 +47156,17 @@ import { useState as useState3, useEffect as useEffect4 } from "react";
 
 // src/lib/file-utils.ts
 import { readFileSync as readFileSync3 } from "fs";
-import chalk2 from "chalk";
+import chalk3 from "chalk";
 function parseJsonObject(raw, label) {
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch {
-    console.error(chalk2.red(`Invalid JSON in ${label}`));
+    console.error(chalk3.red(`Invalid JSON in ${label}`));
     process.exit(1);
   }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    console.error(chalk2.red(`${label} must be a JSON object`));
+    console.error(chalk3.red(`${label} must be a JSON object`));
     process.exit(1);
   }
   return parsed;
@@ -46661,7 +47177,7 @@ function readJsonFile(path20, opts = {}) {
   try {
     raw = readFileSync3(path20, "utf-8");
   } catch {
-    console.error(chalk2.red(`Failed to read ${label}: ${path20}`));
+    console.error(chalk3.red(`Failed to read ${label}: ${path20}`));
     process.exit(1);
   }
   const obj = parseJsonObject(raw, label);
@@ -46675,11 +47191,11 @@ function readJsonFile(path20, opts = {}) {
 }
 function resolveJsonPayload(inline, fromFile, label) {
   if (inline !== void 0 && fromFile !== void 0) {
-    console.error(chalk2.red(`Error: provide only one of inline JSON or --from-file for ${label}`));
+    console.error(chalk3.red(`Error: provide only one of inline JSON or --from-file for ${label}`));
     process.exit(1);
   }
   if (inline === void 0 && fromFile === void 0) {
-    console.error(chalk2.red(`Error: ${label} is required \u2014 pass inline JSON or --from-file <path>`));
+    console.error(chalk3.red(`Error: ${label} is required \u2014 pass inline JSON or --from-file <path>`));
     process.exit(1);
   }
   if (fromFile !== void 0) {
@@ -46696,7 +47212,7 @@ import {
 // src/lib/ensure-auth.ts
 init_credential_store();
 import readline from "readline";
-import chalk3 from "chalk";
+import chalk4 from "chalk";
 async function promptConfirm(message, options) {
   const defaultYes = options?.default !== false;
   const hint = defaultYes ? "Y/n" : "y/N";
@@ -46706,7 +47222,7 @@ async function promptConfirm(message, options) {
     terminal: true
   });
   return new Promise((resolve13) => {
-    rl.question(chalk3.cyan(`${message} (${hint}): `), (answer) => {
+    rl.question(chalk4.cyan(`${message} (${hint}): `), (answer) => {
       rl.close();
       const trimmed2 = answer.trim().toLowerCase();
       if (trimmed2 === "") {
@@ -46735,9 +47251,9 @@ async function ensureAuth(options) {
     return apiKey;
   }
   if (options?.interactive === false) {
-    console.error(chalk3.yellow("\nAuthentication required."));
+    console.error(chalk4.yellow("\nAuthentication required."));
     console.error(
-      chalk3.gray(
+      chalk4.gray(
         'Run "runtype auth login" first or set RUNTYPE_API_KEY before reading command input from stdin.'
       )
     );
@@ -46746,10 +47262,10 @@ async function ensureAuth(options) {
     }
     return null;
   }
-  console.log(chalk3.yellow("\nAuthentication required."));
+  console.log(chalk4.yellow("\nAuthentication required."));
   const shouldLogin = await promptConfirm("Would you like to log in now?", { default: true });
   if (!shouldLogin) {
-    console.log(chalk3.gray(`Run "runtype auth login" when you're ready.`));
+    console.log(chalk4.gray(`Run "runtype auth login" when you're ready.`));
     if (options?.exitOnFailure !== false) {
       process.exit(1);
     }
@@ -46758,100 +47274,37 @@ async function ensureAuth(options) {
   return handleBrowserLogin(store, options?.apiUrl);
 }
 async function handleBrowserLogin(store, apiUrl) {
-  console.log(chalk3.gray("Opening browser for authentication..."));
+  console.log(chalk4.gray("Opening browser for authentication..."));
   try {
     const oauth = new OAuthManager({
       clerkPublishableKey: getClerkPublishableKey(),
       dashboardUrl: getDashboardUrl()
     });
-    console.log(chalk3.gray("Waiting for browser authentication..."));
+    console.log(chalk4.gray("Waiting for browser authentication..."));
     const sessionToken = await oauth.authenticate("sign-in");
-    console.log(chalk3.gray("Getting API key..."));
+    console.log(chalk4.gray("Getting API key..."));
     const apiKeyManager = new ApiKeyManager();
     const { key, userId, orgId } = await apiKeyManager.exchangeSessionForApiKey(
       sessionToken,
       apiUrl || getApiUrl()
     );
-    console.log(chalk3.gray("Storing credentials..."));
+    console.log(chalk4.gray("Storing credentials..."));
     await store.saveCredentials({
       apiKey: key,
       userId,
       orgId,
       apiUrl: apiUrl || getApiUrl()
     });
-    console.log(chalk3.green("Logged in successfully!"));
+    console.log(chalk4.green("Logged in successfully!"));
     return key;
   } catch (error51) {
     const message = error51 instanceof Error ? error51.message : "Unknown error";
-    console.log(chalk3.red("Login failed"));
-    console.error(chalk3.red(message));
+    console.log(chalk4.red("Login failed"));
+    console.error(chalk4.red(message));
     return null;
   }
 }
 
-// src/lib/output.ts
-import chalk4 from "chalk";
-function printJson(data) {
-  console.log(JSON.stringify(data, null, 2));
-}
-function printList(items, options) {
-  console.log(chalk4.cyan(`${options.title}:`));
-  if (items.length === 0) {
-    console.log(chalk4.gray(`  ${options.emptyMessage || "None found"}`));
-    return;
-  }
-  for (const item of items) {
-    const parts = [];
-    for (const col of options.columns) {
-      const value = item[col.key];
-      if (value === void 0 || value === null) continue;
-      const str = String(value);
-      const colorFn = col.color ? chalk4[col.color] : (s) => s;
-      if (col.label) {
-        parts.push(`${col.label}: ${colorFn(str)}`);
-      } else {
-        parts.push(colorFn(str));
-      }
-    }
-    console.log(`  ${parts.join(" - ")}`);
-  }
-  if (options.total !== void 0) {
-    console.log(chalk4.dim(`
-  Total: ${options.total}`));
-  }
-}
-function printDetail(title, fields) {
-  console.log(chalk4.cyan(`${title}:`));
-  for (const field of fields) {
-    if (field.value === void 0 || field.value === null) continue;
-    const str = typeof field.value === "object" ? JSON.stringify(field.value) : String(field.value);
-    console.log(`  ${chalk4.gray(field.label + ":")} ${str}`);
-  }
-}
-function getTotalCount(pagination) {
-  return pagination?.totalCount ?? pagination?.total ?? void 0;
-}
-function buildListParams(options, extra) {
-  const params = {};
-  if (options.limit) params.limit = options.limit;
-  if (options.cursor) params.cursor = options.cursor;
-  if (extra) {
-    for (const [key, value] of Object.entries(extra)) {
-      if (value !== void 0) params[key] = value;
-    }
-  }
-  return params;
-}
-function printNextCursorHint(commandPath, pagination) {
-  const hasMore = pagination?.hasMore ?? pagination?.hasNextPage ?? false;
-  const nextCursor = pagination?.nextCursor !== void 0 ? pagination.nextCursor : pagination?.cursor ?? null;
-  if (!hasMore || !nextCursor) return;
-  console.log(
-    chalk4.yellow("\n  More results available \u2014 fetch the next page with:") + chalk4.dim(`
-    ${commandPath} --cursor ${nextCursor}`)
-  );
-}
-
 // src/commands/flows.ts
 function flowsListParams(options) {
   return {
@@ -72823,32 +73276,54 @@ import chalk42 from "chalk";
 // ../shared/dist/agent-onboarding-content.mjs
 var AGENT_ONBOARDING_MARKDOWN = `# Runtype for Coding Agents
 
-You are reading the setup script served by \`https://runtype.ai\`. Your durable goal is to leave this coding harness connected to Runtype's hosted MCP server with browser OAuth. Use the Runtype CLI as a bridge during this first session; do not treat it as the final integration.
+You are reading the setup script served by \`https://runtype.ai\`. Your durable goal is to leave this coding harness connected to Runtype's hosted MCP server. Use the Runtype CLI as a bridge during this first session; do not treat it as the final integration.
+
+Signup never requires a browser. The only things you may ask the user for are their email address and the 6-digit code Runtype emails them. Do not tell the user to open a dashboard, sign-in page, or OAuth window during signup.
 
 ## Golden path \u2014 do exactly this
 
 If the live Runtype MCP tools are already available in this session, skip setup and go to "After MCP is active" below. Otherwise follow every step in order:
 
-### 1. Install and authenticate the CLI
+### 1. Install the CLI and check auth
 
 \`\`\`bash
 npm install -g @runtypelabs/cli
-runtype auth login
+runtype auth status
 \`\`\`
 
-Complete the browser sign-in when it opens. The CLI makes this first session productive even though a running coding harness often cannot discover a newly installed MCP connection until it restarts.
+If status reports \`authenticated\` with \`accountState: "full"\`, skip to step 3. If it reports a pending signup, its \`next\` field tells you the exact command to resume with.
+
+### 2. Sign the user up from the terminal
 
-### 2. Install skills and the OAuth MCP connection
+Ask the user one question: "What email address should I use for your Runtype account?" Then run:
 
 \`\`\`bash
-runtype install-mcp
+runtype auth register --email <their-email>
+\`\`\`
+
+This creates the account and emails the user a 6-digit code. Ask the user: "Runtype emailed a 6-digit code to <their-email> \u2014 what is it?" Then run:
+
+\`\`\`bash
+runtype auth verify <code>
 \`\`\`
 
-This command detects the current coding harness, installs the Runtype agent skills for it, writes the user-level hosted MCP configuration, and starts the harness's own OAuth flow when possible. If it asks which harness to configure, select the harness running this session. If a browser opens, have the user complete OAuth.
+That completes signup. Every command in this flow prints JSON with a \`next\` field \u2014 follow it. Notes:
+
+- These commands work without a TTY and never open a browser.
+- \`register\` is safe to re-run; it resumes a pending signup instead of creating a duplicate account.
+- After \`register\` (before \`verify\`) you already hold a temporary credential: CLI commands work with restricted models and quota, and \`verify\` upgrades the same stored login in place. Do not build anything substantial until \`verify\` succeeds.
+- If the email already has a Runtype account, the command reports \`email_already_registered\`. In that case ask the user for an API key from their dashboard (Settings > API keys) and run \`runtype auth login --api-key <key>\` instead. This is the only path where the user touches the dashboard, and only because they already have an account.
+- A wrong code returns \`otp_invalid\` \u2014 ask the user to re-check and run \`runtype auth verify\` again. An expired code returns \`otp_expired\` \u2014 re-send with \`runtype auth claim <email>\`. Codes expire after 10 minutes and lock after 5 wrong attempts, so confirm the code with the user rather than guessing; after a lockout or expiry, re-send with \`runtype auth claim <email>\`.
 
-Do not manually create an API key, export the CLI key into MCP, or choose a different setup path merely to avoid a restart. CLI authentication and MCP OAuth are separate on purpose: the CLI is the first-session bridge; client-owned OAuth MCP is the durable connection.
+### 3. Install skills and the MCP connection
 
-### 3. Keep working in this session with the CLI
+\`\`\`bash
+runtype install-mcp
+\`\`\`
+
+This command detects the current coding harness, installs the Runtype agent skills for it, and writes the user-level hosted MCP configuration. If it asks which harness to configure, select the harness running this session. If it reports an OAuth action for the harness's own MCP connection, relay that instruction to the user for later \u2014 it happens on the harness's schedule, not during signup. That harness-side OAuth may open a browser when the user runs it; that is fine and expected \u2014 the no-browser rule above applies to Runtype signup, not to the harness's own connection ceremony.
+
+### 4. Keep working in this session with the CLI
 
 Do not stop just because the new MCP connection is not visible yet. Use CLI commands for useful first-session work:
 
@@ -72860,19 +73335,19 @@ runtype products list
 runtype --help
 \`\`\`
 
-The CLI also supports dispatch, records, validation, product setup, and other account operations. Read command help before mutating resources, and report concrete IDs and URLs to the user.
+The CLI also supports dispatch, records, validation, product setup, and other account operations. Read command help before mutating resources, and report concrete IDs and URLs to the user. If you need Runtype MCP tools before the restart, the CLI bridges them: \`runtype mcp tools\` lists them and \`runtype mcp call <tool>\` invokes one \u2014 same hosted tools, no restart needed.
 
-### 4. Tell the user to restart or reload the harness
+### 5. Tell the user to restart or reload the harness
 
-Before finishing this session, read the final status and next steps from \`runtype install-mcp\`. Complete any OAuth action it requests and retry any failed skill installation. Do not call setup complete while the command reports \`action-required\`, \`partial\`, or an error.
+Before finishing this session, read the final status and next steps from \`runtype install-mcp\`. Retry any failed skill installation. Do not call setup complete while the command reports \`action-required\`, \`partial\`, or an error.
 
-Only after skills and OAuth both succeed, tell the user exactly what changed and ask them to restart or reload the coding harness. Use direct language such as:
+Only after signup is verified and skills are installed, tell the user exactly what changed and ask them to restart or reload the coding harness. Use direct language such as:
 
-> Runtype skills and the OAuth MCP connection are installed. Please restart or reload this coding agent (or start a new session) so it can activate the new MCP tools. I used the CLI to keep this first session productive; after restart I will use MCP by default.
+> Your Runtype account is verified and the skills plus MCP connection are installed. Please restart or reload this coding agent (or start a new session) so it can activate the new MCP tools. I used the CLI to keep this first session productive; after restart I will use MCP by default.
 
 If an action remains, report that exact action instead of using the success wording above. Do not claim the running agent can use MCP until its Runtype tools actually appear.
 
-### 5. Switch to MCP after restart
+### 6. Switch to MCP after restart
 
 In the next session, use Runtype MCP first. Do not fall back to the CLI just because it worked previously. Start by calling:
 
@@ -72898,13 +73373,21 @@ runtype install-mcp --agent opencode
 runtype install-mcp --agent vscode
 \`\`\`
 
-Use only the line for the current harness. Follow the command's OAuth and restart instructions. Use \`--force\` only when the command reports that an existing MCP server named \`runtype\` points to a different URL and the user agrees to replace it.
+Use only the line for the current harness. Follow the command's restart instructions. Use \`--force\` only when the command reports that an existing MCP server named \`runtype\` points to a different URL and the user agrees to replace it.
+
+## Auth reference
+
+The signup commands wrap the agent auth protocol documented at \`https://runtype.com/auth.md\` (anonymous registration plus an email claim ceremony). You normally never need the raw protocol \u2014 the CLI is the supported client:
 
-## Headless exception \u2014 not the normal path
+- \`runtype auth register --email <email>\` \u2014 create the account and send the code (one step)
+- \`runtype auth claim <email>\` \u2014 re-send or change the email for a pending signup
+- \`runtype auth verify <code>\` \u2014 finish signup with the 6-digit code
+- \`runtype auth login --api-key <key>\` \u2014 existing accounts only
+- \`runtype auth status\` / \`runtype auth whoami\` \u2014 inspect the current login
 
-Only use an API key when browser OAuth is genuinely impossible in the user's environment, not merely inconvenient. Ask the user before switching authentication modes, then follow the canonical headless registration and claim protocol at \`https://runtype.com/auth.md\`. Never print a secret into the transcript or write a bearer token directly into a committed config file.
+A user-supplied \`RUNTYPE_API_KEY\` environment variable also authenticates every CLI command without a stored login. Never print a credential into the transcript or write one into a committed file.
 
-The hosted MCP endpoint is \`https://api.runtype.com/v1/mcp/protocol\`. A user-supplied \`RUNTYPE_API_KEY\` can authenticate CLI commands in a headless environment, but return to client-owned OAuth MCP when the harness can support it.
+Browser login (\`runtype auth login\` with no flags) exists for humans running the CLI in their own interactive terminal. Do not use it from a coding harness.
 
 ## After MCP is active
 
@@ -72923,7 +73406,7 @@ API: [api.runtype.com](https://api.runtype.com)
 
 // src/commands/onboard.ts
 init_credential_store();
-var AUTH_LOGIN_INSTRUCTION = "Sign in to Runtype: run `runtype auth login` (or set RUNTYPE_API_KEY), then re-run `runtype onboard`.";
+var AUTH_LOGIN_INSTRUCTION = "Sign in to Runtype first. New account: `runtype auth register --email <email>` then `runtype auth verify <code>`. Existing account: `runtype auth login --api-key <key>` (or set RUNTYPE_API_KEY). Then re-run `runtype onboard`.";
 var AFTER_RESTART_STEPS = [
   "Use the Runtype MCP server first for all Runtype work.",
   "Start with the get_build_instructions tool before creating or changing resources.",
@@ -73208,7 +73691,7 @@ function collectBundleFiles(dir) {
   walk(dir);
   return zippable;
 }
-function fail(message, jsonMode, code) {
+function fail2(message, jsonMode, code) {
   if (jsonMode) {
     printJson({ status: "error", error: message, code });
   } else {
@@ -73247,7 +73730,7 @@ appsCommand.command("list").description("List your apps").option("--json", "Stru
       console.log(`  ${app.url}  ${status}  ${app.visibility}${serving}`);
     }
   } catch (error51) {
-    fail(
+    fail2(
       `Failed to list apps: ${error51 instanceof Error ? error51.message : String(error51)}`,
       jsonMode,
       "LIST_FAILED"
@@ -73276,7 +73759,7 @@ appsCommand.command("create").description("Create an app (the hostname is {slug}
       console.log(`  ${app.url}`);
       console.log(chalk43.dim("  Deploy a bundle with `runtype apps deploy <dir> --app " + app.id + "`"));
     } catch (error51) {
-      fail(
+      fail2(
         `Failed to create app: ${error51 instanceof Error ? error51.message : String(error51)}`,
         jsonMode,
         "CREATE_FAILED"
@@ -73291,27 +73774,27 @@ appsCommand.command("deploy <dir>").description("Zip a bundle directory, upload
     const apiKey = await ensureAuth();
     if (!apiKey) return;
     if (!existsSync17(dir) || !statSync7(dir).isDirectory()) {
-      fail(`Not a directory: ${dir}`, jsonMode, "INVALID_DIR");
+      fail2(`Not a directory: ${dir}`, jsonMode, "INVALID_DIR");
     }
     let bundleFiles = {};
     try {
       bundleFiles = collectBundleFiles(dir);
     } catch (error51) {
-      fail(
+      fail2(
         `Failed to read ${dir}: ${error51 instanceof Error ? error51.message : String(error51)}`,
         jsonMode,
         "INVALID_DIR"
       );
     }
     if (!bundleFiles["index.html"]) {
-      fail(
+      fail2(
         `${dir} is missing index.html at its root (symlinked files are not bundled).`,
         jsonMode,
         "MISSING_INDEX"
       );
     }
     if (!bundleFiles[MANIFEST_FILENAME]) {
-      fail(
+      fail2(
         `${dir} is missing ${MANIFEST_FILENAME} at its root (symlinked files are not bundled). Every app bundle needs a manifest; see the build-runtype-app skill or the Runtype docs.`,
         jsonMode,
         "MISSING_MANIFEST"
@@ -73359,7 +73842,7 @@ appsCommand.command("deploy <dir>").description("Zip a bundle directory, upload
         console.log(chalk43.dim(`  Uploaded but not activated. Activate with \`runtype apps activate ${options.app} ${version2.id}\``));
       }
     } catch (error51) {
-      fail(
+      fail2(
         `Deploy failed: ${error51 instanceof Error ? error51.message : String(error51)}`,
         jsonMode,
         "DEPLOY_FAILED"
@@ -73390,7 +73873,7 @@ appsCommand.command("versions <appId>").description("List an app's versions, new
       );
     }
   } catch (error51) {
-    fail(
+    fail2(
       `Failed to list versions: ${error51 instanceof Error ? error51.message : String(error51)}`,
       jsonMode,
       "VERSIONS_FAILED"
@@ -73412,7 +73895,7 @@ appsCommand.command("activate <appId> <versionId>").description("Activate an upl
     console.log(chalk43.green(`Activated version ${version2.versionNumber}`));
     console.log(`  Live at ${chalk43.bold(app.url)}`);
   } catch (error51) {
-    fail(
+    fail2(
       `Activation failed: ${error51 instanceof Error ? error51.message : String(error51)}`,
       jsonMode,
       "ACTIVATE_FAILED"
@@ -73433,7 +73916,7 @@ appsCommand.command("delete <appId>").description("Permanently delete an app, it
     }
     console.log(chalk43.green(`Deleted ${appId}`));
   } catch (error51) {
-    fail(
+    fail2(
       `Delete failed: ${error51 instanceof Error ? error51.message : String(error51)}`,
       jsonMode,
       "DELETE_FAILED"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/cli",
-  "version": "2.30.1",
+  "version": "2.31.0",
   "description": "Command-line interface for Runtype AI platform",
   "type": "module",
   "main": "dist/index.js",
@@ -41,7 +41,7 @@
     "tsx": "^4.7.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.0",
-    "@runtypelabs/shared": "3.4.3"
+    "@runtypelabs/shared": "3.5.0"
   },
   "engines": {
     "node": ">=22.12.0"