CLI

Your saved tests run from one command.

The browser runs on your machine or CI runner, and your instance makes every decision. A blocking failure exits non-zero, so your pipeline can act on it. Prefer nothing to install? Use the web app.

Run your tests
npx zerocheck run --env staging

Version 0.2.1. Node 20.19 or newer. Needs a dedicated Zerocheck instance from onboarding, and Chromium installed with one command.

Your coding agent writes the tests, runs them and reads the results.

Tests are plain YAML files in your repository. Any agent that can edit a file and run a command can add a test, run it with the CLI and read the run record.

Works with

  • CLI
  • Web app
  • VS Code
  • Cursor
  • Claude Code
  • Codex
  • GitHub Copilot
  • Amp

From install to your first CLI run.

The CLI reads zerocheck.yaml and the selected YAML tests, and drives the browser. Your repository supplies the tests and configuration, and your instance keeps the results.

01Install the CLI and its browser

Add zerocheck to devDependencies and download the Chromium browser it drives. You need Node 20.19 or newer.

Terminal
npm install --save-dev --save-exact zerocheck
npx playwright install chromium

02Sign in to your instance

Your instance URL comes from onboarding; there is no default public service. login prints a URL and a code for you to approve in your browser. In CI, set a project token as ZEROCHECK_TOKEN instead.

Terminal
export ZEROCHECK_API="https://your-instance.example.com"
npx zerocheck login
npx zerocheck whoami

03Keep the tests in the repo

Repository tests are YAML files next to your code, and zerocheck.yaml names the project and environments. We set these up with you during onboarding. Download YAML brings a web test across as an independent copy; edits do not synchronize.

zerocheck/tests/release-notes.yaml
version: zerocheck/v1
name: Release notes are available
blocks_merge: true
steps:
  - Navigate to /releases
  - Verify text "Release notes" is visible

04Run them

run executes the selected YAML files in a browser on your machine. A blocking failure exits 1, so a CI job you write can act on it. Require that job in branch protection to enforce your merge policy.

Terminal
npx zerocheck run --env dev
npx zerocheck run zerocheck/tests/release-notes.yaml
npx zerocheck run --env staging --json .zerocheck/latest-run.json

What the CLI gives you.

Your browser, your instance's decisions

The CLI drives Chromium on your machine or CI runner. Your instance reads each test, makes the model calls, chooses each action and keeps the results.

Localhost and private networks

The browser runs where you run the CLI, so it reaches what your machine reaches. It still needs network access to your instance; it does not run offline.

Pick the tests that matter

Pass a file path or a folder. With no path, run uses your configured test directory. Selection is by path only.

Exit codes you can trust

0 when every blocking test passed, 1 for a blocking failure, 2 when the run gave no verdict. A pass after a transient retry is labeled flaky; --fail-on-flaky makes a blocking flaky test exit 1.

A run record your pipeline can read

--json writes the run record to a file. Steps, screenshots and any recording are on your instance, behind its sign-in.

Test secrets stay on your machine

Secrets are environment variable references. Your instance receives their names, not their values, and the CLI types a value only where the test refers to it.

What it looks like.

The output format, with example test names. A failed test names its step, and the link opens the evidence on your instance.

zerocheck run
$ npx zerocheck run --env staging
staging / local: failed (RUN_ID)
  PASS  Release notes are available
  FAIL  Discount code reaches confirmation
    Attempt 1: Verify text "Order confirmed" is visible: <error text>
Results: https://your-instance.example.com/runs/RUN_ID

The CLI, answered.

How do I install the CLI?

Add zerocheck to devDependencies, run npx playwright install chromium, set ZEROCHECK_API to your instance URL, then run npx zerocheck login.

What does zerocheck run do?

It reads zerocheck.yaml and the selected YAML tests, then drives a browser on your machine. It prints each result and a link to the run, which is kept on your instance.

Where do the tests live?

CLI tests live in your repository as YAML files. Tests created in the web app are saved and edited there, and Download YAML creates an independent repository copy. Web and repository edits do not synchronize.

Do I need a token to run tests?

Yes. Sign in with zerocheck login on your machine. In CI, set ZEROCHECK_API and put a project token from Settings in ZEROCHECK_TOKEN.

Which commands does the CLI have?

login, logout, whoami and run. Checklist import and hosted runs are in the web app.

Which report formats does the CLI write?

A JSON run record with --json. That is the only format.

Can a coding agent run these commands?

Yes. An agent can run zerocheck run --json and read the run record and exit code. A person approves the sign-in. The CLI has no MCP server.

Can I run tests without a browser window?

Yes. Runs are headless by default, and --headed shows the browser. Chromium still has to be installed where the CLI runs.

How do I pass secrets to a run?

In zerocheck.yaml, map each secret to an environment variable, such as PASSWORD: ${APP_TEST_PASSWORD}, and set that variable where the CLI runs. Missing values stop the run before it starts. A run whose environment has configured secrets is not recorded on video.

How do I run against a preview deployment?

Point an environment at the preview URL in zerocheck.yaml and select it with --env. Environments are named dev, staging and production. The URL is a literal value, so for a per-pull-request preview, have your job write it into the file first.

Get your instance set up.

US$500 in credits at sign up, then US$500/month: a dedicated instance for your team, with hands-on setup of your first tests.

Book a setup callContact sales