CLI Reference

Set up Beryl in this repo — sign in, pin a project, wire up your coding agent (interactive)

One-command onboarding: signs you in (emailed one-time code), pins this repo to a workspace and project via .beryl.json (offering to create the project — the agent starts exploring and authoring tests immediately), and writes the MCP server config for your coding agent (.mcp.json for Claude Code, .cursor/mcp.json for Cursor). Safe to re-run; every step skips what is already set up.

• --editor-tools <claude-code|cursor|both|none> — Which coding agent to write MCP config for (default: auto-detect)
• --no-pin — Skip writing .beryl.json
• --local — Also wire the Playwright MCP so your coding agent can drive a local browser (for authoring tests yourself). Default: on whenever a coding agent is wired; pass --no-local to skip it

Also accepts --workspace and --project — see Configuration.

npx @beryl-so/cli@latest init
beryl init --editor-tools claude-code
beryl init --project https://app.example.com --editor-tools none

Authenticate the CLI with your Beryl account (interactive)

Signs in with an emailed one-time code and mints a personal access token, which is stored in the CLI config. Pass --token to use an existing token from Account → API tokens instead. In CI, prefer the BERYL_API_KEY environment variable.

• --token <string> — Use an existing personal access token
• --email <string> — Email for the one-time code sign-in (default: your last sign-in, or your git user.email — offered as the prompt default)
• --token-name <string> — Name for the minted token (default: CLI on <hostname>)

beryl login
beryl login --token beryl_pat_…
beryl login --email [email protected]

Remove the stored token from the CLI config

• --revoke — Also revoke the token server-side so it can never be used again

Show the signed-in account and the CLI's resolved defaults

List your personal access tokens

Mint a new personal access token (shown once)

• name — A label for the token

• --expires-at <string> — Expiry as an ISO timestamp (default: never)

Revoke a personal access token

• token-id — Token id from `beryl tokens list`

List workspaces you belong to

Show one workspace

Also accepts --workspace — see Configuration.

Create a workspace

• name — Workspace name

• --domain <string> — Company domain to associate
• --visible-to-org — Let anyone on your email domain discover and join it

Rename a workspace or change its visibility

• --name <string> — New name
• --visible-to-org — Toggle org discoverability
• --autofix — Toggle autofix

Also accepts --workspace — see Configuration.

Delete a workspace and everything in it

• --force — Skip the confirmation prompt

Also accepts --workspace — see Configuration.

Set the default workspace for future commands

• workspace — Workspace id or name

Show the workspace's action history (who did what, when)

Also accepts --workspace — see Configuration.

Leave a workspace you are a member of

• --force — Skip the confirmation prompt

Also accepts --workspace — see Configuration.

List workspace members

Also accepts --workspace — see Configuration.

Change a member's role

• user-id — Member's user id
• role — OWNER or USER

Also accepts --workspace — see Configuration.

Remove a member from the workspace

• user-id — Member's user id

• --force — Skip the confirmation prompt

Also accepts --workspace — see Configuration.

Invite someone to the workspace by email

• email — Invitee email

• --role <OWNER|USER> — Role (default USER)

Also accepts --workspace — see Configuration.

List the workspace's outstanding invitations

Also accepts --workspace — see Configuration.

Revoke a pending invitation

• invitation-id — Invitation id

Also accepts --workspace — see Configuration.

List invitations sent to you

Accept an invitation (by id, or by the token from the invite email)

• invitation — Invitation id or emailed token

Decline an invitation

• invitation-id — Invitation id

List projects in the workspace

Also accepts --workspace — see Configuration.

Show one project, including its current exploration state

Also accepts --workspace and --project — see Configuration.

Create a project — the agent starts exploring and authoring tests immediately

• url — Root URL of the site to test

• --auth <public|gated> — Whether the site needs a login (gated) or not (public). Default: detected from the site — only asked when detection is genuinely unsure
• --allow-mutations — Let the agent perform state-changing actions while exploring
• --force-new-login — Ignore any reusable saved login
• --no-explore — Create the project without starting the cloud exploration — author tests yourself via `beryl tests create` or your coding agent over MCP
• --watch — Stream the agent's exploration live
• --timeout <number> — With --watch: max minutes to wait

Also accepts --workspace — see Configuration.

beryl projects create https://app.example.com --watch
beryl projects create https://app.example.com --auth gated
beryl projects create https://app.example.com --auth public --no-explore

Rename a project

• name — New name

Also accepts --workspace and --project — see Configuration.

Delete a project and all its tests and runs

• --force — Skip the confirmation prompt

Also accepts --workspace and --project — see Configuration.

Send the agent back in — run/heal existing tests and discover new flows

• --watch — Stream the agent's exploration live
• --timeout <number> — With --watch: max minutes to wait

Also accepts --workspace and --project — see Configuration.

Aggregate quality report across recent runs (pass rates, flaky tests, trend)

• --runs <number> — How many recent runs to aggregate
• --env <string> — Limit to one environment id

Also accepts --workspace and --project — see Configuration.

Check whether a saved login can be reused for a URL before creating a project

• url — The URL you plan to test

Also accepts --workspace — see Configuration.

Set the default project for future commands

• project — Project id, name, or URL

Also accepts --workspace — see Configuration.

List a project's environments

Also accepts --workspace and --project — see Configuration.

Show one environment

• env-id — Environment id

Also accepts --workspace and --project — see Configuration.

Add an environment (e.g. staging) to a project

• name — Environment name
• url — Root URL for this environment

• --auth <public|gated> — Whether this environment needs a login
• --allow-mutations — Allow state-changing actions

Also accepts --workspace and --project — see Configuration.

Update an environment's name, URL, or auth settings

• env-id — Environment id

• --name <string> — New name
• --url <string> — New root URL
• --auth <public|gated> — New auth choice

Also accepts --workspace and --project — see Configuration.

Delete an environment

• env-id — Environment id

• --force — Skip the confirmation prompt

Also accepts --workspace and --project — see Configuration.

Show the project's daily/weekly run schedule

Also accepts --workspace and --project — see Configuration.

Enable scheduled runs (daily, or weekly on a given day)

• --frequency <daily|weekly> — How often (default daily)
• --day <number> — Weekly only: day of week, 0=Monday … 6=Sunday
• --hour <number> — Hour of day 0-23
• --minute <number> — Minute 0-59
• --tz <string> — IANA timezone (e.g. America/Los_Angeles)

Also accepts --workspace and --project — see Configuration.

beryl schedule set --frequency daily --hour 6 --tz UTC

Turn scheduled runs off

Also accepts --workspace and --project — see Configuration.

Validate a plan JSON file offline, before sending it to the server

Checks a plan against the published ActionPlan JSON Schema — every action's required fields, plus the two structural rules (the first EXECUTED step must be a goto, and at least one step across before + steps must be an expect). Runs entirely locally, so a malformed plan fails here instead of costing a server round-trip. Schema: https://api.beryl.so/api/v1/schemas/action-plan.schema.json

• --file <string> — Plan JSON file, or - for stdin (required)

beryl tests lint --file plan.json

List the project's tests with their latest result

• --env <string> — Filter by environment id

Also accepts --workspace and --project — see Configuration.

Show one test

• test-id — Test id

Also accepts --workspace and --project — see Configuration.

Print a test's current step plan (JSON)

• test-id — Test id

Also accepts --workspace and --project — see Configuration.

Create a test case from a JSON action plan — for tests authored locally, e.g. by your coding agent

The plan is a JSON object whose steps are {action, selector, url, value, ...}: the first EXECUTED step must be a goto, and at least one step must be an expect. By default the plan is verified in a real browser before the test is accepted. Optional `before` and `after` arrays hold setup and teardown steps: `after` runs even when a main step fails, which is how a create/update/delete test cleans up the record it made on the runs that go red.

• --title <string> — Title for the new test (required)
• --file <string> — Plan JSON file, or - for stdin (required)
• --no-verify — Skip the compile-time browser/AI verification — trust the authored plan as-is

Also accepts --workspace and --project — see Configuration.

beryl tests create --title "Checkout happy path" --file plan.json

Replace a test's step plan from a JSON file (creates a new version)

Accepts the same plan shape as `tests create`, including the optional `before` and `after` sections — `after` runs on pass and on fail, so cleanup happens even when the test goes red.

• test-id — Test id

• --file <string> — Plan JSON file, or - for stdin (required)

Also accepts --workspace and --project — see Configuration.

beryl tests plan 4f… > plan.json  # edit, then:
beryl tests set-plan 4f… --file plan.json

Rename a test

• test-id — Test id
• title — New title

Also accepts --workspace and --project — see Configuration.

beryl tests rename 4f… "Checkout happy path"

Mute a flaky test: it keeps running, but its failures stop failing the run

A quarantined test still executes and its result is still recorded and visible — its red just doesn't count towards the run's verdict, so it can't red-light a deploy. Use it on a persistently flaky test instead of deleting it (which destroys the history) or asking support to deactivate it (which stops it running at all). `off` un-quarantines.

• test-id — Test id
• state — on | off

Also accepts --workspace and --project — see Configuration.

beryl tests quarantine 4f… on
beryl tests quarantine 4f… off

Delete a test, its version history, and its results

• test-id — Test id

• --force — Skip the confirmation prompt

Also accepts --workspace and --project — see Configuration.

Validate + verify an edited plan against the live site before persisting

• test-id — Test id

• --file <string> — Plan JSON file, or - for stdin (required)

Also accepts --workspace and --project — see Configuration.

List a test's version history

• test-id — Test id

• --limit <number> — Page size
• --cursor <number> — Continue from a previous next_cursor

Also accepts --workspace and --project — see Configuration.

Show one specific version of a test (including its plan)

• test-id — Test id
• version-no — Version number

Also accepts --workspace and --project — see Configuration.

Diff two versions of a test's plan

• test-id — Test id
• from — From version number
• to — To version number

Also accepts --workspace and --project — see Configuration.

Restore a test to an earlier version

• test-id — Test id
• version-no — Version number to restore

Also accepts --workspace and --project — see Configuration.

Discard user edits and return the test to its latest system-authored version

• test-id — Test id

Also accepts --workspace and --project — see Configuration.

Turn self-healing on or off for a test

• test-id — Test id
• state — on or off

Also accepts --workspace and --project — see Configuration.

Pass/fail history, streak, and stability for a test

• test-id — Test id

• --limit <number> — How many runs of history
• --env <string> — Filter by environment id

Also accepts --workspace and --project — see Configuration.

Print the rendered Playwright spec for a test

• test-id — Test id

Also accepts --workspace and --project — see Configuration.

Export tests as Playwright .spec.ts files in a ZIP

• test-ids... — One or more test ids

• --out <string> — Output file (default beryl-tests.zip)

Also accepts --workspace and --project — see Configuration.

Trigger a test run (whole suite, a subset, or one environment)

Runs execute in Beryl's cloud. With --watch the CLI streams live progress and exits 0 only if every test passed — wire it straight into CI.

• --test <strings> — Run only these test ids (repeatable)
• --env <string> — Environment id to run against
• --url-override <string> — Replace the base URL (preview deploys)
• --watch — Stream progress and exit non-zero on failure
• --timeout <number> — With --watch: max minutes to wait
• --retries <number> — Retry a failing test up to N times (0 disables); omit for the default

Also accepts --workspace and --project — see Configuration.

beryl runs trigger --watch
beryl runs trigger --url-override https://preview-123.example.com --watch --timeout 30
beryl runs trigger --test 4f… --test 9a…
beryl runs trigger --retries 0 --watch

List recent runs

• --env <string> — Filter by environment id

Also accepts --workspace and --project — see Configuration.

Show one run with its per-test results

Over MCP the failure screenshots come back as viewable image content, so an agent can look at the page that broke instead of guessing from the error string. Set screenshots to false to skip fetching them. Ignored outside MCP — the terminal cannot show an image.

• run-id — Run id

• --screenshots — Attach failure screenshots as image content (MCP only; default true)

Also accepts --workspace and --project — see Configuration.

Attach to a run and stream progress until it finishes

Replays what already happened, then follows live. Exits 0 only if every test passed.

• run-id — Run id

• --timeout <number> — Max minutes to wait

Also accepts --workspace and --project — see Configuration.

Cancel an in-flight run

• run-id — Run id

Also accepts --workspace and --project — see Configuration.

Show the generated report for a run

• run-id — Run id

Also accepts --workspace and --project — see Configuration.

Download a run's results, with its artifacts, to disk

With --dir, fetches the artifact bytes — screenshots, DOM snapshots, the Playwright trace zip, and the filmstrip frames of the failing tests — into <dir>/<test-result-id>/ alongside a run.json manifest. Artifact URLs are short-lived, so download rather than stash them. With --out (or neither), writes only the JSON manifest.

• run-id — Run id

• --dir <string> — Write run.json plus the artifact files into this directory
• --all-frames — With --dir: also fetch the filmstrip frames of passing tests
• --out <string> — Write the JSON to a file instead of stdout

Also accepts --workspace and --project — see Configuration.

beryl runs download 7c1… --dir ./beryl-run
beryl runs download 7c1… --out run.json

AI explanation of why a test result failed

• result-id — Test result id (from `beryl runs get`)

Also accepts --workspace and --project — see Configuration.

List the agent's exploration passes for a project

Also accepts --workspace and --project — see Configuration.

Show one exploration: authored tests, abandoned flows, coverage, frontier

• exploration-id — Exploration id

Also accepts --workspace and --project — see Configuration.

List every step the agent took in an exploration

• exploration-id — Exploration id

Also accepts --workspace and --project — see Configuration.

Stream an exploration live — watch the agent explore and author tests

Replays every recorded step on connect, then follows live until the exploration completes or fails.

• exploration-id — Exploration id

• --timeout <number> — Max minutes to wait

Also accepts --workspace and --project — see Configuration.

List the project's config variables (visible to the agent during runs)

Also accepts --workspace and --project — see Configuration.

Create or update a config variable

• key — Variable name
• value — Variable value

• --env <string> — Scope to one environment id

Also accepts --workspace and --project — see Configuration.

Delete a config variable

• key — Variable key or id

Also accepts --workspace and --project — see Configuration.

List the project's secrets (values are never returned)

Also accepts --workspace and --project — see Configuration.

Create a secret (write-only; re-setting a key replaces it)

• key — Secret name
• value — Secret value (or - to read from stdin)

• --env <string> — Scope to one environment id

Also accepts --workspace and --project — see Configuration.

Delete a secret

• key — Secret key or id

Also accepts --workspace and --project — see Configuration.

List files uploaded for the agent to use (e.g. CSVs, upload fixtures)

Also accepts --workspace and --project — see Configuration.

Upload a file

• file — Path to the local file

• --env <string> — Scope to one environment id

Also accepts --workspace and --project — see Configuration.

Get a short-lived download URL for a file

• file-id — File id

Also accepts --workspace and --project — see Configuration.

Delete an uploaded file

• file-id — File id

• --force — Skip the confirmation prompt

Also accepts --workspace and --project — see Configuration.

List the workspace's saved logins

Also accepts --workspace — see Configuration.

Show one saved login (status and freshness — never the session itself)

• credential-id — Credential id

List the projects using a saved login

• credential-id — Credential id

Delete a saved login

• credential-id — Credential id

• --force — Skip the confirmation prompt

Attach a saved login to a project

• credential-id — Credential id

Also accepts --workspace and --project — see Configuration.

Detach the project's saved login

Also accepts --workspace and --project — see Configuration.

Start a re-capture for an expiring saved login (returns a live browser URL)

• credential-id — Credential id

Capture a login for the project interactively: log in once in a real browser (interactive)

Opens a live cloud-browser session on the project's site. Log in there like a normal user, come back, and press Enter — Beryl captures the session (encrypted at rest, never shown to anyone) so the agent can test the authenticated app.

Also accepts --workspace and --project — see Configuration.

Start a login-capture browser session for the project (non-interactive)

Also accepts --workspace and --project — see Configuration.

Capture the session after the user has logged in via the live-view URL

• session-id — Session id from auth-capture start

Also accepts --workspace and --project — see Configuration.

Capture a refreshed session for a project whose login is expiring

• session-id — Session id from auth-capture start

Also accepts --workspace and --project — see Configuration.

Release a login-capture browser session without capturing

• session-id — Session id from auth-capture start

Also accepts --workspace and --project — see Configuration.

Show your account profile

Update your profile

• --name <string> — New display name
• --newsletter — Toggle the newsletter subscription

Preview what deleting your account would remove or leave

Send product feedback to the Beryl team

• message — Your feedback

Show plan usage: services and weekly AI units

Also accepts --workspace — see Configuration.

Show the workspace's subscription

Also accepts --workspace — see Configuration.

List recent invoices

• --limit <number> — How many invoices

Also accepts --workspace — see Configuration.

Get a Stripe billing-portal link for the workspace

Also accepts --workspace — see Configuration.

Run the Beryl MCP server (stdio) — every CLI command as an agent tool

Exposes the CLI's commands as MCP tools over stdio, so coding agents (Claude Code, Cursor, …) can create projects, trigger runs, watch the agent, and edit tests. Authenticate via BERYL_API_KEY or a prior `beryl login`.

claude mcp add beryl -- beryl mcp