@beryl-so/cli 0.73.2 → 0.78.0

package/README.md

@@ -13,10 +13,9 @@ npx @beryl-so/cli@latest init
 ```
 
 Signs you in (browser approval by default, emailed one-time code as fallback; new
-emails are signed up on the spot), wires the beryl + playwright MCP servers into the
+emails are signed up on the spot), wires the beryl MCP server into the
 agent you pick with --claude, --cursor, --vscode or --opencode (it asks when you pass
-none), installs the beryl-test authoring skill, and installs Playwright for local runs.
-Safe to re-run.
+none), and installs the beryl-test authoring skill. Safe to re-run.
 
 ## Install
 
@@ -193,7 +192,7 @@ Manage a project's environments: the URLs and auth Beryl runs tests against.
 | `beryl envs list` | List a project's environments | `envs_list` |
 | `beryl envs get <env-id>` | Show one environment | `envs_get` |
 | `beryl envs create <name> <url>` | Add an environment (e.g. staging) to a project | `envs_create` |
-| `beryl envs update <env-id>` | Update an environment's name, URL, auth settings, Site Health screen sizes, schedule, CI and pages, or issue tracker settings | `envs_update` |
+| `beryl envs update <env-id>` | Update an environment's name, URL, app ids, auth settings, Site Health screen sizes, schedule, CI and pages, or issue tracker settings | `envs_update` |
 | `beryl envs delete <env-id>` | Delete an environment | `envs_delete` |
 
 ### schedule
@@ -215,11 +214,9 @@ Author, inspect, version, and heal a project's tests: the checks Beryl runs on e
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl tests lint` | Validate a plan JSON file offline, before sending it to the server | `tests_lint` |
 | `beryl tests list` | List the project's tests with their latest result | `tests_list` |
 | `beryl tests get <test-id>` | Show one test | `tests_get` |
 | `beryl tests plan <test-id>` | Print a test's current step plan (JSON) | `tests_plan` |
-| `beryl tests create` | Retired: tests are now created by the cloud test-creation job (`jobs create`) | `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-intent <test-id> <intent>` | Edit what a test proves, the target heal judges against | `tests_set_intent` |
@@ -237,7 +234,7 @@ Author, inspect, version, and heal a project's tests: the checks Beryl runs on e
 | `beryl tests reset <test-id>` | Discard user edits and return the test to its latest system-authored version | `tests_reset` |
 | `beryl tests heal <test-id> <state>` | Turn self-healing on or off for a test | `tests_heal` |
 | `beryl tests history <test-id>` | Pass/fail history, streak, and stability for a test | `tests_history` |
-| `beryl tests script [test-id]` | Print the rendered Playwright spec for a test (or an unbanked plan file) | `tests_script` |
+| `beryl tests script <test-id>` | Print the rendered Playwright spec for a test | `tests_script` |
 | `beryl tests export <test-ids...>` | Export tests as Playwright .spec.ts files in a ZIP | `tests_export` |
 
 ### groups
@@ -262,7 +259,6 @@ Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and downlo
 | Command | Summary | MCP tool |
 | --- | --- | --- |
 | `beryl runs trigger` | Trigger a test run (whole suite, a subset, or one environment) | `runs_trigger` |
-| `beryl runs local [test-ids...]` | Run tests on your machine with Playwright; results sync to Beryl | `runs_local` |
 | `beryl runs list` | List recent runs | `runs_list` |
 | `beryl runs get <run-id>` | Show one run with its per-test results | `runs_get` |
 | `beryl runs watch <run-id>` | Follow a run until it finishes | `runs_watch` |
@@ -327,9 +323,9 @@ Manage the variables, secrets, and files the agent can use while exploring and r
 | `beryl config secrets set <key> <value>` | Create a secret (write-only; re-setting a key replaces it) | `config_secrets_set` |
 | `beryl config secrets get <key>` | Show one secret's metadata, or reveal its value with --reveal | `config_secrets_get` |
 | `beryl config secrets delete <key>` | Delete a secret | `config_secrets_delete` |
-| `beryl config files list` | List files uploaded for the agent to use (e.g. CSVs, upload fixtures) | `config_files_list` |
+| `beryl config files list` | List uploaded files: fixtures tests attach and Android and iOS app builds | `config_files_list` |
 | `beryl config files get <file>` | Show one uploaded file's metadata | `config_files_get` |
-| `beryl config files upload <file>` | Upload a file | `config_files_upload` |
+| `beryl config files upload <file>` | Upload a file: a fixture an upload step attaches, or an Android or iOS app build | `config_files_upload` |
 | `beryl config files download <file-id>` | Get a short-lived download URL for a file | `config_files_download` |
 | `beryl config files delete <file-id>` | Delete an uploaded file | `config_files_delete` |
 

package/dist/adapters/mcp.js

@@ -282,7 +282,7 @@ export function mcpInstructions() {
         "magic-link flows are self-contained, with no human login needed. " +
         "New tests are authored only by Beryl's cloud agent: give it a document describing " +
         "the flows with `jobs_create`; there is no local authoring. " +
-        "The guide (plan shape, outcome assertions, accounts, email/OTP wiring, the local " +
+        "The guide (plan shape, outcome assertions, accounts, email/OTP wiring, the " +
         "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, " +

package/dist/beryl-test-skill.js

@@ -23,7 +23,7 @@ ActionPlan shape, outcome assertions, test accounts and the project mailbox, and
 local run-fix loop.
 
 Then use the Beryl MCP tools: \`projects_list\` to find the project, \`jobs_create\` to
-have Beryl's cloud agent author tests from a document, and \`runs_local\` to run them here.
+have Beryl's cloud agent author tests from a document, and \`runs_trigger\` to run them.
 
 The \`guide\` tool ships with the CLI and always matches the installed version, so treat
 it as the source of truth over anything cached here.`;
@@ -90,7 +90,7 @@ export const BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN = {
 };
 export const BERYL_TEST_SKILL = `---
 name: beryl-test
-description: Create, run, and fix durable, healable end-to-end tests for a web app with Beryl. Use when asking Beryl's cloud agent to create tests from a document (\`jobs_create\`), running tests locally with \`runs_local\`, setting up test accounts, or fixing a banked test's plan with your own coding agent.
+description: Create, run, and fix durable, healable end-to-end tests for a web app with Beryl. Use when asking Beryl's cloud agent to create tests from a document (\`jobs_create\`), running them in Beryl's cloud with \`runs_trigger\`, setting up test accounts, or fixing a banked test's plan with your own coding agent.
 ---
 
 # Beryl tests
@@ -98,12 +98,12 @@ description: Create, run, and fix durable, healable end-to-end tests for a web a
 beryl-test v${cliVersion()}, installed by \`beryl init\`; the \`guide\` tool always returns the current version of this guide.
 
 A Beryl test drives a real browser through a flow and asserts the flow reached its
-meaningful outcome. \`beryl init\` wired two MCP servers: **beryl** (\`jobs_create\`,
-\`accounts_list\`, \`runs_local\`, and the rest) and **playwright** (drive a real
-browser). You do everything below by calling those tools. Beryl **heals** tests as the
-app's markup drifts, but only when a test has the three things that make it durable: a
-real **outcome assertion**, a strong **natural-language intent**, and the **local
-run-fix loop**.
+meaningful outcome. \`beryl init\` wired the **beryl** MCP server (\`jobs_create\`,
+\`accounts_list\`, \`runs_trigger\`, and the rest). You do everything below by
+calling those tools; tests are authored and run in Beryl's cloud. Beryl **heals**
+tests as the app's markup drifts, but only when a test has the three things that make
+it durable: a real **outcome assertion**, a strong **natural-language intent**, and a
+**verified plan** (every save is proven by a replay).
 
 ## 0. Start here
 
@@ -114,16 +114,16 @@ authors one test per scenario and surface. \`jobs_get\` shows the job's status,
 it produced and any scenario it skipped. The document is sent to the LLM that drives the
 agent, so it must not hold anything the user would not share with it.
 
-What you do locally: set up the accounts tests sign in as (§1), run tests on this machine
+What you do here: set up the accounts tests sign in as (§1), trigger and read runs
 (§4), and fix a banked test's plan when it needs it (§2).
 
-Set up (once): if you cannot call the Beryl tools yet, run \`beryl init\` in a terminal to
-install the browser and wire the tools. Then, before the first job:
+Set up (once): if you cannot call the Beryl tools yet, run \`beryl init\` in a terminal
+to wire them. Then, before the first job:
 
 - \`envs_list\`: the root URL gotos resolve against (§2). If it is empty, set it with
   \`envs_update\` to a URL Beryl's cloud can reach, never \`localhost\`, \`127.0.0.1\`
-  or a private IP (refused). For a local dev server, pass \`url-override\` to
-  \`runs_local\` instead.
+  or a private IP (refused). A local dev server is not testable until it is reachable
+  from the cloud (deploy a preview, or tunnel it).
 - \`accounts_list\`: who do authenticated tests sign in as (§1)? Store its sign-in with
   \`accounts_set_login\`, prove it with \`accounts_check\`.
 - \`mailbox_get\`: the address the account receives mail at (§5).
@@ -133,10 +133,16 @@ login plan is stored.
 
 Then:
 
-1. **Create tests** with \`jobs_create\` (the document, and the environment to explore).
-2. When the job is done, run the new ids together ONCE with \`runs_local\` (or
-   \`runs_trigger\` for the cloud) so they land as one run with real first results.
-3. **A test is red or wrong?** Fix its plan with the local run-fix loop (§4).
+1. **Create tests** with \`jobs_create\` (the document, and the environment to
+   explore). \`jobs_get\` shows progress, the tests it banked (each one already
+   proven by a clean replay), and every scenario it skipped, with why.
+2. A job can pause as \`awaiting_input\` when the app's login wall blocks it (no
+   self-serve signup). Its \`needs\` field says what to do: capture a signed-in
+   session with the Beryl browser extension from the webapp. The job resumes by
+   itself and keeps everything it already banked.
+3. When the job is done, run the new ids together ONCE with \`runs_trigger\` so they
+   land as one run with real first results.
+4. **A test is red or wrong?** Fix its plan with the run-fix loop (§4).
 
 ## 1. First: who do your tests sign in as?
 
@@ -285,18 +291,18 @@ SSO-only sites are not a dead end: with a dedicated Google test account they fol
 item 2 like any password account. The captured session is the FALLBACK — no test account
 can be provided, or Google challenges the scripted sign-in: a human signs in once
 through a live browser view in the Beryl webapp, Beryl stores the session encrypted
-server-side and injects it into cloud runs: \`runs_trigger\` runs such tests,
-\`runs_local\` skips them (the session never leaves Beryl's cloud).
+server-side and injects it into cloud runs; the session never leaves Beryl's cloud.
 
-## 2. Fixing a test's plan over the Playwright MCP
+## 2. Fixing a test's plan
 
 New tests come from \`jobs_create\` (§0). You write plan JSON only to fix a banked test
 (\`tests_plan\` returns its current plan) or to store an account's sign-in or signup
 plan (§1). Either way, the rules below hold.
 
-1. **Drive the flow in a real browser first.** Walk it by hand over the Playwright MCP
-   — log in, fill, submit — acting on elements by their accessibility ref from the
-   latest page snapshot, never a guessed selector. Watch what actually happens.
+1. **Start from evidence, not memory.** Pull the failed run first: \`runs_get\` for
+   the failing step and error, \`runs_explain\` for the run's own diagnosis,
+   \`tests_events\` for how the test behaved over time. Fix what the evidence shows,
+   never what you assume the page looks like.
 2. **Write it as an ActionPlan** — a JSON object whose \`steps\` are
    \`{action, selector, url, value, ...}\`. Two structural rules:
    - the **first executed step is a \`goto\`**, and
@@ -354,10 +360,10 @@ ${JSON.stringify(BERYL_TEST_SKILL_EXAMPLE_PLAN, null, 2)
     .map((line) => `   ${line}`)
     .join("\n")}
    \`\`\`
-3. **Validate offline, then save.** Lint with \`tests_lint\` (schema check, no network),
-   inspect the exact spec with \`tests_script\`, then save with \`tests_recompile\`
-   (replays the edit against the live site first and rejects it on a red replay) or
-   \`tests_set_plan\` (saves with no replay; the next run proves it). Pass a new
+3. **Save through the replay gate.** \`tests_recompile\` replays the edited plan
+   against the live site first and rejects it on a red replay; prefer it always.
+   \`tests_set_plan\` saves with no replay (the next run proves it); reserve it for
+   when the flow cannot replay right now (for example a third-party step). Pass a new
    \`description\` only when the edit changes what the test proves (§3).
    Full ActionPlan JSON Schema:
    https://api.beryl.so/api/v1/schemas/action-plan.schema.json.
@@ -369,9 +375,32 @@ full Chromium device emulation, not a resize: the viewport, a mobile Chrome user
 touch and the device pixel ratio all change together, so a hamburger or a nav that only
 exists on small screens actually renders and is testable. \`mobile\` emulates a Pixel-class
 phone, \`tablet\` a Galaxy-class tablet; both keep a Chrome user-agent so the emulated UA
-matches the engine. Drive the flow at that size over the Playwright MCP (resize the MCP
-browser to match) so the refs you act on are the ones the small-screen layout renders. The
-account, session and teardown rules are unchanged; \`device\` only sets the frame it runs in.
+matches the engine. A test's surface is fixed when it is created, so when fixing a plan
+keep \`device\` as it is: a small-screen test's selectors must come from what the
+small-screen layout renders (a hamburger, not the desktop nav). The account, session and
+teardown rules are unchanged; \`device\` only sets the frame it runs in.
+
+### App tests (Android and iOS)
+\`device: "android"\` and \`device: "ios"\` are not browsers: the plan drives the environment's
+app (its \`app_ids.android\` from the newest APK, or \`app_ids.ios\` from the newest simulator
+build, uploaded to Files) on an emulator or simulator in Beryl's cloud. App tests are written
+and verified by a test-creation job (\`jobs_create\`), never run locally. When you edit one,
+its rules differ from a web plan's:
+
+- The first step is \`launch\` (open the app), not \`goto\`. A later \`launch\` relaunches
+  with the app's data kept, which is how a plan proves something persisted.
+- Steps: launch, back (Android only; iOS has no back button), fill, click, press, scroll,
+  wait_for, expect, await_email.
+- Selectors are \`id=<resource id>\` (Android) or \`id=<accessibility identifier>\` (iOS), or
+  \`text=<visible text or accessibility label>\`; no CSS. React Native's \`testID\` shows up as
+  the id on both; a Flutter icon button needs a \`Semantics\` label to have text.
+- \`have_text\` needs an \`id=\` selector; to check text is on screen, use \`visible\` with
+  \`text=\`. No URL or title expects: an app has no URL.
+- Keys: Enter and Backspace, plus Tab on Android. Never put \`\${\` in plan text.
+- A signed-in app test sets \`requires_auth\` and \`auth_mode: "session"\` and rides the
+  account's sign-in on that surface. The test-creation job saves that sign-in itself when
+  the app has a login screen; \`accounts_set_login\` with \`surface: "android"\` or
+  \`surface: "ios"\` only replaces it.
 
 ### The outcome assertion is the whole game
 
@@ -396,6 +425,13 @@ observable proof the flow worked.
   chrome. Target the element that carries the text (the \`h1\`, the toast), assert the
   page with \`have_title\` (substring), or check "this string is visible somewhere"
   with \`expect_kind: "visible"\` + a \`text=…\` selector.
+- **For output that varies run to run** (a chatbot or AI assistant reply), assert its
+  meaning with \`expect_kind: "judged"\`: \`selector\` locates the reply (the LAST match
+  is judged, so a selector matching every assistant message reads the newest one) and
+  \`expect_text\` states the criteria in plain words ("Lists at least two decisions and
+  names the people involved; no error or refusal"). Beryl waits up to 120s for the text
+  to appear and stop changing, then a model passes or fails it and the failure carries
+  the model's reason. Write criteria a correct answer always meets, never exact wording.
 - **If you can't name a success signal, the flow is not test-worthy.** Don't bank a
   test that verifies nothing; explore a different flow.
 - **Don't work around a real app failure to make a test go green.** A genuinely broken
@@ -405,13 +441,12 @@ observable proof the flow worked.
 
 Every one of these has produced a wrong plan or a red run. Check them.
 
-1. **Your browser may already be signed in.** The Playwright MCP keeps a persistent
-   profile. Author while signed in and you never see the gate — you will mark gated
-   pages as public. **Log out first**, then confirm the gated page really redirects to
-   the login.
+1. **A gated page can look public in signed-in evidence.** Run artifacts captured
+   while a session was live never show the login wall, so do not mark a flow public
+   (no \`requires_auth\`) from them; check how the page behaves logged out.
 2. **The sign-UP flow is not the sign-IN flow.** A brand-new address often gets an
    extra "create your account" step a returning address skips. A stored login plan must
-   be the **returning** path — drive it twice: once to create, once to sign in again.
+   be the **returning** path: what the app shows the SECOND time that account arrives.
 3. **Read the DOM, not just the accessibility tree, before picking a selector.** Two
    buttons can share a label ("Continue" / "Continue with Google"), and Beryl relaxes
    \`text=X\` to a case-insensitive SUBSTRING — \`text=Continue\` is ambiguous. Use
@@ -453,19 +488,18 @@ Good:
 Weak (describes steps + asserts nothing meaningful):
 > "Goes to /login, fills the form, and checks the page loaded."
 
-## 4. The local run-fix loop
+## 4. The run-fix loop
 
-Iterate on your machine before you rely on the cloud. \`runs_local\` runs banked tests
-with the Playwright runner bundled in the CLI: no cloud, no waiting for a scheduled run.
-Run it un-synced with a report directory against one test id while you iterate, or with
-no id to run the whole suite and record the results in Beryl.
+Every run happens in Beryl's cloud. \`runs_trigger\` against one test id (or a list)
+starts a run; \`runs_watch\` follows it live; \`runs_get\` returns each result's
+failing step, error and artifacts; \`runs_explain\` turns a red run into a diagnosis.
 
-The loop: \`runs_local\` un-synced against the test id → read the run's \`report.json\` to
-see which step or assertion failed and why → fix the plan (§2) → \`tests_lint\` →
-\`tests_set_plan\` → run again. When the batch is done, one synced \`runs_local\` (or
-\`runs_trigger\`) records it as a single run. Its options,
-session-mode behavior, and \`await_email\` / authenticated-test handling are in the
-\`runs_local\` tool's own description.
+The loop: \`runs_trigger\` against the test id, read the failure with \`runs_get\` /
+\`runs_explain\`, fix the plan (§2), save with \`tests_recompile\` (which already
+replays it against the live site, so a green recompile IS the fix proven), then one
+final \`runs_trigger\` so the suite records a clean run. If recompile keeps rejecting
+an edit, the evidence disagrees with your theory: pull more of it rather than trying
+variations.
 
 ## 5. Testing an OTP / signup flow (\`await_email\`)
 
@@ -521,9 +555,8 @@ For a magic-link flow, replace the code steps with
 
 Two caveats:
 
-- \`runs_local\` serves \`await_email\` like a cloud run: it receives at the project
-  mailbox and answers each step over the API, so the local loop covers OTP/signup flows
-  end to end. It signs up / sends mail FOR REAL, like every run.
+- Every run serves \`await_email\` from the project mailbox. It signs up / sends
+  mail FOR REAL, like every run.
 - §2's outcome discipline still applies: the green signal is the post-verification
   state (the welcome screen, the dashboard), not "an email arrived".
 
@@ -562,14 +595,19 @@ Two shapes:
   \`third_party_integrations_target\` names, trigger the app's message, then
   \`{ "action": "await_third_party", "provider": "slack", "expect_text": "..." }\`.
 - **Integration intact**: no declaration. Trigger the app's message, then
-  \`await_third_party\`.
+  \`await_third_party\`. When the app only answers its bot, ping the bot instead:
+  \`{ "action": "send_third_party", "provider": "slack", "value": "hello" }\` mentions it in
+  the project's channel, then \`await_third_party\` waits for its reply (in the channel or
+  in the thread). The bot's app must be recorded for the environment first:
+  \`third_party_integrations_target\` with \`env\` and \`app\`. A reply only the sender can
+  see never reaches Beryl, so such a bot can't be tested this way.
 
 Rules:
 
 - Always tear down what the test connected in \`after\`: disconnect the integration in
   the app.
-- These steps run only in Beryl's cloud: \`runs_local\` skips them, so run them with
-  \`runs_trigger\`.
+- These steps need Beryl's provider accounts, which live in Beryl's cloud; they run
+  like any other cloud test.
 - A setup error saying Beryl's access "is being restored" is on Beryl's side: do not
   edit the test.
 - Never add steps that browse Slack itself; the actions above do all of it.

package/dist/commands/accounts.js

@@ -253,6 +253,10 @@ export const testAccountCommands = [
             "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" +
+            "--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 " +
+            "is for fixing or replacing it.\n\n" +
             "Storing only stores. Run `beryl accounts check` to prove it against the live app.",
         scope: "project",
         args: [
@@ -278,11 +282,20 @@ export const testAccountCommands = [
                 description: "The login_plan_hash from `beryl accounts get-login`. The write is rejected if " +
                     "the stored plan changed since. Omit only when writing the first plan",
             },
+            {
+                name: "surface",
+                type: "string",
+                enum: ["android", "ios"],
+                description: "An app surface: store (or read) the sign-in through the app's own screens. Both " +
+                    "plans are plans for that device (device android or ios, starting with a launch); " +
+                    "a signed-in app test restores the session this sign-in saved on the device",
+            },
         ],
         examples: [
             "beryl accounts set-login acc_123 --file signin.json --probe probe.json",
             "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",
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
@@ -291,11 +304,15 @@ export const testAccountCommands = [
                     plan: flagStr(input, "file") ? readJsonFlag(input, "file") : null,
                     probe: readJsonFlag(input, "probe"),
                     base_hash: flagStr(input, "base-hash") ?? null,
+                    ...(flagStr(input, "surface") ? { surface: flagStr(input, "surface") } : {}),
                 }));
+                const surface = flagStr(input, "surface");
                 return {
                     data: account,
                     human: `${green("Stored")} — ${account.email}\n` +
-                        dim("Now run `beryl accounts check " + account.id + "` to prove it works."),
+                        dim(surface
+                            ? `Beryl proves it the first time a signed-in ${surface} test runs.`
+                            : "Now run `beryl accounts check " + account.id + "` to prove it works."),
                 };
             }
             catch (err) {
@@ -314,9 +331,21 @@ export const testAccountCommands = [
             "--base-hash on the next `accounts set-login`.",
         scope: "project",
         args: [{ name: "account-id", description: "Account id", required: true }],
+        flags: [
+            {
+                name: "surface",
+                type: "string",
+                enum: ["android", "ios"],
+                description: "An app surface: store (or read) the sign-in through the app's own screens. Both " +
+                    "plans are plans for that device (device android or ios, starting with a launch); " +
+                    "a signed-in app test restores the session this sign-in saved on the device",
+            },
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const login = (await ctx.client.get(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/login`));
+            const surface = flagStr(input, "surface");
+            const login = (await ctx.client.get(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/login` +
+                (surface ? `?surface=${encodeURIComponent(surface)}` : "")));
             if (!login.plan && !login.probe)
                 return {
                     data: login,

package/dist/commands/config-vars.js

@@ -1,7 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
-import { UsageError } from "../errors.js";
+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;
+const BUILD_KINDS = new Set(["android_build", "ios_build"]);
+const buildLabel = (f) => `${f.app_id ?? "?"} ${f.app_version ?? "?"} (${f.build_number ?? "?"})`;
 const configPath = (ws, p) => `${projectPath(ws, p)}/config`;
 function findByKey(rows, value, kind) {
     const byId = rows.find((r) => r.id === value);
@@ -165,11 +170,20 @@ export const configCommands = [
     },
     {
         name: "config files list",
-        summary: "List files uploaded for the agent to use (e.g. CSVs, upload fixtures)",
+        summary: "List uploaded files: fixtures tests attach and Android and iOS app builds",
         scope: "project",
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            return { data: await ctx.client.get(`${configPath(workspaceId, projectId)}/files`) };
+            const rows = (await ctx.client.get(`${configPath(workspaceId, projectId)}/files`));
+            const human = table(rows.map((f) => ({
+                name: f.name,
+                kind: f.kind ?? "fixture",
+                app: BUILD_KINDS.has(String(f.kind)) ? buildLabel(f) : "",
+                env: f.environment_id ?? "",
+                created: timeAgo(f.created_at),
+                id: f.id,
+            })));
+            return { data: rows, human };
         },
     },
     {
@@ -195,32 +209,89 @@ export const configCommands = [
     },
     {
         name: "config files upload",
-        summary: "Upload a file",
+        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.",
         scope: "project",
         args: [{ name: "file", description: "Path to the local file", required: true }],
-        flags: [{ name: "env", type: "string", description: "Scope to one environment id" }],
+        flags: [
+            { name: "env", type: "string", description: "Scope to one environment id" },
+            {
+                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",
+            },
+        ],
+        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 ./MyApp.zip --kind ios_build",
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             const file = arg(input, "file");
-            let bytes;
+            const explicitKind = flagStr(input, "kind");
+            const kind = explicitKind ?? (APK_RE.test(file) ? "android_build" : "fixture");
+            const envId = flagStr(input, "env");
+            let blob;
             try {
-                bytes = new Uint8Array(fs.readFileSync(file));
+                if (!fs.statSync(file).isFile())
+                    throw new UsageError(`not a file: ${file}`);
+                blob = await fs.openAsBlob(file);
             }
             catch (err) {
+                if (err instanceof UsageError)
+                    throw err;
                 const code = err.code;
                 if (code === "ENOENT")
                     throw new UsageError(`file not found: ${file}`);
                 throw new UsageError(`cannot read ${file} (${code ?? err.message})`);
             }
-            const form = new FormData();
-            form.set("file", new Blob([bytes]), path.basename(file));
-            const envId = flagStr(input, "env");
-            if (envId)
-                form.set("environment_id", envId);
+            if (blob.size === 0)
+                throw new UsageError(`${file} is empty`);
+            const base = `${configPath(workspaceId, projectId)}/files`;
+            const upload = (await ctx.client.post(`${base}/uploads`, {
+                name: path.basename(file),
+                size: blob.size,
+                kind,
+                ...(envId ? { environment_id: envId } : {}),
+            }));
+            let put;
+            try {
+                put = await fetch(upload.upload_url, {
+                    method: upload.method,
+                    headers: upload.headers,
+                    body: blob,
+                });
+            }
+            catch (err) {
+                throw new CliError(`Upload of ${file} failed: ${err.message}`);
+            }
+            if (!put.ok)
+                throw new CliError(`Upload of ${file} failed: storage answered HTTP ${put.status}`);
+            let done;
+            try {
+                done = (await ctx.client.post(`${base}/uploads/${upload.file_id}/complete`));
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.status === 422 && typeof err.detail === "string")
+                    throw new CliError(`Build refused: ${err.detail}`);
+                throw err;
+            }
             return {
-                data: await ctx.client.request("POST", `${configPath(workspaceId, projectId)}/files`, {
-                    form,
-                }),
+                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))}`,
             };
         },
     },

package/dist/commands/environments.js

@@ -72,12 +72,17 @@ export const environmentCommands = [
     },
     {
         name: "envs update",
-        summary: "Update an environment's name, URL, auth settings, Site Health screen sizes, schedule, CI and pages, or issue tracker settings",
+        summary: "Update an environment's name, URL, app ids, auth settings, Site Health screen sizes, schedule, CI and pages, or issue tracker settings",
         scope: "project",
         args: [{ name: "env-id", description: "Environment id", required: true }],
         flags: [
             { name: "name", type: "string", description: "New name" },
             { name: "url", type: "string", description: "New root URL" },
+            {
+                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',
+            },
             { name: "auth", type: "string", enum: ["public", "gated"], description: "New auth choice" },
             {
                 name: "viewport",
@@ -91,6 +96,7 @@ export const environmentCommands = [
         ],
         examples: [
             "beryl envs update <env-id> --tracker linear --tracker-team <team-id>",
+            "beryl envs update <env-id> --app-id android=com.acme.app --app-id ios=com.acme.App",
             "beryl envs update <env-id> --tracker-threshold medium --tracker-max-tickets 5",
             "beryl envs update <env-id> --tracker-priority high=urgent --tracker-pause on",
             "beryl envs update <env-id> --health-schedule daily --health-time 06:00 --health-timezone Europe/Berlin",
@@ -104,6 +110,17 @@ export const environmentCommands = [
                 body.name = flagStr(input, "name");
             if (flagStr(input, "url"))
                 body.root_url = flagStr(input, "url");
+            const appIds = flagStrings(input, "app-id");
+            if (appIds) {
+                const parsed = {};
+                for (const pair of appIds) {
+                    const [surface, ...rest] = pair.split("=");
+                    if (!surface || rest.length === 0)
+                        throw new UsageError(`--app-id must be surface=id (android=com.acme.app), got ${pair}`);
+                    parsed[surface] = rest.join("=");
+                }
+                body.app_ids = parsed;
+            }
             if (flagStr(input, "auth"))
                 body.requires_auth_choice = flagStr(input, "auth");
             const viewports = flagStrings(input, "viewport");