beryl CLI

Beryl on the command line: create projects, author tests, trigger runs in CI, and manage everything the web app can. Coding agents reach the same commands through Beryl's hosted MCP server at https://api.beryl.so/mcp.

Quickstart: one command

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), registers the hosted MCP server in the agent you pick with --claude, --cursor, --vscode or --opencode (it asks when you pass none), and installs the beryl-test authoring skill. 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 version reports whether the running CLI is behind the latest npm release (best-effort). Set BERYL_NO_UPDATE_CHECK=1 to skip that check.

The CLI reports which commands run (never their arguments or output) so onboarding can be measured; set BERYL_TELEMETRY=0 or DO_NOT_TRACK=1 to send nothing.

Authenticate

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 → Personal access tokens

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.

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 · 4 plan limit reached.

A project CI token (BERYL_TOKEN=beryl_ci_…, from the project's Settings, CI tab) is enough to trigger runs and to turn a brief into tests: beryl jobs create "Cover the brief" --file ./brief.md --ci (pass --workspace and --project ids). A CI job never waits for input; what a login blocks is listed as skipped in beryl jobs get.

MCP server

claude mcp add --transport http -s user beryl https://api.beryl.so/mcp

Your agent signs you in through the server's OAuth the first time it connects (in Claude Code, run /mcp and pick beryl). Clients without OAuth send a personal access token as Authorization: Bearer beryl_pat_…. The server is always current, so there is nothing to update.

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. none marks commands kept CLI-only: account/billing/team admin, feedback, cloud exploration, and the commands that read or write your local disk (logout, config files upload, config signing set).

Commands

init

Set up Beryl in this repo: sign in and wire up your coding agent

guide

Print the Beryl test guide, or one of its sections

login

Authenticate the CLI with your Beryl account

signup

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

logout

Remove the stored token from the CLI config

whoami

Show the signed-in account

tokens

Manage the personal access tokens that authenticate the CLI and CI.

workspaces

Create and manage workspaces, and pick the one your commands act on by default.

members

Manage who belongs to a workspace and their roles.

invites

Send, list, and revoke workspace invitations, and accept ones sent to you.

projects

Create and manage projects: a site you author tests for and run.

beryl projects with no subcommand runs projects list.

envs

Manage a project's environments: the URLs and auth Beryl runs tests against.

schedule

Manage the schedules on which Beryl runs a project's tests automatically. A project can hold many independent schedules; each has its own environment, cadence (daily or weekly), local run time, timezone, and target groups (none = every active test).

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.

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.

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.

health

Site Health, or how your site reads to search engines and visitors: content, speed, links, security, and a visual check of layout at phone, tablet and desktop sizes, graded from a real check of your live pages.

beryl health with no subcommand runs health get.

jobs

Test-creation jobs: the cloud agent follows a prompt, a document, or both, and authors tests.

explorations

Inspect the agent's exploration runs: how it crawled a site and authored its tests.

config

Manage the variables, secrets, and files the agent can use while exploring and running.

mailbox

The project's standing email addresses, where its tests receive sign-in mail.

beryl mailbox with no subcommand runs mailbox get.

third-party-integrations

Test a site's own integrations (Connect Slack) against Beryl's accounts on those providers.

beryl third-party-integrations with no subcommand runs third-party-integrations list.

accounts

Durable identities on the site under test: what an authenticated test signs in as.

beryl accounts with no subcommand runs accounts list.

account

View and update your personal account profile.

feedback

Send product feedback to the Beryl team.

billing

Review a workspace's plan usage, subscription, and invoices; upgrade or switch plans.

version

Show the running CLI version, API URL, and Node version

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