---
title: CLI
description: Commands, flags, output formats, and exit codes.
---
```bash npm
npx e2e init [directory]
npx e2e login [provider]
npx e2e logout [provider]
npx e2e models [provider]
npx e2e guide [topic]
npx e2e mcp [options]
npx e2e run [files...] [options]
npx e2e explore [goal] [options]
npx e2e list [files...] [options]
npx e2e cache ls|clear|stats [--config ]
npx e2e feedback -m [options]
npx e2e telemetry [status|enable|disable]
npx e2e --help
npx e2e --version
```
```bash pnpm
pnpm dlx e2e init [directory]
pnpm exec e2e login [provider]
pnpm exec e2e logout [provider]
pnpm exec e2e models [provider]
pnpm exec e2e guide [topic]
pnpm exec e2e mcp [options]
pnpm exec e2e run [files...] [options]
pnpm exec e2e explore [goal] [options]
pnpm exec e2e list [files...] [options]
pnpm exec e2e cache ls|clear|stats [--config ]
pnpm exec e2e feedback -m [options]
pnpm exec e2e telemetry [status|enable|disable]
pnpm exec e2e --help
pnpm exec e2e --version
```
```bash bun
bunx e2e init [directory]
bunx e2e login [provider]
bunx e2e logout [provider]
bunx e2e models [provider]
bunx e2e guide [topic]
bunx e2e mcp [options]
bunx e2e run [files...] [options]
bunx e2e explore [goal] [options]
bunx e2e list [files...] [options]
bunx e2e cache ls|clear|stats [--config ]
bunx e2e feedback -m [options]
bunx e2e telemetry [status|enable|disable]
bunx e2e --help
bunx e2e --version
```
The CLI needs Node.js 24.8 or newer, or 22.22.3 or newer on Node.js 22. Any package manager installs it (npm, pnpm, Yarn with or without Plug'n'Play, Bun); the CLI itself runs on Node.js, not on the Bun or Deno runtimes (`bunx e2e` runs it on Node.js). 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.
## Help and version
| Flag | Behavior |
| --- | --- |
| `-h`, `--help` | Prints the help of the command it follows and exits 0. `e2e help run` is the same as `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, 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 at least 55 columns wide, `e2e --help` opens with the e2e
wordmark, the site's lettering drawn in block characters; piped output and
narrower terminals get the text alone.
## e2e init
Scaffolds a project and adds `e2e` to `devDependencies`. Existing
config and test files are skipped. With a `directory` argument the project is
scaffolded there.
On a terminal, the wizard opens with the e2e wordmark written in over about
a second, letter by letter, the way a pen writes it. With `--yes`, in CI, on
a dumb terminal, and on a terminal shorter than 11 rows the wordmark prints at
once, and piped output never shows it. Ctrl-C or SIGTERM while it is being
written exits 130.
For a new project, the wizard asks you to choose:
- The engine. **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. **None** adds nothing.
- A model provider or subscription for agent steps. Choose Vercel AI Gateway,
OpenRouter, an OpenAI-compatible endpoint, ChatGPT, GitHub Copilot,
OpenCode Console, or SuperGrok. Choose None for tests that only use
locators. The wizard adds the required packages and model config. Subscription users then sign in
with `e2e login`. See [Models](/models) and [Subscriptions](/subscriptions).
- Where to install the agent skill (see [e2e guide](#e2e-guide)):
`.agents/skills/` for Codex, Cursor, Copilot, Gemini CLI, OpenCode, and
Zed, and `.claude/skills/` for Claude Code. Both are preselected; with
both, `.claude/skills/e2e` is a symlink to `.agents/skills/e2e`, the
layout `npx skills add` produces.
- Where to register the [MCP server](/reference/mcp): `.mcp.json` for
Claude Code and `.cursor/mcp.json` for Cursor. Both are preselected.
After confirming the file changes, choose whether to install the selected
dependencies. The installer follows the project's `packageManager` field or
lockfile, then the invoking package manager, then npm.
| Argument or flag | Type | Default | Behavior |
| --- | --- | --- | --- |
| `[directory]` | path | the working directory | Where to scaffold; created when missing |
| `-y`, `--yes` | boolean | `false` | Uses the Web engine and Vercel AI Gateway, installs the skill and MCP config in both locations, and skips dependency installation |
| Creates | Content |
| --- | --- |
| `package.json` | Created as a private ESM package when missing; otherwise only missing dependencies and scripts are added. 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. A `test:e2e` script runs `e2e run` unless one exists |
| `e2e.config.ts` | One target for the 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. 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 |
| `.gitignore` | Appends `node_modules/`, `.e2e/artifacts/`, `.e2e/cache/`, `.e2e/sessions/`, `.e2e/report.json`, `.e2e/ai-trace.json`, `.e2e/junit.xml`, `.e2e/summary.md`, `.e2e/failures/`, `.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 |
| `.mcp.json`, `.cursor/mcp.json` | Registers `e2e mcp` without changing other servers |
```bash npm
npx e2e init --yes
```
```bash pnpm
pnpm dlx e2e init --yes
```
```bash bun
bunx e2e init --yes
```
Re-running `init` keeps an existing config and adds no packages for it. Once
a skill directory exists, later runs refresh copies that differ from the
installed version and never add a directory the project did not choose. A
`.claude/skills/e2e/` copy from an earlier version becomes the symlink when
it holds nothing but the shipped files; one with other files in it stays a
copy and is refreshed. A skill directory that is a symlink elsewhere, or sits
under one, is never written through: `--yes` skips it with a warning naming
the link and its target, and an interactive run offers to replace a linked
skill directory 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.
Cancellation leaves files untouched and exits 0. An invalid `package.json`
exits 2 before any write. Without a terminal on stdin and stdout, `init`
without `--yes` exits 2 and names the flag.
## e2e login
```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 spacexai # 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 spacexai # 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 spacexai # SuperGrok, device code
bunx e2e login # choose a provider
```
Signs in to a subscription and stores credentials in
`$XDG_CONFIG_HOME/e2e/oauth.json`, by default `~/.config/e2e/oauth.json`. A failed sign-in exits 1, a cancelled one 130; an
unknown provider exits 2. See [Subscriptions](/subscriptions) for model
configuration.
| Argument or flag | Type | Default | Behavior |
| --- | --- | --- | --- |
| `[provider]` | `openai`, `github-copilot`, `opencode-console`, or `spacexai` | a picker | The subscription to sign in to |
| `--device` | boolean | `false` | ChatGPT: show a code to enter on another device instead of opening a browser |
| `--from-gh` | boolean | `false` | GitHub Copilot: reuse the token of the signed-in GitHub CLI |
| `--client-id ` | string | none | GitHub Copilot: the client id of your GitHub OAuth App with the device flow enabled |
| `--enterprise-url ` | string | none | GitHub Copilot: the GitHub Enterprise host |
## e2e logout
```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
```
## e2e models
```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
```
Asks the vendor which models the stored login serves and prints one line per
model: the id `chatgpt()`, `copilot()`, `opencodeConsole()`, or `grok()`
takes, the vendor's name for it, and its notes (reasoning levels, vision,
preview, hidden, for Copilot `not enabled` or `no chat or responses` when
`copilot()` cannot call it, and for OpenCode Console the plan, Zen or Go,
that serves it). Without a
stored login, or when the named provider has none, exits 1 with the sign-in
command; when one of several logins fails to list, the others still print and
the command exits 1. An unknown provider exits 2. See
[Pick a model](/subscriptions#pick-a-model).
## e2e guide
```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
```
Prints the skill that `init` installs. `guide` alone prints the overview;
`guide ` prints one of `setup`, `writing-tests`, `agent`, `running`,
`explore`, `debugging`, `mcp`, or `bug-bash`. An unknown topic exits 2 and names the
valid ones. The same skill installs with `npx skills add tester-army/e2e`.
See [Coding agents](/coding-agents).
## e2e mcp
```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 ]
```
An MCP server on stdio that gives a coding agent a live session on the app.
Flags, tools, and session rules are on the [MCP server](/reference/mcp) page.
## e2e run
### Positional arguments
```bash
e2e run [files...]
```
Test files, directories, or globs relative to the project root:
- a file path (`tests/signup.e2e.ts`) selects that file;
- a directory (`tests/agent`, `.`) selects every discovered test file beneath
it;
- a bare name selects every discovered file whose path ends with it at a
segment boundary. `signup.e2e.ts` and `agent/signup.e2e.ts` both select
`tests/agent/signup.e2e.ts`. Without a `/` or `.` it matches the file name
with extensions dropped, so `signup` selects it too;
- any of these with `:line` appended (`tests/signup.e2e.ts:12`, `signup:12`)
selects only the test declared at that line of each file it names: the line
the `test(` call opens on, as an editor or a report's `source` shows it. A
serial group runs whole when a line names one member. Several lines of one
file add up; naming 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 its name ends in `:12`;
- a glob (`'tests/**/*.smoke.e2e.ts'`, quoted) uses the grammar of the config
`tests` globs: `*`, `?`, and a whole `**` segment. Braces, character
classes, and extglobs are `INVALID_GLOB` with a hint rather than 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 they do for any positional path, and an existing file or
directory is selected by its path whatever its name is spelled with.
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 only a
few. This lets a selected test find its session setup in another file.
Other ordinary tests remain unselected. A collection error in a selected
file, or in any file of a run with no positionals, fails the run. 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 in the suite 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 starting with `-` that names no file is a usage error, exit 2.
This is what `pnpm test:e2e -- --headed` produces: the `--` reaches e2e and
`--headed` would otherwise be taken for a file. The message names the direct
form, `pnpm exec e2e run --headed`.
For npm, the direct form 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-alike files 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
| Flag | Type | Default | Behavior |
| --- | --- | --- | --- |
| `--config ` | string | discovered | Explicit config path. A missing file is `CONFIG_NOT_FOUND`. |
| `--target ` | comma-separated or repeated | every configured target | Selects targets by name. Only the app commands of selected targets start. An unknown ID is `UNKNOWN_TARGET`. |
| `--tag ` | comma-separated or repeated | none | Only tests carrying the tags: any of them, or every one with `--tag-mode all`. When the filter leaves nothing to run, `NO_TESTS` counts the tests it filtered, marks each tag no test declares, and names the nearest declared one. |
| `--tag-mode ` | `any` or `all` | `any` | How several tags combine: any of them, or every one. |
| `--exclude-tag ` | comma-separated or repeated | none | Leaves out every test carrying any of the tags, 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 ` | regular expression, repeatable | none | Only tests whose title matches one of the patterns. The text matched is the describe titles and the test title joined by one space (`checkout pays`); the file and the tags are not part of it. A bare pattern is case-sensitive; `'/pattern/i'` adds flags. A pattern that does not compile is a usage error, exit 2. |
| `--grep-invert ` | regular expression, repeatable | none | Leaves out every test whose title matches one of the patterns. Same text and pattern forms as `--grep`; both together keep the tests `--grep` matches minus the ones `--grep-invert` matches. |
| `--last-failed` | boolean | `false` | Only the tests the previous run did not pass, read from the `report.json` this run overwrites, `