@beryl-so/cli 0.6.0 → 0.8.0

package/README.md

@@ -26,6 +26,10 @@ npx @beryl-so/cli@latest …    # or run one-off without installing
 
 From the monorepo (development): `cd cli && npm install && npm run build && npm link`.
 
+`beryl init` and `beryl mcp` warn (stderr, best-effort) when the running CLI is behind the
+latest npm release — a stale MCP server silently exposes fewer tools. Set
+`BERYL_NO_UPDATE_CHECK=1` to opt out.
+
 ## Authenticate
 
 ```bash
@@ -251,11 +255,14 @@ Manage the variables, secrets, and files the agent can use while exploring and r
 | --- | --- | --- |
 | `beryl config vars list` | List the project's config variables (visible to the agent during runs) | `config_vars_list` |
 | `beryl config vars set <key> <value>` | Create or update a config variable | `config_vars_set` |
+| `beryl config vars get <key>` | Show one config variable | `config_vars_get` |
 | `beryl config vars delete <key>` | Delete a config variable | `config_vars_delete` |
 | `beryl config secrets list` | List the project's secrets (values are never returned) | `config_secrets_list` |
 | `beryl config secrets set <key> <value>` | Create a secret (write-only; re-setting a key replaces it) | `config_secrets_set` |
+| `beryl config secrets get <key>` | Show one secret's metadata (the value is never returned) | `config_secrets_get` |
 | `beryl config secrets delete <key>` | Delete a secret | `config_secrets_delete` |
 | `beryl config files list` | List files uploaded for the agent to use (e.g. CSVs, upload fixtures) | `config_files_list` |
+| `beryl config files get <file>` | Show one uploaded file's metadata | `config_files_get` |
 | `beryl config files upload <file>` | Upload a file | `config_files_upload` |
 | `beryl config files download <file-id>` | Get a short-lived download URL for a file | `config_files_download` |
 | `beryl config files delete <file-id>` | Delete an uploaded file | `config_files_delete` |
@@ -307,6 +314,7 @@ Disposable email inboxes for testing flows that send mail — signups, OTPs, rec
 | Command | Summary | MCP tool |
 | --- | --- | --- |
 | `beryl inbox create` | Mint a disposable email inbox that Beryl receives mail for | `inbox_create` |
+| `beryl inbox list` | List the workspace's inboxes, newest first | `inbox_list` |
 | `beryl inbox read <inbox-id>` | Read the latest email from an inbox (waits for one to arrive) | `inbox_read` |
 | `beryl inbox emails <inbox-id>` | List the emails an inbox has received | `inbox_emails` |
 

package/dist/adapters/cli.js

@@ -1,10 +1,10 @@
-import fs from "node:fs";
 import { loadConfig } from "../config.js";
 import { createContext } from "../context.js";
 import { CliError, EXIT_OK, EXIT_USAGE, UsageError } from "../errors.js";
 import { ApiClient } from "../http.js";
 import { autoFormat, bold, cyan, dim } from "../output.js";
 import { commandGroups, findCommand, groupSummary } from "../registry/index.js";
+import { cliVersion } from "../version-check.js";
 import { mcpToolFor } from "./mcp.js";
 export const GLOBAL_FLAGS = [
     { name: "version", description: "Print the CLI version and exit", alias: "V" },
@@ -13,15 +13,6 @@ export const GLOBAL_FLAGS = [
     { name: "token", description: "Personal access token (overrides config/BERYL_API_KEY)", value: true },
     { name: "help", description: "Show help", alias: "h" },
 ];
-export function cliVersion() {
-    try {
-        const pkg = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
-        return pkg.version;
-    }
-    catch {
-        return "unknown";
-    }
-}
 export function parseArgv(spec, tokens) {
     const flags = {};
     const positional = [];
@@ -222,21 +213,47 @@ function groupHelp(group, specs) {
     lines.push("", `Run ${cyan(`beryl ${group} <subcommand> --help`)} for details.`);
     return lines.join("\n");
 }
+// Whether argv[i] is a recognised global flag, and how many tokens it spans (2 when it
+// takes its value from the next token, 1 for boolean/alias/inline `--name=value` forms).
+function globalFlagSpan(argv, i) {
+    const tok = argv[i];
+    const eq = tok.indexOf("=");
+    const name = (eq === -1 ? tok : tok.slice(0, eq)).replace(/^--?/, "");
+    const flag = GLOBAL_FLAGS.find((g) => (tok.startsWith("--") ? g.name === name : "alias" in g && g.alias === name));
+    if (!flag)
+        return 0;
+    return "value" in flag && flag.value && eq === -1 ? 2 : 1;
+}
 export async function runCli(argv) {
+    // Global flags are position-independent: collect command words by skipping over
+    // recognised global flags (leaving them in place for parseArgv), and stop only at a
+    // flag we don't recognise as global — that one belongs to the command.
     const words = [];
-    let rest = argv;
-    for (const tok of argv) {
-        if (tok.startsWith("-"))
+    const wordIndices = [];
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === "--")
             break;
+        if (tok.startsWith("-") && tok !== "-") {
+            const span = globalFlagSpan(argv, i);
+            if (span === 0)
+                break;
+            i += span - 1;
+            continue;
+        }
         words.push(tok);
+        wordIndices.push(i);
     }
-    if (argv.includes("--version") || argv.includes("-V") || argv[0] === "version") {
+    let rest = argv;
+    let restWordIndices = wordIndices;
+    if (argv.includes("--version") || argv.includes("-V") || words[0] === "version") {
         process.stdout.write(cliVersion() + "\n");
         return EXIT_OK;
     }
     if (words[0] === "help") {
         words.shift();
         rest = [...words, "--help"];
+        restWordIndices = words.map((_, i) => i);
     }
     if (words.length === 0) {
         process.stdout.write(rootHelp() + "\n");
@@ -266,7 +283,10 @@ export async function runCli(argv) {
         return EXIT_USAGE;
     }
     const { spec } = found;
-    const tokens = rest.slice(found.consumed);
+    // Drop the consumed command words wherever they sit — global flags before or between
+    // them stay in place for parseArgv.
+    const consumedIndices = new Set(restWordIndices.slice(0, found.consumed));
+    const tokens = rest.filter((_, i) => !consumedIndices.has(i));
     let parsed;
     try {
         parsed = parseArgv(spec, tokens);

package/dist/adapters/mcp.js

@@ -4,7 +4,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { createContext } from "../context.js";
 import { CliError } from "../errors.js";
 import { commands } from "../registry/index.js";
-import { cliVersion } from "./cli.js";
+import { cliVersion, warnIfStale } from "../version-check.js";
 export function toolName(spec) {
     return spec.name.replace(/ /g, "_").replace(/-/g, "_");
 }
@@ -72,6 +72,9 @@ function toInput(spec, params) {
     return { args, flags };
 }
 export async function serveMcp(baseCtx) {
+    // Fire-and-forget staleness warning: a stale MCP server silently exposes fewer
+    // tools, and stderr is the one channel a stdio MCP server can safely log to.
+    void warnIfStale(cliVersion(), (msg) => console.error(msg));
     const server = new Server({ name: "beryl", version: cliVersion() }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, () => ({
         tools: mcpTools().map((spec) => ({

package/dist/beryl-test-skill.js

@@ -5,6 +5,40 @@
 // the CLI and another in the docs. Edit here; `init` writes it verbatim.
 export const BERYL_TEST_SKILL_FILENAME = "SKILL.md";
 export const BERYL_TEST_SKILL_DIR = "beryl-test";
+// The example plan the skill shows verbatim. Exported so the test suite lints it with
+// 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: "expect",
+            expect_kind: "have_text",
+            selector: "h1",
+            expect_text: "Pricing",
+        },
+        { action: "expect", expect_kind: "visible", selector: "text=Pro plan" },
+    ],
+};
+// The OTP/signup example the skill shows verbatim (§5). Exported so the test suite lints
+// it with lintPlan, same as the minimal example — the documented await_email shape must
+// 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: "fill", selector: "input[name=email]", value: "{{inbox_address}}" },
+        { action: "click", selector: "button[type=submit]" },
+        {
+            action: "await_email",
+            extract: "code",
+            subject_contains: "verification code",
+            capture_as: "otp",
+            wait_s: 45,
+        },
+        { action: "fill", selector: "input[name=code]", value: "{{otp}}" },
+        { action: "click", selector: "text=Verify" },
+        { action: "expect", expect_kind: "visible", selector: "text=Welcome" },
+    ],
+};
 export const BERYL_TEST_SKILL = `---
 name: beryl-test
 description: Author durable, healable end-to-end tests for a web app with Beryl. Use when writing, running, or fixing a Beryl test locally with your own coding agent — drafting the plan over the Playwright MCP, writing the natural-language intent, and running it with \`beryl runs local\`.
@@ -33,6 +67,28 @@ assertion**, a strong **natural-language intent**, and the **local run-fix loop*
    - **at least one step is an \`expect\`** (a test that asserts nothing is not a test).
    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.
+
+   An \`expect\` step's shape is \`{action: "expect", expect_kind, selector, expect_text}\`:
+   - \`expect_kind\` (required) is one of \`visible\`, \`attached\`, \`hidden\`, \`checked\`,
+     \`enabled\`, \`disabled\`, \`have_text\`, \`have_value\`, \`have_url\`, \`have_title\`,
+     \`have_count\`, \`persisted\`, \`gone\`, \`count_delta\`.
+   - \`selector\` is required for every kind except the page-level \`have_url\` /
+     \`have_title\` (those assert on the page, not an element).
+   - \`expect_text\` carries the expected string for \`have_text\` / \`have_value\` (exact
+     match on the element) and \`have_url\` / \`have_title\` (substring match on the page).
+     There is no \`value\` field on an expect and no bare \`text\` / \`url\` kind.
+   - Two kinds take other fields instead: \`have_count\` needs \`expect_count\`, and
+     \`count_delta\` needs \`capture_ref\` + \`expect_delta\` (vs a baseline banked by an
+     earlier \`capture_count\` step).
+
+   A fully valid minimal plan ("the pricing page renders"):
+
+   \`\`\`json
+${JSON.stringify(BERYL_TEST_SKILL_EXAMPLE_PLAN, null, 2)
+    .split("\n")
+    .map((line) => `   ${line}`)
+    .join("\n")}
+   \`\`\`
 3. **Validate offline, then create:**
    \`\`\`
    beryl tests lint --file plan.json        # check the plan against the schema, no network
@@ -60,8 +116,15 @@ observable proof the flow worked. Get this right and everything else follows.
   "the URL is /pricing" passes even on a blank or broken page that never rendered.
   Reserve a URL-only assertion for when the URL *is* the outcome (a form that lands on
   \`/thank-you\`) and no distinctive destination content is available.
-- \`expect\` kinds: \`text\` (a string is visible), \`url\` (the URL contains a value), \`gone\`
-  (an element disappeared — e.g. a spinner, or the item you just deleted).
+- The usual outcome kinds: \`visible\` (the success element showed up), \`have_text\` (an
+  element's text matches), \`have_url\` (the URL contains a value), \`gone\` (an element
+  disappeared — e.g. a spinner, or the item you just deleted). §1 has the full
+  \`expect_kind\` list and the step shape.
+- **\`have_text\` is an EXACT full-text match on the selector's element** — asserting
+  \`have_text: "Documentation"\` on \`body\` fails, because \`body\`'s text includes all the
+  nav chrome. Target the specific element that carries the text (the \`h1\`, the toast),
+  or assert the page instead (\`have_title\`, which is a substring match). To check "this
+  string is visible somewhere", use \`expect_kind: "visible"\` with a \`text=…\` selector.
 - **If you can't name a success signal, the flow is not test-worthy.** Don't bank a test
   that verifies nothing. Explore a different flow instead.
 - **Don't work around a real app failure to make a test go green.** If the flow is
@@ -133,4 +196,52 @@ beryl runs local <test-id> --url-override http://localhost:3000 --dir ./beryl-lo
 
 Once the test passes locally against a real outcome, it's ready to bank and let Beryl run
 and heal it.
+
+## 5. Testing an OTP / signup flow (\`await_email\`)
+
+A flow that emails the user — a signup verification code, a magic sign-in link, a receipt
+— is testable with the \`await_email\` action. Beryl mints a **run-scoped inbox**
+automatically whenever a plan contains an \`await_email\` step (or cites
+\`{{inbox_address}}\`): no setup, no environment configuration, no flag to turn on. The
+minted address is in scope from step 1 as the reserved \`{{inbox_address}}\` handle.
+
+The wiring is a three-part chain:
+
+1. **Type the minted address into the app** — a \`fill\` with \`value: "{{inbox_address}}"\`.
+   Every run gets a fresh address, so a signup flow is repeatable by construction (no
+   \`{{unique}}\` needed for the email itself; use \`{{unique}}\` for other must-not-collide
+   values like a username).
+2. **Await the mail and bank the extracted value** — an \`await_email\` step with:
+   - \`extract\` (required): \`code\` (an OTP), \`link\` (the sign-in/verify URL), or
+     \`pattern\` (your own regex in \`extract_pattern\`, exactly one capture group).
+   - \`capture_as\` (required): the handle name the extracted string is banked under.
+   - \`subject_contains\` / \`from_contains\` (optional): match the right mail when the app
+     sends more than one.
+   - \`wait_s\` (optional, 1–50, default 30): how many seconds the step blocks waiting
+     for the mail to land.
+3. **Use the banked value** — cite \`{{<capture_as>}}\` in a later step's \`value\` (fill the
+   code) or \`url\` (goto the magic link). A captured handle is legal **only** in
+   \`value\`/\`url\`; in a \`selector\`, \`option\`, or \`expect_text\` it would be used as
+   literal text, and the linter rejects it there.
+
+A fully valid signup-with-OTP plan:
+
+\`\`\`json
+${JSON.stringify(BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN, null, 2)}
+\`\`\`
+
+For a magic-link flow, replace the code steps with
+\`{ "action": "await_email", "extract": "link", "capture_as": "signin_link" }\` followed by
+\`{ "action": "goto", "url": "{{signin_link}}" }\`.
+
+Two caveats:
+
+- \`beryl tests create\` verifies an \`await_email\` plan like any other — the replay mints
+  its own inbox, so the app's mail really is received and extracted before the test is
+  accepted. (Note the replay signs up / sends mail for real; pass \`--no-verify\` only if
+  that side effect is unwanted.) \`runs local\` cannot serve \`await_email\` — the inbox
+  lives in Beryl's cloud — so iterate on these flows with
+  \`beryl runs trigger --test <id> --watch\`.
+- The outcome assertion discipline from §1 still applies: the green signal is the
+  post-verification state (the welcome screen, the dashboard), not "an email arrived".
 `;

package/dist/commands/config-vars.js

@@ -3,13 +3,16 @@ import path from "node:path";
 import { UsageError } from "../errors.js";
 import { arg, flagBool, flagStr, projectPath } from "./util.js";
 const configPath = (ws, p) => `${projectPath(ws, p)}/config`;
-async function resolveByKey(rows, value, kind) {
+function findByKey(rows, value, kind) {
     const byId = rows.find((r) => r.id === value);
     if (byId)
-        return byId.id;
+        return byId;
     const byKey = rows.filter((r) => r.key === value);
     if (byKey.length === 1)
-        return byKey[0].id;
+        return byKey[0];
+    if (byKey.length > 1) {
+        throw new UsageError(`Multiple ${kind}s have key "${value}" (per-environment copies) — use the id instead`);
+    }
     throw new UsageError(`No ${kind} with key or id "${value}"`);
 }
 export const configCommands = [
@@ -51,17 +54,30 @@ export const configCommands = [
             };
         },
     },
+    {
+        name: "config vars get",
+        summary: "Show one config variable",
+        scope: "project",
+        args: [{ name: "key", description: "Variable key or id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const rows = (await ctx.client.get(`${configPath(workspaceId, projectId)}/variables`));
+            return { data: findByKey(rows, arg(input, "key"), "variable") };
+        },
+    },
     {
         name: "config vars delete",
         summary: "Delete a config variable",
         scope: "project",
         args: [{ name: "key", description: "Variable key or id", required: true }],
+        flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             const base = `${configPath(workspaceId, projectId)}/variables`;
             const rows = (await ctx.client.get(base));
-            const id = await resolveByKey(rows, arg(input, "key"), "variable");
-            await ctx.client.del(`${base}/${id}`);
+            const row = findByKey(rows, arg(input, "key"), "variable");
+            await ctx.confirm(`Delete config variable ${row.key}?`, flagBool(input, "force"));
+            await ctx.client.del(`${base}/${row.id}`);
             return { human: "Deleted." };
         },
     },
@@ -94,17 +110,30 @@ export const configCommands = [
             return { data: await ctx.client.post(base, { key, value, environment_id: envId }) };
         },
     },
+    {
+        name: "config secrets get",
+        summary: "Show one secret's metadata (the value is never returned)",
+        scope: "project",
+        args: [{ name: "key", description: "Secret key or id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const rows = (await ctx.client.get(`${configPath(workspaceId, projectId)}/secrets`));
+            return { data: findByKey(rows, arg(input, "key"), "secret") };
+        },
+    },
     {
         name: "config secrets delete",
         summary: "Delete a secret",
         scope: "project",
         args: [{ name: "key", description: "Secret key or id", required: true }],
+        flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             const base = `${configPath(workspaceId, projectId)}/secrets`;
             const rows = (await ctx.client.get(base));
-            const id = await resolveByKey(rows, arg(input, "key"), "secret");
-            await ctx.client.del(`${base}/${id}`);
+            const row = findByKey(rows, arg(input, "key"), "secret");
+            await ctx.confirm(`Delete secret ${row.key}?`, flagBool(input, "force"));
+            await ctx.client.del(`${base}/${row.id}`);
             return { human: "Deleted." };
         },
     },
@@ -117,6 +146,27 @@ export const configCommands = [
             return { data: await ctx.client.get(`${configPath(workspaceId, projectId)}/files`) };
         },
     },
+    {
+        name: "config files get",
+        summary: "Show one uploaded file's metadata",
+        scope: "project",
+        args: [{ name: "file", description: "File name or id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const rows = (await ctx.client.get(`${configPath(workspaceId, projectId)}/files`));
+            const value = arg(input, "file");
+            const byId = rows.find((r) => r.id === value);
+            if (byId)
+                return { data: byId };
+            const byName = rows.filter((r) => r.name === value);
+            if (byName.length === 1)
+                return { data: byName[0] };
+            if (byName.length > 1) {
+                throw new UsageError(`Multiple files are named "${value}" (per-environment copies) — use the id instead`);
+            }
+            throw new UsageError(`No file with name or id "${value}"`);
+        },
+    },
     {
         name: "config files upload",
         summary: "Upload a file",
@@ -126,8 +176,18 @@ export const configCommands = [
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             const file = arg(input, "file");
+            let bytes;
+            try {
+                bytes = new Uint8Array(fs.readFileSync(file));
+            }
+            catch (err) {
+                const code = err.code;
+                if (code === "ENOENT")
+                    throw new UsageError(`file not found: ${file}`);
+                throw new UsageError(`cannot read ${file} (${code ?? err.message})`);
+            }
             const form = new FormData();
-            form.set("file", new Blob([fs.readFileSync(file)]), path.basename(file));
+            form.set("file", new Blob([bytes]), path.basename(file));
             const envId = flagStr(input, "env");
             if (envId)
                 form.set("environment_id", envId);

package/dist/commands/inboxes.js

@@ -53,6 +53,18 @@ export const inboxCommands = [
             };
         },
     },
+    {
+        name: "inbox list",
+        summary: "List the workspace's inboxes, newest first",
+        description: "Every inbox the workspace has minted with `beryl inbox create`. Expired inboxes " +
+            "stop receiving and are hard-deleted by a background sweep, so they drop off " +
+            "this list shortly after their TTL.",
+        scope: "workspace",
+        async run(ctx, input) {
+            const ws = await ctx.requireWorkspace(input);
+            return { data: await ctx.client.get(`/workspaces/${ws}/inboxes`) };
+        },
+    },
     {
         name: "inbox read",
         summary: "Read the latest email from an inbox (waits for one to arrive)",

package/dist/commands/init.js

@@ -1,19 +1,29 @@
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
+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 { LOCAL_CONFIG_FILENAME, loadConfig } from "../config.js";
 import { CliError, UsageError } from "../errors.js";
 import { ApiClient } from "../http.js";
-import { bold, cyan, dim, green } from "../output.js";
+import { bold, cyan, dim, green, yellow } from "../output.js";
+import { cliVersion, warnIfStale } from "../version-check.js";
 import { authCommands } from "./auth.js";
 import { flagBool, flagStr } from "./util.js";
+// Pinned to @latest (like the Playwright entry below) — an unpinned spec lets npx
+// serve whatever stale global/cache install already resolves, so the agent's MCP
+// server would silently miss newer tools. mergeMcpConfig compares entries verbatim,
+// so re-running init also upgrades an old unpinned entry in place.
 const MCP_SERVER_ENTRY = {
     command: "npx",
-    args: ["-y", "@beryl-so/cli", "mcp"],
+    args: ["-y", "@beryl-so/cli@latest", "mcp"],
 };
+// Headless: the coding agent drives this browser to author tests — nobody watches the
+// window, and a headed default breaks on CI / headless boxes. Matches how most devs
+// already wire their own user-scoped playwright.
 const PLAYWRIGHT_SERVER_ENTRY = {
     command: "npx",
-    args: ["@playwright/mcp@latest"],
+    args: ["@playwright/mcp@latest", "--headless"],
 };
 const ACTION_PLAN_SCHEMA_URL = "https://api.beryl.so/api/v1/schemas/action-plan.schema.json";
 // The authoring fork only appears when we create a fresh project with no tests yet; an
@@ -71,6 +81,36 @@ function mergeMcpConfig(file, withPlaywright) {
     }
     return { beryl, playwright };
 }
+// A tool's config lives per-user (same as the PAT it needs, in ~/.config/beryl) — so wire the
+// MCP servers per-user too, not in a committed .mcp.json that 401s for every teammate until
+// they run `beryl login` anyway. We DON'T hand-edit ~/.claude.json (Claude Code owns it; a
+// corrupt write breaks the user's whole CLI) — we shell out to `claude mcp add` and let Claude
+// own the edit. Returns false when the `claude` binary isn't on PATH so the caller can fall
+// back to a copy-paste command.
+function claudeUserAdd(name, entry) {
+    try {
+        execFileSync("claude", ["mcp", "add", name, "-s", "user", "--", entry.command, ...entry.args], {
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch (err) {
+        // A non-zero exit ALSO covers "already exists" — but so does a missing binary. Distinguish:
+        // ENOENT means no `claude` on PATH (fall back), anything else means it ran and declined
+        // (already configured — treat as success, nothing to do).
+        if (err.code === "ENOENT")
+            return false;
+        return true;
+    }
+}
+function claudeAddHint(name, entry) {
+    return `claude mcp add ${name} -s user -- ${entry.command} ${entry.args.join(" ")}`;
+}
+// ~/.cursor/mcp.json is Cursor's user-scope config — small and ours to write safely, unlike
+// ~/.claude.json — so we merge it directly rather than shelling out.
+function cursorUserConfigPath() {
+    return path.join(os.homedir(), ".cursor", "mcp.json");
+}
 function detectEditors(cwd) {
     const editors = [];
     if (fs.existsSync(path.join(cwd, ".claude")) || fs.existsSync(path.join(cwd, "CLAUDE.md")))
@@ -103,9 +143,11 @@ export const initCommands = [
         name: "init",
         summary: "Set up Beryl in this repo — sign in, pin a project, wire up your coding agent",
         description: "One-command onboarding: signs you in (emailed one-time code), pins this repo to a " +
-            "workspace and project via .beryl.json (offering to create the project), and writes the " +
-            "MCP server config for your coding agent (.mcp.json for Claude Code, .cursor/mcp.json for " +
-            "Cursor). When creating a fresh project it asks how you want to author tests — locally with " +
+            "workspace and project via .beryl.json (offering to create the project), and wires the " +
+            "MCP servers for your coding agent. By default they're wired per-user (matching where your " +
+            "login token lives) — via `claude mcp add -s user` for Claude Code, ~/.cursor/mcp.json for " +
+            "Cursor; pass --scope project to write a committed .mcp.json for a shared repo instead. " +
+            "When creating a fresh project it asks how you want to author tests — locally with " +
             "your own coding agent or by hand (the default), or by letting Beryl's agent explore and " +
             "author them for you. Safe to re-run; every step skips what is already set up.",
         interactive: true,
@@ -133,6 +175,15 @@ export const initCommands = [
                 description: "Which coding agent to write MCP config for (default: auto-detect)",
             },
             { name: "no-pin", type: "boolean", description: "Skip writing .beryl.json" },
+            {
+                name: "scope",
+                type: "string",
+                enum: ["user", "project"],
+                description: "Where to wire the MCP servers. `user` (default) configures them per-user (matching " +
+                    "where your Beryl login token lives) via `claude mcp add -s user` / ~/.cursor/mcp.json. " +
+                    "`project` writes a committed .mcp.json for a shared repo — every teammate still runs " +
+                    "`beryl login` to authenticate",
+            },
             {
                 name: "local",
                 type: "boolean",
@@ -144,6 +195,7 @@ export const initCommands = [
         examples: [
             "npx @beryl-so/cli@latest init",
             "beryl init --editor-tools claude-code",
+            "beryl init --scope project",
             "beryl init --project https://app.example.com --authoring agent",
             "beryl init --project https://app.example.com --authoring local --editor-tools none",
         ],
@@ -227,14 +279,35 @@ export const initCommands = [
             // and local authoring needs the Playwright MCP — so default it on. `--no-local` (parsed
             // as an explicit false) opts out.
             const local = input.flags.local ?? editors.length > 0;
+            const scope = (flagStr(input, "scope") ?? "user");
             for (const editor of editors) {
+                if (scope === "user" && editor === "claude-code") {
+                    // Claude Code owns ~/.claude.json — shell out to `claude mcp add` rather than write it.
+                    const berylOk = claudeUserAdd("beryl", MCP_SERVER_ENTRY);
+                    const playwrightOk = local ? claudeUserAdd("playwright", PLAYWRIGHT_SERVER_ENTRY) : undefined;
+                    if (berylOk) {
+                        ctx.err(`${green("✓")} claude-code MCP configured ${dim("(user scope)")}`);
+                        if (playwrightOk)
+                            ctx.err(`${green("✓")} claude-code Playwright MCP configured ${dim("(user scope)")}`);
+                    }
+                    else {
+                        ctx.err(yellow("• `claude` not on PATH — run these to wire user-scope MCP servers:"));
+                        ctx.err(`    ${cyan(claudeAddHint("beryl", MCP_SERVER_ENTRY))}`);
+                        if (local)
+                            ctx.err(`    ${cyan(claudeAddHint("playwright", PLAYWRIGHT_SERVER_ENTRY))}`);
+                    }
+                    continue;
+                }
                 const file = editor === "claude-code"
                     ? path.join(cwd, ".mcp.json")
-                    : path.join(cwd, ".cursor", "mcp.json");
+                    : scope === "user"
+                        ? cursorUserConfigPath()
+                        : path.join(cwd, ".cursor", "mcp.json");
                 const wrote = mergeMcpConfig(file, local);
-                ctx.err(`${green("✓")} ${editor} MCP ${wrote.beryl ? "configured" : "already configured"} ${dim(path.relative(cwd, file))}`);
+                const where = scope === "user" ? file : path.relative(cwd, file);
+                ctx.err(`${green("✓")} ${editor} MCP ${wrote.beryl ? "configured" : "already configured"} ${dim(where)}`);
                 if (wrote.playwright !== undefined)
-                    ctx.err(`${green("✓")} ${editor} Playwright MCP ${wrote.playwright ? "configured" : "already configured"} ${dim(path.relative(cwd, file))}`);
+                    ctx.err(`${green("✓")} ${editor} Playwright MCP ${wrote.playwright ? "configured" : "already configured"} ${dim(where)}`);
             }
             if (choice === "auto" && editors.length === 0)
                 ctx.err(dim("No coding agent detected — pass --editor-tools claude-code|cursor to wire one."));
@@ -263,6 +336,9 @@ export const initCommands = [
                         ? `\n\nPlaywright MCP is wired — your coding agent can explore the site locally ` +
                             `and push tests with ${cyan("beryl tests create")}.`
                         : "");
+            // The .mcp.json entry is pinned to @latest, but a global install / old npx cache
+            // still wins resolution — so tell the user when the CLI they just ran is stale.
+            await warnIfStale(cliVersion(), (msg) => ctx.err(yellow(msg)));
             return {
                 data: { workspace: workspaceId ?? null, project: projectId ?? null, editors },
                 human: nextSteps,

package/dist/commands/tests.js

@@ -1,9 +1,23 @@
 import fs from "node:fs";
 import { UsageError } from "../errors.js";
 import { lintPlan } from "../lint.js";
+import { table } from "../output.js";
 import { ACTION_PLAN_SCHEMA } from "../schema.generated.js";
 import { arg, argList, flagBool, flagNum, flagStr, projectPath, readJsonFlag } from "./util.js";
 const testPath = (ws, p, id) => `${projectPath(ws, p)}/tests/${id}`;
+// The concise human table for `tests list` — the full TestResponse is a 24-column
+// firehose of internal ids that wraps unreadably in a normal terminal. `--wide`
+// (and `--json`) still expose every field.
+const LIST_COLUMNS = ["title", "status", "id", "last_result_status", "last_run_at"];
+function conciseTestRow(row) {
+    return {
+        title: row.nl_title,
+        status: row.quarantined ? "quarantined" : row.is_active ? "active" : "inactive",
+        id: row.id,
+        last_result_status: row.last_result_status,
+        last_run_at: row.last_run_at,
+    };
+}
 export const testCommands = [
     {
         name: "tests lint",
@@ -33,17 +47,24 @@ export const testCommands = [
     {
         name: "tests list",
         summary: "List the project's tests with their latest result",
+        description: "Prints a concise table by default (title / status / id / last result / last run). " +
+            "Pass --wide for every field, or --json for the raw records.",
         scope: "project",
         groupDefault: true,
         groupSummary: "Author, inspect, version, and heal a project's tests — the checks Beryl runs on each run.",
-        flags: [{ name: "env", type: "string", description: "Filter by environment id" }],
+        flags: [
+            { name: "env", type: "string", description: "Filter by environment id" },
+            { name: "wide", type: "boolean", description: "Show all columns, not the concise default" },
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            return {
-                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests`, {
-                    environment_id: flagStr(input, "env"),
-                }),
-            };
+            const data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests`, {
+                environment_id: flagStr(input, "env"),
+            }));
+            if (flagBool(input, "wide"))
+                return { data };
+            // `data` stays the full records so --json is unchanged; only the human table is trimmed.
+            return { data, human: table(data.map(conciseTestRow), LIST_COLUMNS) };
         },
     },
     {

package/dist/commands/util.js

@@ -29,11 +29,24 @@ export function flagNum(input, name) {
         throw new UsageError(`--${name} must be a number`);
     return n;
 }
+/** Read a local file for a flag/arg, turning fs errors (ENOENT, EACCES, EISDIR…) into a
+ *  clean usage message instead of a raw Node stack. */
+export function readFileArg(path, label) {
+    try {
+        return fs.readFileSync(path === "-" ? 0 : path, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            throw new UsageError(`${label}: file not found: ${path}`);
+        throw new UsageError(`${label}: cannot read ${path} (${code ?? err.message})`);
+    }
+}
 export function readJsonFlag(input, name) {
     const file = flagStr(input, name);
     if (!file)
         throw new UsageError(`--${name} <file> is required`);
-    const text = file === "-" ? fs.readFileSync(0, "utf8") : fs.readFileSync(file, "utf8");
+    const text = readFileArg(file, `--${name}`);
     try {
         return JSON.parse(text);
     }

package/dist/version-check.js

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+// Best-effort "are we stale?" check against the npm registry. The `.mcp.json` entry
+// `init` writes pins `@beryl-so/cli@latest`, but a user with a global install (or an
+// old npx cache) can still be running a stale CLI — and an MCP server that's behind
+// silently exposes fewer tools. So `init` and `beryl mcp` warn when the running
+// version is behind the registry's `latest`. Never fatal: offline, a slow registry,
+// or an unparseable response just skips the warning.
+const REGISTRY_LATEST_URL = "https://registry.npmjs.org/@beryl-so/cli/latest";
+const TIMEOUT_MS = 1500;
+export function cliVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return pkg.version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+// Numeric-triple compare; returns true only when `current` is strictly behind
+// `latest`. Anything non-numeric (dev builds, "unknown", dist-tags) compares as
+// not-behind so we never nag on unparseable versions.
+export function isBehind(current, latest) {
+    const parse = (v) => {
+        const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+        return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    };
+    const cur = parse(current);
+    const lat = parse(latest);
+    if (!cur || !lat)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (cur[i] !== lat[i])
+            return cur[i] < lat[i];
+    }
+    return false;
+}
+/** The registry's `latest` version, or null when it can't be fetched quickly. */
+export async function fetchLatestVersion() {
+    try {
+        const res = await fetch(REGISTRY_LATEST_URL, {
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === "string" ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Warn (via `warn`) when `current` is behind the registry's `latest`.
+ * Best-effort and quiet on any failure — safe to await on every startup.
+ * BERYL_NO_UPDATE_CHECK=1 opts out entirely (no network call).
+ */
+export async function warnIfStale(current, warn) {
+    if (process.env.BERYL_NO_UPDATE_CHECK)
+        return;
+    const latest = await fetchLatestVersion();
+    if (latest && isBehind(current, latest)) {
+        warn(`@beryl-so/cli ${current} is behind the latest release ${latest} — ` +
+            `some commands/MCP tools may be missing. Upgrade with: npm i -g @beryl-so/cli@latest`);
+    }
+}

package/package.json

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