---
title: CLI
description: Commands, flags, output formats, and exit codes.
"og:image": "https://e2e.com/docs/images/og/reference/cli.png?v=e0e03be674"
"twitter:image": "https://e2e.com/docs/images/og/reference/cli.png?v=e0e03be674"
---
The `e2e` command scaffolds a project, runs, lists, and explores tests,
manages the replay cache, subscription logins, and telemetry, and upgrades
itself. Every command takes `--help`.
```bash npm
npx e2e init # scaffold a project
npx e2e run # run every test
npx e2e run tests/signup.e2e.ts --headed # one file, with a visible browser
```
```bash pnpm
pnpm dlx e2e init # scaffold a project
pnpm exec e2e run # run every test
pnpm exec e2e run tests/signup.e2e.ts --headed # one file, with a visible browser
```
```bash bun
bunx e2e init # scaffold a project
bunx e2e run # run every test
bunx e2e run tests/signup.e2e.ts --headed # one file, with a visible browser
```
The CLI needs Node.js 24.8 or newer (22.22.3 or newer on Node.js 22), or
[Bun](#bun) 1.4.3 or newer. Any package manager installs it: npm, pnpm, Yarn
with or without Plug'n'Play, or Bun. Under Yarn Plug'n'Play on Node.js 24.8
through 24.11.0, a `.cts` file fails to load: Node.js rejects the source
Yarn's loader hands on. 24.11.1 and later load it.
## Reference
### Help and version
| Option | Description |
| --- | --- |
| `-h`, `--help` | Prints the help of the command it follows and exits 0. `e2e help run` equals `e2e run --help`. |
| `-v`, `--version` | Prints the installed `e2e` version and exits 0. |
```console
$ npx e2e --version
0.14.0
```
- Output is colored on a terminal or in CI, and plain when piped or when
`NO_COLOR` is set. `FORCE_COLOR` keeps the colors.
- `e2e` without a command prints the help on stderr and exits 2.
- On a terminal 52 or more columns wide, `e2e --help` opens with the e2e
logo in block characters. Piped output and
narrower terminals get the text alone.
- When a newer `e2e` is on npm, a command run on a terminal ends with the
version, the [`e2e upgrade`](#e2e-upgrade) command for the project's
package manager, and a link to star e2e on GitHub. The
registry is checked once a day. Nothing prints in CI, when stderr is not a
terminal, for `e2e mcp` and `e2e upgrade`, or with
`E2E_UPDATE_CHECK_DISABLED=1`, `NO_UPDATE_NOTIFIER=1`,
`E2E_TELEMETRY_DISABLED=1`, or `DO_NOT_TRACK=1` set.
### Commands
| Command | Description |
| --- | --- |
| [`e2e init`](#e2e-init) | Scaffolds a project |
| [`e2e login`](#e2e-login) | Signs in to a model subscription |
| [`e2e logout`](#e2e-logout) | Forgets a stored login |
| [`e2e models`](#e2e-models) | Lists a stored login's models |
| [`e2e guide`](#e2e-guide) | Prints the agent skill |
| [`e2e mcp`](#e2e-mcp) | Serves live sessions over MCP |
| [`e2e run`](#e2e-run) | Runs the tests |
| [`e2e explore`](#e2e-explore) | Explores the app toward a goal |
| [`e2e list`](#e2e-list) | Prints the tests a run selects |
| [`e2e doctor`](#e2e-doctor) | Checks that a run can start |
| [`e2e cache`](#e2e-cache) | Inspects or clears the replay cache |
| [`e2e report`](#e2e-report) | Opens the HTML report in a browser |
| [`e2e upgrade`](#e2e-upgrade) | Upgrades e2e and its packages |
| [`e2e feedback`](#e2e-feedback) | Sends feedback to the e2e team |
| [`e2e telemetry`](#e2e-telemetry) | Shows or switches usage telemetry |
An option with no default listed is off unless given.
#### `e2e init`
Scaffolds a project and adds `e2e` to `devDependencies`. It skips existing
config and test files.
```bash npm
npx e2e init --yes
npx e2e init --yes --gateway openrouter --skills .agents/skills --mcp .mcp.json --install
```
```bash pnpm
pnpm dlx e2e init --yes
pnpm dlx e2e init --yes --gateway openrouter --skills .agents/skills --mcp .mcp.json --install
```
```bash bun
bunx e2e init --yes
bunx e2e init --yes --gateway openrouter --skills .agents/skills --mcp .mcp.json --install
```
| Option | Description |
| --- | --- |
| `[directory]` | Where to scaffold; created when missing. Default: the working directory. |
| `-y`, `--yes` | Skips the prompts. Each answer not given as a flag takes its default: Web engine, Vercel AI Gateway, skill and MCP config in both locations, no CI pipeline, no install. |
| `--example ` | Starts from an example app: `with-vite`, `with-next`, `with-astro`, `with-angular`, `with-expo`, `with-swiftui`, `with-compose`, `with-kotlin-multiplatform`, `with-flutter`, or `with-maui`. The `with-` prefix is optional. See [Starting from an example](#starting-from-an-example). |
| `--engine ` | The engines for a new config: `web`, `mobile`, or `none`. Comma-separated or repeated; `web,mobile` writes a target for each. Default: asked. |
| `--gateway ` | The model gateway for agent steps in a new config: `vercel`, `openrouter`, `openai-compatible`, `chatgpt`, `copilot`, `opencode-console`, `grok`, or `none`. Default: asked. |
| `--endpoint ` | Base URL for `--gateway openai-compatible`, and implies it. HTTPS, or HTTP on a loopback host. Default: asked; `http://127.0.0.1:11434/v1` with `--yes`. |
| `--skills ` | Where to install the agent skill: `.agents/skills`, `.claude/skills`, or `none`. Comma-separated or repeated. Default: asked. |
| `--mcp ` | Where to register the MCP server: `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, or `none`. Comma-separated or repeated. Default: asked. |
| `--ci ` | The CI pipeline for the tests, one job per platform: `github-actions`, `gitlab`, or `none`. See [CI pipeline](#ci-pipeline). Default: asked; `none` with `--yes`. |
| `--install`, `--no-install` | Whether to install dependencies. Default: asked; `--no-install` with `--yes`. |
- A flag answers its question and skips that prompt.
- `--engine`, `--gateway`, and `--endpoint` apply only to a new config. With
`--example` they are a usage error.
| Exit code | When |
| --- | --- |
| 0 | The scaffold finished, or the wizard was cancelled. Cancelling leaves files untouched and removes a copied example. |
| 2 | An unknown flag value. Exits before any write and lists the valid values. |
| 2 | An invalid `package.json`. Exits before any write. |
| 2 | No terminal on stdin and stdout, and no `--yes`. The message names the flag. |
| 2 | `--example` with a directory that has files in it, or the example download failed. Nothing stays behind. |
| 2 | The dependency installation failed. |
| 130 | Ctrl-C or SIGTERM while the logo is drawn or the example downloads, or SIGINT during the dependency installation. A partial example is removed. |
##### Prompts
On a terminal 52 or more columns wide, the wizard opens with the e2e logo,
shading in from ░ to █, top rows first, in about half a second. With
`--yes`, in CI, on a dumb terminal, or on a terminal under 7 rows, it prints
at once. Piped output and narrower terminals never show it.
On a terminal outside CI, a finished scaffold ends with a link to star e2e on
GitHub, unless init goes straight on to the command it was started for.
For a new project, the wizard asks for:
- **The engines.** Select one, both, or none. **Web** (Playwright, the
default) adds `@e2e-dev/web`. **Mobile (iOS/Android)** adds
`@e2e-dev/mobile`, defaults to iOS on macOS and Android elsewhere, and opens
Settings. Selecting none adds no engine, for HTTP tests or your own.
- **A model provider or subscription for agent steps:** Vercel AI Gateway,
OpenRouter, an OpenAI-compatible endpoint, ChatGPT, GitHub Copilot, OpenCode
Console, or SuperGrok. None is for tests that use only locators. The wizard
adds the required packages and model config. Subscription users then sign
in with [`e2e login`](#e2e-login). See [Models](/models) and
[Subscriptions](/subscriptions).
- **Where to install the agent skill** (see [e2e guide](#e2e-guide)).
`.agents/skills/` serves Codex, Cursor, Copilot, Gemini CLI, OpenCode, and
Zed; `.claude/skills/` serves Claude Code. Both are preselected.
- **Where to register the [MCP server](/reference/mcp).** `.mcp.json` for
Claude Code, `.cursor/mcp.json` for Cursor, `.codex/config.toml` for Codex.
All are preselected. Codex loads the config in trusted projects; start a new
session after installing dependencies.
- **A CI pipeline** for a project with the web or mobile engine: GitHub
Actions or GitLab CI/CD, with a job for each platform. The wizard
preselects the service the repository's remote, `.github/` folder, or
`.gitlab-ci.yml` points to. See [CI pipeline](#ci-pipeline).
After you confirm the file changes, the wizard asks whether to install the
selected dependencies. The installer follows the project's `packageManager`
field or lockfile, then the invoking package manager, then npm.
##### Files
| Creates | Content |
| --- | --- |
| `package.json` | Created as a private ESM package when missing; otherwise gets only the missing dependencies and scripts. Sibling packages (`@e2e-dev/web`, `@e2e-dev/mobile`) get the caret range of the version released with the CLI, or that exact version when the CLI is a prerelease. Adds a `test:e2e` script that runs `e2e run`, unless one exists |
| `e2e.config.ts` | One target per selected engine, with the app in its `app`. Playwright reads `APP_URL` (default `http://localhost:3000`) into `app.url` and shows `app.command` in a comment. Mobile sets `app: { bundleId: 'Settings' }` on iOS and `com.android.settings` on Android, and `workers: 1`. With a gateway, `agents.default` is `{ model, system }` |
| `tests/example.e2e.ts` | An app-open test that passes against any page, plus a commented agent test. Device setup gets a Settings check instead. With both engines, `tests/web.e2e.ts` and `tests/mobile.e2e.ts` instead, each test with `requires: ['browser']` or `requires: ['device']` so the other target skips it |
| `.gitignore` | Appends `node_modules/`, `.e2e/results/`, `.e2e/cache/`, `.e2e/sessions/`, `.e2e/report.json`, `.e2e/ai-trace.json`, `.e2e/timings.json`, `.e2e/junit.xml`, `.e2e/summary.md`, `.e2e/logs/`, and `.e2e/videos/`. Committing the cache is opt-in; see [commit the replay cache](/cache#commit-the-replay-cache) |
| `.agents/skills/e2e/`, `.claude/skills/e2e/` | `SKILL.md` and one `references/.md` per `e2e guide` topic. With both chosen, the Claude Code directory is a relative symlink (`../../.agents/skills/e2e`) to the copy, the layout `npx skills add` produces |
| `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml` | Registers `e2e mcp` without changing other servers |
| `.github/workflows/e2e.yml`, `.gitlab-ci.yml` | With `--ci`: a job for each platform the targets run on. At the repository root, also for a project in a subfolder. See [CI pipeline](#ci-pipeline) |
##### CI pipeline
`--ci github-actions` or `--ci gitlab` writes a pipeline with one job for
each platform the config's targets run on: web, iOS, and Android. A config
with web and mobile targets gets all of its jobs in one file. Each job
installs the dependencies, runs `e2e run --target --reporter
list,junit`, and keeps `.e2e/report.json`, `.e2e/junit.xml`, and
`.e2e/results/`.
```bash npm
npx e2e init --yes --ci gitlab
```
```bash pnpm
pnpm dlx e2e init --yes --ci gitlab
```
```bash bun
bunx e2e init --yes --ci gitlab
```
| Job | GitHub Actions | GitLab CI/CD |
| --- | --- | --- |
| Web | `ubuntu-latest`, with Chromium | The `node` image on GitLab's runners, with Chromium |
| iOS | `macos-26`: builds the app, boots the image's iPhone 17 Pro on a pinned iOS runtime, installs the app | A self-managed Mac: creates a simulator of its own on a pinned runtime |
| Android | `ubuntu-latest` with KVM: builds a release APK, runs it on an API 36 emulator | A self-managed Linux runner with KVM: boots an AVD named `e2e` |
| Service | File | Runs | Model key |
| --- | --- | --- | --- |
| GitHub Actions | `.github/workflows/e2e.yml` | On pull requests and pushes to `main` | A repository secret, passed in the run step's `env` |
| GitLab CI/CD | `.gitlab-ci.yml` | In merge request pipelines and on the default branch. The JUnit report shows in the merge request | A CI/CD variable, which GitLab gives the job |
- `init` reads the targets from the new config it writes, or loads an
existing one the way `e2e run` does, after you confirm the changes and
after the install. When an existing config still doesn't load, `init` says
why and falls back to `package.json`: with only the web engine, one web job
runs every target; with the mobile engine, there's no pipeline.
- The web job runs every target that isn't iOS or Android, HTTP tests
included, and all of them when the config has no mobile target.
- The mobile jobs build the app. An Expo app builds with `expo run:ios` and
`expo prebuild` and Gradle. A bare React Native app builds its
`ios/*.xcworkspace` with `xcodebuild` (through Bundler with a `Gemfile`)
and runs `android/gradlew`. Any other app gets a build step that fails
until you replace it, and `init` names the file to edit.
- The mobile jobs name the device they booted in `E2E_DEVICE`. A target
that names a device reads it with `device: process.env.E2E_DEVICE` in
`mobile()`, so the run drives that device. A target that names none drives
the booted one.
- GitLab's hosted runners can't run a simulator or an emulator, so its
mobile jobs need self-managed runners: set their `tags`. See
[GitLab CI/CD](/ci/gitlab#ios-and-android).
- The file starts from a template the package ships in `templates/ci/`, a
complete pipeline for npm at the repository root and an Expo app. `init`
fills it in for your project and keeps its comments.
- The jobs use the project's package manager, and the Node version in
`.nvmrc` or `.node-version` (24 without one). GitHub reads the file, so it
gets the exact version. GitLab runs the web job in the `node` image of the
file's major version: `node:22` for `22.22.3`. GitHub actions are pinned by
commit.
- `init` names the secret or variable to add, such as `AI_GATEWAY_API_KEY`,
with the `gh` or `glab` command that adds it.
- For a project in a subfolder, the file goes to the repository root and the
jobs run in the subfolder.
- `init` warns when the config has no `app.command`, since nothing else
starts the app on the runner. It also warns about a subscription gateway,
whose sign-in stays on your machine, and an OpenAI-compatible `baseURL` on
your machine: agent steps fail in CI with either.
- An existing pipeline file stays unchanged. Beside an existing
`.gitlab-ci.yml`, `init` writes `.gitlab/e2e.gitlab-ci.yml` and prints the
`include:` lines to add. The jobs run in the `test` stage, and `init` says
when your `stages:` leave it out. Beside a job named like one of them
(`e2e-web`, `e2e-ios`, `e2e-android`), every job's name gets `-run`.
- `init` never writes through a symlinked `.github` or `.gitlab` folder. It
warns and writes nothing.
- A workflow or `.gitlab-ci.yml` that already runs `e2e run` gets nothing,
and neither does a project without the web or mobile engine.
##### Starting from an example
`--example` copies one of the
[example apps](https://github.com/e2e-inc/e2e/tree/main/examples) into a
new or empty directory, then runs the wizard in its e2e project. That is
the directory itself for a web or Expo app, and its `e2e/` folder for a
native app.
```bash npm
npx e2e init my-app --example with-expo
```
```bash pnpm
pnpm dlx e2e init my-app --example with-expo
```
```bash bun
bunx e2e init my-app --example with-expo
```
- The CLI downloads the example from GitHub, from the `e2e@` tag
of the running CLI. When that tag doesn't exist, it uses `main` and warns.
- A directory that holds only `.git`, `.DS_Store`, or `Thumbs.db` counts as
empty.
- The example's config, tests, and scripts stay as they are. The wizard
asks only for the skill, the MCP server, and the install, and adds missing
`.gitignore` entries. For a native app these files go in `e2e/`, so open
your coding agent there.
- The e2e project's `package.json` takes the directory's name (with `-e2e`
beside a native app). `e2e`, `@e2e-dev/web`, and `@e2e-dev/mobile` get the
ranges `init` writes for a new project.
- The closing `Next:` line names the example's test script. A native app
needs a build first; its `README.md` says how.
##### Re-running init
- An existing config and existing test files stay byte-for-byte unchanged.
The engine and gateway answers apply to a new config only, so their
packages are not added. A missing example test is still created, unless
per-engine examples exist.
- `package.json` and `.gitignore` are still updated with what they lack: the
`e2e` dev dependency, the `test:e2e` script, and the ignore entries.
Existing dependencies, scripts, and entries stay as they are.
- MCP registration keeps extra settings on the e2e server, such as
environment variables and client timeouts, even when it repairs the launch
command. A current registration stays byte-for-byte unchanged.
- Once a skill directory exists, later runs refresh copies that differ from
the installed version. They never add a directory the project did not
choose. `--skills` and `--mcp` name the exact locations instead and leave
the others as they are.
- A `.claude/skills/e2e/` copy from an earlier version becomes the symlink
when it holds only the shipped files. A copy with other files stays a copy
and is refreshed.
- `init` never writes through a skill directory that is a symlink elsewhere,
or sits under one. `--yes` skips it with a warning naming the link and its
target. An interactive run offers to replace it with a copy, or with the
link where the link goes.
- A copy with a directory where a file goes, or a file where a directory
goes, is skipped with a warning naming the entry. `init` removes nothing to
repair it.
- An MCP config file reached through a symlink, or under a linked directory,
is skipped with the same warning and left unchanged, so the server is not
registered there. A plain config is merged as usual.
#### `e2e login`
Signs in to a subscription and stores the credentials in
`$XDG_CONFIG_HOME/e2e/oauth.json`, by default `~/.config/e2e/oauth.json`. See
[Subscriptions](/subscriptions) for the model configuration.
```bash npm
npx e2e login openai # ChatGPT, browser sign-in
npx e2e login openai --device # sign in with a device code
npx e2e login github-copilot --from-gh # use your GitHub CLI login
npx e2e login github-copilot --client-id [--enterprise-url ]
npx e2e login opencode-console # OpenCode Console, device code
npx e2e login spacexsi # SuperGrok, device code
npx e2e login # choose a provider
```
```bash pnpm
pnpm exec e2e login openai # ChatGPT, browser sign-in
pnpm exec e2e login openai --device # sign in with a device code
pnpm exec e2e login github-copilot --from-gh # use your GitHub CLI login
pnpm exec e2e login github-copilot --client-id [--enterprise-url ]
pnpm exec e2e login opencode-console # OpenCode Console, device code
pnpm exec e2e login spacexsi # SuperGrok, device code
pnpm exec e2e login # choose a provider
```
```bash bun
bunx e2e login openai # ChatGPT, browser sign-in
bunx e2e login openai --device # sign in with a device code
bunx e2e login github-copilot --from-gh # use your GitHub CLI login
bunx e2e login github-copilot --client-id [--enterprise-url ]
bunx e2e login opencode-console # OpenCode Console, device code
bunx e2e login spacexsi # SuperGrok, device code
bunx e2e login # choose a provider
```
| Option | Description |
| --- | --- |
| `[provider]` | The subscription: `openai`, `github-copilot`, `opencode-console`, or `spacexsi`. `spacexai` and `grok` are aliases of `spacexsi`, here and in `logout` and `models`. Default: a picker. |
| `--device` | ChatGPT: shows a code to enter on another device instead of opening a browser. |
| `--from-gh` | GitHub Copilot: reuses the signed-in GitHub CLI's token. |
| `--client-id ` | GitHub Copilot: the client id of your GitHub OAuth App, with the device flow enabled. |
| `--enterprise-url ` | GitHub Copilot: the GitHub Enterprise host. |
| Exit code | When |
| --- | --- |
| 1 | The sign-in failed. |
| 2 | An unknown provider. |
| 130 | The sign-in was cancelled. |
#### `e2e logout`
Forgets the stored login of one provider.
```bash npm
npx e2e logout # pick one of the stored logins
npx e2e logout openai # forget one
```
```bash pnpm
pnpm exec e2e logout # pick one of the stored logins
pnpm exec e2e logout openai # forget one
```
```bash bun
bunx e2e logout # pick one of the stored logins
bunx e2e logout openai # forget one
```
| Option | Description |
| --- | --- |
| `[provider]` | The login to forget: `openai`, `github-copilot`, `opencode-console`, or `spacexsi`. Default: a picker over the stored logins. |
#### `e2e models`
Asks the vendor which models the stored login serves and prints one line per
model. For OpenCode Console it asks with `OPENCODE_API_KEY` when set.
```bash npm
npx e2e models # every stored login
npx e2e models openai # one provider
```
```bash pnpm
pnpm exec e2e models # every stored login
pnpm exec e2e models openai # one provider
```
```bash bun
bunx e2e models # every stored login
bunx e2e models openai # one provider
```
| Option | Description |
| --- | --- |
| `[provider]` | `openai`, `github-copilot`, `opencode-console`, or `spacexsi`. Default: every stored login, plus OpenCode Console when only `OPENCODE_API_KEY` is set. |
Each line holds:
- the id `chatgpt()`, `copilot()`, `opencodeConsole()`, or `grok()` takes;
- the vendor's name for the model;
- its notes: reasoning levels, vision, preview, hidden; for Copilot
`not enabled` or `no chat or responses` when `copilot()` cannot call it;
for OpenCode Console the plan that serves it, Zen or Go.
Only a call finds out whether a Copilot account can use a listed model.
| Exit code | When |
| --- | --- |
| 1 | No credential, or none for the named provider. The message names the sign-in command. |
| 1 | One of several logins failed to list. The others still print. |
| 2 | An unknown provider. |
See [Pick a model](/subscriptions#pick-a-model).
#### `e2e guide`
Prints the skill that `init` installs; `npx skills add e2e-inc/e2e`
installs the same skill. See [Coding agents](/coding-agents).
```bash npm
npx e2e guide # the overview
npx e2e guide setup # one topic
```
```bash pnpm
pnpm exec e2e guide # the overview
pnpm exec e2e guide setup # one topic
```
```bash bun
bunx e2e guide # the overview
bunx e2e guide setup # one topic
```
| Option | Description |
| --- | --- |
| `[topic]` | One of `setup`, `writing-tests`, `agent`, `running`, `explore`, `debugging`, `mcp`, or `bug-bash`. Default: the overview. An unknown topic exits 2 and names the valid ones. |
#### `e2e mcp`
An MCP server on stdio that gives a coding agent a live session on the app.
```bash npm
npx e2e mcp [--config ] [--target ] [--headed] [--max-sessions ]
```
```bash pnpm
pnpm exec e2e mcp [--config ] [--target ] [--headed] [--max-sessions ]
```
```bash bun
bunx e2e mcp [--config ] [--target ] [--headed] [--max-sessions ]
```
| Option | Description |
| --- | --- |
| `--config ` | The config every session loads unless `open_session` names one. Default: the nearest `e2e.config.ts`, `.mts`, `.js`, or `.mjs`. |
| `--target ` | The target every session opens on. Default: the only target, or the one `open_session` names. |
| `--headed` | Shows the UI in sessions whose `open_session` does not set `headed`, when the engine supports it. |
| `--max-sessions ` | Sessions open at once, each with its own browser or device, 1 through 16. Default: 4. On [Bun](#bun), 1. |
The [MCP server](/reference/mcp) page covers these options in full, plus the
tools and the session rules.
#### `e2e run`
Runs the tests the config discovers and writes `report.json` under the
[output directory](/reference/config#output).
```bash npm
npx e2e run
npx e2e run tests/signup.e2e.ts --tag smoke
npx e2e run tests/signup.e2e.ts:12
npx e2e run tests/agent
npx e2e run 'tests/**/*.smoke.e2e.ts'
npx e2e run --target web,webkit --tag smoke,billing --tag-mode all
npx e2e run --tag smoke --exclude-tag slow
npx e2e run --grep checkout --grep-invert '/refund/i'
npx e2e run --last-failed
npx e2e run --changed-since origin/main
npx e2e run --shard 2/3
npx e2e run --reporter json --workers 4 --retries 2
npx e2e run --max-failures 3
npx e2e run --repeat-each 5 --no-cache tests/checkout.e2e.ts
npx e2e run --reporter list,junit
```
```bash pnpm
pnpm exec e2e run
pnpm exec e2e run tests/signup.e2e.ts --tag smoke
pnpm exec e2e run tests/signup.e2e.ts:12
pnpm exec e2e run tests/agent
pnpm exec e2e run 'tests/**/*.smoke.e2e.ts'
pnpm exec e2e run --target web,webkit --tag smoke,billing --tag-mode all
pnpm exec e2e run --tag smoke --exclude-tag slow
pnpm exec e2e run --grep checkout --grep-invert '/refund/i'
pnpm exec e2e run --last-failed
pnpm exec e2e run --changed-since origin/main
pnpm exec e2e run --shard 2/3
pnpm exec e2e run --reporter json --workers 4 --retries 2
pnpm exec e2e run --max-failures 3
pnpm exec e2e run --repeat-each 5 --no-cache tests/checkout.e2e.ts
pnpm exec e2e run --reporter list,junit
```
```bash bun
bunx e2e run
bunx e2e run tests/signup.e2e.ts --tag smoke
bunx e2e run tests/signup.e2e.ts:12
bunx e2e run tests/agent
bunx e2e run 'tests/**/*.smoke.e2e.ts'
bunx e2e run --target web,webkit --tag smoke,billing --tag-mode all
bunx e2e run --tag smoke --exclude-tag slow
bunx e2e run --grep checkout --grep-invert '/refund/i'
bunx e2e run --last-failed
bunx e2e run --changed-since origin/main
bunx e2e run --shard 2/3
bunx e2e run --reporter json --workers 4 --retries 2
bunx e2e run --max-failures 3
bunx e2e run --repeat-each 5 --no-cache tests/checkout.e2e.ts
bunx e2e run --reporter list,junit
```
##### Positional arguments
```bash
e2e run [files...]
```
Test files, directories, or globs relative to the project root:
| Positional | Selects |
| --- | --- |
| A file path (`tests/signup.e2e.ts`) | That file. |
| A directory (`tests/agent`, `.`) | Every discovered test file beneath it. |
| A bare name (`signup.e2e.ts`, `agent/signup.e2e.ts`, `signup`) | Every discovered file whose path ends with it at a segment boundary; the first two both select `tests/agent/signup.e2e.ts`. Without a `/` or `.`, it matches the file name without extensions, so `signup` selects it too. |
| Any of these with `:line` (`tests/signup.e2e.ts:12`, `signup:12`) | Only the test declared at that line of each file it names: the line its `test(` call opens on, as an editor or a report's `source` shows it. |
| A quoted glob (`'tests/**/*.smoke.e2e.ts'`) | Every discovered file it matches, in the grammar of the config `tests` globs: `*`, `?`, and a whole `**` segment. |
- **Lines.** A line that names one member of a serial group runs the group
whole. Several lines of one file add up; the file without a line selects it
whole. When no test is declared at a named line, `NO_TESTS` names the
positional and the lines the file declares tests at. A positional that
exists on disk as written is a path, even when it ends in `:12`.
- **Globs.** Braces, character classes, and extglobs are `INVALID_GLOB` with a
hint, not a pattern that matches nothing. There is no expansion, so name one
glob per alternative. `./`, `..`, a trailing `/`, and an absolute path
inside the project resolve as for any positional path. An existing file or
directory is selected by its path, whatever characters its name holds.
- Positionals narrow the config globs and the tag, platform, and capability
filters; they never bypass them. Names and globs are case-sensitive on
every OS. A path outside the project root is `COLLECTION_ERROR`.
- The runner imports every discovered test file, even when you select a few,
so a selected test finds its session setup in another file. Other ordinary
tests stay unselected. A collection error fails the run when it is in a
selected file, or in any file of a run with no positionals. A file the
positionals left out that fails to import or register its tests is skipped
with a notice. So a half-written file elsewhere does not stop
`npx e2e run tests/login.e2e.ts`. If a selected test's session then has no
setup test, the error names that file as where the setup may be.
- A positional that starts with `-` and names no file is a usage error, exit
2. `pnpm test:e2e -- --headed` produces it: the `--` reaches e2e, which
would otherwise take `--headed` for a file. The message names the direct
form, `pnpm exec e2e run --headed`. For npm it is
`npm exec -- e2e run --headed`; npm needs the separator before the binary
to pass its flags through.
- When nothing is left to run, `NO_TESTS` names the cause: no file matched
the globs (with look-alikes such as `tests/login.test.ts`), a positional
matched nothing (with the nearest path), a matched file registered no
tests, or every test was filtered out.
##### Flags
**Selection**
| Option | Description |
| --- | --- |
| `--config ` | Explicit config path. Default: the nearest `e2e.config.ts`, `.mts`, `.js`, or `.mjs` (see [Loading](/reference/config#loading)). A missing file is `CONFIG_NOT_FOUND`. |
| `--target ` | Targets by name, comma-separated or repeated. Default: every configured target. Only selected targets' app commands start. An unknown ID is `UNKNOWN_TARGET`. |
| `--tag ` | Only tests with the tags, comma-separated or repeated: any of them, or every one with `--tag-mode all`. |
| `--tag-mode ` | How several tags combine: `any` or `all`. Default: `any`. |
| `--exclude-tag ` | Leaves out tests with any of the tags, comma-separated or repeated, whatever `--tag` or a positional selected. A serial group still runs whole when any member is selected; tag the serial `describe` to exclude the flow. |
| `--grep ` | Only tests whose title matches one of the regular expressions; repeatable. The title is the describe titles and the test title joined by one space (`checkout pays`), without the file or the tags. A bare pattern is case-sensitive; `'/pattern/i'` adds flags. A pattern that does not compile is a usage error, exit 2. |
| `--grep-invert ` | Leaves out tests whose title matches one of the regular expressions; repeatable, with the text and forms of `--grep`. With both, the run keeps what `--grep` matches minus what `--grep-invert` matches. |
| `--changed-since [` | Runs the configured [test filters](/filters) on the change since the ref: every file that differs from the merge base of the ref and `HEAD`, uncommitted and untracked files included. Each target starts the files of the tests the filters score likeliest first. Without it, no filter runs. With no filters configured, a warning says every test runs. |
| `--last-failed` | Only the tests the previous run did not pass; the list after these tables says which. |
| `--shard ` | Runs one contiguous slice of the selected tests, such as `2/3`, cut after every other flag. Slices differ by at most one test. A serial group counts as one and is never split. Each shard brings only the setup tests its own tests need. Skipped tests are not cut: the shard that runs the nearest test before one reports it, else the first shard, so only one shard does. Every shard runs the same command with a different index. The order is the report order, so a suite shards the same way on every machine. A shard with no test is `NO_TESTS` unless `--pass-with-no-tests`. See [Sharding](/ci#sharding). |
| `--pass-with-no-tests` | Exits 0 instead of `NO_TESTS` when nothing is selected. A run with nothing to run prepares no engine and starts no app or service command. |
**Execution**
| Option | Description |
| --- | --- |
| `--headed` | Visible UI when the engine supports it. |
| `--agent ` | Runs unpinned tests once per selected agent, comma-separated or repeated. Default: `default`. For a test with `{ agent }`, it selects the shared names when they overlap, else keeps the test's own. An unknown name is `INVALID_CONFIG`. |
| `--retries ` | Replaces `config.retries`; an integer 0-10. Default: the config. |
| `--workers ` | Replaces `config.workers`; an integer 1-1024. Default: the config. |
| `--action-timeout ` | Replaces [`actionTimeout`](/reference/config#actiontimeout) for this run; an integer 1-2147483647, anything else is a usage error, exit 2. Default: the config, else `30000`. A call's own `timeout` still wins. While you write a test, a low value such as `5000` makes a wrong locator fail with `LOCATOR_NOT_FOUND` after 5 s instead of 30 s. |
| `--assertion-timeout ` | Replaces [`assertionTimeout`](/reference/config#assertiontimeout) for this run; an integer 1-2147483647, anything else is a usage error, exit 2. Default: the config, else `5000`. A matcher's own `timeout` still wins. |
| `--max-failures ` | Stops the run once this many tests (at least 1) have failed or timed out. Nothing more is dispatched, and tests running on other workers end `interrupted`. Tests not started, including the rest of the file whose test reached the limit, are skipped with cause `failure-limit` and the reason `run stopped after 3 failures (--max-failures 3)`. Exits 1, the failures' own code, not 130. |
| `--max-duration ` | Overrides [`maxDuration`](/reference/config#maxduration) for one run; an integer 1-2147483647. Default: the config. Exits 1, not 130. |
| `--repeat-each ` | Runs every selected test this many times, at least 1. Default: `1`. Each run is its own result, with `repeat` 0 through `n - 1` and its own `id`. The list reporter titles later runs `(repeat #1)`, `(repeat #2)`, and puts their artifacts under a `repeat-` directory. Setup tests run once. With the replay cache on, the first run records and the rest replay; add `--no-cache` to call the model each time. The `list` summary adds a `Repeats` row (`1 of 2 tests passed all 5 runs`) and one line per test that did not pass every run, naming the failed runs. The `markdown` page has the same tally. |
| `--no-cache` | Turns the replay cache off for this run, whatever `config.cache` says. |
| `--strict-cache` | Turns on `cache.strict` for this run. A step whose recording exists but no longer replays fails with `REPLAY_STALE` instead of handing off to the agent. Retries replay too, and the run never writes the cache. See [Fail on a stale recording](/cache#fail-on-a-stale-recording). |
| `-u`, `--update-snapshots` | Writes each stored screenshot [`toHaveScreenshot`](/reference/expect#screenshot-matchers) finds missing or different, and passes the matcher. Without it, a missing one is written and fails; in CI it is only attached to the results. |
| `-w`, `--watch` | Runs, then reruns when a test file or the config changes, or on a key. See [Watch mode](#watch-mode). |
| `--step` | Runs the first step, then holds each later step until a key at its prompt: Enter runs it, `n` runs the rest of the test, `a` the rest of the run, `h` lists the keys, `q` stops with exit 130. Held time counts toward no timeout. Without a terminal, the run goes on in the background and each command returns at the next held step with its screen: `--step next` runs it, `--step rest` runs the rest, `--step stop` ends the run. `--step next`, `rest`, and `stop` also resume or stop a test at a [`screen.pause()`](/debugging#pause-a-test). Runs one worker; refused in CI, with `--watch`, `--workers` above 1, and the json reporter (exit 2). See [Step through a test](/debugging#step-through-a-test) and [without a terminal](/debugging#step-through-a-test-without-a-terminal). |
**Output**
| Option | Description |
| --- | --- |
| `--reporter ` | Replaces the built-in reporters in `config.reporters`, comma-separated: `list`, `dot`, `json`, `junit`, `markdown`. Default: the config. A built-in the config configured, such as `junit({ outputFile })`, keeps its options. Beside `json`, `list` and `dot` print to stderr. `dot` with `list` is `INVALID_CONFIG`. [Other reporters](/reference/reporters) in the config keep running. |
| `--output ` | The results directory for this run, over the config's [`output`](/reference/config#output): the report, the reporter files, the AI trace, `results/`, and `sessions/`. Default: the config, else `.e2e`. Resolved from the project root, and must be a directory inside it, not the root itself; that and the other directories the run cannot own (listed there) are `INVALID_CONFIG`. `results/` is cleared once the tests start; a `--last-failed` rerun keeps what the previous report names. |
| `--cache-dir ` | The replay cache directory for this run, over [`E2E_CACHE_DIR`](/reference/environment#replay-cache) and [`cache.dir`](/reference/config#cache). Default: `E2E_CACHE_DIR`, else `cache.dir`, else `.e2e/cache`. Resolved from the project root; `~` or a leading `~/` is the home directory. The cache mode stays as configured. With a custom `cache.store` it is `INVALID_CONFIG`. |
| `--timings ` | The [timings history](/ci#cache-the-timings-history) to update when the run ends, over `]