@beryl-so/cli 0.78.0 → 0.92.1

package/dist/commands/accounts.js

@@ -1,6 +1,8 @@
+import { SESSION_CAPTURE_EXTENSION_URL } from "../config.js";
+import { UsageError } from "../errors.js";
 import { ApiError } from "../http.js";
 import { dim, green, table, yellow } from "../output.js";
-import { arg, flagBool, flagStr, projectPath, readJsonFlag } from "./util.js";
+import { arg, flagBool, flagNum, flagStr, jsonFileOrInline, jsonFlag, projectPath, } from "./util.js";
 // The stored login plan heals, so a blind overwrite could silently clobber a repair the
 // caller never read. A write cites the hash it read; this turns the server's refusal into
 // the two-step recovery, and treats "you already wrote exactly this" as success.
@@ -32,6 +34,17 @@ function accountTable(rows) {
         id: a.id,
     })));
 }
+function throwawayTable(rows) {
+    return table(rows.map((a) => ({
+        email: a.email,
+        minted_by: a.mint_source ?? "",
+        run: a.test_run_id ?? "",
+        test: a.test_case_id ?? "",
+        teardown: a.teardown_outcome ?? (a.mint_source === "run" ? "not reported" : "not tracked"),
+        created: a.created_at ?? "",
+    })));
+}
+const THROWAWAY_LIMIT = 50;
 export const testAccountCommands = [
     {
         name: "accounts list",
@@ -40,13 +53,26 @@ export const testAccountCommands = [
         groupSummary: "Durable identities on the site under test: what an authenticated test signs in as.",
         description: "Every test account on the project, with the identity label a plan's `auth_label` " +
             "names. The row marked * is the default: what a plan gets when it sets " +
-            "requires_auth without an auth_label.",
+            "requires_auth without an auth_label. Below them, grouped as throwaway, the newest " +
+            "accounts test executions created for themselves through {{inbox_address}}: which " +
+            "run and test minted each, and how its teardown ended. They are kept for 30 days.",
         scope: "project",
-        flags: [{ name: "env", type: "string", description: "Only accounts on this environment id" }],
+        flags: [
+            { name: "env", type: "string", description: "Only accounts on this environment id" },
+            {
+                name: "throwaway-limit",
+                type: "number",
+                description: `How many of the newest throwaway accounts to show (default ${THROWAWAY_LIMIT}, max 500, 0 hides them)`,
+            },
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
+            const throwawayLimit = flagNum(input, "throwaway-limit") ?? THROWAWAY_LIMIT;
+            if (!Number.isInteger(throwawayLimit) || throwawayLimit < 0 || throwawayLimit > 500)
+                throw new UsageError("--throwaway-limit must be a whole number from 0 to 500");
             const rows = (await ctx.client.get(accountsPath(workspaceId, projectId), {
                 environment_id: flagStr(input, "env"),
+                throwaway_limit: throwawayLimit,
             }));
             if (rows.length === 0)
                 return {
@@ -55,7 +81,14 @@ export const testAccountCommands = [
                         "resolve to. Add one with `beryl accounts create`. A flow that must sign up " +
                         "fresh cites {{inbox_address}} and deletes the account in `after`."),
                 };
-            return { data: rows, human: accountTable(rows) };
+            const durable = rows.filter((a) => !a.mint_source);
+            const throwaway = rows.filter((a) => a.mint_source);
+            const parts = [durable.length ? accountTable(durable) : dim("No durable test accounts.")];
+            if (throwaway.length) {
+                const capped = throwaway.length >= throwawayLimit;
+                parts.push("", `Throwaway (created by test executions${capped ? `, newest ${throwawayLimit} shown` : ""}):`, throwawayTable(throwaway));
+            }
+            return { data: rows, human: parts.join("\n") };
         },
     },
     {
@@ -82,7 +115,8 @@ export const testAccountCommands = [
             "mailbox; `--lifetime` says whether it is kept (permanent, the default) or a " +
             "throwaway. It starts `pending` and becomes usable after `beryl accounts signup`. " +
             "A captured account (a signed-in session from the Beryl Chrome extension) is not " +
-            "created here: capture it with the extension, then give it a probe with " +
+            `created here: capture it with the extension (${SESSION_CAPTURE_EXTENSION_URL}), ` +
+            "then give it a probe with " +
             "`beryl accounts set-login --probe`. " +
             "Works for Google-only apps too: bank a dedicated Google test account as provided " +
             "and author its sign-in plan through Google's form. " +
@@ -153,8 +187,9 @@ export const testAccountCommands = [
     {
         name: "accounts capture",
         summary: "Store a signed-in session as a captured test account",
-        description: "Usually done by the Beryl Chrome extension from a signed-in tab; this takes the " +
-            "same session JSON from a file: {schema_version: 2, final_url, cookies (CDP " +
+        description: `Usually done by the Beryl Chrome extension (${SESSION_CAPTURE_EXTENSION_URL}) ` +
+            "from a signed-in tab; this takes the " +
+            "same session JSON from a file or inline: {schema_version: 2, final_url, cookies (CDP " +
             "shape), local_storage, session_storage, indexed_db}. Upserts by --label on the " +
             "environment, so capturing an existing label replaces its session. Cookies for " +
             "other domains are dropped and listed. A captured account cannot sign itself in: " +
@@ -165,9 +200,13 @@ export const testAccountCommands = [
             {
                 name: "file",
                 type: "string",
-                required: true,
                 description: "The captured session, as JSON (path, or - for stdin)",
             },
+            {
+                name: "session",
+                type: "json",
+                description: "The captured session inline, instead of --file",
+            },
             {
                 name: "label",
                 type: "string",
@@ -179,9 +218,10 @@ export const testAccountCommands = [
         ],
         examples: ["beryl accounts capture --file session.json --label admin"],
         async run(ctx, input) {
+            const session = jsonFileOrInline(input, "file", "session", true);
             const { workspaceId, projectId } = await ctx.requireProject(input);
             const account = (await ctx.client.put(`${accountsPath(workspaceId, projectId)}/captured`, {
-                session: readJsonFlag(input, "file"),
+                session,
                 identity_label: flagStr(input, "label") ?? "default",
                 email: flagStr(input, "email") ?? null,
                 environment_id: flagStr(input, "env") ?? null,
@@ -214,14 +254,19 @@ export const testAccountCommands = [
             {
                 name: "file",
                 type: "string",
-                required: true,
                 description: "The signup ActionPlan, ending logged in, as JSON (path, or - for stdin)",
             },
+            {
+                name: "plan",
+                type: "json",
+                description: "The signup ActionPlan inline, instead of --file",
+            },
         ],
         examples: ["beryl accounts signup acc_123 --file signup-plan.json"],
         async run(ctx, input) {
+            const plan = jsonFileOrInline(input, "file", "plan", true);
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const account = (await ctx.client.post(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/signup`, { plan: readJsonFlag(input, "file") }));
+            const account = (await ctx.client.post(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/signup`, { plan }));
             if (account.status !== "ready")
                 return {
                     data: account,
@@ -240,8 +285,8 @@ export const testAccountCommands = [
         description: "Session mode: instead of every authenticated test signing in for itself, the " +
             "account signs in ONCE at the start of a run and every test rides that session. " +
             "This stores the two plans that makes possible.\n\n" +
-            "--file is the SIGN-IN plan (not the signup): it must end logged in. Type " +
-            "{{login_email}} into the email field and {{login_password}} into the password " +
+            "--file (or --plan inline) is the SIGN-IN plan (not the signup): it must end " +
+            "logged in. Type {{login_email}} into the email field and {{login_password}} into the password " +
             "field; an emailed code or magic link arrives at the account's own address, so an " +
             "`await_email` step reads it with no human involved.\n\n" +
             "--probe is the liveness check: a two-step plan (goto a gated page, then a POSITIVE " +
@@ -252,7 +297,7 @@ export const testAccountCommands = [
             "signal a dead session would run every test logged-out and still report the run " +
             "green.\n\n" +
             "A captured account (from the Beryl Chrome extension) takes --probe alone: it rides " +
-            "the captured session and cannot sign itself in, so there is no --file.\n\n" +
+            "the captured session and cannot sign itself in, so there is no --file or --plan.\n\n" +
             "--surface android stores the sign-in Android tests use instead, beside the web one; " +
             "Beryl proves it on an Android worker the first time a signed-in android test runs. " +
             "A test-creation job saves one itself when it meets the app's login screen, so this " +
@@ -269,12 +314,19 @@ export const testAccountCommands = [
                 description: "The sign-in ActionPlan, as JSON (path, or - for stdin). Required except for a " +
                     "captured account",
             },
+            {
+                name: "plan",
+                type: "json",
+                description: "The sign-in ActionPlan inline, instead of --file",
+            },
             {
                 name: "probe",
-                type: "string",
+                type: "json",
                 required: true,
-                description: "The liveness probe plan, as JSON (path, or - for stdin): goto a gated page, " +
+                description: "The liveness probe plan (JSON, a path, or - for stdin): goto a gated page, " +
                     "then assert something only a signed-in user sees",
+                mcpDescription: "The liveness probe plan, as a JSON object: goto a gated page, then assert " +
+                    "something only a signed-in user sees",
             },
             {
                 name: "base-hash",
@@ -296,13 +348,17 @@ export const testAccountCommands = [
             "beryl accounts set-login acc_123 --file signin.json --probe probe.json --base-hash 9f2c…",
             "beryl accounts set-login acc_456 --probe probe.json  # captured account",
             "beryl accounts set-login acc_123 --surface android --file app-signin.json --probe app-probe.json",
+            `beryl accounts set-login acc_456 --probe '{"steps":[{"action":"goto","url":"/account"},` +
+                `{"action":"expect","selector":"text=Sign out","expect_kind":"visible"}]}'`,
         ],
         async run(ctx, input) {
+            const plan = jsonFileOrInline(input, "file", "plan", false) ?? null;
+            const probe = jsonFlag(input, "probe");
             const { workspaceId, projectId } = await ctx.requireProject(input);
             try {
                 const account = (await ctx.client.put(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/login`, {
-                    plan: flagStr(input, "file") ? readJsonFlag(input, "file") : null,
-                    probe: readJsonFlag(input, "probe"),
+                    plan,
+                    probe,
                     base_hash: flagStr(input, "base-hash") ?? null,
                     ...(flagStr(input, "surface") ? { surface: flagStr(input, "surface") } : {}),
                 }));

package/dist/commands/config-vars.js

@@ -3,10 +3,90 @@ import path from "node:path";
 import { CliError, UsageError } from "../errors.js";
 import { ApiError } from "../http.js";
 import { dim, green, table, timeAgo } from "../output.js";
-import { arg, flagBool, flagStr, projectPath } from "./util.js";
-const APK_RE = /\.apk$/i;
+import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+const ANDROID_BUILD_RE = /\.(apk|aab)$/i;
 const BUILD_KINDS = new Set(["android_build", "ios_build"]);
+// A bundle conversion takes a minute or three; poll gently, and faster for a short wait.
+const BUILD_POLL_MS = 5000;
+const BUILD_WAIT_DEFAULT_S = 900;
+const SIGNER_LABEL = {
+    as_uploaded: "as uploaded (your own certificate)",
+    beryl_key: "Beryl's key for this project",
+    customer_keystore: "your keystore",
+};
+const SIGNER_SHORT = {
+    as_uploaded: "as uploaded",
+    beryl_key: "Beryl key",
+    customer_keystore: "your keystore",
+};
 const buildLabel = (f) => `${f.app_id ?? "?"} ${f.app_version ?? "?"} (${f.build_number ?? "?"})`;
+const signerCell = (f) => f.signer_source
+    ? `${SIGNER_SHORT[String(f.signer_source)] ?? f.signer_source} ${String(f.signer_sha256 ?? "").slice(0, 8)}`
+    : "";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const signingPath = (ws, p) => `${configPath(ws, p)}/signing/android`;
+// stdin is read once and handed out one line per `-` flag, in flag order, so
+// `--store-pass - --key-pass -` takes two lines instead of the first flag eating both.
+let stdinLines = null;
+function secretFlag(value) {
+    if (value !== "-")
+        return value;
+    stdinLines ??= fs.readFileSync(0, "utf8").split(/\r?\n/);
+    const line = stdinLines.shift();
+    if (line === undefined || line === "")
+        throw new UsageError("stdin had no line left for a - password");
+    return line.trim();
+}
+function signingHuman(record) {
+    const key = (k) => `  SHA-1   ${k.sha1}\n  SHA-256 ${k.sha256}`;
+    if (record.mode === "customer_keystore" && record.customer_keystore) {
+        return [
+            `Converted Android builds are signed with your keystore` +
+                (record.customer_keystore.key_alias ? ` (key ${record.customer_keystore.key_alias})` : ""),
+            key(record.customer_keystore),
+            dim("Beryl's key for this project stays available: `beryl config signing clear`"),
+        ].join("\n");
+    }
+    return [
+        "Converted Android builds are signed with Beryl's key for this project",
+        key(record.beryl_key),
+        dim("Register these with Google Sign-In, Firebase or Play Integrity if the app uses them, " +
+            "or sign with your own keystore: `beryl config signing set`"),
+    ].join("\n");
+}
+function buildSummary(done) {
+    const lines = [`${green("Build uploaded")}: ${buildLabel(done)} ${dim(String(done.id))}`];
+    if (done.signer_source) {
+        lines.push(`Signed ${SIGNER_LABEL[String(done.signer_source)] ?? done.signer_source}`);
+        lines.push(`  SHA-1   ${done.signer_sha1}`);
+        lines.push(`  SHA-256 ${done.signer_sha256}`);
+        if (done.signer_source === "beryl_key")
+            lines.push(dim("  Register these with Google Sign-In, Firebase or Play Integrity if the app uses them."));
+    }
+    if (done.note)
+        lines.push(String(done.note));
+    if (done.app_id_warning)
+        lines.push(`Warning: ${String(done.app_id_warning)}`);
+    return lines.join("\n");
+}
+async function waitForBuild(ctx, filesPath, fileId, waitS) {
+    const deadline = Date.now() + waitS * 1000;
+    const pollMs = Math.min(BUILD_POLL_MS, Math.max(50, (waitS * 1000) / 4));
+    for (;;) {
+        await sleep(pollMs);
+        const rows = (await ctx.client.get(filesPath));
+        const row = rows.find((r) => r.id === fileId);
+        if (!row)
+            throw new CliError(`Build ${fileId} disappeared while converting`);
+        if (row.status === "ready")
+            return row;
+        if (row.status === "failed")
+            throw new CliError(`Build refused: ${String(row.failure_reason ?? "conversion failed")}`);
+        if (Date.now() >= deadline)
+            throw new CliError(`Still converting after ${waitS}s. Check later with \`beryl config files get ${fileId}\`; ` +
+                "tests install it once it is ready.");
+    }
+}
 const configPath = (ws, p) => `${projectPath(ws, p)}/config`;
 function findByKey(rows, value, kind) {
     const byId = rows.find((r) => r.id === value);
@@ -168,6 +248,86 @@ export const configCommands = [
             return { human: "Deleted." };
         },
     },
+    {
+        name: "config signing get",
+        summary: "Which key signs Android builds converted from an .aab, with its fingerprints",
+        description: "An .apk keeps your signature; a converted .aab is signed with this key: Beryl's key for " +
+            "the project unless you set your keystore. Register the fingerprints with Google " +
+            "Sign-In, Firebase or Play Integrity when the app uses them.",
+        scope: "project",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const record = (await ctx.client.get(signingPath(workspaceId, projectId)));
+            return { data: record, human: signingHuman(record) };
+        },
+    },
+    {
+        name: "config signing set",
+        summary: "Sign converted Android builds with your own keystore",
+        description: "A JKS or PKCS12 keystore with its passwords, checked now (a wrong password or alias " +
+            "fails here), encrypted at rest and never returned. Pass - as a password to read it " +
+            "from stdin, one line per - flag in flag order.",
+        scope: "project",
+        flags: [
+            { name: "keystore", type: "string", required: true, description: "Path to the .jks or .p12" },
+            {
+                name: "store-pass",
+                type: "string",
+                required: true,
+                description: "Keystore password (or - to read from stdin)",
+            },
+            { name: "alias", type: "string", description: "Key alias; needed when the store holds several" },
+            {
+                name: "key-pass",
+                type: "string",
+                description: "Key password when it differs from the store password (or -)",
+            },
+        ],
+        examples: [
+            "beryl config signing set --keystore release.jks --store-pass - --alias upload --key-pass -",
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const keystore = flagStr(input, "keystore");
+            if (!keystore)
+                throw new UsageError("--keystore is required");
+            const storePass = flagStr(input, "store-pass");
+            if (!storePass)
+                throw new UsageError("--store-pass is required (or - to read it from stdin)");
+            let blob;
+            try {
+                blob = await fs.openAsBlob(keystore);
+            }
+            catch (err) {
+                throw new UsageError(`cannot read ${keystore} (${err.code ?? "error"})`);
+            }
+            const form = new FormData();
+            form.set("keystore", blob, path.basename(keystore));
+            form.set("store_password", secretFlag(storePass));
+            const alias = flagStr(input, "alias");
+            if (alias)
+                form.set("key_alias", alias);
+            const keyPass = flagStr(input, "key-pass");
+            if (keyPass)
+                form.set("key_password", secretFlag(keyPass));
+            const record = (await ctx.client.request("PUT", signingPath(workspaceId, projectId), {
+                form,
+            }));
+            return { data: record, human: signingHuman(record) };
+        },
+    },
+    {
+        name: "config signing clear",
+        summary: "Forget your keystore; converted builds go back to Beryl's key",
+        scope: "project",
+        flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            await ctx.confirm("Forget the project's keystore? Builds converted from now on are signed with Beryl's key.", flagBool(input, "force"));
+            const record = (await ctx.client.del(signingPath(workspaceId, projectId)));
+            return { data: record, human: signingHuman(record) };
+        },
+    },
     {
         name: "config files list",
         summary: "List uploaded files: fixtures tests attach and Android and iOS app builds",
@@ -179,6 +339,12 @@ export const configCommands = [
                 name: f.name,
                 kind: f.kind ?? "fixture",
                 app: BUILD_KINDS.has(String(f.kind)) ? buildLabel(f) : "",
+                status: BUILD_KINDS.has(String(f.kind))
+                    ? f.status === "failed"
+                        ? `failed: ${String(f.failure_reason ?? "").slice(0, 60)}`
+                        : String(f.status ?? "unknown")
+                    : "",
+                signer: signerCell(f),
                 env: f.environment_id ?? "",
                 created: timeAgo(f.created_at),
                 id: f.id,
@@ -210,15 +376,14 @@ export const configCommands = [
     {
         name: "config files upload",
         summary: "Upload a file: a fixture an upload step attaches, or an Android or iOS app build",
-        description: "The bytes go straight to storage over a short-lived URL, never through the API, up to " +
-            "1 GB. An .apk uploads as an Android build (or pass --kind android_build): Beryl reads " +
-            "its package name, version and native ABIs, refuses one the emulators cannot run (an " +
-            ".aab, a split APK, a too-new minSdk, ARM-only native code on x86 emulators). An iOS " +
-            "simulator build (the .app folder zipped, or EAS's .tar.gz) uploads with --kind " +
-            "ios_build: Beryl reads its bundle id and version and refuses an .ipa, a device build " +
-            "or one with no arm64 slice. App tests of an environment whose app id for that surface " +
-            "matches install the newest build. Beryl keeps the newest 5 builds per app per " +
-            "environment. Upload after each build, e.g. in CI.",
+        description: "The bytes go straight to storage over a short-lived URL, up to 1 GB. An .apk or .aab " +
+            "uploads as an Android build: an APK is read at once (package, version, ABIs, signing " +
+            "certificate) and refused if the emulators cannot run it; an .aab is converted on an " +
+            "Android worker to a universal APK signed with the project's key (`config signing get`), " +
+            "and the command waits until it is ready or failed (--no-wait returns at once). An iOS " +
+            "simulator build (the .app zipped, or EAS's .tar.gz) uploads with --kind ios_build; an " +
+            ".ipa is refused. A ready build names the app for environments that name none yet. " +
+            "Beryl keeps the newest 5 builds per app per environment.",
         scope: "project",
         args: [{ name: "file", description: "Path to the local file", required: true }],
         flags: [
@@ -227,20 +392,31 @@ export const configCommands = [
                 name: "kind",
                 type: "string",
                 enum: ["fixture", "android_build", "ios_build"],
-                description: "fixture: a file tests attach. android_build: an Android APK (the default for .apk). " +
-                    "ios_build: a zipped or tarred iOS simulator .app",
+                description: "fixture: a file tests attach. android_build: an Android APK or App Bundle (the " +
+                    "default for .apk and .aab). ios_build: a zipped or tarred iOS simulator .app",
+            },
+            {
+                name: "wait-s",
+                type: "number",
+                description: `Seconds to wait for an .aab to convert (default ${BUILD_WAIT_DEFAULT_S})`,
+            },
+            {
+                name: "no-wait",
+                type: "boolean",
+                description: "Return as soon as an .aab is queued; `config files get <id>` shows when it is ready",
             },
         ],
         examples: [
             "beryl config files upload ./fixtures/avatar.png",
             "beryl config files upload ./android/app/build/outputs/apk/release/app-release.apk",
+            "beryl config files upload ./app-release.aab",
             "beryl config files upload ./MyApp.zip --kind ios_build",
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             const file = arg(input, "file");
             const explicitKind = flagStr(input, "kind");
-            const kind = explicitKind ?? (APK_RE.test(file) ? "android_build" : "fixture");
+            const kind = explicitKind ?? (ANDROID_BUILD_RE.test(file) ? "android_build" : "fixture");
             const envId = flagStr(input, "env");
             let blob;
             try {
@@ -287,12 +463,23 @@ export const configCommands = [
                     throw new CliError(`Build refused: ${err.detail}`);
                 throw err;
             }
-            return {
-                data: done,
-                human: BUILD_KINDS.has(String(done.kind))
-                    ? `${green("Build uploaded")}: ${buildLabel(done)} ${dim(String(done.id))}`
-                    : `${green("Uploaded")}: ${String(done.name)} ${dim(String(done.id))}`,
-            };
+            if (!BUILD_KINDS.has(String(done.kind))) {
+                return { data: done, human: `${green("Uploaded")}: ${String(done.name)} ${dim(String(done.id))}` };
+            }
+            if (done.status === "converting") {
+                const fileId = String(done.id);
+                if (flagBool(input, "no-wait")) {
+                    return {
+                        data: done,
+                        human: `Queued: ${path.basename(file)} is being converted to an APK ${dim(fileId)}\n` +
+                            `${String(done.note ?? "")}\nCheck with \`beryl config files get ${fileId}\`.`,
+                    };
+                }
+                const waitS = flagNum(input, "wait-s") ?? BUILD_WAIT_DEFAULT_S;
+                ctx.err(dim(`Converting ${path.basename(file)} to a universal APK on an Android worker…`));
+                done = await waitForBuild(ctx, base, fileId, waitS);
+            }
+            return { data: done, human: buildSummary(done) };
         },
     },
     {

package/dist/commands/environments.js

@@ -1,4 +1,5 @@
 import { UsageError } from "../errors.js";
+import { autoFormat } from "../output.js";
 import { HEALTH_RUN_SETTING_FLAGS, VIEWPORTS, runSettingsFromFlags } from "./health.js";
 import { TRACKER_SETTING_FLAGS, trackerSettingsFromFlags } from "./tracker.js";
 import { arg, findGroup, flagBool, flagNum, flagStr, flagStrings, projectPath } from "./util.js";
@@ -15,6 +16,16 @@ const SCHEDULE_CADENCE_FLAGS = [
     { name: "minute", type: "number", description: "Minute 0-59" },
     { name: "tz", type: "string", description: "IANA timezone (e.g. America/Los_Angeles)" },
 ];
+// A matching build can be uploaded later, so a mismatch warns instead of failing.
+export function withAppBuildWarnings(env) {
+    const { app_build_warnings: warnings, ...rest } = env;
+    if (!warnings?.length)
+        return { data: env };
+    return {
+        data: env,
+        human: [autoFormat(rest), ...warnings.map((w) => `Warning: ${w.message}`)].join("\n"),
+    };
+}
 export const environmentCommands = [
     {
         name: "envs list",
@@ -38,9 +49,7 @@ export const environmentCommands = [
         args: [{ name: "env-id", description: "Environment id", required: true }],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            return {
-                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/environments/${arg(input, "env-id")}`),
-            };
+            return withAppBuildWarnings(await ctx.client.get(`${projectPath(workspaceId, projectId)}/environments/${arg(input, "env-id")}`));
         },
     },
     {
@@ -81,7 +90,7 @@ export const environmentCommands = [
             {
                 name: "app-id",
                 type: "strings",
-                description: 'App id for an app surface, as surface=id (android=com.acme.app, ios=com.acme.App), repeatable: that surface\'s tests install the newest uploaded build of it; "ios=" clears it',
+                description: 'Usually not needed: a ready build fills it in. Set it by hand when the project has several apps (flavours), as surface=id (android=com.acme.app, ios=com.acme.App), repeatable: that surface\'s tests install the newest uploaded build of it; "ios=" clears it. Warns, naming the uploaded ids, when no uploaded build has it',
             },
             { name: "auth", type: "string", enum: ["public", "gated"], description: "New auth choice" },
             {
@@ -139,9 +148,7 @@ export const environmentCommands = [
                 body.site_health_runs = runs;
             if (Object.keys(body).length === 0)
                 throw new UsageError("Nothing to update");
-            return {
-                data: await ctx.client.patch(`${projectPath(workspaceId, projectId)}/environments/${arg(input, "env-id")}`, body),
-            };
+            return withAppBuildWarnings(await ctx.client.patch(`${projectPath(workspaceId, projectId)}/environments/${arg(input, "env-id")}`, body));
         },
     },
     {

package/dist/commands/init.js

@@ -461,8 +461,8 @@ export const initCommands = [
                     `    ${dim("Some clients name that key `servers` or `mcp`.")}\n` +
                     `    ${yellow(`Details: ${MANUAL_SETUP_DOCS}`)}\n`
                 : `\n${bold(`Beryl is set up. Now ${ed.open} and ask ${ed.agent} to create tests.`)}\n` +
-                    `  ${dim(`• Say: "create tests for https://example.com from docs/checkout.md" and ${ed.agent} starts`)}\n` +
-                    `  ${dim("  a cloud test-creation job (jobs create) that authors them from that document.")}\n` +
+                    `  ${dim(`• Say: "create tests for the checkout flow on https://example.com" and ${ed.agent} starts`)}\n` +
+                    `  ${dim("  a cloud test-creation job (jobs create) that authors them from that prompt.")}\n` +
                     `  ${dim(`• Then ask ${ed.agent} to run them in Beryl's cloud (runs trigger).`)}\n`;
             // 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.