@beryl-so/cli 0.21.4 → 0.24.0

package/README.md

@@ -12,10 +12,10 @@ that exposes every command to coding agents.
 npx @beryl-so/cli@latest init
 ```
 
-Signs you in, pins this repo to a project (creating it if needed — and asking whether
-you want to author tests locally with your own coding agent, the default, or let Beryl's
-agent explore and author them), and wires the MCP server into Claude Code or Cursor.
-Safe to re-run.
+Signs you in (browser approval by default, emailed one-time code as fallback — new
+emails are signed up on the spot), wires the beryl + playwright MCP servers into Claude
+Code or Cursor, installs the beryl-test authoring skill, and installs Playwright for
+local runs. Safe to re-run.
 
 ## Install
 
@@ -33,7 +33,8 @@ latest npm release — a stale MCP server silently exposes fewer tools. Set
 ## Authenticate
 
 ```bash
-beryl login                  # emailed one-time code; mints + stores a personal access token
+beryl login                  # opens the browser to approve — press Enter for an emailed code instead
+beryl login --otp            # skip the browser; emailed one-time code (signs up new emails too)
 export BERYL_API_KEY=beryl_pat_…   # CI: use a token from Account → API tokens
 ```
 
@@ -120,6 +121,7 @@ Manage the personal access tokens that authenticate the CLI and CI.
 | `beryl tokens list` | List your personal access tokens | `tokens_list` |
 | `beryl tokens create <name>` | Mint a new personal access token (shown once) | `tokens_create` |
 | `beryl tokens revoke <token-id>` | Revoke a personal access token | `tokens_revoke` |
+| `beryl tokens dismiss <token-id>` | Remove an already-revoked token from your list | `tokens_dismiss` |
 
 ### workspaces
 

package/dist/beryl-test-skill.js

@@ -11,7 +11,7 @@ export const BERYL_TEST_SKILL_DIR = "beryl-test";
 // lintPlan — the skill's documented shape must pass `beryl tests lint` on the first try.
 export const BERYL_TEST_SKILL_EXAMPLE_PLAN = {
     steps: [
-        { action: "goto", url: "https://app.example.com/pricing" },
+        { action: "goto", url: "/pricing" },
         {
             action: "expect",
             expect_kind: "have_text",
@@ -26,7 +26,7 @@ export const BERYL_TEST_SKILL_EXAMPLE_PLAN = {
 // pass `beryl tests lint` on the first try.
 export const BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN = {
     steps: [
-        { action: "goto", url: "https://app.example.com/signup" },
+        { action: "goto", url: "/signup" },
         { action: "fill", selector: "input[name=email]", value: "{{inbox_address}}" },
         { action: "click", selector: "button[type=submit]" },
         {
@@ -70,6 +70,8 @@ Before the first plan:
 
 \`\`\`
 npm i -D @playwright/test && npx playwright install chromium   # once, per project
+beryl envs list                                       # the root URL gotos resolve against (§2)
+beryl envs update <id> --url https://app.example.com  # set it if root_url is empty — required
 beryl accounts list                                   # who do authenticated tests sign in as? (§1)
 beryl accounts set-login <id> --file … --probe …      # store its sign-in — required (§1)
 beryl accounts check <id>                             # does that stored sign-in still work? (§1)
@@ -197,11 +199,10 @@ beryl accounts check <id>          # signs in NOW and proves it — do not skip
 Then write the tests with \`requires_auth: true\` and \`auth_mode: "session"\`, and NO
 sign-in steps.
 
-**Create them one at a time.** Locally there is no run to share a session across, so
-\`tests create\` renders each session-mode test with the account's sign-in in front of it —
-every create performs a real sign-in. Two at once would both trigger a code and race for
-the newest mail in the same mailbox. In the cloud that cost disappears: the whole run
-shares one sign-in.
+**Creates share the sign-in.** \`tests create\` replays a session-mode plan against the
+account's established session — reused from the last proven sign-in when it is still
+live — so a batch of creates costs at most one sign-in, same as a run. Still create one
+at a time: two racing creates would race the same mailbox for mail.
 
 Reading before writing matters here: the login plan self-heals, so
 \`beryl accounts get-login <id>\` first and pass its \`login_plan_hash\` back as
@@ -220,8 +221,8 @@ your bug, but it IS your move: the account is marked unsupported, and its sessio
 tests fail at setup with \`SESSION_UNSUPPORTED\` on every run until you re-author them
 with \`auth_mode: "inline"\` and their own sign-in steps. Inline tests are unaffected.
 
-\`beryl runs local\` works on session-mode tests too — locally the server renders the
-account's sign-in steps in front of the test, so it proves the same thing on your machine.
+\`beryl runs local\` works on session-mode tests too — same shape as the cloud: one
+sign-in per invocation, shared by every session-mode test.
 
 ### Two identities in one test
 
@@ -242,6 +243,11 @@ SSO-only sites (no email+password form at all) remain webapp territory.
    \`{action, selector, url, value, ...}\`. Two structural rules the plan must satisfy:
    - the **first executed step is a \`goto\`** (the flow has to start by navigating somewhere), and
    - **at least one step is an \`expect\`** (a test that asserts nothing is not a test).
+   **A \`goto\` at your own app is a PATH, never a full URL** — \`/pricing\`, not
+   \`https://app.example.com/pricing\`. The origin comes from the environment's root URL, so
+   one plan runs against prod, staging and a preview. Bake the origin in and \`--env\` is
+   silently ignored: the test keeps hitting whatever host you typed. Absolute URLs stay
+   legal for OTHER origins (an OAuth handoff, a magic link on another domain).
    Optional \`before\` / \`after\` arrays hold setup and teardown; \`after\` runs even when a
    main step fails, so a create/update/delete flow can clean up the record it made.
 
@@ -379,7 +385,8 @@ beryl runs local              # the whole suite, results recorded in Beryl
 - **Results sync to Beryl by default** — the finished run is imported as a first-class
   run (history, replay, report; trigger source \`local\`). While ITERATING on a draft,
   pass \`--no-sync\` so every fix-loop attempt doesn't land in the project's run history.
-- \`--url-override\` points the run at a local dev server or a preview deploy.
+- \`--url-override\` swaps the root URL for THIS run — for a throwaway host (a dev server, a
+  per-PR preview). A standing environment is \`--env <id>\` instead, not an override.
 - \`--dir\` keeps the **spec, artifacts, and a JSON \`report.json\`** on disk so you (or your
   coding agent) can read exactly what happened and iterate: read the report, see which step
   or assertion failed and why, fix the plan, \`beryl tests set-plan\`, run again.

package/dist/commands/auth.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import os from "node:os";
 import { saveGlobalConfig } from "../config.js";
+import { deviceLogin, SWITCH_TO_OTP } from "../device-login.js";
 import { CliError, UsageError } from "../errors.js";
 import { ApiClient } from "../http.js";
 import { dim, green } from "../output.js";
@@ -48,18 +49,67 @@ export async function promptForOtpCode(ctx) {
         throw new UsageError("No valid 6-digit code entered");
     return code;
 }
+// The emailed-code flow, returning a raw PAT. With a --code the email already has a
+// code, so nothing is sent (and check-email is skipped entirely).
+async function otpLogin(ctx, input, codeFlag) {
+    const apiUrl = ctx.client.baseUrl;
+    const email = flagStr(input, "email") ?? (await promptForEmail(ctx));
+    if (!email.includes("@"))
+        throw new UsageError(`"${email}" is not an email address`);
+    const anon = new ApiClient(apiUrl);
+    let code = codeFlag;
+    if (!code) {
+        const check = (await anon.post("/auth/check-email", { email }));
+        if (!check.exists) {
+            await anon.post("/auth/signup", { email });
+            ctx.err(dim(`No Beryl account for ${email} yet — creating one. Sent a 6-digit code to ${email}`));
+        }
+        else if ((check.auth_methods ?? []).includes("otp")) {
+            await anon.post("/auth/request-login-otp", { email });
+            ctx.err(dim(`Sent a 6-digit code to ${email}`));
+        }
+        else {
+            const why = `${email} signs in with Google, so there is no emailed code`;
+            if (!ctx.interactive) {
+                throw new UsageError(`${why} — run \`beryl login\` in a terminal to sign in via the browser, ` +
+                    "or pass --token with a token from beryl.so → Account → API tokens");
+            }
+            ctx.err(`${why} — confirm the sign-in in your browser instead.`);
+            const fromBrowser = await deviceLogin(ctx, process.stdin, flagStr(input, "token-name"));
+            if (fromBrowser === SWITCH_TO_OTP)
+                throw new UsageError(why);
+            return fromBrowser;
+        }
+        code = await promptForOtpCode(ctx);
+    }
+    const login = (await anon.post("/auth/verify-otp", { email, code }));
+    if (!login.access_token)
+        throw new CliError("Login did not return an access token");
+    const session = new ApiClient(apiUrl, login.access_token);
+    const minted = (await session.post("/account/tokens", {
+        name: flagStr(input, "token-name") ?? `CLI on ${os.hostname()}`,
+    }));
+    return minted.token;
+}
 export const authCommands = [
     {
         name: "login",
         summary: "Authenticate the CLI with your Beryl account",
-        description: "Signs in with an emailed one-time code and mints a personal access token, " +
-            "which is stored in the CLI config. Pass --token to use an existing token " +
-            "from Account → API tokens instead. Pass --email plus --code (the 6 digits " +
-            "from the email, e.g. read from a `beryl inbox`) to complete the OTP flow " +
-            "without a prompt. In CI, prefer the BERYL_API_KEY environment variable.",
+        description: "Signs in via your browser (a code you confirm at beryl.so) and stores a personal " +
+            "access token in the CLI config. Pass --otp (or --email) to skip the browser and " +
+            "sign in with an emailed one-time code instead — a new email gets an account " +
+            "created automatically. Pass --token to use an existing token from Account → API " +
+            "tokens. Pass --email plus --code (the 6 digits from the email, e.g. read from a " +
+            "`beryl inbox`) to complete the OTP flow without a prompt. In CI, prefer the " +
+            "BERYL_API_KEY environment variable.",
         interactive: true,
         flags: [
             { name: "token", type: "string", description: "Use an existing personal access token" },
+            {
+                name: "otp",
+                type: "boolean",
+                description: "Skip the browser — sign in with an emailed code",
+            },
             {
                 name: "email",
                 type: "string",
@@ -81,6 +131,7 @@ export const authCommands = [
         ],
         examples: [
             "beryl login",
+            "beryl login --otp",
             "beryl login --token beryl_pat_…",
             "beryl login --email you@example.com",
             "beryl login --email agent@example.com --code 123456 --json",
@@ -96,26 +147,22 @@ export const authCommands = [
                     if (!flagStr(input, "email"))
                         throw new UsageError("--code requires --email");
                 }
-                const email = flagStr(input, "email") ?? (await promptForEmail(ctx));
-                if (!email.includes("@"))
-                    throw new UsageError(`"${email}" is not an email address`);
-                const anon = new ApiClient(apiUrl);
-                let code = codeFlag;
-                if (!code) {
-                    await anon.post("/auth/request-login-otp", { email });
-                    ctx.err(dim(`Sent a 6-digit code to ${email}`));
-                    ctx.err(dim("Not arriving? Check spam; if you're new to Beryl, sign up at https://beryl.so first — " +
-                        "or use `beryl login --token` with a token from beryl.so → Account → API tokens."));
-                    code = await promptForOtpCode(ctx);
+                // Guard before any network call — the OTP flow's check-email/signup would create
+                // a real account and send an email before dying on the interactive code prompt.
+                if (!ctx.interactive && codeFlag === undefined) {
+                    throw new UsageError("Cannot prompt for a code without a terminal — pass --email with --code, " +
+                        "--token, or set BERYL_API_KEY");
+                }
+                const wantsOtp = flagBool(input, "otp") ||
+                    flagStr(input, "email") !== undefined ||
+                    codeFlag !== undefined;
+                if (!wantsOtp && ctx.interactive) {
+                    const fromBrowser = await deviceLogin(ctx, process.stdin, flagStr(input, "token-name"));
+                    token = fromBrowser === SWITCH_TO_OTP ? await otpLogin(ctx, input) : fromBrowser;
+                }
+                else {
+                    token = await otpLogin(ctx, input, codeFlag);
                 }
-                const login = (await anon.post("/auth/verify-otp", { email, code }));
-                if (!login.access_token)
-                    throw new CliError("Login did not return an access token");
-                const session = new ApiClient(apiUrl, login.access_token);
-                const minted = (await session.post("/account/tokens", {
-                    name: flagStr(input, "token-name") ?? `CLI on ${os.hostname()}`,
-                }));
-                token = minted.token;
             }
             const authed = new ApiClient(apiUrl, token);
             const me = (await authed.get("/account/"));
@@ -240,4 +287,13 @@ export const authCommands = [
             return { human: "Revoked." };
         },
     },
+    {
+        name: "tokens dismiss",
+        summary: "Remove an already-revoked token from your list",
+        args: [{ name: "token-id", description: "Token id from `beryl tokens list`", required: true }],
+        async run(ctx, input) {
+            await ctx.client.post(`/account/tokens/${arg(input, "token-id")}/dismiss`, {});
+            return { human: "Dismissed." };
+        },
+    },
 ];

package/dist/commands/init.js

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { BERYL_TEST_SKILL, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME, } from "../beryl-test-skill.js";
 import { loadConfig } from "../config.js";
-import { CliError } from "../errors.js";
+import { AuthError, CliError } from "../errors.js";
 import { ApiClient } from "../http.js";
 import { bold, cyan, dim, green, red, yellow } from "../output.js";
 import { anyGap, describeGaps, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
@@ -148,7 +148,8 @@ export const initCommands = [
     {
         name: "init",
         summary: "Set up Beryl in this repo — sign in and wire up your coding agent",
-        description: "One-command onboarding: signs you in (emailed one-time code) and wires up your coding " +
+        description: "One-command onboarding: signs you in (browser confirm, or an emailed one-time code) " +
+            "and wires up your coding " +
             "agent. Nothing is detected and nothing is conditional — every run wires the beryl AND " +
             "playwright MCP servers, writes the authoring skill (user scope: your home " +
             ".agents/skills/ + .claude/skills/, so it follows you into every session; --scope " +
@@ -186,17 +187,33 @@ export const initCommands = [
         async run(ctx, input) {
             const cwd = process.cwd();
             let { client, config } = ctx;
-            if (config.token) {
-                const me = (await client.get("/account/"));
-                ctx.err(`${green("✓")} Signed in as ${me.email}`);
-            }
-            else {
+            const signIn = async () => {
+                // Non-interactive skips the picker and lets `login` fail with its own
+                // "interactive input required" message, exactly as before.
+                const answer = ctx.interactive
+                    ? await ctx.prompt("Sign in: [1] Browser (opens beryl.so)  [2] Email me a code — [1]: ")
+                    : "";
                 const login = authCommands.find((c) => c.name === "login");
-                await login.run(ctx, { args: {}, flags: {} });
+                await login.run(ctx, { args: {}, flags: answer.trim() === "2" ? { otp: true } : {} });
                 config = loadConfig();
                 if (!config.token)
                     throw new CliError("Login did not persist a token");
                 client = new ApiClient(config.apiUrl, config.token);
+            };
+            if (config.token) {
+                try {
+                    const me = (await client.get("/account/"));
+                    ctx.err(`${green("✓")} Signed in as ${me.email}`);
+                }
+                catch (err) {
+                    if (!(err instanceof AuthError))
+                        throw err;
+                    ctx.err(yellow("Your session token is invalid or expired."));
+                    await signIn();
+                }
+            }
+            else {
+                await signIn();
             }
             const scope = (flagStr(input, "scope") ?? "user");
             const report = (label, fresh, where) => ctx.err(`${green("✓")} ${label} ${fresh ? "configured" : "already configured"} ${dim(where)}`);

package/dist/commands/runs.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { downloadRunArtifacts, failureImages, isFailing, resultsOf, } from "../artifacts.js";
 import { CliError, UsageError } from "../errors.js";
-import { buildImportForm, executeLocalSpec, toRunEntry, } from "../local-exec.js";
+import { buildImportForm, establishAccountSession, executeLocalSpec, IMPORT_MAX_ERROR_LEN, toRunEntry, } from "../local-exec.js";
 import { countPlannedFrames, countWrittenFrames, PlaywrightMissingError, } from "../local-run.js";
 import { dim, green, red, yellow } from "../output.js";
 import { anyGap, confirmInstall, describeGaps, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
@@ -108,11 +108,11 @@ export const runCommands = [
             "does, and scrubbed from any error text or DOM snapshot before results upload. When the " +
             "run finishes, the results and replay artifacts are imported into Beryl as a normal run " +
             "(trigger source `local`) — history, replay, and reports all work; pass --no-sync to " +
-            "keep a run entirely off the record while iterating. Session-mode tests run here too: " +
-            "in the cloud their account signs in once per run and every test rides that session, " +
-            "and locally the server hands you the same test with that account's sign-in steps in " +
-            "front, so it proves the same thing on your machine. Only a test that depends on a " +
-            "session Beryl captured server-side is skipped, with a note. Point " +
+            "keep a run entirely off the record while iterating. Session-mode tests behave as " +
+            "in the cloud: their account signs in once per invocation and every session-mode " +
+            "test rides that session; a failed sign-in fails those tests with the same " +
+            "SESSION_* reason a cloud run reports. Only a test that depends on a session Beryl " +
+            "captured server-side is skipped, with a note. Point " +
             "--url-override at a local dev server or preview, and --dir to keep specs, artifacts, " +
             "and reports on disk. Exits 0 only if every executed test passed.",
         scope: "project",
@@ -176,19 +176,33 @@ export const runCommands = [
             const ids = all ? listed.filter((t) => t.is_active !== false).map((t) => t.id) : explicitIds;
             if (ids.length === 0)
                 throw new CliError("This project has no tests to run.");
+            const fetchScript = (id) => ctx.client.get(`${projectPath(workspaceId, projectId)}/tests/${id}/script`, {
+                // frames only matter when the run will be imported: they become the replay.
+                // environment_id keeps the baked login_email on the same environment the
+                // LOGIN_PASSWORD reveal below is scoped to.
+                base_url: urlOverride,
+                frames: sync ? true : undefined,
+                environment_id: flagStr(input, "env"),
+            });
+            const toLocalSpec = (id, script) => ({
+                id,
+                title: titles.get(id) ?? id.slice(0, 8),
+                content: script.content,
+                requiresAuth: Boolean(script.requires_auth),
+                usesEmail: /__vmInbox\(|__vmAwaitEmail\(/.test(script.content),
+                usesLoginPassword: Boolean(script.uses_login_password),
+                inlinedLoginSteps: script.inlined_login_steps ?? 0,
+                ...(script.session_mode && script.account_id
+                    ? { sessionMode: true, accountId: script.account_id }
+                    : {}),
+                ...(script.email ? { email: script.email } : {}),
+                ...(script.login_config_error ? { loginConfigError: script.login_config_error } : {}),
+            });
             const specs = [];
             for (const id of ids) {
                 let script;
                 try {
-                    script = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests/${id}/script`, 
-                    // frames only matter when the run will be imported: they become the replay.
-                    // environment_id keeps the baked login_email on the same environment the
-                    // LOGIN_PASSWORD reveal below is scoped to.
-                    {
-                        base_url: urlOverride,
-                        frames: sync ? true : undefined,
-                        environment_id: flagStr(input, "env"),
-                    }));
+                    script = await fetchScript(id);
                 }
                 catch (err) {
                     // With --all an unrenderable test (no plan yet) is a skip, not an abort;
@@ -200,36 +214,66 @@ export const runCommands = [
                     }
                     throw err;
                 }
-                specs.push({
-                    id,
-                    title: titles.get(id) ?? id.slice(0, 8),
-                    content: script.content,
-                    requiresAuth: Boolean(script.requires_auth),
-                    usesEmail: /__vmInbox\(|__vmAwaitEmail\(/.test(script.content),
-                    usesLoginPassword: Boolean(script.uses_login_password),
-                    inlinedLoginSteps: script.inlined_login_steps ?? 0,
-                    ...(script.email ? { email: script.email } : {}),
-                    ...(script.login_config_error ? { loginConfigError: script.login_config_error } : {}),
-                });
+                specs.push(toLocalSpec(id, script));
             }
             if (specs.length === 0)
                 throw new CliError("No runnable tests were found.");
-            // A test that leans on a session Beryl holds server-side gets no session here, so
-            // skip it rather than run a spec doomed at the login wall. Session-mode tests are
-            // NOT in that set: the server renders them with their account's own sign-in steps
-            // in front, so they sign themselves in here and run like any other. A test whose
-            // account is missing its password would type a literal placeholder into the page:
-            // same treatment, with the server's fix-it message.
-            const skipped = specs.filter((s) => s.requiresAuth || s.loginConfigError);
-            const runnable = specs.filter((s) => !s.requiresAuth && !s.loginConfigError);
+            // A test that leans on a session this CLI cannot establish gets no session here,
+            // so skip it rather than run a spec doomed at the login wall. A session-mode test
+            // is NOT in that set: its account's session is established below, once, exactly as
+            // a cloud run's setup phase does. A test whose account is missing its password
+            // would type a literal placeholder into the page: skip, with the server's fix-it
+            // message.
+            const skipped = specs.filter((s) => (s.requiresAuth && !(s.sessionMode && s.accountId)) || s.loginConfigError);
+            const runnable = specs.filter((s) => !skipped.includes(s));
             for (const s of skipped) {
-                ctx.err(yellow(s.requiresAuth
-                    ? `! ${s.title}: needs a session only Beryl's cloud holds — skipped ` +
-                        `(use \`beryl runs trigger\`).`
-                    : `! ${s.title}: skipped — ${s.loginConfigError}`));
+                ctx.err(yellow(s.loginConfigError
+                    ? `! ${s.title}: skipped — ${s.loginConfigError}`
+                    : `! ${s.title}: needs a session only Beryl's cloud holds — skipped ` +
+                        `(use \`beryl runs trigger\`).`));
             }
             if (runnable.length === 0)
                 throw new CliError("None of the selected tests can run locally.");
+            // Once per account, before any test runs — the local counterpart of the cloud
+            // worker's run-setup phase, produced by the same server-side establish (stored-
+            // session cache, login replay, proof). A failure here fails only that account's
+            // tests, with the same stable-prefixed reason a cloud run reports; an account
+            // proven unable to carry a session gets its tests re-rendered to sign themselves
+            // in, the same degraded mode a cloud run applies.
+            const sessions = new Map();
+            const sessionErrors = new Map();
+            const accountIds = [
+                ...new Set(runnable.filter((s) => s.sessionMode && s.accountId).map((s) => s.accountId)),
+            ];
+            for (const accountId of accountIds) {
+                ctx.err(dim("Establishing the test account's session (once per run)…"));
+                const established = await establishAccountSession(ctx.client, projectPath(workspaceId, projectId), accountId);
+                if (established.session) {
+                    sessions.set(accountId, established.session);
+                }
+                else if (established.unsupported) {
+                    // The server just latched UNSUPPORTED, so a re-fetch renders these specs with
+                    // their account's sign-in steps inlined — they run self-signing like any other.
+                    // Whole-object replacement, not a merge: the inlined render carries no
+                    // session_mode, and a merge would leave the stale sessionMode/accountId behind.
+                    ctx.err(yellow(`! ${established.error} — signing in per test.`));
+                    try {
+                        for (const [i, s] of runnable.entries()) {
+                            if (s.accountId !== accountId)
+                                continue;
+                            runnable[i] = toLocalSpec(s.id, await fetchScript(s.id));
+                        }
+                    }
+                    catch (err) {
+                        // A failed re-fetch fails only this account's tests, like any other
+                        // establish failure — not the whole invocation.
+                        sessionErrors.set(accountId, err instanceof Error ? err.message : String(err));
+                    }
+                }
+                else {
+                    sessionErrors.set(accountId, established.error ?? "SESSION_UNAVAILABLE");
+                }
+            }
             // Revealed once for the batch over the member-gated, logged route — the same
             // secret the cloud runner banks into run-config.json; never in the spec source.
             let loginPassword;
@@ -264,6 +308,30 @@ export const runCommands = [
                 if (!bar.active)
                     ctx.err(dim(`Running ${spec.title}…`));
                 const testStarted = new Date().toISOString();
+                // No proven session for this account: running the spec would open the page
+                // logged out and pass every assertion that tolerates that — fail it in the
+                // setup phase with the establish error, exactly as a cloud run does.
+                const sessionError = spec.accountId ? sessionErrors.get(spec.accountId) : undefined;
+                if (spec.sessionMode && sessionError !== undefined) {
+                    entries.push({
+                        test_case_id: spec.id,
+                        status: "failed",
+                        phase: "setup",
+                        error_message: sessionError.slice(0, IMPORT_MAX_ERROR_LEN),
+                        started_at: testStarted,
+                        completed_at: new Date().toISOString(),
+                        frames: [],
+                        frame_urls: [],
+                        frame_durations_ms: [],
+                        files: [],
+                    });
+                    done += 1;
+                    failed += 1;
+                    bar.clear();
+                    ctx.err(`${red("✗")} ${spec.title}\n    ${dim(sessionError.split("\n")[0] ?? "")}`);
+                    continue;
+                }
+                const session = spec.sessionMode ? sessions.get(spec.accountId ?? "") : undefined;
                 let outcome;
                 let runError;
                 let lastStep = 0;
@@ -272,6 +340,7 @@ export const runCommands = [
                     dir: dir ? path.join(dir, spec.id) : undefined,
                     harvest: sync,
                     loginPassword,
+                    session,
                     // Clear the rewriting bar before a mid-test log line, or the line is
                     // appended onto the live bar and fossilises it into scrollback.
                     onEvent: (line) => {
@@ -323,7 +392,10 @@ export const runCommands = [
                     // result, not an aborted batch: the remaining tests still deserve their run.
                     runError = err instanceof Error ? err.message : String(err);
                 }
-                const entry = toRunEntry(spec, outcome, runError, testStarted, entries.length, spec.usesLoginPassword ? loginPassword : undefined);
+                const entry = toRunEntry(spec, outcome, runError, testStarted, entries.length, [
+                    ...(spec.usesLoginPassword && loginPassword ? [loginPassword] : []),
+                    ...(session?.secrets ?? []),
+                ]);
                 entries.push(entry);
                 done += 1;
                 if (entry.status === "passed")

package/dist/commands/tests.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import { CliError, UsageError } from "../errors.js";
 import { ApiError } from "../http.js";
 import { lintPlan } from "../lint.js";
-import { buildImportForm, executeLocalSpec, toRunEntry, } from "../local-exec.js";
+import { buildImportForm, establishAccountSession, executeLocalSpec, toRunEntry, } from "../local-exec.js";
 import { PlaywrightMissingError } from "../local-run.js";
 import { dim, green, red, table, yellow } from "../output.js";
 import { confirmInstall, installPlaywright } from "../playwright-install.js";
@@ -243,9 +243,27 @@ export const testCommands = [
                 frames: sync ? true : undefined,
             });
             let compiled = await compile();
+            // Session-mode plan: establish the account's session once (server-side, reused
+            // from the stored one when it still proves live) and replay against it — the
+            // cloud shape. An unsupported account is re-compiled to sign itself in.
+            let session;
+            if (compiled.session_mode && compiled.account_id) {
+                ctx.err(dim("Establishing the test account's session…"));
+                const established = await establishAccountSession(ctx.client, projectPath(workspaceId, projectId), compiled.account_id);
+                if (established.session) {
+                    session = established.session;
+                }
+                else if (established.unsupported) {
+                    ctx.err(yellow(`! ${established.error} — the replay signs in itself.`));
+                    compiled = await compile();
+                }
+                else {
+                    throw new CliError(established.error ?? "SESSION_UNAVAILABLE");
+                }
+            }
             // A captured session lives encrypted in Beryl's cloud and is never handed to
             // this machine — the cloud is the only place this plan can be proven.
-            if (compiled.requires_auth) {
+            if (compiled.requires_auth && !session) {
                 ctx.err(yellow("! This plan signs in with a captured session, so it can only be verified " +
                     "in Beryl's cloud — verifying server-side instead."));
                 try {
@@ -281,6 +299,7 @@ export const testCommands = [
                 requiresAuth: false,
                 usesEmail: /__vmInbox\(|__vmAwaitEmail\(/.test(content),
                 usesLoginPassword: compiled.uses_login_password,
+                inlinedLoginSteps: compiled.inlined_login_steps ?? 0,
                 email: compiled.email ?? undefined,
             });
             const startedAt = new Date().toISOString();
@@ -303,6 +322,7 @@ export const testCommands = [
                         dir: flagStr(input, "dir"),
                         harvest: true,
                         loginPassword,
+                        session,
                         onEvent: (line) => ctx.err(dim(line)),
                     }));
                 }
@@ -369,7 +389,7 @@ export const testCommands = [
             }
             let runId;
             if (sync) {
-                const entry = toRunEntry({ ...specOf(compiled.content), id: String(created.id) }, outcome, undefined, startedAt, 0, loginPassword);
+                const entry = toRunEntry({ ...specOf(compiled.content), id: String(created.id) }, outcome, undefined, startedAt, 0, [...(loginPassword ? [loginPassword] : []), ...(session?.secrets ?? [])]);
                 const imported = (await ctx.client.request("POST", `${projectPath(workspaceId, projectId)}/runs/import`, {
                     form: buildImportForm([entry], {
                         environmentId: env,

package/dist/device-login.js

@@ -0,0 +1,132 @@
+import { spawn } from "node:child_process";
+import os from "node:os";
+import { CliError } from "./errors.js";
+import { ApiClient, ApiError } from "./http.js";
+import { dim } from "./output.js";
+/** Returned when the user presses Enter to fall back to the emailed-code flow. */
+export const SWITCH_TO_OTP = Symbol("switch-to-otp");
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // no browser is fine — the URL is printed for copy-paste
+    }
+}
+/** Browser device-code sign-in: opens beryl.so, polls until the user confirms the code
+ *  there, and resolves to the raw PAT — or to SWITCH_TO_OTP on Enter. */
+export async function deviceLogin(ctx, stdin = process.stdin, tokenName) {
+    const anon = new ApiClient(ctx.client.baseUrl);
+    const start = (await anon.post("/auth/cli/start", {
+        token_name: tokenName ?? `CLI on ${os.hostname()}`,
+    }));
+    openBrowser(start.verification_url);
+    ctx.err(start.verification_url);
+    ctx.err(`Confirm this code in the browser: ${start.user_code}`);
+    ctx.err(dim("Press Enter to sign in with an emailed code instead"));
+    let timer;
+    let onData;
+    let done = false;
+    try {
+        return await new Promise((resolve, reject) => {
+            let interval = start.interval;
+            let failures = 0;
+            let pollInFlight = false;
+            let switchRequested = false;
+            const finish = (token) => {
+                done = true;
+                resolve(token);
+            };
+            const fail = (err) => {
+                done = true;
+                reject(err);
+            };
+            const switchToOtp = () => {
+                done = true;
+                resolve(SWITCH_TO_OTP);
+            };
+            onData = (chunk) => {
+                if (!/[\r\n]/.test(chunk.toString()))
+                    return;
+                if (done || switchRequested)
+                    return;
+                // An in-flight poll may already be approved server-side (the session is consumed);
+                // its result must win or the minted token is lost forever.
+                if (pollInFlight)
+                    switchRequested = true;
+                else
+                    switchToOtp();
+            };
+            stdin.on("data", onData);
+            stdin.resume();
+            const poll = async () => {
+                pollInFlight = true;
+                let res;
+                try {
+                    res = (await anon.post("/auth/cli/poll", {
+                        device_code: start.device_code,
+                    }));
+                }
+                catch (err) {
+                    pollInFlight = false;
+                    if (done)
+                        return;
+                    if (switchRequested) {
+                        switchToOtp();
+                    }
+                    else if (++failures >= 5) {
+                        fail(err);
+                    }
+                    else {
+                        if (err instanceof ApiError && err.status === 429)
+                            interval *= 2;
+                        timer = setTimeout(() => void poll(), interval * 1000);
+                    }
+                    return;
+                }
+                pollInFlight = false;
+                failures = 0;
+                if (done)
+                    return;
+                if (res.status === "approved" && res.token) {
+                    if (switchRequested)
+                        ctx.err("Already approved in the browser — signed in");
+                    finish(res.token);
+                }
+                else if (switchRequested) {
+                    switchToOtp();
+                }
+                else if (res.status === "approved") {
+                    fail(new CliError("Sign-in approved but no token was returned — try again"));
+                }
+                else if (res.status === "denied") {
+                    fail(new CliError("Sign-in was denied in the browser"));
+                }
+                else if (res.status !== "pending") {
+                    fail(new CliError("The sign-in request expired — run `beryl login` again"));
+                }
+                else {
+                    timer = setTimeout(() => void poll(), interval * 1000);
+                }
+            };
+            timer = setTimeout(() => void poll(), interval * 1000);
+        });
+    }
+    finally {
+        // Both racers are torn down whichever wins — a live timer or stdin listener would
+        // keep the process alive after login.
+        done = true;
+        if (timer)
+            clearTimeout(timer);
+        if (onData)
+            stdin.off("data", onData);
+        stdin.pause();
+    }
+}

package/dist/local-exec.js

@@ -9,12 +9,14 @@ export const IMPORT_MAX_FILE_BYTES = 14 * 1024 * 1024;
 export const IMPORT_MAX_TOTAL_BYTES = 180 * 1024 * 1024;
 export const IMPORT_MAX_FILES = 3600;
 export function toRunEntry(spec, outcome, runError, startedAt, ordinal, redact) {
-    // Mirrors the cloud runner's redact_result: the spec types the secret into the
-    // page, so error text and the DOM snapshot can echo it back — scrub before the
-    // bytes leave this machine. Frames and screenshots are pixels; nothing to scrub.
-    const scrub = (text) => (redact ? text.split(redact).join("***") : text);
-    const scrubBytes = (bytes) => redact && bytes.includes(redact)
-        ? Buffer.from(bytes.toString("utf8").split(redact).join("***"), "utf8")
+    // Mirrors the cloud runner's redact_result: the spec types secrets into the page
+    // and an injected session authenticates its requests, so error text and the DOM
+    // snapshot can echo them back — scrub before the bytes leave this machine. Frames
+    // and screenshots are pixels; nothing to scrub.
+    const values = (Array.isArray(redact) ? redact : [redact]).filter((v) => Boolean(v));
+    const scrub = (text) => values.reduce((out, v) => out.split(v).join("***"), text);
+    const scrubBytes = (bytes) => values.some((v) => bytes.includes(v))
+        ? Buffer.from(scrub(bytes.toString("utf8")), "utf8")
         : bytes;
     const completedAt = new Date().toISOString();
     const base = {
@@ -129,6 +131,30 @@ export function buildImportForm(entries, opts) {
     }
     return form;
 }
+/** Establish (or reuse) an account's proven session server-side — the same establish a
+ *  cloud run's setup phase does, so one sign-in serves cloud and local alike. */
+export async function establishAccountSession(client, projectBase, accountId) {
+    let res;
+    try {
+        res = (await client.request("POST", `${projectBase}/test-accounts/${accountId}/session`));
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    if (res.ok && res.storage_state) {
+        return {
+            session: {
+                storageState: res.storage_state,
+                initScripts: res.init_scripts ?? [],
+                secrets: res.secrets ?? [],
+            },
+        };
+    }
+    return {
+        error: res.error ?? "SESSION_UNAVAILABLE",
+        unsupported: Boolean(res.unsupported),
+    };
+}
 /**
  * Run one rendered spec on this machine with its full service harness: write the
  * inbox/login sidecars and pump `await_email` requests over the API while Playwright
@@ -158,7 +184,18 @@ export async function executeLocalSpec(deps, opts) {
             testName: spec.title,
             dir: opts.dir,
             harvest: opts.harvest,
-            redact: spec.usesLoginPassword ? opts.loginPassword : undefined,
+            redact: [
+                ...(spec.usesLoginPassword && opts.loginPassword ? [opts.loginPassword] : []),
+                ...(opts.session?.secrets ?? []),
+            ],
+            ...(opts.session
+                ? {
+                    authSession: {
+                        storageState: opts.session.storageState,
+                        initScripts: opts.session.initScripts,
+                    },
+                }
+                : {}),
             setup: inbox || (spec.usesLoginPassword && opts.loginPassword !== undefined)
                 ? (runDir) => {
                     if (inbox)

package/dist/local-run.js

@@ -21,12 +21,20 @@ const ISOLATING_CONFIG = (testDir, artifactsDir) => `import { defineConfig } fro
     `  outputDir: ${JSON.stringify(artifactsDir)},\n` +
     `  fullyParallel: false,\n` +
     `});\n`;
+export function scrubText(text, redact) {
+    let out = text;
+    for (const value of redact ?? []) {
+        if (value)
+            out = out.split(value).join("***");
+    }
+    return out;
+}
 export function copyTextScrubbed(src, dest, redact) {
-    if (!redact) {
+    if (!redact?.length) {
         fs.copyFileSync(src, dest);
         return;
     }
-    fs.writeFileSync(dest, fs.readFileSync(src, "utf8").split(redact).join("***"));
+    fs.writeFileSync(dest, scrubText(fs.readFileSync(src, "utf8"), redact));
 }
 const PASSING = new Set(["passed", "expected"]);
 const SKIPPED = new Set(["skipped"]);
@@ -224,8 +232,18 @@ export async function runSpecLocally(opts) {
     // ephemeral run dir.
     const outDir = opts.dir ? path.resolve(opts.dir) : runDir;
     fs.mkdirSync(outDir, { recursive: true });
+    let specContent = opts.spec;
+    if (opts.authSession) {
+        // Mirror the cloud runner's staging: write the session files into the workdir and
+        // point the spec's storageState reference at the absolute path (auth-init.json is
+        // read relative to cwd, which is the run dir — same as the cloud workdir).
+        const storagePath = path.join(runDir, "auth-state.json");
+        fs.writeFileSync(storagePath, opts.authSession.storageState, "utf8");
+        fs.writeFileSync(path.join(runDir, "auth-init.json"), JSON.stringify(opts.authSession.initScripts), "utf8");
+        specContent = specContent.split('"auth-state.json"').join(JSON.stringify(storagePath));
+    }
     const specPath = path.join(runDir, "beryl-local.spec.ts");
-    fs.writeFileSync(specPath, opts.spec);
+    fs.writeFileSync(specPath, specContent);
     const configPath = path.join(runDir, "beryl-local.config.ts");
     const artifactsDir = path.join(outDir, "artifacts");
     fs.writeFileSync(configPath, ISOLATING_CONFIG(runDir, artifactsDir));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.21.4",
+  "version": "0.24.0",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",