@beryl-so/cli 0.1.0 → 0.5.0

package/README.md

@@ -12,9 +12,10 @@ that exposes every command to coding agents.
 npx @beryl-so/cli@latest init
 ```
 
-Signs you in, pins this repo to a project (creating it if needed — the agent starts
-exploring and authoring tests immediately), and wires the MCP server into Claude Code
-or Cursor. Safe to re-run.
+Signs you in, pins this repo to a project (creating it if needed — and asking whether
+you want to author tests locally with your own coding agent, the default, or let Beryl's
+agent explore and author them), and wires the MCP server into Claude Code or Cursor.
+Safe to re-run.
 
 ## Install
 
@@ -58,213 +59,267 @@ Every non-interactive command below is exposed as an MCP tool with the same name
 
 ### init
 
-| Command | Summary |
-| --- | --- |
-| `beryl init` | Set up Beryl in this repo — sign in, pin a project, wire up your coding agent |
+Set up Beryl in this repo — sign in, pin a project, wire up your coding agent
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl init` | Set up Beryl in this repo — sign in, pin a project, wire up your coding agent | — |
 
 ### login
 
-| Command | Summary |
-| --- | --- |
-| `beryl login` | Authenticate the CLI with your Beryl account |
+Authenticate the CLI with your Beryl account
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl login` | Authenticate the CLI with your Beryl account | — |
 
 ### logout
 
-| Command | Summary |
-| --- | --- |
-| `beryl logout` | Remove the stored token from the CLI config |
+Remove the stored token from the CLI config
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl logout` | Remove the stored token from the CLI config | `logout` |
 
 ### whoami
 
-| Command | Summary |
-| --- | --- |
-| `beryl whoami` | Show the signed-in account and the CLI's resolved defaults |
+Show the signed-in account and the CLI's resolved defaults
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl whoami` | Show the signed-in account and the CLI's resolved defaults | `whoami` |
 
 ### tokens
 
-| Command | Summary |
-| --- | --- |
-| `beryl tokens list` | List your personal access tokens |
-| `beryl tokens create <name>` | Mint a new personal access token (shown once) |
-| `beryl tokens revoke <token-id>` | Revoke a personal access token |
+Manage the personal access tokens that authenticate the CLI and CI.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl tokens list` | List your personal access tokens | `tokens_list` |
+| `beryl tokens create <name>` | Mint a new personal access token (shown once) | `tokens_create` |
+| `beryl tokens revoke <token-id>` | Revoke a personal access token | `tokens_revoke` |
 
 ### workspaces
 
-| Command | Summary |
-| --- | --- |
-| `beryl workspaces list` | List workspaces you belong to |
-| `beryl workspaces get` | Show one workspace |
-| `beryl workspaces create <name>` | Create a workspace |
-| `beryl workspaces update` | Rename a workspace or change its visibility |
-| `beryl workspaces delete` | Delete a workspace and everything in it |
-| `beryl workspaces use <workspace>` | Set the default workspace for future commands |
-| `beryl workspaces history` | Show the workspace's action history (who did what, when) |
-| `beryl workspaces leave` | Leave a workspace you are a member of |
+Create and manage workspaces, and pick the one your commands act on by default.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl workspaces list` | List workspaces you belong to | `workspaces_list` |
+| `beryl workspaces get` | Show one workspace | `workspaces_get` |
+| `beryl workspaces create <name>` | Create a workspace | `workspaces_create` |
+| `beryl workspaces update` | Rename a workspace or change its visibility | `workspaces_update` |
+| `beryl workspaces delete` | Delete a workspace and everything in it | `workspaces_delete` |
+| `beryl workspaces use <workspace>` | Set the default workspace for future commands | `workspaces_use` |
+| `beryl workspaces history` | Show the workspace's action history (who did what, when) | `workspaces_history` |
+| `beryl workspaces leave` | Leave a workspace you are a member of | `workspaces_leave` |
 
 ### members
 
-| Command | Summary |
-| --- | --- |
-| `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 |
+Manage who belongs to a workspace and their roles.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl members list` | List workspace members | `members_list` |
+| `beryl members set-role <user-id> <role>` | Change a member's role | `members_set_role` |
+| `beryl members remove <user-id>` | Remove a member from the workspace | `members_remove` |
 
 ### invites
 
-| Command | Summary |
-| --- | --- |
-| `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 |
+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 | `invites_send` |
+| `beryl invites list` | List the workspace's outstanding invitations | `invites_list` |
+| `beryl invites revoke <invitation-id>` | Revoke a pending invitation | `invites_revoke` |
+| `beryl invites mine` | List invitations sent to you | `invites_mine` |
+| `beryl invites accept <invitation>` | Accept an invitation (by id, or by the token from the invite email) | `invites_accept` |
+| `beryl invites decline <invitation-id>` | Decline an invitation | `invites_decline` |
 
 ### projects
 
-| Command | Summary |
-| --- | --- |
-| `beryl projects list` | List projects in the workspace |
-| `beryl projects get` | Show one project, including its current exploration state |
-| `beryl projects create <url>` | Create a project — the agent starts exploring and authoring tests immediately |
-| `beryl projects rename <name>` | Rename a project |
-| `beryl projects delete` | Delete a project and all its tests and runs |
-| `beryl projects re-explore` | Send the agent back in — run/heal existing tests and discover new flows |
-| `beryl projects report` | Aggregate quality report across recent runs (pass rates, flaky tests, trend) |
-| `beryl projects reusable-auth <url>` | Check whether a saved login can be reused for a URL before creating a project |
-| `beryl projects use <project>` | Set the default project for future commands |
+Create and manage projects — a site Beryl explores, authors tests for, and runs.
+
+`beryl projects` with no subcommand runs `projects list`.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `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 — the agent starts exploring and authoring tests immediately | `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 | `projects_re_explore` |
+| `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` |
+| `beryl projects use <project>` | Set the default project for future commands | `projects_use` |
 
 ### envs
 
-| Command | Summary |
-| --- | --- |
-| `beryl envs list` | List a project's environments |
-| `beryl envs get <env-id>` | Show one environment |
-| `beryl envs create <name> <url>` | Add an environment (e.g. staging) to a project |
-| `beryl envs update <env-id>` | Update an environment's name, URL, or auth settings |
-| `beryl envs delete <env-id>` | Delete an environment |
+Manage a project's environments — the URLs and auth Beryl runs tests against.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `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, or auth settings | `envs_update` |
+| `beryl envs delete <env-id>` | Delete an environment | `envs_delete` |
 
 ### schedule
 
-| Command | Summary |
-| --- | --- |
-| `beryl schedule get` | Show the project's daily/weekly run schedule |
-| `beryl schedule set` | Enable scheduled runs (daily, or weekly on a given day) |
-| `beryl schedule disable` | Turn scheduled runs off |
+View and set the schedule on which Beryl runs a project's tests automatically.
+
+| 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` |
 
 ### tests
 
-| Command | Summary |
-| --- | --- |
-| `beryl tests list` | List the project's tests with their latest result |
-| `beryl tests get <test-id>` | Show one test |
-| `beryl tests plan <test-id>` | Print a test's current step plan (JSON) |
-| `beryl tests create` | Create a test case from a JSON action plan — for tests authored locally, e.g. by your coding agent |
-| `beryl tests set-plan <test-id>` | Replace a test's step plan from a JSON file (creates a new version) |
-| `beryl tests recompile <test-id>` | Validate + verify an edited plan against the live site before persisting |
-| `beryl tests versions <test-id>` | List a test's version history |
-| `beryl tests version <test-id> <version-no>` | Show one specific version of a test (including its plan) |
-| `beryl tests diff <test-id> <from> <to>` | Diff two versions of a test's plan |
-| `beryl tests restore <test-id> <version-no>` | Restore a test to an earlier version |
-| `beryl tests reset <test-id>` | Discard user edits and return the test to its latest system-authored version |
-| `beryl tests heal <test-id> <state>` | Turn self-healing on or off for a test |
-| `beryl tests history <test-id>` | Pass/fail history, streak, and stability for a test |
-| `beryl tests script <test-id>` | Print the rendered Playwright spec for a test |
-| `beryl tests export <test-ids...>` | Export tests as Playwright .spec.ts files in a ZIP |
+Author, inspect, version, and heal a project's tests — the checks Beryl runs on each run.
+
+`beryl tests` with no subcommand runs `tests list`.
+
+| 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` | 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 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` |
+| `beryl tests versions <test-id>` | List a test's version history | `tests_versions` |
+| `beryl tests version <test-id> <version-no>` | Show one specific version of a test (including its plan) | `tests_version` |
+| `beryl tests diff <test-id> <from> <to>` | Diff two versions of a test's plan | `tests_diff` |
+| `beryl tests restore <test-id> <version-no>` | Restore a test to an earlier version | `tests_restore` |
+| `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 | `tests_script` |
+| `beryl tests export <test-ids...>` | Export tests as Playwright .spec.ts files in a ZIP | `tests_export` |
 
 ### runs
 
-| Command | Summary |
-| --- | --- |
-| `beryl runs trigger` | Trigger a test run (whole suite, a subset, or one environment) |
-| `beryl runs list` | List recent runs |
-| `beryl runs get <run-id>` | Show one run with its per-test results |
-| `beryl runs watch <run-id>` | Attach to a run and stream progress until it finishes |
-| `beryl runs cancel <run-id>` | Cancel an in-flight run |
-| `beryl runs report <run-id>` | Show the generated report for a run |
-| `beryl runs download <run-id>` | Download a run's full results as JSON |
-| `beryl runs explain <result-id>` | AI explanation of why a test result failed |
+Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and download results.
+
+`beryl runs` with no subcommand runs `runs list`.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl runs trigger` | Trigger a test run (whole suite, a subset, or one environment) | `runs_trigger` |
+| `beryl runs local <test-id>` | Run a banked test locally with your own Playwright (public flows) | `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>` | Attach to a run and stream progress until it finishes | `runs_watch` |
+| `beryl runs cancel <run-id>` | Cancel an in-flight run | `runs_cancel` |
+| `beryl runs report <run-id>` | Show the generated report for a run | `runs_report` |
+| `beryl runs download <run-id>` | Download a run's results, with its artifacts, to disk | `runs_download` |
+| `beryl runs explain <result-id>` | Explain, with AI, why a test result failed | `runs_explain` |
 
 ### explorations
 
-| Command | Summary |
-| --- | --- |
-| `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 watch <exploration-id>` | Stream an exploration live — watch the agent explore and author 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 | `explorations_list` |
+| `beryl explorations get <exploration-id>` | Show one exploration: authored tests, abandoned flows, coverage, frontier | `explorations_get` |
+| `beryl explorations steps <exploration-id>` | List every step the agent took in an exploration | `explorations_steps` |
+| `beryl explorations watch <exploration-id>` | Stream an exploration live — watch the agent explore and author tests | `explorations_watch` |
 
 ### config
 
-| Command | Summary |
-| --- | --- |
-| `beryl config vars list` | List the project's config variables (visible to the agent during runs) |
-| `beryl config vars set <key> <value>` | Create or update a config variable |
-| `beryl config vars delete <key>` | Delete a config variable |
-| `beryl config secrets list` | List the project's secrets (values are never returned) |
-| `beryl config secrets set <key> <value>` | Create a secret (write-only; re-setting a key replaces it) |
-| `beryl config secrets delete <key>` | Delete a secret |
-| `beryl config files list` | List files uploaded for the agent to use (e.g. CSVs, upload fixtures) |
-| `beryl config files upload <file>` | Upload a file |
-| `beryl config files download <file-id>` | Get a short-lived download URL for a file |
-| `beryl config files delete <file-id>` | Delete an uploaded file |
+Manage the variables, secrets, and files the agent can use while exploring and running.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl config vars list` | List the project's config variables (visible to the agent during runs) | `config_vars_list` |
+| `beryl config vars set <key> <value>` | Create or update a config variable | `config_vars_set` |
+| `beryl config vars delete <key>` | Delete a config variable | `config_vars_delete` |
+| `beryl config secrets list` | List the project's secrets (values are never returned) | `config_secrets_list` |
+| `beryl config secrets set <key> <value>` | Create a secret (write-only; re-setting a key replaces it) | `config_secrets_set` |
+| `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 upload <file>` | Upload a file | `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` |
 
 ### credentials
 
-| Command | Summary |
-| --- | --- |
-| `beryl credentials list` | List the workspace's saved logins |
-| `beryl credentials get <credential-id>` | Show one saved login (status and freshness — never the session itself) |
-| `beryl credentials projects <credential-id>` | List the projects using a saved login |
-| `beryl credentials delete <credential-id>` | Delete a saved login |
-| `beryl credentials attach <credential-id>` | Attach a saved login to a project |
-| `beryl credentials detach` | Detach the project's saved login |
-| `beryl credentials recapture <credential-id>` | Start a re-capture for an expiring saved login (returns a live browser URL) |
-| `beryl credentials capture` | Capture a login for the project interactively: log in once in a real browser |
+Manage saved logins Beryl reuses to test behind authentication, and attach them to projects.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl credentials list` | List the workspace's saved logins | `credentials_list` |
+| `beryl credentials get <credential-id>` | Show one saved login (status and freshness — never the session itself) | `credentials_get` |
+| `beryl credentials projects <credential-id>` | List the projects using a saved login | `credentials_projects` |
+| `beryl credentials delete <credential-id>` | Delete a saved login | `credentials_delete` |
+| `beryl credentials attach <credential-id>` | Attach a saved login to a project | `credentials_attach` |
+| `beryl credentials detach` | Detach the project's saved login | `credentials_detach` |
+| `beryl credentials recapture <credential-id>` | Start a re-capture for an expiring saved login (returns a live browser URL) | `credentials_recapture` |
+| `beryl credentials capture` | Capture a login for the project interactively: log in once in a real browser | — |
 
 ### auth-capture
 
-| Command | Summary |
-| --- | --- |
-| `beryl auth-capture start` | Start a login-capture browser session for the project (non-interactive) |
-| `beryl auth-capture capture <session-id>` | Capture the session after the user has logged in via the live-view URL |
-| `beryl auth-capture refresh <session-id>` | Capture a refreshed session for a project whose login is expiring |
-| `beryl auth-capture release <session-id>` | Release a login-capture browser session without capturing |
+Drive a browser session that captures a target-site login for Beryl to reuse.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl auth-capture start` | Start a login-capture browser session for the project (non-interactive) | `auth_capture_start` |
+| `beryl auth-capture capture <session-id>` | Capture the session after the user has logged in via the live-view URL | `auth_capture_capture` |
+| `beryl auth-capture refresh <session-id>` | Capture a refreshed session for a project whose login is expiring | `auth_capture_refresh` |
+| `beryl auth-capture release <session-id>` | Release a login-capture browser session without capturing | `auth_capture_release` |
 
 ### account
 
-| Command | Summary |
-| --- | --- |
-| `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 |
+View and update your personal account profile.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl account get` | Show your account profile | `account_get` |
+| `beryl account update` | Update your profile | `account_update` |
+| `beryl account deletion-preview` | Preview what deleting your account would remove or leave | `account_deletion_preview` |
 
 ### feedback
 
-| Command | Summary |
-| --- | --- |
-| `beryl feedback send <message>` | Send product feedback to the Beryl team |
+Send product feedback to the Beryl team.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl feedback send <message>` | Send product feedback to the Beryl team | `feedback_send` |
 
 ### billing
 
-| Command | Summary |
-| --- | --- |
-| `beryl billing usage` | Show plan usage: services and weekly AI units |
-| `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 |
+Review a workspace's plan usage, subscription, and invoices.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl billing usage` | Show plan usage: services and weekly AI units | `billing_usage` |
+| `beryl billing subscription` | Show the workspace's subscription | `billing_subscription` |
+| `beryl billing invoices` | List recent invoices | `billing_invoices` |
+| `beryl billing portal` | Get a Stripe billing-portal link for the workspace | `billing_portal` |
 
 ### mcp
 
-| Command | Summary |
-| --- | --- |
-| `beryl 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 | — |
 
 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)
-- `--help` — Show help
+- `-h, --help` — Show help

package/dist/adapters/cli.js

@@ -4,8 +4,10 @@ import { createContext } from "../context.js";
 import { CliError, EXIT_OK, EXIT_USAGE, UsageError } from "../errors.js";
 import { ApiClient } from "../http.js";
 import { autoFormat, bold, cyan, dim } from "../output.js";
-import { commandGroups, findCommand } from "../registry/index.js";
+import { commandGroups, findCommand, groupSummary } from "../registry/index.js";
+import { mcpToolFor } from "./mcp.js";
 export const GLOBAL_FLAGS = [
+    { name: "version", description: "Print the CLI version and exit", alias: "V" },
     { name: "json", description: "Print machine-readable JSON (NDJSON for streams)" },
     { name: "api-url", description: "API base URL (default https://api.beryl.so)", value: true },
     { name: "token", description: "Personal access token (overrides config/BERYL_API_KEY)", value: true },
@@ -90,6 +92,10 @@ export function parseArgv(spec, tokens) {
             throw new UsageError(`Unknown flag --${name} for \`beryl ${spec.name}\``);
         }
     }
+    // `--help` wins over every completeness check below: you ask for help precisely when you
+    // don't yet know which flags/args the command needs.
+    if (help)
+        return { input: { args: {}, flags }, json, apiUrl, token, help };
     for (const f of specFlags) {
         if (flags[f.name] === undefined && f.default !== undefined)
             flags[f.name] = f.default;
@@ -133,10 +139,25 @@ export function usageLine(spec) {
         .join(" ");
     return `Usage: beryl ${spec.name}${args ? " " + args : ""} [flags]`;
 }
+function globalFlagLabel(flag) {
+    const value = "value" in flag && flag.value ? " <value>" : "";
+    const long = `--${flag.name}${value}`;
+    return "alias" in flag && flag.alias ? `-${flag.alias}, ${long}` : long;
+}
+function globalFlagLines() {
+    const lines = [bold("Global options:")];
+    for (const g of GLOBAL_FLAGS) {
+        lines.push(`  ${cyan(globalFlagLabel(g).padEnd(24))} ${g.description}`);
+    }
+    return lines;
+}
 export function commandHelp(spec) {
     const lines = [spec.summary, "", usageLine(spec)];
     if (spec.description)
         lines.push("", spec.description);
+    const tool = mcpToolFor(spec);
+    if (tool)
+        lines.push("", `${dim("MCP tool:")} ${cyan(tool)}`);
     if (spec.args?.length) {
         lines.push("", bold("Arguments:"));
         for (const a of spec.args)
@@ -150,10 +171,7 @@ export function commandHelp(spec) {
             lines.push(`  ${cyan(label.padEnd(24))} ${f.description}${suffix}`);
         }
     }
-    lines.push("", bold("Global flags:"));
-    for (const g of GLOBAL_FLAGS) {
-        lines.push(`  ${cyan(("--" + g.name).padEnd(24))} ${g.description}`);
-    }
+    lines.push("", ...globalFlagLines());
     if (spec.examples?.length) {
         lines.push("", bold("Examples:"));
         for (const e of spec.examples)
@@ -167,24 +185,39 @@ export function rootHelp() {
         "",
         "Usage: beryl <command> [args] [flags]",
         "",
+        bold("Commands:"),
     ];
     for (const [group, specs] of commandGroups()) {
-        if (specs.length === 1 && specs[0].name === group) {
-            lines.push(`  ${cyan(group.padEnd(14))} ${specs[0].summary}`);
+        const single = specs.length === 1 && specs[0].name === group;
+        const purpose = single ? specs[0].summary : groupSummary(specs);
+        lines.push(`  ${cyan(group.padEnd(14))} ${purpose ?? ""}`.trimEnd());
+        if (single) {
+            const tool = mcpToolFor(specs[0]);
+            if (tool)
+                lines.push(`  ${" ".repeat(14)} ${dim("MCP tool " + tool)}`);
         }
         else {
-            lines.push(`  ${cyan(group.padEnd(14))} ${specs
-                .map((s) => s.name.split(" ").slice(1).join(" "))
-                .join(", ")}`);
+            const subs = specs.map((s) => s.name.split(" ").slice(1).join(" ")).join(", ");
+            const toolPrefix = group.replace(/-/g, "_");
+            const tools = specs.some((s) => mcpToolFor(s)) ? ` · ${dim("MCP tools " + toolPrefix + "_*")}` : "";
+            lines.push(`  ${" ".repeat(14)} ${dim(subs)}`, `  ${" ".repeat(14)} ${dim(`beryl ${group} --help`)}${tools}`);
         }
     }
+    lines.push("", ...globalFlagLines());
     lines.push("", `Run ${cyan("beryl <command> --help")} for details, ${cyan("beryl login")} to get started.`, `Docs: ${cyan("https://beryl.so/docs/cli")}`);
     return lines.join("\n");
 }
 function groupHelp(group, specs) {
     const lines = [`${bold("beryl " + group)} — subcommands:`, ""];
+    const purpose = groupSummary(specs);
+    if (purpose)
+        lines.push(purpose, "");
     for (const spec of specs) {
-        lines.push(`  ${cyan(spec.name.padEnd(28))} ${spec.summary}`);
+        const suffix = spec.groupDefault ? dim(`  (default — \`beryl ${group}\` runs this)`) : "";
+        lines.push(`  ${cyan(spec.name.padEnd(28))} ${spec.summary}${suffix}`);
+        const tool = mcpToolFor(spec);
+        if (tool)
+            lines.push(`  ${" ".repeat(28)} ${dim("MCP tool " + tool)}`);
     }
     lines.push("", `Run ${cyan(`beryl ${group} <subcommand> --help`)} for details.`);
     return lines.join("\n");
@@ -197,7 +230,7 @@ export async function runCli(argv) {
             break;
         words.push(tok);
     }
-    if (argv.includes("--version") || argv[0] === "version") {
+    if (argv.includes("--version") || argv.includes("-V") || argv[0] === "version") {
         process.stdout.write(cliVersion() + "\n");
         return EXIT_OK;
     }
@@ -207,15 +240,25 @@ export async function runCli(argv) {
     }
     if (words.length === 0) {
         process.stdout.write(rootHelp() + "\n");
-        return argv.length === 0 || argv.includes("--help") || argv.includes("-h")
+        return rest.length === 0 || rest.includes("--help") || rest.includes("-h")
             ? EXIT_OK
             : EXIT_USAGE;
     }
+    // A group of subcommands, as opposed to a single-word command like `init`, which
+    // commandGroups() also keys under its own name.
+    const groupSpecs = words.length === 1 ? commandGroups().get(words[0]) : undefined;
+    const group = groupSpecs && !(groupSpecs.length === 1 && groupSpecs[0].name === words[0])
+        ? groupSpecs
+        : undefined;
+    // `beryl tests --help` asks about the group, not about the subcommand `beryl tests`
+    // happens to default to — so group help wins over the default's own help.
+    if (group && (rest.includes("--help") || rest.includes("-h"))) {
+        process.stdout.write(groupHelp(words[0], group) + "\n");
+        return EXIT_OK;
+    }
     const found = findCommand(words);
     if (!found) {
-        const groups = commandGroups();
-        const group = groups.get(words[0]);
-        if (group && words.length === 1) {
+        if (group) {
             process.stdout.write(groupHelp(words[0], group) + "\n");
             return EXIT_OK;
         }
@@ -245,7 +288,7 @@ export async function runCli(argv) {
     if (parsed.token)
         config.token = parsed.token;
     const client = new ApiClient(config.apiUrl, config.token);
-    const ctx = createContext({ client, config, json: parsed.json });
+    const ctx = createContext({ client, config, json: parsed.json, mcp: false });
     try {
         const result = (await spec.run(ctx, parsed.input)) ?? {};
         if (parsed.json) {