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) that exposes every command to coding agents.

Quickstart — one command

npx @beryl-so/cli@latest init

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

npm install -g @beryl-so/cli   # `beryl` on your PATH
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 BERYL_NO_UPDATE_CHECK=1 to opt out.

Authenticate

beryl login                  # emailed one-time code; mints + stores a personal access token
export BERYL_API_KEY=beryl_pat_…   # CI: use a token from Account → API tokens

Defaults can be pinned per repo in a .beryl.json ({"workspace": "…", "project": "…"}) or globally via beryl workspaces use / beryl projects use. Precedence: flags > BERYL_* env > .beryl.json > ~/.config/beryl/config.json.

CI in one line

beryl runs trigger --url-override "$PREVIEW_URL" --watch --timeout 30

Exit codes: 0 success / all tests passed · 1 failure · 2 usage error · 3 auth error.

MCP server

claude mcp add beryl -- npx -y @beryl-so/cli mcp    # no install needed
claude mcp add beryl -- beryl mcp                    # or, with the CLI installed

Every non-interactive command below is exposed as an MCP tool with the same name (spaces and dashes become underscores).

Commands

init

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

Authenticate the CLI with your Beryl account

| Command | Summary | MCP tool | | --- | --- | --- | | beryl login | Authenticate the CLI with your Beryl account | — |

signup

Register a new Beryl account (emails a 6-digit verification code)

| Command | Summary | MCP tool | | --- | --- | --- | | beryl signup | Register a new Beryl account (emails a 6-digit verification code) | signup |

logout

Remove the stored token from the CLI config

| Command | Summary | MCP tool | | --- | --- | --- | | beryl logout | Remove the stored token from the CLI config | logout |

whoami

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

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

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

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

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

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

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

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

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

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

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 cancel <exploration-id> | Cancel an in-flight exploration | explorations_cancel | | beryl explorations watch <exploration-id> | Stream an exploration live — watch the agent explore and author tests | explorations_watch |

config

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 get <key> | Show one config variable | config_vars_get | | 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 get <key> | Show one secret's metadata (the value is never returned) | 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 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 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 |

slack

Send run outcomes to a Slack channel via a per-project incoming webhook.

beryl slack with no subcommand runs slack show.

| Command | Summary | MCP tool | | --- | --- | --- | | beryl slack show | Show the project's Slack alert config (webhook is masked) | slack_show | | beryl slack set-webhook <url> | Set the Slack incoming-webhook URL run alerts post to | slack_set_webhook | | beryl slack clear | Remove the project's Slack webhook (stops all alerts) | slack_clear | | beryl slack test | Post a sample alert to the configured webhook | slack_test |

credentials

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

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 login <session-id> | Log into the target site headlessly with credentials (no human at the browser) | auth_capture_login | | 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 |

inbox

Disposable email inboxes for testing flows that send mail — signups, OTPs, receipts.

| Command | Summary | MCP tool | | --- | --- | --- | | beryl inbox create | Mint a disposable email inbox that Beryl receives mail for | inbox_create | | beryl inbox list | List the workspace's inboxes, newest first | inbox_list | | beryl inbox read <inbox-id> | Read the latest email from an inbox (waits for one to arrive) | inbox_read | | beryl inbox emails <inbox-id> | List the emails an inbox has received | inbox_emails |

account

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

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

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

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)
• -h, --help — Show help