@beryl-so/cli 0.34.3 → 0.35.0

package/README.md

@@ -30,6 +30,9 @@ From the monorepo (development): `cd cli && npm install && npm run build && npm
 latest npm release; a stale MCP server silently exposes fewer tools. Set
 `BERYL_NO_UPDATE_CHECK=1` to opt out.
 
+The CLI reports which commands run (never their arguments or output) so onboarding can
+be measured; set `BERYL_TELEMETRY=0` or `DO_NOT_TRACK=1` to send nothing.
+
 ## Authenticate
 
 ```bash

package/dist/adapters/cli.js

@@ -4,7 +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 { captureCliEvent, shutdownTelemetry, withTool, } from "../telemetry.js";
 import { cliVersion } from "../version-check.js";
 import { mcpToolFor } from "./mcp.js";
 export const GLOBAL_FLAGS = [
@@ -324,6 +324,10 @@ export async function runCli(argv) {
         config.token = parsed.token;
     const client = new ApiClient(config.apiUrl, config.token);
     const ctx = createContext({ client, config, json: parsed.json, mcp: false });
+    // The MCP server reports its own tool calls; every other invocation is one command.
+    if (spec.name !== "mcp") {
+        captureCliEvent("cli_command", config.apiUrl, { command: spec.name });
+    }
     try {
         const result = (await withTool(spec.name, () => spec.run(ctx, parsed.input))) ?? {};
         if (parsed.json) {
@@ -345,4 +349,7 @@ export async function runCli(argv) {
         }
         throw err;
     }
+    finally {
+        await shutdownTelemetry();
+    }
 }

package/dist/adapters/mcp.js

@@ -18,29 +18,68 @@ export function mcpTools() {
     return commands.filter((c) => !c.interactive && !c.hidden && !c.mcpHidden && c.name !== "mcp");
 }
 const mcpToolNames = new Set(mcpTools().map(toolName));
+const toolByCommand = new Map(mcpTools().map((spec) => [spec.name, toolName(spec)]));
+const flagNames = new Set(commands.flatMap((spec) => (spec.flags ?? []).map((f) => f.name)));
 /** The tool name a command is exposed as under `beryl mcp`, or undefined if it isn't exposed. */
 export function mcpToolFor(spec) {
     const name = toolName(spec);
     return mcpToolNames.has(name) ? name : undefined;
 }
+/** `[beryl] tests list ...` as its tool name plus the rest, or undefined when the words are
+ *  no MCP tool (login, init, mcp): those are real terminal instructions and must stay. */
+function commandToTool(text) {
+    const words = text.trim().split(/\s+/);
+    if (words[0] === "beryl")
+        words.shift();
+    for (const n of [3, 2, 1]) {
+        const tool = toolByCommand.get(words.slice(0, n).join(" "));
+        if (tool)
+            return [tool, ...words.slice(n)].join(" ");
+    }
+    return undefined;
+}
+function flagsToParams(text, wrap) {
+    return text
+        .replace(/--json\b/g, "JSON output (always on over MCP)")
+        .replace(/--no-([a-z][a-z-]*)/g, (_, name) => flagNames.has(`no-${name}`) ? wrap(`no-${name}`) : wrap(`${name}: false`))
+        .replace(/--([a-z][a-z-]*)/g, (_, name) => wrap(name));
+}
+/** Registry text is written for `beryl --help`; the agent sees JSON parameters and tool
+ *  names, so `--wide` becomes `wide`, `beryl groups list` becomes `groups_list`, and a
+ *  command that only exists in a terminal is left verbatim. */
+export function toMcpDialect(text) {
+    return text.replace(/`[^`]*`|[^`]+/g, (segment) => {
+        if (segment.startsWith("`")) {
+            const inner = segment.slice(1, -1);
+            const asTool = commandToTool(inner);
+            if (asTool === undefined && inner.startsWith("beryl "))
+                return segment;
+            return `\`${flagsToParams(asTool ?? inner, (n) => n)}\``;
+        }
+        const prose = segment.replace(/\bberyl( [a-z][a-z-]*){1,3}(?=$|[^a-z-])/g, (command) => commandToTool(command) ?? command);
+        return flagsToParams(prose, (n) => `\`${n}\``);
+    });
+}
 export function toolInputSchema(spec) {
     const properties = {};
     const required = [];
     for (const a of spec.args ?? []) {
+        const description = toMcpDialect(a.description);
         properties[a.name] = a.variadic
-            ? { type: "array", items: { type: "string" }, description: a.description }
-            : { type: "string", description: a.description };
+            ? { type: "array", items: { type: "string" }, description }
+            : { type: "string", description };
         if (a.required)
             required.push(a.name);
     }
     for (const f of spec.flags ?? []) {
         const withDefault = f.default !== undefined ? { default: f.default } : {};
+        const description = toMcpDialect(f.mcpDescription ?? f.description);
         properties[f.name] =
             f.type === "strings"
-                ? { type: "array", items: { type: "string" }, description: f.description, ...withDefault }
+                ? { type: "array", items: { type: "string" }, description, ...withDefault }
                 : {
                     type: f.type,
-                    description: f.description,
+                    description,
                     ...(f.enum ? { enum: f.enum } : {}),
                     ...withDefault,
                 };
@@ -124,7 +163,7 @@ export function exampleArgs(spec, example) {
     return Object.keys(out).length ? out : null;
 }
 export function toolDescription(spec) {
-    const base = spec.description ? `${spec.summary}. ${spec.description}` : spec.summary;
+    const base = toMcpDialect(spec.description ? `${spec.summary}. ${spec.description}` : spec.summary);
     const lines = (spec.examples ?? [])
         .map((e) => exampleArgs(spec, e))
         .filter((a) => a !== null)
@@ -211,14 +250,7 @@ export function identifyUser(baseCtx) {
                 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),
-                        },
+                        properties: { email: me.email, name: me.name },
                     };
                 }
             }
@@ -251,7 +283,9 @@ export function mcpInstructions() {
         "run-fix loop) ships as both the beryl-test skill and the `guide` tool — same " +
         `content. If a beryl-test skill stating v${version} is already loaded, do not ` +
         "call `guide`; if no beryl-test skill is available or it states another version, " +
-        "call `guide` before authoring your first test plan.");
+        "call `guide` before authoring your first test plan. " +
+        "An account can hold several workspaces and projects: call `projects_list` first " +
+        "and pass `project` (an id is enough) on every project-scoped tool, or the call fails.");
 }
 export async function serveMcp(baseCtx) {
     setSurface("mcp");
@@ -300,7 +334,7 @@ export async function serveMcp(baseCtx) {
             return toolResult(result, lines);
         }
         catch (err) {
-            const message = err instanceof CliError ? err.message : String(err);
+            const message = toMcpDialect(err instanceof CliError ? err.message : String(err));
             return {
                 content: [{ type: "text", text: [...lines, message].join("\n") }],
                 isError: true,

package/dist/commands/auth.js

@@ -5,6 +5,7 @@ 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";
+import { aliasMachineToAccount, flushTelemetry } from "../telemetry.js";
 import { arg, flagBool, flagStr } from "./util.js";
 function gitEmail() {
     try {
@@ -172,6 +173,8 @@ export const authCommands = [
                 token,
                 api_url: apiUrl === "https://api.beryl.so" ? undefined : apiUrl,
             });
+            aliasMachineToAccount(me.id);
+            flushTelemetry();
             const human = `${green("Logged in")} as ${me.name} <${me.email}>` +
                 `\n${dim(`Token saved to ${saved}`)}`;
             return {
@@ -186,7 +189,7 @@ export const authCommands = [
         description: "Creates a passwordless account for the email and sends it a 6-digit code. " +
             "Finish with `beryl login --email <addr> --code <the 6 digits>`, which verifies " +
             "the account, creates its workspace, and signs the CLI in. With an inbox from " +
-            "`beryl inbox create` as the address, an agent can provision a fresh account " +
+            "`beryl mailbox create` as the address, an agent can provision a fresh account " +
             "end-to-end with no human at a prompt.",
         flags: [
             {

package/dist/commands/init.js

@@ -8,7 +8,7 @@ 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";
-import { aliasSessionToAccount, captureCliEvent, flushTelemetry, shutdownTelemetry, } from "../telemetry.js";
+import { aliasMachineToAccount, captureCliEvent, flushTelemetry, shutdownTelemetry, } from "../telemetry.js";
 import { cliVersion, warnIfStale } from "../version-check.js";
 import { authCommands } from "./auth.js";
 import { flagStr } from "./util.js";
@@ -227,7 +227,7 @@ export const initCommands = [
                 await signIn();
             }
             if (accountId) {
-                aliasSessionToAccount(accountId);
+                aliasMachineToAccount(accountId);
                 flushTelemetry();
             }
             const report = (label, fresh, where) => ctx.err(`${green("✓")} ${label} ${fresh ? "configured" : "already configured"} ${dim(where)}`);

package/dist/config.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -45,3 +46,13 @@ export function saveGlobalConfig(patch, env = process.env) {
     }
     return file;
 }
+// One id per install: every CLI event from this machine lands on it, and a login aliases
+// it onto the account, so an install joins the same PostHog person as the signup.
+export function machineId(env = process.env) {
+    const current = readJson(globalConfigPath(env)) ?? {};
+    if (current.machine_id)
+        return current.machine_id;
+    const id = randomUUID();
+    saveGlobalConfig({ machine_id: id }, env);
+    return id;
+}

package/dist/context.js

@@ -18,6 +18,23 @@ async function pickOne(ctx, candidates, kind, usageMessage) {
     }
     return candidates[n - 1].id;
 }
+// Over MCP there is no --flag and no env var to set: the only fix is a JSON parameter on
+// every call, and a project id alone already resolves its workspace.
+function ambiguousMessage(ctx, kind, candidates) {
+    const rows = candidates.map((c) => `  ${c.id}  ${c.name ?? c.root_url ?? ""}`).join("\n");
+    let how;
+    if (ctx.mcp) {
+        how =
+            kind === "workspace"
+                ? 'pass "workspace": "<id>" on each call, or "project": "<project id>", which implies its workspace:'
+                : 'pass "project": "<id>" on every project-scoped call (a project id alone is enough, no workspace needed):';
+    }
+    else {
+        const forms = kind === "workspace" ? "<id|name>" : "<id|name|url>";
+        how = `pass --${kind} ${forms} or set BERYL_${kind.toUpperCase()}:`;
+    }
+    return `Multiple ${kind}s: ${how}\n${rows}`;
+}
 function matchByName(candidates, value, kind) {
     const lower = value.toLowerCase();
     const matches = candidates.filter((c) => c.name?.toLowerCase() === lower ||
@@ -82,8 +99,7 @@ export function createContext(options) {
                 throw new CliError("You have no workspaces yet — create one with `beryl workspaces create`");
             }
             else {
-                workspaceCache = await pickOne(ctx, workspaces, "workspace", "Multiple workspaces — pass --workspace <id|name> or set BERYL_WORKSPACE:\n" +
-                    workspaces.map((w) => `  ${w.id}  ${w.name ?? ""}`).join("\n"));
+                workspaceCache = await pickOne(ctx, workspaces, "workspace", ambiguousMessage(ctx, "workspace", workspaces));
             }
             return workspaceCache;
         },
@@ -121,8 +137,7 @@ export function createContext(options) {
                     "`beryl projects create <url>` (add --no-explore to author tests yourself).");
             }
             else {
-                projectId = await pickOne(ctx, projects, "project", "Multiple projects — pass --project <id|name|url> or set BERYL_PROJECT:\n" +
-                    projects.map((p) => `  ${p.id}  ${p.name ?? p.root_url ?? ""}`).join("\n"));
+                projectId = await pickOne(ctx, projects, "project", ambiguousMessage(ctx, "project", projects));
             }
             projectCache = { workspaceId, projectId };
             return projectCache;

package/dist/registry/index.js

@@ -17,11 +17,15 @@ export const WORKSPACE_FLAG = {
     name: "workspace",
     type: "string",
     description: "Workspace id or name (defaults to BERYL_WORKSPACE, or your only workspace)",
+    mcpDescription: "Workspace id or name. Needed only when the account has more than one workspace and " +
+        "no project id is passed (a project id implies its workspace)",
 };
 export const PROJECT_FLAG = {
     name: "project",
     type: "string",
     description: "Project id, name, or URL (defaults to BERYL_PROJECT, or the workspace's only project)",
+    mcpDescription: "Project id, name, or URL. Pass it on every call unless the account has exactly one " +
+        "project; a project id alone is enough, its workspace is looked up",
 };
 function withScopeFlags(spec) {
     if (!spec.scope || spec.scope === "none")

package/dist/telemetry.js

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { PostHog } from "posthog-node";
+import { machineId } from "./config.js";
 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
@@ -229,22 +230,38 @@ export function baseEventProperties(apiUrl) {
     };
 }
 let posthog;
+export function telemetryDisabled(env = process.env) {
+    return env.BERYL_TELEMETRY === "0" || env.DO_NOT_TRACK === "1";
+}
 export function createPostHogClient() {
-    posthog ??= new PostHog(POSTHOG_KEY, { host: POSTHOG_HOST, disableGeoip: false });
+    posthog ??= new PostHog(POSTHOG_KEY, {
+        host: POSTHOG_HOST,
+        disableGeoip: false,
+        disabled: telemetryDisabled(),
+    });
     return posthog;
 }
-// `beryl init` starts before there is an account to attribute to: its events land on the
-// process session id, and the session is aliased onto the account once init has signed in,
-// so the install joins the same person as the signup and the later MCP work.
+// CLI events land on the install's machine id, which a login aliases onto the account:
+// an install made before there is an account still joins the person who later signs up.
 export function captureCliEvent(event, apiUrl, properties = {}) {
-    createPostHogClient().capture({
-        distinctId: sessionId,
-        event,
-        properties: { ...baseEventProperties(apiUrl), ...properties },
-    });
+    try {
+        createPostHogClient().capture({
+            distinctId: machineId(),
+            event,
+            properties: { ...baseEventProperties(apiUrl), ...properties },
+        });
+    }
+    catch {
+        // telemetry must never break a command
+    }
 }
-export function aliasSessionToAccount(userId) {
-    createPostHogClient().alias({ distinctId: userId, alias: sessionId });
+export function aliasMachineToAccount(userId) {
+    try {
+        createPostHogClient().alias({ distinctId: userId, alias: machineId() });
+    }
+    catch {
+        // telemetry must never break a command
+    }
 }
 export function flushTelemetry() {
     // Fire-and-forget: init keeps running (login, installs) while the batch goes out, and a

package/package.json

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