@beryl-so/cli 0.29.0 → 0.33.0

package/README.md

@@ -1,18 +1,18 @@
-<!-- GENERATED by `npm run docs` — edit the command registry (src/commands/), not this file. -->
+<!-- GENERATED by `npm run docs`. Edit the command registry (src/commands/), not this file. -->
 
 # beryl CLI
 
 Beryl on the command line: create projects, watch the agent explore and author tests,
-trigger runs in CI, manage everything the web app can — plus an MCP server (`beryl mcp`)
+trigger runs in CI, manage everything the web app can, plus an MCP server (`beryl mcp`)
 that exposes every command to coding agents.
 
-## Quickstart — one command
+## Quickstart: one command
 
 ```bash
 npx @beryl-so/cli@latest init
 ```
 
-Signs you in (browser approval by default, emailed one-time code as fallback — new
+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 Claude
 Code or Cursor, installs the beryl-test authoring skill, and installs Playwright for
 local runs. Safe to re-run.
@@ -27,18 +27,18 @@ npx @beryl-so/cli@latest …    # or run one-off without installing
 From the monorepo (development): `cd cli && npm install && npm run build && npm link`.
 
 `beryl init` and `beryl mcp` warn (stderr, best-effort) when the running CLI is behind the
-latest npm release — a stale MCP server silently exposes fewer tools. Set
+latest npm release; a stale MCP server silently exposes fewer tools. Set
 `BERYL_NO_UPDATE_CHECK=1` to opt out.
 
 ## Authenticate
 
 ```bash
-beryl login                  # opens the browser to approve — press Enter for an emailed code instead
+beryl login                  # opens the browser to approve; press Enter for an emailed code instead
 beryl login --otp            # skip the browser; emailed one-time code (signs up new emails too)
 export BERYL_API_KEY=beryl_pat_…   # CI: use a token from Account → API tokens
 ```
 
-Config stores your token + API URL only — nothing else persists. Point a command at a
+Config stores your token + API URL only; nothing else persists. Point a command at a
 workspace/project with the `--workspace` / `--project` flags or the `BERYL_WORKSPACE` /
 `BERYL_PROJECT` env vars; with exactly one, the CLI auto-picks it.
 Precedence: flags > `BERYL_*` env > auto-pick-if-one.
@@ -59,18 +59,18 @@ claude mcp add beryl -- beryl mcp                    # or, with the CLI installe
 ```
 
 Most non-interactive commands below are exposed as an MCP tool with the same name
-(spaces and dashes become underscores) — see the MCP tool column. `—` marks commands
+(spaces and dashes become underscores); see the MCP tool column. `none` marks commands
 kept CLI-only: account/billing/team admin, feedback, and cloud exploration.
 
 ## Commands
 
 ### init
 
-Set up Beryl in this repo — sign in and wire up your coding agent
+Set up Beryl in this repo: sign in and wire up your coding agent
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl init` | Set up Beryl in this repo — sign in and wire up your coding agent | — |
+| `beryl init` | Set up Beryl in this repo: sign in and wire up your coding agent | none |
 
 ### guide
 
@@ -86,7 +86,7 @@ Authenticate the CLI with your Beryl account
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl login` | Authenticate the CLI with your Beryl account | — |
+| `beryl login` | Authenticate the CLI with your Beryl account | none |
 
 ### signup
 
@@ -143,9 +143,9 @@ Manage who belongs to a workspace and their roles.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl members list` | List workspace members | — |
-| `beryl members set-role <user-id> <role>` | Change a member's role | — |
-| `beryl members remove <user-id>` | Remove a member from the workspace | — |
+| `beryl members list` | List workspace members | none |
+| `beryl members set-role <user-id> <role>` | Change a member's role | none |
+| `beryl members remove <user-id>` | Remove a member from the workspace | none |
 
 ### invites
 
@@ -153,16 +153,16 @@ Send, list, and revoke workspace invitations, and accept ones sent to you.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl invites send <email>` | Invite someone to the workspace by email | — |
-| `beryl invites list` | List the workspace's outstanding invitations | — |
-| `beryl invites revoke <invitation-id>` | Revoke a pending invitation | — |
-| `beryl invites mine` | List invitations sent to you | — |
-| `beryl invites accept <invitation>` | Accept an invitation (by id, or by the token from the invite email) | — |
-| `beryl invites decline <invitation-id>` | Decline an invitation | — |
+| `beryl invites send <email>` | Invite someone to the workspace by email | none |
+| `beryl invites list` | List the workspace's outstanding invitations | none |
+| `beryl invites revoke <invitation-id>` | Revoke a pending invitation | none |
+| `beryl invites mine` | List invitations sent to you | none |
+| `beryl invites accept <invitation>` | Accept an invitation (by id, or by the token from the invite email) | none |
+| `beryl invites decline <invitation-id>` | Decline an invitation | none |
 
 ### projects
 
-Create and manage projects — a site Beryl explores, authors tests for, and runs.
+Create and manage projects: a site Beryl explores, authors tests for, and runs.
 
 `beryl projects` with no subcommand runs `projects list`.
 
@@ -170,16 +170,16 @@ Create and manage projects — a site Beryl explores, authors tests for, and run
 | --- | --- | --- |
 | `beryl projects list` | List projects in the workspace | `projects_list` |
 | `beryl projects get` | Show one project, including its current exploration state | `projects_get` |
-| `beryl projects create [url]` | Create a project — with a URL the agent starts exploring; with just --name an empty one | `projects_create` |
+| `beryl projects create [url]` | Create a project. With a URL the agent starts exploring; with just --name an empty one | `projects_create` |
 | `beryl projects rename <name>` | Rename a project | `projects_rename` |
 | `beryl projects delete` | Delete a project and all its tests and runs | `projects_delete` |
-| `beryl projects re-explore` | Send the agent back in — run/heal existing tests and discover new flows | — |
+| `beryl projects re-explore` | Send the agent back in to run/heal existing tests and discover new flows | none |
 | `beryl projects report` | Aggregate quality report across recent runs (pass rates, flaky tests, trend) | `projects_report` |
 | `beryl projects reusable-auth <url>` | Check whether a saved login can be reused for a URL before creating a project | `projects_reusable_auth` |
 
 ### envs
 
-Manage a project's environments — the URLs and auth Beryl runs tests against.
+Manage a project's environments: the URLs and auth Beryl runs tests against.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
@@ -191,17 +191,18 @@ 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.
+Manage the schedules on which Beryl runs a project's tests automatically. A project can hold many independent schedules; each has its own cadence (daily or weekly), local run time, timezone, and target groups (none = every active test).
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl schedule get` | Show the project's daily/weekly run schedule | `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 list` | List the project's schedules | `schedule_list` |
+| `beryl schedule add` | Add a schedule (daily, or weekly on a given day) | `schedule_add` |
+| `beryl schedule update <schedule-id>` | Change a schedule's cadence, time, timezone, or groups | `schedule_update` |
+| `beryl schedule remove <schedule-id>` | Remove a schedule (its tests and groups stay) | `schedule_remove` |
 
 ### tests
 
-Author, inspect, version, and heal a project's tests — the checks Beryl runs on each run.
+Author, inspect, version, and heal a project's tests: the checks Beryl runs on each run.
 
 `beryl tests` with no subcommand runs `tests list`.
 
@@ -211,9 +212,10 @@ Author, inspect, version, and heal a project's tests — the checks Beryl runs o
 | `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` | Create a test case from a JSON action plan — for tests authored locally, e.g. by your coding agent | `tests_create` |
+| `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; a schedule targeting only this group goes with it | `groups_delete` |
+
 ### runs
 
 Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and download results.
@@ -247,7 +262,7 @@ Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and downlo
 
 ### 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.
+Site Health, or 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`.
 
@@ -258,15 +273,15 @@ Site Health — how your site reads to search engines and visitors: content, spe
 
 ### explorations
 
-Inspect the agent's exploration runs — how it crawled a site and authored its tests.
+Inspect the agent's exploration runs: how it crawled a site and authored its tests.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl explorations list` | List the agent's exploration passes for a project | — |
-| `beryl explorations get <exploration-id>` | Show one exploration: authored tests, abandoned flows, coverage, frontier | — |
-| `beryl explorations steps <exploration-id>` | List every step the agent took in an exploration | — |
-| `beryl explorations cancel <exploration-id>` | Cancel an in-flight exploration | — |
-| `beryl explorations watch <exploration-id>` | Stream an exploration live — watch the agent explore and author tests | — |
+| `beryl explorations list` | List the agent's exploration passes for a project | none |
+| `beryl explorations get <exploration-id>` | Show one exploration: authored tests, abandoned flows, coverage, frontier | none |
+| `beryl explorations steps <exploration-id>` | List every step the agent took in an exploration | none |
+| `beryl explorations cancel <exploration-id>` | Cancel an in-flight exploration | none |
+| `beryl explorations watch <exploration-id>` | Stream an exploration live: watch the agent explore and author tests | none |
 
 ### config
 
@@ -290,7 +305,7 @@ Manage the variables, secrets, and files the agent can use while exploring and r
 
 ### mailbox
 
-The project's standing email addresses — where its tests receive sign-in mail.
+The project's standing email addresses, where its tests receive sign-in mail.
 
 `beryl mailbox` with no subcommand runs `mailbox get`.
 
@@ -305,14 +320,14 @@ The project's standing email addresses — where its tests receive sign-in mail.
 
 ### accounts
 
-Durable identities on the site under test — what an authenticated test signs in as.
+Durable identities on the site under test: what an authenticated test signs in as.
 
 `beryl accounts` with no subcommand runs `accounts list`.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
 | `beryl accounts list` | List the test accounts an environment's tests sign in as | `accounts_list` |
-| `beryl accounts create` | Add a test account — the customer's own, or one Beryl signs up | `accounts_create` |
+| `beryl accounts create` | Add a test account: the customer's own, or one Beryl signs up | `accounts_create` |
 | `beryl accounts provision <account-id>` | Prove a test account can get in, by replaying a plan that ends logged in | `accounts_provision` |
 | `beryl accounts set-login <account-id>` | Store the sign-in plan a run replays once, plus the probe that proves it | `accounts_set_login` |
 | `beryl accounts get-login <account-id>` | Read the stored sign-in plan, its probe, and the hash a safe write must cite | `accounts_get_login` |
@@ -326,9 +341,9 @@ View and update your personal account profile.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl account get` | Show your account profile | — |
-| `beryl account update` | Update your profile | — |
-| `beryl account deletion-preview` | Preview what deleting your account would remove or leave | — |
+| `beryl account get` | Show your account profile | none |
+| `beryl account update` | Update your profile | none |
+| `beryl account deletion-preview` | Preview what deleting your account would remove or leave | none |
 
 ### feedback
 
@@ -336,7 +351,7 @@ Send product feedback to the Beryl team.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl feedback send <message>` | Send product feedback to the Beryl team | — |
+| `beryl feedback send <message>` | Send product feedback to the Beryl team | none |
 
 ### billing
 
@@ -344,10 +359,10 @@ Review a workspace's plan usage, subscription, and invoices.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl billing usage` | Show plan usage: monthly cloud run minutes | — |
-| `beryl billing subscription` | Show the workspace's subscription | — |
-| `beryl billing invoices` | List recent invoices | — |
-| `beryl billing portal` | Get a Stripe billing-portal link for the workspace | — |
+| `beryl billing usage` | Show plan usage: monthly cloud run minutes | none |
+| `beryl billing subscription` | Show the workspace's subscription | none |
+| `beryl billing invoices` | List recent invoices | none |
+| `beryl billing portal` | Get a Stripe billing-portal link for the workspace | none |
 
 ### version
 
@@ -359,18 +374,18 @@ Show the running CLI version, API URL, and Node version
 
 ### mcp
 
-Run the Beryl MCP server (stdio) — every CLI command as an agent tool
+Run the Beryl MCP server (stdio): every CLI command as an agent tool
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl mcp` | Run the Beryl MCP server (stdio) — every CLI command as an agent tool | — |
+| `beryl mcp` | Run the Beryl MCP server (stdio): every CLI command as an agent tool | none |
 
 Run `beryl <command> --help` for flags and examples.
 
 ## Global flags
 
-- `-V, --version` — Print the CLI version and exit
-- `--json` — Print machine-readable JSON (NDJSON for streams)
-- `--api-url` — API base URL (default https://api.beryl.so)
-- `--token` — Personal access token (overrides config/BERYL_API_KEY)
-- `-h, --help` — Show help
+- `-V, --version`: Print the CLI version and exit
+- `--json`: Print machine-readable JSON (NDJSON for streams)
+- `--api-url`: API base URL (default https://api.beryl.so)
+- `--token`: Personal access token (overrides config/BERYL_API_KEY)
+- `-h, --help`: Show help

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/accounts.js

@@ -37,7 +37,7 @@ export const testAccountCommands = [
         name: "accounts list",
         summary: "List the test accounts an environment's tests sign in as",
         groupDefault: true,
-        groupSummary: "Durable identities on the site under test — what an authenticated test signs in as.",
+        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.",
@@ -59,10 +59,10 @@ export const testAccountCommands = [
     },
     {
         name: "accounts create",
-        summary: "Add a test account — the customer's own, or one Beryl signs up",
+        summary: "Add a test account: the customer's own, or one Beryl signs up",
         description: "Two kinds. `--type user_provided` records a dedicated account you already have on " +
             "the site: pass --email and --password, and it is usable immediately. `--type beryl` " +
-            "reserves one Beryl will sign up itself, addressed at the project mailbox — it starts " +
+            "reserves one Beryl will sign up itself, addressed at the project mailbox. It starts " +
             "`pending` and becomes usable after `beryl accounts provision`. " +
             "The first account an environment gets is its default whatever you pass.",
         scope: "project",
@@ -124,11 +124,11 @@ export const testAccountCommands = [
         name: "accounts provision",
         summary: "Prove a test account can get in, by replaying a plan that ends logged in",
         description: "Runs the plan once in a real browser and, if it passes, marks the account ready. " +
-            "The plan is an ordinary ActionPlan that ends logged in — a SIGNUP when the account " +
+            "The plan is an ordinary ActionPlan that ends logged in: a SIGNUP when the account " +
             "does not exist yet, or a SIGN-IN when it already does (you created it by hand, or " +
             "the site already had it). Either proves the same thing, and a sign-in is what every " +
             "later test will do anyway. Type {{mailbox_address}} into the email field and " +
-            "{{login_password}} into the password field — both resolve at replay time, and an " +
+            "{{login_password}} into the password field. Both resolve at replay time, and an " +
             "`await_email` step reads the project mailbox, so a verification code works.",
         scope: "project",
         args: [{ name: "account-id", description: "Account id from `beryl accounts list`", required: true }],
@@ -170,7 +170,7 @@ export const testAccountCommands = [
             "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 " +
-            "assertion that only holds when signed in — the account menu, a 'Sign out' control). " +
+            "assertion that only holds when signed in: the account menu, a 'Sign out' control). " +
             "It is replayed in a fresh browser carrying only the captured session. It is " +
             "REQUIRED, and not a formality: assertions like `hidden`, `count 0`, and a URL " +
             "match on a redirect all pass against a logged-out page, so without a positive " +

package/dist/commands/auth.js

@@ -97,7 +97,7 @@ export const authCommands = [
         summary: "Authenticate the CLI with your Beryl account",
         description: "Signs in via your browser (a code you confirm at beryl.so) and stores a personal " +
             "access token in the CLI config. Pass --otp (or --email) to skip the browser and " +
-            "sign in with an emailed one-time code instead — a new email gets an account " +
+            "sign in with an emailed one-time code instead. A new email gets an account " +
             "created automatically. Pass --token to use an existing token from Account → API " +
             "tokens. Pass --email plus --code (the 6 digits from the email, e.g. read from a " +
             "`beryl inbox`) to complete the OTP flow without a prompt. In CI, prefer the " +
@@ -108,18 +108,18 @@ export const authCommands = [
             {
                 name: "otp",
                 type: "boolean",
-                description: "Skip the browser — sign in with an emailed code",
+                description: "Skip the browser and sign in with an emailed code",
             },
             {
                 name: "email",
                 type: "string",
                 description: "Email for the one-time code sign-in (default: your last sign-in, or your git " +
-                    "user.email — offered as the prompt default)",
+                    "user.email, offered as the prompt default)",
             },
             {
                 name: "code",
                 type: "string",
-                description: "The emailed 6-digit code — skips the prompt for non-interactive use " +
+                description: "The emailed 6-digit code. Skips the prompt for non-interactive use " +
                     "(requires --email; also skips sending a fresh code, so pair it with a " +
                     "code already requested via `beryl login`, `beryl signup`, or the API)",
             },
@@ -184,7 +184,7 @@ export const authCommands = [
         name: "signup",
         summary: "Register a new Beryl account (emails a 6-digit verification code)",
         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>` — that verifies " +
+            "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 " +
             "end-to-end with no human at a prompt.",

package/dist/commands/config-vars.js

@@ -57,8 +57,8 @@ export const configCommands = [
     {
         name: "config vars get",
         summary: "Show one config variable",
-        description: "Returns the variable row with its value in plaintext (variables are not secret) — " +
-            "a sensitive value lives in `config secrets`, readable only via `config secrets " +
+        description: "Returns the variable row with its value in plaintext (variables are not secret). " +
+            "A sensitive value lives in `config secrets`, readable only via `config secrets " +
             "get --reveal`.",
         scope: "project",
         args: [{ name: "key", description: "Variable key or id", required: true }],
@@ -116,15 +116,15 @@ export const configCommands = [
     {
         name: "config secrets get",
         summary: "Show one secret's metadata, or reveal its value with --reveal",
-        description: "Returns metadata only by default; --reveal is a logged, member-gated decrypt — " +
-            "unlike `config vars get`, which returns its value in plaintext.",
+        description: "Returns metadata only by default; --reveal is a logged, member-gated decrypt " +
+            "(unlike `config vars get`, which returns its value in plaintext).",
         scope: "project",
         args: [{ name: "key", description: "Secret key or id", required: true }],
         flags: [
             {
                 name: "reveal",
                 type: "boolean",
-                description: "Return the decrypted value — the explicit read that lets the agent drive a " +
+                description: "Return the decrypted value: the explicit read that lets the agent drive a " +
                     "real login while authoring. Member-gated; every reveal is logged",
             },
             {

package/dist/commands/environments.js

@@ -1,11 +1,24 @@
 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_GROUPS_FLAG = "Comma-separated group names or ids the schedule targets (the run covers the union of their active tests at fire time); omit to run every active test";
+const SCHEDULE_CADENCE_FLAGS = [
+    {
+        name: "frequency",
+        type: "string",
+        enum: ["daily", "weekly"],
+        description: "How often (default daily)",
+    },
+    { name: "day", type: "number", description: "Weekly only: day of week, 0=Monday … 6=Sunday" },
+    { 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)" },
+];
 export const environmentCommands = [
     {
         name: "envs list",
         summary: "List a project's environments",
         scope: "project",
-        groupSummary: "Manage a project's environments — the URLs and auth Beryl runs tests against.",
+        groupSummary: "Manage a project's environments: the URLs and auth Beryl runs tests against.",
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             return { data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/environments`) };
@@ -91,57 +104,110 @@ export const environmentCommands = [
         },
     },
     {
-        name: "schedule get",
-        summary: "Show the project's daily/weekly run schedule",
+        name: "schedule list",
+        summary: "List the project's schedules",
         scope: "project",
-        groupSummary: "View and set the schedule on which Beryl runs a project's tests automatically.",
+        groupSummary: "Manage the schedules on which Beryl runs a project's tests automatically. A project can hold many independent schedules; each has its own cadence (daily or weekly), local run time, timezone, and target groups (none = every active test).",
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            return { data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/schedule`) };
+            return { data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/schedules`) };
         },
     },
     {
-        name: "schedule set",
-        summary: "Enable scheduled runs (daily, or weekly on a given day)",
+        name: "schedule add",
+        summary: "Add a schedule (daily, or weekly on a given day)",
         scope: "project",
         flags: [
-            {
-                name: "frequency",
-                type: "string",
-                enum: ["daily", "weekly"],
-                description: "How often (default daily)",
-            },
-            { name: "day", type: "number", description: "Weekly only: day of week, 0=Monday … 6=Sunday" },
-            { 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)" },
+            ...SCHEDULE_CADENCE_FLAGS,
+            { name: "groups", type: "string", description: SCHEDULE_GROUPS_FLAG },
+        ],
+        examples: [
+            "beryl schedule add --frequency daily --hour 6 --tz UTC",
+            'beryl schedule add --groups "Smoke,Checkout" --frequency weekly --day 0 --hour 9 --minute 15 --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`, {
-                    enabled: true,
+                data: await ctx.client.post(`${projectPath(workspaceId, projectId)}/schedules`, {
                     frequency: flagStr(input, "frequency") ?? "daily",
                     day_of_week: flagNum(input, "day") ?? null,
                     run_hour: flagNum(input, "hour"),
                     run_minute: flagNum(input, "minute"),
                     timezone: flagStr(input, "tz"),
+                    group_ids: await resolveGroupIds(ctx, input, workspaceId, projectId),
                 }),
             };
         },
     },
     {
-        name: "schedule disable",
-        summary: "Turn scheduled runs off",
+        name: "schedule update",
+        summary: "Change a schedule's cadence, time, timezone, or groups",
         scope: "project",
+        args: [{ name: "schedule-id", description: "Schedule id (see schedule list)", required: true }],
+        flags: [
+            ...SCHEDULE_CADENCE_FLAGS,
+            { name: "groups", type: "string", description: SCHEDULE_GROUPS_FLAG },
+            {
+                name: "all-tests",
+                type: "boolean",
+                description: "Target every active test (clears the schedule's groups)",
+            },
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
+            const scheduleId = arg(input, "schedule-id");
+            const schedules = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/schedules`));
+            const existing = schedules.find((sch) => sch.id === scheduleId);
+            if (!existing)
+                throw new UsageError(`No schedule '${scheduleId}' in this project.`);
+            if (flagBool(input, "all-tests") && flagStr(input, "groups"))
+                throw new UsageError("--all-tests and --groups are mutually exclusive");
+            const groupIds = flagBool(input, "all-tests")
+                ? []
+                : flagStr(input, "groups")
+                    ? await resolveGroupIds(ctx, input, workspaceId, projectId)
+                    : existing.group_ids;
             return {
-                data: await ctx.client.put(`${projectPath(workspaceId, projectId)}/schedule`, {
-                    enabled: false,
+                data: await ctx.client.put(`${projectPath(workspaceId, projectId)}/schedules/${scheduleId}`, {
+                    frequency: flagStr(input, "frequency") ?? existing.frequency,
+                    day_of_week: flagNum(input, "day") ?? existing.day_of_week,
+                    run_hour: flagNum(input, "hour") ?? existing.run_hour,
+                    run_minute: flagNum(input, "minute") ?? existing.run_minute,
+                    timezone: flagStr(input, "tz") ?? existing.timezone,
+                    group_ids: groupIds,
                 }),
             };
         },
     },
+    {
+        name: "schedule remove",
+        summary: "Remove a schedule (its tests and groups stay)",
+        scope: "project",
+        args: [{ name: "schedule-id", description: "Schedule id (see schedule list)", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            await ctx.client.del(`${projectPath(workspaceId, projectId)}/schedules/${arg(input, "schedule-id")}`);
+            return { human: "Removed." };
+        },
+    },
 ];
+async function resolveGroupIds(ctx, input, workspaceId, projectId) {
+    const raw = flagStr(input, "groups");
+    if (!raw)
+        return [];
+    const refs = raw
+        .split(",")
+        .map((r) => r.trim())
+        .filter(Boolean);
+    if (refs.length === 0)
+        return [];
+    const groups = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/groups`));
+    return refs.map((ref) => {
+        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 group.id;
+    });
+}

package/dist/commands/explorations.js

@@ -3,7 +3,7 @@ import { watchExploration } from "./watch.js";
 export const explorationCommands = [
     {
         name: "explorations list",
-        groupSummary: "Inspect the agent's exploration runs — how it crawled a site and authored its tests.",
+        groupSummary: "Inspect the agent's exploration runs: how it crawled a site and authored its tests.",
         summary: "List the agent's exploration passes for a project",
         scope: "project",
         async run(ctx, input) {
@@ -38,7 +38,7 @@ export const explorationCommands = [
     {
         name: "explorations cancel",
         summary: "Cancel an in-flight exploration",
-        description: "Stops a running exploration without touching the project or its tests — the " +
+        description: "Stops a running exploration without touching the project or its tests: the " +
             "lever for a runaway/non-convergent pass burning agent budget.",
         scope: "project",
         args: [{ name: "exploration-id", description: "Exploration id", required: true }],
@@ -51,7 +51,7 @@ export const explorationCommands = [
     },
     {
         name: "explorations watch",
-        summary: "Stream an exploration live — watch the agent explore and author tests",
+        summary: "Stream an exploration live: watch the agent explore and author tests",
         description: "Replays every recorded step on connect, then follows live until the exploration " +
             "completes or fails.",
         scope: "project",