# Run browser tests locally with the CLI

The optional Zerocheck CLI runs repository tests on your machine, in CI or in a hosted browser. The web app remains available for authoring and hosted runs with no local installation.

## Prerequisites

- Node.js 20.19 or newer.
- Access to a provisioned Zerocheck instance and project.
- A running target app and any required test accounts or fixtures.

Local browser execution still uses Zerocheck's AI service and uploads results and artifacts. It needs network access and authentication. The local browser can reach localhost and private networks available to your machine; the hosted browser needs a URL reachable from the instance.

## Install and authorize

Run these commands from your app's repository. The examples use CLI version 0.1.1.

```bash
npm install --save-dev --save-exact zerocheck@0.1.1
npx zerocheck login
npx zerocheck init --url http://localhost:3000
npx zerocheck install
```

Replace the URL with your app's address. `login` authorizes the machine. `init` writes `zerocheck.yaml` and creates an empty test directory; it does not create or execute a test. `install` downloads Chromium for local runs.

For a dedicated instance using a different service address, set `ZEROCHECK_API` to the URL supplied during onboarding before logging in. In CI, use a project API token in `ZEROCHECK_TOKEN`.

## Import, review and save

Create `release-checklist.md` using the [checklist format](https://tryzerocheck.com/docs/checklist/), then run:

```bash
npx zerocheck import release-checklist.md --env dev --runner local
```

Read the output states and the exact drafted YAML. Open Recent drafts in your Zerocheck instance to inspect the imported tests, screenshots and failed steps. Import prints a draft identifier rather than a results URL. Import exits nonzero while any item is not verified passing; the draft remains available for review.

After reviewing, replace `DRAFT_ID` with the identifier from your import and save its drafted tests:

```bash
npx zerocheck import --draft DRAFT_ID
npx zerocheck validate
npx zerocheck run --env dev --runner local
```

Adoption saves the available drafted definitions; it does not make failed tests pass. Check the draft before adopting it, and resolve missing inputs or edit the saved YAML as needed. Do not skip saving: `run` needs tests in the configured test directory.

## Choose where the browser runs

```bash
npx zerocheck run --env staging --runner hosted
```

Configure the selected environment's URL and login steps first. Local and hosted describe browser location; dev, staging and production describe which environment to test. There is no automatic tunnel from a hosted browser to localhost.

## Save reports and inspect a run

```bash
npx zerocheck run --env dev --json .zerocheck/latest-run.json --junit .zerocheck/junit.xml
npx zerocheck results RUN_ID --json
```

The CLI prints test outcomes, failed steps and a results URL. JSON and the web app contain full attempts and artifact links. `--fail-on-flaky` can make a blocking test that passed after a transient retry fail your CI policy.

| Exit code | Meaning |
| --- | --- |
| 0 | Execution completed within the merge policy. |
| 1 | A blocking test failed, or a blocking flaky test failed the `--fail-on-flaky` policy. |
| 2 | Setup, configuration, policy, infrastructure, cancellation or incomplete execution prevented a complete result. |

Use `npx zerocheck doctor --env dev --runner local` to check setup. See [GitHub Actions](https://tryzerocheck.com/docs/github-actions/), [MCP](https://tryzerocheck.com/docs/mcp/) and the [test reference](https://tryzerocheck.com/docs/test-format/).

---
Canonical: https://tryzerocheck.com/docs/cli/
Updated: 2026-09-14