@beryl-so/cli 0.27.0 → 0.32.0

package/README.md

@@ -191,13 +191,14 @@ Manage a project's environments — the URLs and auth Beryl runs tests against.
 
 ### schedule
 
-View and set the schedule on which Beryl runs a project's tests automatically.
+View and set the schedule on which Beryl runs a project's tests automatically — the whole project, or one group with --group.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl schedule get` | Show the project's daily/weekly run schedule | `schedule_get` |
+| `beryl schedule get` | Show the project's run schedule and any per-group schedules | `schedule_get` |
 | `beryl schedule set` | Enable scheduled runs (daily, or weekly on a given day) | `schedule_set` |
 | `beryl schedule disable` | Turn scheduled runs off | `schedule_disable` |
+| `beryl schedule remove` | Remove a group's schedule entirely (the group itself stays) | `schedule_remove` |
 
 ### tests
 
@@ -214,6 +215,7 @@ Author, inspect, version, and heal a project's tests — the checks Beryl runs o
 | `beryl tests create` | Create a test case from a JSON action plan — for tests authored locally, e.g. by your coding agent | `tests_create` |
 | `beryl tests set-plan <test-id>` | Replace a test's step plan from a JSON file (creates a new version) | `tests_set_plan` |
 | `beryl tests rename <test-id> <title>` | Rename a test | `tests_rename` |
+| `beryl tests set-groups <test-id>` | Replace the groups a test belongs to | `tests_set_groups` |
 | `beryl tests quarantine <test-id> <state>` | Mute a flaky test: it keeps running, but its failures stop failing the run | `tests_quarantine` |
 | `beryl tests delete <test-id>` | Delete a test, its version history, and its results | `tests_delete` |
 | `beryl tests recompile <test-id>` | Validate + verify an edited plan against the live site before persisting | `tests_recompile` |
@@ -227,6 +229,19 @@ Author, inspect, version, and heal a project's tests — the checks Beryl runs o
 | `beryl tests script [test-id]` | Print the rendered Playwright spec for a test (or an unbanked plan file) | `tests_script` |
 | `beryl tests export <test-ids...>` | Export tests as Playwright .spec.ts files in a ZIP | `tests_export` |
 
+### groups
+
+Manage a project's test groups — labels a test can carry any number of, used to filter, run, or schedule a slice of the suite. Groups are created only here (or in Settings → Groups); assigning a test to an unknown name is an error.
+
+`beryl groups` with no subcommand runs `groups list`.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl groups list` | List the project's test groups and how many tests each holds | `groups_list` |
+| `beryl groups create <name>` | Create a group | `groups_create` |
+| `beryl groups rename <group> <name>` | Rename a group (tests keep their membership) | `groups_rename` |
+| `beryl groups delete <group>` | Delete a group — its tests stay, its schedule (if any) goes with it | `groups_delete` |
+
 ### runs
 
 Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and download results.
@@ -245,6 +260,17 @@ Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and downlo
 | `beryl runs download <run-id>` | Download a run's results, with its artifacts, to disk | `runs_download` |
 | `beryl runs explain <result-id>` | Explain, with AI, why a test result failed | `runs_explain` |
 
+### health
+
+Site Health — how your site reads to search engines and visitors: content, speed, mobile, links and security, graded from a real check of your live pages.
+
+`beryl health` with no subcommand runs `health get`.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl health get` | Show the latest Site Health report for a project environment | `health_get` |
+| `beryl health run` | Run a fresh Site Health check for a project environment | `health_run` |
+
 ### explorations
 
 Inspect the agent's exploration runs — how it crawled a site and authored its tests.

package/dist/adapters/cli.js

@@ -4,6 +4,7 @@ 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 { withTool } from "../telemetry.js";
 import { cliVersion } from "../version-check.js";
 import { mcpToolFor } from "./mcp.js";
 export const GLOBAL_FLAGS = [
@@ -324,7 +325,7 @@ export async function runCli(argv) {
     const client = new ApiClient(config.apiUrl, config.token);
     const ctx = createContext({ client, config, json: parsed.json, mcp: false });
     try {
-        const result = (await spec.run(ctx, parsed.input)) ?? {};
+        const result = (await withTool(spec.name, () => spec.run(ctx, parsed.input))) ?? {};
         if (parsed.json) {
             if (result.data !== undefined)
                 process.stdout.write(JSON.stringify(result.data) + "\n");

package/dist/adapters/mcp.js

@@ -1,13 +1,15 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { instrument } from "@posthog/mcp";
 import fs from "node:fs";
 import { loadConfig } from "../config.js";
 import { createContext } from "../context.js";
-import { CliError } from "../errors.js";
-import { ApiClient } from "../http.js";
+import { AuthError, CliError } from "../errors.js";
+import { ApiClient, ApiError } from "../http.js";
 import { parseArgv } from "./cli.js";
 import { commands } from "../registry/index.js";
+import { analyticsOptions, createPostHogClient, setClient, setSurface, shutdownTelemetry, withTool, } from "../telemetry.js";
 import { cliVersion, warnIfStale } from "../version-check.js";
 export function toolName(spec) {
     return spec.name.replace(/ /g, "_").replace(/-/g, "_");
@@ -190,6 +192,48 @@ export function currentAuth(fallback) {
 }
 export function __resetAuthCacheForTests() {
     authCache = undefined;
+    identifyCache = undefined;
+}
+let identifyCache;
+/** Resolves the signed-in account once per token so MCP events land on the same PostHog
+ *  person as that user's webapp sessions. Anonymous (null) when unauthenticated: the
+ *  session is still counted, just not attributed. */
+export function identifyUser(baseCtx) {
+    return async () => {
+        const auth = currentAuth(baseCtx);
+        const cached = identifyCache;
+        if (cached && cached.token === auth.config.token)
+            return cached.identity;
+        let identity = null;
+        if (auth.config.token) {
+            try {
+                const me = (await auth.client.get("/account/"));
+                if (me?.id) {
+                    identity = {
+                        distinctId: me.id,
+                        // Internal dogfooding is stamped rather than dropped: unlike the webapp we
+                        // want our own MCP sessions visible when debugging, so dashboards exclude
+                        // them by cohort instead.
+                        properties: {
+                            email: me.email,
+                            name: me.name,
+                            is_internal: Boolean(me.is_vibemonitor),
+                        },
+                    };
+                }
+            }
+            catch (err) {
+                // A rejected token is a settled answer worth caching; a network blip or a 5xx is
+                // not. This server outlives the blip, so caching one would leave every later tool
+                // call in the session anonymous with no way back.
+                const settled = err instanceof AuthError || (err instanceof ApiError && err.status < 500);
+                if (!settled)
+                    return null;
+            }
+        }
+        identifyCache = { token: auth.config.token, identity };
+        return identity;
+    };
 }
 // The running version is stated up front because this server is long-lived and never
 // hot-reloads: a session can sit on a days-old build while `@latest` has moved, and
@@ -210,6 +254,7 @@ export function mcpInstructions() {
         "call `guide` before authoring your first test plan.");
 }
 export async function serveMcp(baseCtx) {
+    setSurface("mcp");
     // 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));
@@ -250,7 +295,8 @@ export async function serveMcp(baseCtx) {
             err: push,
         });
         try {
-            const result = (await spec.run(ctx, toInput(spec, request.params.arguments ?? {}))) ?? {};
+            const input = toInput(spec, request.params.arguments ?? {});
+            const result = (await withTool(request.params.name, () => spec.run(ctx, input))) ?? {};
             return toolResult(result, lines);
         }
         catch (err) {
@@ -261,8 +307,25 @@ export async function serveMcp(baseCtx) {
             };
         }
     });
+    server.oninitialized = () => setClient(server.getClientVersion());
+    instrument(server, createPostHogClient(), analyticsOptions(baseCtx.config.apiUrl, identifyUser(baseCtx)));
+    // A coding agent ends an MCP server either by closing the pipe or by signalling it, and
+    // only the first path reaches onclose — without these the last batch of events dies with
+    // the process. Bounded inside shutdownTelemetry, so a wedged flush can't hold up exit.
+    const flushAndExit = (signal) => {
+        void shutdownTelemetry().then(() => {
+            process.kill(process.pid, signal);
+        });
+    };
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.once(signal, () => {
+            process.removeAllListeners(signal);
+            flushAndExit(signal);
+        });
+    }
     await server.connect(new StdioServerTransport());
     await new Promise((resolve) => {
         server.onclose = resolve;
     });
+    await shutdownTelemetry();
 }

package/dist/beryl-test-skill.js

@@ -289,6 +289,9 @@ ${JSON.stringify(BERYL_TEST_SKILL_EXAMPLE_PLAN, null, 2)
    description. Inspect the exact spec with \`beryl tests script --file plan.json\`.
    Full ActionPlan JSON Schema:
    https://api.beryl.so/api/v1/schemas/action-plan.schema.json.
+   Groups are optional and never block: after the test is banked, if \`beryl groups list\`
+   shows any, offer them once (\`tests set-groups <id> --group <name>\`); no answer = leave
+   it ungrouped and move on. Never create a group yourself — that's the user's call.
 
 ### The outcome assertion is the whole game
 

package/dist/commands/environments.js

@@ -1,5 +1,6 @@
 import { UsageError } from "../errors.js";
-import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+import { arg, findGroup, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+const SCHEDULE_GROUP_FLAG = "Schedule one group (by name or id) instead of the whole project; the run covers the group's active tests at fire time";
 export const environmentCommands = [
     {
         name: "envs list",
@@ -92,9 +93,9 @@ export const environmentCommands = [
     },
     {
         name: "schedule get",
-        summary: "Show the project's daily/weekly run schedule",
+        summary: "Show the project's run schedule and any per-group schedules",
         scope: "project",
-        groupSummary: "View and set the schedule on which Beryl runs a project's tests automatically.",
+        groupSummary: "View and set the schedule on which Beryl runs a project's tests automatically — the whole project, or one group with --group.",
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             return { data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/schedule`) };
@@ -115,12 +116,16 @@ export const environmentCommands = [
             { name: "hour", type: "number", description: "Hour of day 0-23" },
             { name: "minute", type: "number", description: "Minute 0-59" },
             { name: "tz", type: "string", description: "IANA timezone (e.g. America/Los_Angeles)" },
+            { name: "group", type: "string", description: SCHEDULE_GROUP_FLAG },
+        ],
+        examples: [
+            "beryl schedule set --frequency daily --hour 6 --tz UTC",
+            "beryl schedule set --group Smoke --frequency weekly --day 0 --hour 9 --tz UTC",
         ],
-        examples: ["beryl schedule set --frequency daily --hour 6 --tz UTC"],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             return {
-                data: await ctx.client.put(`${projectPath(workspaceId, projectId)}/schedule`, {
+                data: await ctx.client.put(await schedulePath(ctx, input, workspaceId, projectId), {
                     enabled: true,
                     frequency: flagStr(input, "frequency") ?? "daily",
                     day_of_week: flagNum(input, "day") ?? null,
@@ -135,13 +140,40 @@ export const environmentCommands = [
         name: "schedule disable",
         summary: "Turn scheduled runs off",
         scope: "project",
+        flags: [{ name: "group", type: "string", description: SCHEDULE_GROUP_FLAG }],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             return {
-                data: await ctx.client.put(`${projectPath(workspaceId, projectId)}/schedule`, {
+                data: await ctx.client.put(await schedulePath(ctx, input, workspaceId, projectId), {
                     enabled: false,
                 }),
             };
         },
     },
+    {
+        name: "schedule remove",
+        summary: "Remove a group's schedule entirely (the group itself stays)",
+        scope: "project",
+        flags: [{ name: "group", type: "string", description: "Group name or id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            if (!flagStr(input, "group"))
+                throw new UsageError("--group is required");
+            await ctx.client.del(await schedulePath(ctx, input, workspaceId, projectId));
+            return { human: "Removed." };
+        },
+    },
 ];
+async function schedulePath(ctx, input, workspaceId, projectId) {
+    const base = `${projectPath(workspaceId, projectId)}/schedule`;
+    const ref = flagStr(input, "group");
+    if (!ref)
+        return base;
+    const groups = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/groups`));
+    const group = findGroup(groups, ref);
+    if (!group) {
+        const names = groups.map((g) => g.name).join(", ") || "none yet";
+        throw new UsageError(`No group '${ref}' in this project (existing: ${names}).`);
+    }
+    return `${projectPath(workspaceId, projectId)}/groups/${group.id}/schedule`;
+}

package/dist/commands/groups.js

@@ -0,0 +1,69 @@
+import { UsageError } from "../errors.js";
+import { arg, findGroup, flagBool, projectPath } from "./util.js";
+async function resolveGroup(ctx, workspaceId, projectId, ref) {
+    const groups = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/groups`));
+    const match = findGroup(groups, ref);
+    if (!match) {
+        const names = groups.map((g) => g.name).join(", ") || "none yet";
+        throw new UsageError(`No group '${ref}' in this project (existing: ${names}).`);
+    }
+    return match;
+}
+export const groupCommands = [
+    {
+        name: "groups list",
+        summary: "List the project's test groups and how many tests each holds",
+        scope: "project",
+        groupDefault: true,
+        groupSummary: "Manage a project's test groups — labels a test can carry any number of, used to filter, run, or schedule a slice of the suite. Groups are created only here (or in Settings → Groups); assigning a test to an unknown name is an error.",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return { data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/groups`) };
+        },
+    },
+    {
+        name: "groups create",
+        summary: "Create a group",
+        scope: "project",
+        args: [{ name: "name", description: "Group name (unique per project)", required: true }],
+        examples: ["beryl groups create Smoke"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.post(`${projectPath(workspaceId, projectId)}/groups`, {
+                    name: arg(input, "name"),
+                }),
+            };
+        },
+    },
+    {
+        name: "groups rename",
+        summary: "Rename a group (tests keep their membership)",
+        scope: "project",
+        args: [
+            { name: "group", description: "Current group name or id", required: true },
+            { name: "name", description: "New name", required: true },
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const group = await resolveGroup(ctx, workspaceId, projectId, arg(input, "group"));
+            return {
+                data: await ctx.client.patch(`${projectPath(workspaceId, projectId)}/groups/${group.id}`, { name: arg(input, "name") }),
+            };
+        },
+    },
+    {
+        name: "groups delete",
+        summary: "Delete a group — its tests stay, its schedule (if any) goes with it",
+        scope: "project",
+        args: [{ name: "group", description: "Group name 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 group = await resolveGroup(ctx, workspaceId, projectId, arg(input, "group"));
+            await ctx.confirm(`Delete group '${group.name}' (${group.test_count ?? 0} tests leave it)?`, flagBool(input, "force"));
+            await ctx.client.del(`${projectPath(workspaceId, projectId)}/groups/${group.id}`);
+            return { human: "Deleted." };
+        },
+    },
+];

package/dist/commands/health.js

@@ -0,0 +1,43 @@
+import { flagStr, projectPath } from "./util.js";
+const ENV_FLAG = {
+    name: "env",
+    type: "string",
+    description: "Environment id (defaults to the project's default environment)",
+};
+export const healthCommands = [
+    {
+        name: "health get",
+        groupDefault: true,
+        groupSummary: "Site Health — how your site reads to search engines and visitors: content, " +
+            "speed, mobile, links and security, graded from a real check of your live pages.",
+        summary: "Show the latest Site Health report for a project environment",
+        description: "A check runs automatically when a project or environment gets its URL. While one " +
+            "is in flight the report comes back with status queued/running and no grades yet; " +
+            "call again to pick up the finished result.",
+        scope: "project",
+        flags: [ENV_FLAG],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/seo-report`, {
+                    environment_id: flagStr(input, "env"),
+                }),
+            };
+        },
+    },
+    {
+        name: "health run",
+        summary: "Run a fresh Site Health check for a project environment",
+        description: "Queues a new check and returns immediately. Returns the in-flight report instead " +
+            "of stacking a second one when a check is already running.",
+        scope: "project",
+        flags: [ENV_FLAG],
+        examples: ["beryl health run", "beryl health run --env 4f…"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.post(`${projectPath(workspaceId, projectId)}/seo-report`, undefined, { environment_id: flagStr(input, "env") }),
+            };
+        },
+    },
+];

package/dist/commands/runs.js

@@ -7,7 +7,7 @@ import { countPlannedFrames, countWrittenFrames, PlaywrightMissingError, } from
 import { dim, green, red, yellow } from "../output.js";
 import { anyGap, confirmInstall, describeGaps, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
 import { ProgressBar } from "../progress.js";
-import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+import { arg, flagBool, flagNum, flagStr, idsInGroup, projectPath } from "./util.js";
 import { watchRun } from "./watch.js";
 const MAX_FAILURE_SCREENSHOTS = 5;
 // One filesystem check before a single spec is fetched. A missing browser binary otherwise
@@ -50,10 +50,19 @@ export const runCommands = [
         name: "runs trigger",
         summary: "Trigger a test run (whole suite, a subset, or one environment)",
         description: "Runs execute in Beryl's cloud. With --watch the CLI streams live progress and " +
-            "exits 0 only if every test passed — wire it straight into CI.",
+            "exits 0 only if every test passed — wire it straight into CI. A run with a " +
+            "heal-eligible failure completes only after Beryl has tried to heal it: a repaired " +
+            "test is re-run inside the same run and counts as passed (reported as `healed`), so " +
+            "the final counts, the report and the completion email all reflect the repair.",
         scope: "project",
         flags: [
             { name: "test", type: "strings", description: "Run only these test ids (repeatable)" },
+            {
+                name: "group",
+                type: "string",
+                description: "Run only the active tests in this group (by name) — resolved to ids before the run, " +
+                    "so the run records exactly what it ran. Cannot be combined with --test.",
+            },
             { name: "env", type: "string", description: "Environment id to run against" },
             { name: "url-override", type: "string", description: "Replace the base URL (preview deploys)" },
             {
@@ -75,11 +84,22 @@ export const runCommands = [
             "beryl runs trigger --url-override https://preview-123.example.com --watch --timeout 30",
             "beryl runs trigger --url-override https://preview-123.example.com --header x-vercel-protection-bypass=<token> --watch",
             "beryl runs trigger --test 4f… --test 9a…",
+            "beryl runs trigger --group Smoke --watch",
             "beryl runs trigger --retries 0 --watch",
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const tests = input.flags.test;
+            let tests = input.flags.test;
+            const group = flagStr(input, "group");
+            if (group && tests && tests.length > 0)
+                throw new UsageError("--group cannot be combined with --test");
+            if (group) {
+                const listed = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests`));
+                tests = idsInGroup(listed, group);
+                // Exiting 0 here would be a green CI run that tested nothing.
+                if (tests.length === 0)
+                    throw new UsageError(`No active tests in group '${group}'.`);
+            }
             const extraHeaders = parseHeaders(input.flags.header);
             const created = (await ctx.client.post(`${projectPath(workspaceId, projectId)}/runs`, {
                 test_case_ids: tests && tests.length > 0 ? tests : null,
@@ -131,6 +151,11 @@ export const runCommands = [
                 type: "boolean",
                 description: "Run every active test in the project (the default when no ids are given)",
             },
+            {
+                name: "group",
+                type: "string",
+                description: "Run only the active tests in this group (by name). Cannot be combined with test ids.",
+            },
             {
                 name: "url-override",
                 type: "string",
@@ -162,15 +187,23 @@ export const runCommands = [
             "beryl runs local 4f… --no-sync --dir ./beryl-local",
         ],
         async run(ctx, input) {
-            await ensureRunnableLocally(ctx);
-            const { workspaceId, projectId } = await ctx.requireProject(input);
+            // Argument validation runs BEFORE the Chromium/Playwright precondition: a bad flag
+            // combination should say so on any machine, not report a missing browser.
             // Deduped: a repeated id would put the same test twice in one imported run,
             // which the import manifest rejects.
             const explicitIds = [...new Set(input.args["test-ids"] ?? [])];
-            // No ids means the whole suite — `beryl runs local` alone is a complete local run.
-            const all = explicitIds.length === 0;
+            const group = flagStr(input, "group");
+            if (group && explicitIds.length > 0)
+                throw new UsageError("--group cannot be combined with explicit test ids");
             if (explicitIds.length > 0 && flagBool(input, "all"))
                 throw new UsageError("--all cannot be combined with explicit test ids");
+            if (group && flagBool(input, "all"))
+                throw new UsageError("--all cannot be combined with --group");
+            // No ids and no group means the whole suite — `beryl runs local` alone is a
+            // complete local run.
+            const all = explicitIds.length === 0 && !group;
+            await ensureRunnableLocally(ctx);
+            const { workspaceId, projectId } = await ctx.requireProject(input);
             const sync = input.flags.sync !== false;
             const urlOverride = flagStr(input, "url-override");
             const dir = flagStr(input, "dir");
@@ -180,9 +213,15 @@ export const runCommands = [
             // The list rows carry the authored name as nl_title (title is the customer's
             // rename, usually unset) — fall through so the terminal shows names, not ids.
             const titles = new Map(listed.map((t) => [t.id, t.title || t.nl_title || t.id.slice(0, 8)]));
-            const ids = all ? listed.filter((t) => t.is_active !== false).map((t) => t.id) : explicitIds;
+            const ids = all
+                ? listed.filter((t) => t.is_active !== false).map((t) => t.id)
+                : group
+                    ? idsInGroup(listed, group)
+                    : explicitIds;
             if (ids.length === 0)
-                throw new CliError("This project has no tests to run.");
+                throw group
+                    ? new UsageError(`No active tests in group '${group}'.`)
+                    : 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
@@ -454,15 +493,36 @@ export const runCommands = [
     {
         name: "runs list",
         summary: "List recent runs",
+        description: "Returns the 50 most recent runs unless --page is given; pass --page to walk the " +
+            "full history a slice at a time.",
         scope: "project",
         groupDefault: true,
         groupSummary: "Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and download results.",
-        flags: [{ name: "env", type: "string", description: "Filter by environment id" }],
+        flags: [
+            { name: "env", type: "string", description: "Filter by environment id" },
+            {
+                name: "page",
+                type: "number",
+                description: "Return only this 1-indexed page instead of the 50 most recent runs",
+            },
+            {
+                name: "page-size",
+                type: "number",
+                description: "Runs per page when --page is given (default 8, max 100)",
+            },
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const rows = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs`, {
-                environment_id: flagStr(input, "env"),
-            }));
+            const page = flagNum(input, "page");
+            const rows = page === undefined
+                ? (await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs`, {
+                    environment_id: flagStr(input, "env"),
+                }))
+                : (await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs/page`, {
+                    page,
+                    page_size: flagNum(input, "page-size"),
+                    environment_id: flagStr(input, "env"),
+                })).items;
             return { data: rows.map(({ test_results: _omit, ...row }) => row) };
         },
     },

package/dist/commands/tests.js

@@ -7,7 +7,7 @@ import { PlaywrightMissingError } from "../local-run.js";
 import { dim, green, red, table, yellow } from "../output.js";
 import { confirmInstall, installPlaywright } from "../playwright-install.js";
 import { ACTION_PLAN_SCHEMA } from "../schema.generated.js";
-import { arg, argList, flagBool, flagNum, flagStr, projectPath, readJsonFlag } from "./util.js";
+import { arg, argList, flagBool, flagNum, flagStr, flagStrings, inGroup, projectPath, readJsonFlag, } from "./util.js";
 const testPath = (ws, p, id) => `${projectPath(ws, p)}/tests/${id}`;
 // A duplicate-title 409 after a green replay is idempotent when the existing row
 // holds the same plan (a retry after a lost response) — success, not an error.
@@ -106,19 +106,62 @@ 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.",
+            "Pass --wide for every field, or --json for the raw records. Returns every test " +
+            "unless --page is given; pass --page to walk a large project a slice at a time.",
         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" },
+            {
+                name: "group",
+                type: "string",
+                description: "Show only tests in this group (by name; see `beryl groups list`)",
+            },
             { name: "wide", type: "boolean", description: "Show all columns, not the concise default" },
+            {
+                name: "page",
+                type: "number",
+                description: "Return only this 1-indexed page instead of every test",
+            },
+            {
+                name: "page-size",
+                type: "number",
+                description: "Tests per page when --page is given (default 20, max 100)",
+            },
+            {
+                name: "status",
+                type: "string",
+                description: "With --page, show only this bucket: passed, failed, or blocked",
+            },
+            {
+                name: "ungrouped",
+                type: "boolean",
+                description: "With --page, show only tests carrying no group",
+            },
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests`, {
-                environment_id: flagStr(input, "env"),
-            }));
+            const page = flagNum(input, "page");
+            const group = flagStr(input, "group");
+            let data;
+            if (page === undefined) {
+                data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests`, {
+                    environment_id: flagStr(input, "env"),
+                }));
+                // GET /tests takes no group param; the paged route below filters server-side.
+                if (group)
+                    data = data.filter((t) => inGroup(t, group));
+            }
+            else {
+                data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests/page`, {
+                    page,
+                    page_size: flagNum(input, "page-size"),
+                    status: flagStr(input, "status"),
+                    group: flagBool(input, "ungrouped") ? "__ungrouped__" : group,
+                    environment_id: flagStr(input, "env"),
+                })).items;
+            }
             if (flagBool(input, "wide"))
                 return { data };
             // `data` stays the full records so --json is unchanged; only the human table is trimmed.
@@ -201,6 +244,12 @@ export const testCommands = [
                 description: "Replay against this base URL instead of the environment's (e.g. http://localhost:3000). " +
                     "The banked test is then unproven against its real environment — the CLI says so.",
             },
+            {
+                name: "group",
+                type: "strings",
+                description: "Put the test in an existing project group (by name), repeatable. An unknown " +
+                    "name is an error — create groups with `beryl groups create`. Omit for no group.",
+            },
             { name: "env", type: "string", description: "Environment id to compile and prove against" },
             {
                 name: "sync",
@@ -230,10 +279,12 @@ export const testCommands = [
             const urlOverride = flagStr(input, "url-override");
             const env = flagStr(input, "env");
             const sync = input.flags.sync !== false;
+            const groups = flagStrings(input, "group");
             const bank = (extra) => ctx.client.post(`${projectPath(workspaceId, projectId)}/tests`, {
                 title,
                 plan,
                 description,
+                groups,
                 ...extra,
             });
             if (flagBool(input, "no-verify")) {
@@ -472,6 +523,35 @@ export const testCommands = [
             };
         },
     },
+    {
+        name: "tests set-groups",
+        summary: "Replace the groups a test belongs to",
+        description: "Groups are project-defined labels used to filter, run, or schedule a slice of the " +
+            "suite (`beryl runs trigger --group <name>`). This REPLACES the whole set — pass every " +
+            "group you want, or none to clear it. Names must already exist in the project " +
+            "(`beryl groups list`); an unknown name is an error, never a new group.",
+        scope: "project",
+        args: [{ name: "test-id", description: "Test id", required: true }],
+        flags: [
+            {
+                name: "group",
+                type: "strings",
+                description: "Group name, repeatable. Omit entirely to clear the set.",
+            },
+        ],
+        examples: [
+            "beryl tests set-groups 4f… --group Checkout --group Smoke",
+            "beryl tests set-groups 4f…",
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.patch(testPath(workspaceId, projectId, arg(input, "test-id")), {
+                    groups: flagStrings(input, "group") ?? [],
+                }),
+            };
+        },
+    },
     {
         name: "tests quarantine",
         summary: "Mute a flaky test: it keeps running, but its failures stop failing the run",

package/dist/commands/util.js

@@ -54,3 +54,23 @@ export function readJsonFlag(input, name) {
         throw new UsageError(`--${name}: ${file} is not valid JSON (${err.message})`);
     }
 }
+export function flagStrings(input, name) {
+    const v = input.flags[name];
+    return v && v.length > 0 ? v : undefined;
+}
+export function inGroup(row, group) {
+    const want = group.trim().toLowerCase();
+    return (row.groups ?? []).some((g) => g.toLowerCase() === want);
+}
+/** Resolve a --group name to the ids of the project's ACTIVE tests in it.
+ *  Client-side on purpose: the run endpoint keeps one selection mechanism
+ *  (test_case_ids), so a run always records the exact ids it ran even if group
+ *  membership changes later. */
+export function idsInGroup(rows, group) {
+    return rows.filter((t) => t.is_active !== false && inGroup(t, group)).map((t) => t.id);
+}
+/** Match a `--group` value against the project's groups by name (case-insensitive) or id. */
+export function findGroup(groups, ref) {
+    const want = ref.trim().toLowerCase();
+    return groups.find((g) => g.id === ref || g.name.toLowerCase() === want);
+}

package/dist/commands/watch.js

@@ -68,7 +68,8 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes) {
     // is reported too, so a suite that only stays green by retrying can't hide it.
     const extra = (counters.cancelled ? yellow(`, ${counters.cancelled} cancelled`) : "") +
         (counters.quarantined ? yellow(`, ${counters.quarantined} quarantined`) : "") +
-        (counters.flaky ? yellow(`, ${counters.flaky} flaky`) : "");
+        (counters.flaky ? yellow(`, ${counters.flaky} flaky`) : "") +
+        (counters.healed ? yellow(`, ${counters.healed} healed`) : "");
     const summary = failed > 0
         ? red(`${failed} failed`) + `, ${passed} passed` + extra
         : green(`${passed} passed`) + extra;

package/dist/http.js

@@ -1,4 +1,5 @@
 import { AuthError, CliError } from "./errors.js";
+import { attributionHeaders } from "./telemetry.js";
 export const API_PREFIX = "/api/v1";
 export class ApiError extends CliError {
     status;
@@ -29,7 +30,11 @@ export class ApiClient {
         return this.token ? { Authorization: `Bearer ${this.token}` } : {};
     }
     async request(method, path, opts = {}) {
-        const headers = { ...this.authHeaders(), ...opts.headers };
+        const headers = {
+            ...attributionHeaders(),
+            ...this.authHeaders(),
+            ...opts.headers,
+        };
         let body;
         if (opts.form) {
             body = opts.form;

package/dist/registry/index.js

@@ -4,6 +4,8 @@ import { authCommands } from "../commands/auth.js";
 import { configCommands } from "../commands/config-vars.js";
 import { environmentCommands } from "../commands/environments.js";
 import { explorationCommands } from "../commands/explorations.js";
+import { groupCommands } from "../commands/groups.js";
+import { healthCommands } from "../commands/health.js";
 import { mailboxCommands } from "../commands/mailboxes.js";
 import { initCommands } from "../commands/init.js";
 import { mcpCommands } from "../commands/mcp.js";
@@ -56,7 +58,9 @@ export const commands = [
     ...projectCommands,
     ...environmentCommands,
     ...testCommands,
+    ...groupCommands,
     ...runCommands,
+    ...healthCommands,
     ...explorationCommands,
     ...configCommands,
     ...mailboxCommands,

package/dist/telemetry.js

@@ -0,0 +1,272 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { PostHog } from "posthog-node";
+import { cliVersion } from "./version-check.js";
+// The webapp already ships this public (write-only) project key in its JS bundle, and
+// dev/prod deploys share it — environments are separated by the `environment` property
+// on every event, not by project. Nothing here is configurable on a customer machine.
+const POSTHOG_KEY = "phc_JRs3q08uFEuLKGR6llGAEBpwAuVHtPoEXAj9IcFFhRH";
+const POSTHOG_HOST = "https://us.i.posthog.com";
+// One process = one session, for both surfaces: a CLI invocation is a one-shot session,
+// an MCP server lives as long as the coding agent keeps it spawned.
+export const sessionId = randomUUID();
+let surface = "cli";
+let client;
+export function setSurface(value) {
+    surface = value;
+}
+export function setClient(value) {
+    client = value;
+}
+export function currentSurface() {
+    return surface;
+}
+export function currentClient() {
+    return client;
+}
+// The MCP SDK dispatches tool calls concurrently, so "which tool is running" has to be
+// per-async-context, not a module global.
+const toolStore = new AsyncLocalStorage();
+export function withTool(tool, fn) {
+    return toolStore.run(tool, fn);
+}
+export function currentTool() {
+    return toolStore.getStore();
+}
+export function userAgent() {
+    const parts = [surface];
+    if (client)
+        parts.push(client.version ? `${client.name}/${client.version}` : client.name);
+    parts.push(`${process.platform} ${process.arch}`, `node/${process.versions.node}`);
+    return `beryl-cli/${cliVersion()} (${parts.join("; ")})`;
+}
+export function attributionHeaders() {
+    const headers = {
+        "User-Agent": userAgent(),
+        "X-Beryl-Session": sessionId,
+    };
+    const tool = currentTool();
+    if (tool)
+        headers["X-Beryl-Tool"] = tool;
+    return headers;
+}
+export function analyticsEnvironment(apiUrl) {
+    let host;
+    try {
+        host = new URL(apiUrl).hostname;
+    }
+    catch {
+        return "local";
+    }
+    if (host === "api.beryl.so")
+        return "prod";
+    if (host === "dev.beryl.so")
+        return "dev";
+    return "local";
+}
+// Values kept verbatim: ids, references, enum choices and other low-cardinality
+// selectors that make the Sessions view readable. Everything else is reduced to a
+// shape, so free-text arguments (plans, credentials, mail bodies) never leave the
+// machine. Keys are the MCP tool's parameter names, hyphens and all.
+const KEEP_VALUE_KEYS = new Set([
+    "account",
+    "auth",
+    "env",
+    "env-id",
+    "environment",
+    "format",
+    "frequency",
+    "id",
+    "limit",
+    "login-method",
+    "mailbox",
+    "name",
+    "project",
+    "role",
+    "run",
+    "scope",
+    "status",
+    "test",
+    "type",
+    "url",
+    "workspace",
+]);
+// Catch-all for keys we never enumerated. Deliberately a loose substring match, which
+// makes it fire on innocent names too (`login-method`, `--force-new-login`, `--otp`) —
+// so the allowlist above and booleans, both settled decisions, are checked first, and
+// this only decides the keys nobody classified. It still guards a real `--otp 123456`,
+// because numbers are kept only after it has had its say.
+const SECRET_KEY = /pass|secret|token|key|otp|code|credential|login|value|blob|cookie|email/i;
+const PAT_PREFIX = "beryl_pat_";
+const REDACTED = "<redacted>";
+function shapeOf(value) {
+    if (typeof value === "string")
+        return `<string:${value.length}>`;
+    if (Array.isArray(value))
+        return `<array:${value.length}>`;
+    if (typeof value === "object")
+        return "<object>";
+    return `<${typeof value}>`;
+}
+function containsSecret(value) {
+    if (typeof value === "string")
+        return value.includes(PAT_PREFIX);
+    if (Array.isArray(value))
+        return value.some(containsSecret);
+    if (value && typeof value === "object")
+        return Object.values(value).some(containsSecret);
+    return false;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function redactArguments(args) {
+    if (!isRecord(args))
+        return shapeOf(args);
+    const out = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (value === null || value === undefined)
+            continue;
+        if (containsSecret(value)) {
+            out[key] = REDACTED;
+        }
+        else if (KEEP_VALUE_KEYS.has(key) && typeof value === "string") {
+            out[key] = value;
+        }
+        else if (typeof value === "boolean") {
+            // true/false cannot carry a credential, whatever the key is called.
+            out[key] = value;
+        }
+        else if (SECRET_KEY.test(key)) {
+            out[key] = shapeOf(value);
+        }
+        else if (typeof value === "number") {
+            out[key] = value;
+        }
+        else {
+            out[key] = shapeOf(value);
+        }
+    }
+    return out;
+}
+// The SDK reports parameters as the JSON-RPC envelope — {request:{id,jsonrpc,method,
+// params:{name,arguments,_meta}}} — so the caller's values live at request.params.arguments.
+// An envelope we don't recognise is treated as arguments wholesale rather than passed
+// through: an unfamiliar shape must fail closed, not leak.
+//
+// `_meta` gets the same treatment as arguments. It is the protocol's open extension point,
+// so its contents are whatever the connected client decided to put there (today, Claude
+// Code's tool-use and progress ids) — unknown by definition, and not ours to forward.
+export function redactCapturedParameters(captured) {
+    if (!isRecord(captured))
+        return shapeOf(captured);
+    const request = captured.request;
+    const params = isRecord(request) ? request.params : undefined;
+    if (!isRecord(request) || !isRecord(params))
+        return redactArguments(captured);
+    const redacted = { ...params };
+    for (const key of ["arguments", "_meta"]) {
+        if (params[key] !== undefined)
+            redacted[key] = redactArguments(params[key]);
+    }
+    return { ...captured, request: { ...request, params: redacted } };
+}
+// How much a tool answered with, never what. Reads lengths off strings the SDK already
+// built — constant time whatever the payload — so this must not serialize the result.
+export function responseShape(response) {
+    if (!isRecord(response))
+        return undefined;
+    const content = response.content;
+    if (!Array.isArray(content))
+        return undefined;
+    let bytes = 0;
+    for (const part of content) {
+        if (!isRecord(part))
+            continue;
+        // text / image+audio / embedded resource, whose payload hangs one level deeper.
+        const resource = isRecord(part.resource) ? part.resource : undefined;
+        const payload = part.text ?? part.data ?? resource?.text ?? resource?.blob;
+        if (typeof payload === "string")
+            bytes += payload.length;
+    }
+    return { response_parts: content.length, response_bytes: bytes };
+}
+// Agent-written free text: it is told not to include secrets, but that is a prompt, not a
+// guarantee — so it gets the same PAT check as any argument, and a hard length cap.
+const MAX_INTENT = 500;
+function redactIntent(intent) {
+    if (typeof intent !== "string")
+        return undefined;
+    if (intent.includes(PAT_PREFIX))
+        return REDACTED;
+    return intent.length > MAX_INTENT ? intent.slice(0, MAX_INTENT) : intent;
+}
+// Tool responses carry plans, mailbox contents and run artifacts wholesale — there is no
+// key-level policy that makes them safe, so only their size survives.
+export const beforeSend = (event) => {
+    const props = event.properties;
+    Object.assign(props, responseShape(props.$mcp_response));
+    delete props.$mcp_response;
+    if (props.$mcp_parameters !== undefined) {
+        props.$mcp_parameters = redactCapturedParameters(props.$mcp_parameters);
+    }
+    if (props.$mcp_intent !== undefined) {
+        props.$mcp_intent = redactIntent(props.$mcp_intent);
+    }
+    return event;
+};
+export function baseEventProperties(apiUrl) {
+    return {
+        environment: analyticsEnvironment(apiUrl),
+        cli_version: cliVersion(),
+        os: process.platform,
+        arch: process.arch,
+        node_version: process.versions.node,
+        api_url: apiUrl,
+        // Same uuid as the X-Beryl-Session header, so a PostHog session and the Sentry tags
+        // on the API requests it caused describe the same thing.
+        beryl_session_id: sessionId,
+    };
+}
+let posthog;
+export function createPostHogClient() {
+    posthog ??= new PostHog(POSTHOG_KEY, { host: POSTHOG_HOST, disableGeoip: false });
+    return posthog;
+}
+export function analyticsOptions(apiUrl, identify) {
+    const properties = baseEventProperties(apiUrl);
+    return {
+        identify,
+        beforeSend,
+        eventProperties: () => properties,
+        // Worth its cost: without the agent's own reason for a call, a session reads as a list
+        // of tool names and you cannot tell deliberate work from a loop. The description is
+        // ours and deliberately terse — the SDK's default one is ~4x longer, and every word is
+        // paid for on all 86 advertised tools on every request (measured: +12.8k tokens vs +3k).
+        context: {
+            description: "Why this call is being made and how it serves the user's goal, in under 15 words. " +
+                "Third person. Never include credentials, tokens or personal data.",
+        },
+        // Would inject a second parameter into every tool to survive reconnects. A stdio
+        // process is already one session, and a user's work is stitched by distinct_id
+        // anyway — not worth another schema rewrite for tidier grouping.
+        enableConversationId: false,
+        reportMissing: false,
+        // Tool failures are already returned to the agent as isError and reported by the
+        // API's own Sentry; a second $exception stream would double-count them.
+        enableExceptionAutocapture: false,
+        logger: (message) => process.stderr.write(`[beryl telemetry] ${message}\n`),
+    };
+}
+export async function shutdownTelemetry() {
+    if (!posthog)
+        return;
+    const client = posthog;
+    posthog = undefined;
+    try {
+        await client.shutdown(2000);
+    }
+    catch {
+        // Telemetry must never delay or fail the process it is observing.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.27.0",
+  "version": "0.32.0",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,9 @@
     "docs": "tsx scripts/gen-docs.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@posthog/mcp": "^0.11.6",
+    "posthog-node": "^5.49.1"
   },
   "devDependencies": {
     "@playwright/test": "^1.61.1",