---
id: app/run-tests/command-line
title: Command line interface (CLI) commands and options in Cypress
description: 'Learn how to run Cypress from the command line using npm, Yarn, or pnpm.'
section: app
source_path: docs/app/run-tests/command-line.mdx
version: 066c46e056f0f322a0670d2d3aa4e6adaebfe717
updated_at: '2026-09-10T13:30:12.426Z'
---
# Command Line

This guide assumes you've already read our [Installing Cypress](/llm/markdown/app/get-started/install-cypress.md) guide and installed Cypress as an `npm` module. After installing you'll be able to execute all of the commands in this document from your **project root**.

You can alternatively require and run Cypress as a node module using our [Module API](/llm/markdown/app/references/module-api.md).

## How to run commands

You can run Cypress from your **project root** using a command which depends on the package manager you are using: npm, Yarn, pnpm or Bun. For example, you would prefix the command [cypress run](#cypress-run) as shown:

*   npm
*   Yarn
*   pnpm
*   Bun

```
npx cypress run
```

```
yarn cypress run
```

```
pnpm cypress run
```

```
bunx cypress run
```

Add any required [options](#Options) to the end of the command line. As an example, if you want to run tests in headless mode from a single spec file and record the results with Cypress Cloud, the command should be:

*   npm
*   Yarn
*   pnpm
*   Bun

```
npx cypress run --record --spec "cypress/e2e/my-spec.cy.js"
```

```
yarn cypress run --record --spec "cypress/e2e/my-spec.cy.js"
```

```
pnpm cypress run --record --spec "cypress/e2e/my-spec.cy.js"
```

```
bunx cypress run --record --spec "cypress/e2e/my-spec.cy.js"
```

**PowerShell**

When `cypress run` [options](#Options) or `cypress open` [options](#Options-1) are specified with multiple values separated by commas, such as for `--config` or `--env` options, and you are using PowerShell on Windows, you may need to surround the key/value pairs with quotes, for example: `--env "host=api.dev.local,port=4222"`.

## Using scripts

Cypress command strings can be saved as scripts for reuse.

Let's say you often need to run Cypress E2E tests in headless mode using the Chrome browser. You can add the corresponding command `cypress run --browser chrome` to the `scripts` object in your `package.json` file and use the name `e2e:chrome` to identify it.

```
{
  "scripts": {
    "e2e:chrome": "cypress run --browser chrome"
  }
}
```

Running the script `e2e:chrome` as follows will run the command you defined:

*   npm
*   Yarn
*   pnpm
*   Bun

```
npm run e2e:chrome
```

```
yarn e2e:chrome
```

```
pnpm e2e:chrome
```

```
bun run e2e:chrome
```

**Best Practice**

Don't use `cypress` as the exact name of a script, especially if you use Yarn as package manager. When running commands on the Cypress binary (e.g. `yarn cypress verify`), Yarn will reference the script of the same name instead and Cypress CLI commands may not work as expected.

### Extending script options

You do not have to define a new script for every variation of a command string you need. You can extend a script with additional options.

Let's say that when you ran the full set of tests with the script `e2e:chrome` it showed a failure in one test spec `cypress/e2e/my-spec.cy.js`. You corrected the problem and would like to re-run the tests only for the test spec which previously failed.

The option [`--spec`](#cypress-run-spec-lt-spec-gt) allows you to specify which test specs to run, so you can add this to the command after the script name `e2e:chrome`:

*   npm
*   Yarn
*   pnpm
*   Bun

```
npm run e2e:chrome -- --spec "cypress/e2e/my-spec.cy.js"
```

```
yarn e2e:chrome --spec "cypress/e2e/my-spec.cy.js"
```

```
pnpm e2e:chrome --spec "cypress/e2e/my-spec.cy.js"
```

```
bun run e2e:chrome --spec "cypress/e2e/my-spec.cy.js"
```

Refer to each package manager's documentation for full details of command and script usage:

*   [npm CLI](https://docs.npmjs.com/cli/)  
    When adding Cypress [options](#Options) after a script name called from `npm`, you need to pass the command's arguments using the `--` string (see [`npm-run-script`](https://docs.npmjs.com/cli/run-script.html)).
*   [Yarn CLI](https://classic.yarnpkg.com/lang/en/docs/cli/)
*   [pnpm CLI](https://pnpm.io/pnpm-cli)
*   [Bun CLI](https://bun.sh/docs/cli/run)

## Commands

The prefix required to run `cypress` is not shown in the list of commands below. You need to add the prefix `npx`, `yarn` or `pnpm` to the command line, corresponding to the package manager you are using. See [How to run commands](#How-to-run-commands).

### `cypress run`

Runs Cypress tests to completion. By default, `cypress run` will run all tests headlessly.

```
cypress run [options]
```

#### Options

| Option | Description |
| --- | --- |
| `--auto-cancel-after-failures` | [Overrides the Cloud project-level configuration to set the failed test threshold for auto cancellation or to disable auto cancellation when recording to the Cloud](#auto-cancel-after-runs) |
| `--browser`, `-b` | [Run Cypress in the browser with the given name. If a filesystem path is supplied, Cypress will attempt to use the browser at that path.](#cypress-run-browser-lt-browser-name-or-path-gt) |
| `--ci-build-id` | [Specify a unique identifier for a run to enable grouping or parallelization.](#cypress-run-ci-build-id-lt-id-gt) |
| `--component` | [Run component tests](/llm/markdown/app/core-concepts/testing-types.md#What-is-Component-Testing) |
| `--config`, `-c` | [Specify configuration](#cypress-run-config-lt-config-gt) |
| `--config-file`, `-C` | [Specify configuration file](#cypress-run-config-file-lt-configuration-file-gt) |
| `--e2e` | Run end to end tests (default) |
| `--env`, `-e` | [Specify secret environment variables](#cypress-run-env-lt-env-gt) |
| `--expose`, `-x` | [Specify public configuration values](#cypress-run-expose-lt-expose-gt) |
| `--group` | [Group recorded tests together under a single run](#cypress-run-group-lt-name-gt) |
| `--headed` | [Displays the browser instead of running headlessly](#cypress-run-headed) |
| `--headless` | Hide the browser instead of running headed (default during `cypress run`) |
| `--help`, `-h` | Output usage information |
| `--key`, `-k` | [Specify your secret record key](#cypress-run-record-key-lt-record-key-gt) |
| `--no-exit` | [Keep Cypress open after tests in a spec file run](#cypress-run-no-exit) |
| `--no-runner-ui` | [Hides the Cypress Runner UI](#cypress-run-no-runner-ui) |
| `--parallel` | [Run recorded specs in parallel across multiple machines](#cypress-run-parallel) |
| `--pass-with-no-tests` | [Exits with success when no spec files are found](#cypress-run-pass-with-no-tests) |
| `--port`,`-p` | [Override default port](#cypress-run-port-lt-port-gt) |
| `--posix-exit-codes` | [Exit with a POSIX-compliant exit code](#cypress-run-posix-exit-codes) rather than the number of failed tests. |
| `--project`, `-P` | [Path to a specific project](#cypress-run-project-lt-project-path-gt) |
| `--quiet`, `-q` | [Reduce output to `stdout`](#cypress-run-quiet) |
| `--record` | [Whether to record the test run](#cypress-run-record-key-lt-record-key-gt) |
| `--reporter`, `-r` | [Specify a Mocha reporter](#cypress-run-reporter-lt-reporter-gt) |
| `--reporter-options`, `-o` | [Specify Mocha reporter options](#cypress-run-reporter-lt-reporter-gt) |
| `--runner-ui` | [Displays the Cypress Runner UI. Useful for when Test Replay is enabled and you would still like the Cypress Runner UI to be displayed for screenshots and video](#cypress-run-runner-ui) |
| `--spec`, `-s` | [Specify the spec files to run](#cypress-run-spec-lt-spec-gt) |
| `--tag`, `-t` | [Identify a run with a tag or tags](#cypress-run-tag-lt-tag-gt) |

#### `cypress run --auto-cancel-after-failures <autoCancelAfterFailures>`

The "autoCancelAfterFailures" argument is the number of times tests can fail before the run is canceled

```
cypress run --record --key <<your_record_key>> --auto-cancel-after-failures 1
```

You can also specify `false` for the value to disable Auto Cancellation for the run:

```
cypress run --record --key <<your_record_key>> --auto-cancel-after-failures false
```

#### `cypress run --browser <browser-name-or-path>`

```
cypress run --browser chrome
```

The "browser" argument can be set to `chrome`, `chromium`, `edge`, or `firefox` to launch a browser detected on your system. Cypress will attempt to automatically find the installed browser for you. `electron` is still accepted for the bundled Electron browser, but it is [deprecated](/llm/markdown/app/references/launching-browsers.md#Electron-Browser) and will be removed in a future version of Cypress.

To launch non-stable browsers, add a colon and the desired release channel. For example, to launch Chrome Canary, use `chrome:canary`.

You can also choose a browser by supplying a path:

```
cypress run --browser /usr/bin/chromium
```

[Having trouble with browser detection? Check out our troubleshooting guide](/llm/markdown/app/references/troubleshooting.md#Launching-browsers)

#### `cypress run --ci-build-id <id>`

This value should be automatically detected for most CI providers and is unnecessary to define unless Cypress is unable to determine it.

Typically, this is defined as a system environment variable within your CI provider, defining a unique "build" or "run".

```
cypress run --ci-build-id BUILD_NUMBER
```

Only valid when providing a `--group` or `--parallel` flag. Read our [parallelization](/llm/markdown/cloud/features/smart-orchestration/parallelization.md) documentation to learn more.

#### `cypress run --config <config>`

Set [configuration](/llm/markdown/app/references/configuration.md) values. Separate multiple values with commas. The values set here override any values set in your configuration file.

```
cypress run --config pageLoadTimeout=100000,watchForFileChanges=false
```

For more complex configuration objects, you may want to consider passing a [JSON.stringified](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) object surrounded by single quotes.

Here, we're passing in the configuration for component spec files.

```
cypress run --config '{"watchForFileChanges":false,"specPattern":["**/*.cy.js","**/*.cy.ts"]}'
```

##### Real World Example

The Cypress [Real World App (RWA)](https://github.com/cypress-io/cypress-realworld-app) uses `--config` flag to easily specify [viewport](/llm/markdown/app/references/configuration.md#Viewport) sizes for responsive testing locally and in dedicated CI jobs.

Examples:

*   [npm scripts](https://github.com/cypress-io/cypress-realworld-app/blob/07a6483dfe7ee44823380832b0b23a4dacd72504/package.json#L120) to run Cypress in mobile viewport.

*   [Circle CI job configuration](https://github.com/cypress-io/cypress-realworld-app/blob/07a6483dfe7ee44823380832b0b23a4dacd72504/.circleci/config.yml#L82-L100) for running test suites in mobile viewport.

#### `cypress run --config-file <configuration-file>`

You can specify a path to a file where [Cypress configuration](/llm/markdown/app/references/configuration.md) values are set.

```
cypress run --config-file tests/cypress.config.js
```

#### `cypress run --env <env>`

**Security Warning**

Secrets passed via CLI may appear in CI logs. For production use, prefer setting secrets via your CI/CD platform's secret management system.

Set secret [environment variables](/llm/markdown/app/guides/environment-variables.md) for use in your tests via [`cy.env()`](/llm/markdown/api/commands/env.md). See the [Environment Variables & Secrets](/llm/markdown/app/guides/environment-variables.md) guide for more details.

```
cypress run --env apiKey=secret-key-12345
```

Pass several variables using commas and no spaces. Numbers are automatically converted from strings.

```
cypress run --env apiKey=secret-key-12345,apiUrl=https://api.example.com
```

Pass an object as a JSON in a string.

```
cypress run --env credentials='{"apiKey":"secret-key-12345","dbPassword":"secure-password"}'
```

#### `cypress run --expose <expose>`

Set public configuration values for use in your tests via [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md). See the [Environment Variables & Secrets](/llm/markdown/app/guides/environment-variables.md) guide for more details.

```
cypress run --expose apiVersion=v2,featureFlag=true
```

#### `cypress run --group <name>`

Group recorded tests together under a single run.

```
cypress run --group develop-env
```

You can add multiple groups to the same run by passing a different name. This can help distinguish groups of specs from each other.

```
cypress run --group admin-tests --spec 'cypress/e2e/admin/**/*'
```

```
cypress run --group user-tests --spec 'cypress/e2e/user/**/*'
```

Specifying the `--ci-build-id` may also be necessary.

[Read more about grouping.](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Grouping-test-runs)

#### `cypress run --headed`

By default, Cypress will run tests headlessly during `cypress run`.

Passing `--headed` will force the browser to be shown. This matches how you run any browser via `cypress open`.

```
cypress run --headed
```

#### `cypress run --no-exit`

To prevent Cypress from exiting after running tests in a spec file, use `--no-exit`.

You can pass `--headed --no-exit` in order to view the **command log** or have access to **developer tools** after a `spec` has run.

```
cypress run --headed --no-exit
```

#### `cypress run --no-runner-ui`

To prevent Cypress from rendering the Runner UI, use `--no-runner-ui`.

```
cypress run --no-runner-ui
```

#### `cypress run --parallel`

Run recorded specs in [parallel](/llm/markdown/cloud/features/smart-orchestration/parallelization.md) across multiple machines.

```
cypress run --record --parallel
```

You can additionally pass a `--group` flag so this shows up as a named [group](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Grouping-test-runs).

```
cypress run --record --parallel --group e2e-staging-specs
```

Read our [parallelization](/llm/markdown/cloud/features/smart-orchestration/parallelization.md) documentation to learn more.

#### `cypress run --pass-with-no-tests`

Exits with a success code when no spec files are found. Useful in CI pipelines where specs may be conditionally generated or filtered out at runtime.

```
cypress run --pass-with-no-tests
```

#### `cypress run --port <port>`

```
cypress run --port 8080
```

#### `cypress run --posix-exit-codes`

This changes the default behavior of Cypress regarding exit codes. This flag causes Cypress to exit with POSIX exit code of 1 when there are test failures or if Cypress could not run, rather than the number of tests that failed. It can return additional POSIX-compliant exit codes for other scenarios as well. See the [Exit Code section](/llm/markdown/app/references/command-line.md#Exit-code) for a comprehensive reference of Cypress exit codes.

```
cypress run --posix-exit-codes
```

#### `cypress run --project <project-path>`

By default, Cypress expects your `cypress.config.js` (or `cypress.config.ts`) to be found in the current working directory. Use `--project` to point Cypress at a different directory. This is useful when you have multiple Cypress projects in one repository and want to run a specific one without changing your working directory.

```
cypress run --project ./some/nested/folder
```

#### `cypress run --quiet`

To reduce the output from Cypress printed to `stdout`, use `--quiet`.

```
cypress run --quiet
```

If passed, Cypress will only print output to `stdout` from the [built-in](/llm/markdown/app/tooling/reporters.md#Built-in-reporters) default [Mocha spec reporter](https://mochajs.org/#spec), or from any other configured [Mocha reporter](/llm/markdown/app/tooling/reporters.md).

#### `cypress run --record --key <record-key>`

Record your test results to [Cypress Cloud](/llm/markdown/cloud/get-started/introduction.md). For this option to work you must first [set up your project to record](/llm/markdown/cloud/get-started/setup.md#Setup), make sure your `projectId` is set in your [Cypress configuration file](/llm/markdown/app/references/configuration.md), and append your **Record Key** to the command.

```
cypress run --record --key <record_key>
```

If you set the **Record Key** as the environment variable `CYPRESS_RECORD_KEY`, you can omit the `--key` flag. You may want to set this environment variable when running in [Continuous Integration](/llm/markdown/app/continuous-integration/overview.md).

```
export CYPRESS_RECORD_KEY=abc-key-123
```

Now you can omit the `--key` flag.

```
cypress run --record
```

`CYPRESS_RECORD_KEY` must be set as an actual operating system environment variable (for example via `export CYPRESS_RECORD_KEY=...` or your CI provider's secrets). Cypress reads it directly from your shell or CI environment — it is **not** read from `cypress.env.json` or the `env` block of your Cypress configuration, since those only populate test environment variables. If you don't want to set an environment variable, pass the key inline with the `--key` flag instead.

For more information on recording runs, see the [Cypress Cloud setup instructions](/llm/markdown/cloud/get-started/setup.md#Setup). For an in-depth explanation of how Cypress uses your record key and `projectId` to save your test results to Cypress Cloud, see the [Identification section](/llm/markdown/cloud/account-management/projects.md#Project-ID).

#### `cypress run --reporter <reporter>`

You can tests specifying a specific [Mocha reporter](/llm/markdown/app/tooling/reporters.md).

```
cypress run --reporter json
```

You can specify reporter options using the `--reporter-options <reporter-options>` flag.

```
cypress run --reporter junit --reporter-options mochaFile=result.xml,toConsole=true
```

#### `cypress run --runner-ui`

To force Cypress to render the Runner UI, use `--runner-ui`.

```
cypress run --runner-ui
```

Useful for when [Test Replay](/llm/markdown/cloud/features/test-replay.md) is enabled and you would still like the Runner UI to be rendered for screenshots and video.

#### `cypress run --spec <spec>`

Run tests specifying a single test file to run instead of all tests. The spec path should be an absolute path or can be relative to the current working directory.

`--spec` only runs specs that **also match the configured [`specPattern`](/llm/markdown/app/references/configuration.md#e2e)**. Specs located outside the configured `specPattern` will not be found. See [Test files not found when using `spec` parameter](/llm/markdown/app/references/configuration.md#Test-files-not-found-when-using-spec-parameter) for details.

```
cypress run --spec "cypress/e2e/examples/actions.cy.js"
```

Run tests within the folder matching the glob _(Note: Using double quotes is strongly recommended)_.

```
cypress run --spec "cypress/e2e/login/**/*"
```

Run tests specifying multiple test files to run.

```
cypress run --spec "cypress/e2e/examples/actions.cy.js,cypress/e2e/examples/files.cy.js"
```

Use in combination with `--project` parameter. Imagine the Cypress tests are in a subfolder `tests/e2e` of the current project:

```
app/
  node_modules/
  package.json
  tests/
    unit/
    e2e/
      cypress/
        e2e/
          spec.cy.js
      cypress.config.js
```

If we are in the `app` folder, we can run the specs using the following command

```
cypress run --project tests/e2e --spec ./tests/e2e/cypress/e2e/spec.cy.js
```

#### `cypress run --tag <tag>`

Add a tag or tags to the recorded run. This can be used to help identify separate runs when displayed in Cypress Cloud.

```
cypress run  --record --tag "staging"
```

Give a run multiple tags.

```
cypress run --record --tag "production,nightly"
```

Cypress Cloud will display any tags sent with the appropriate run.

Tags are also useful for surfacing environment details that Cypress Cloud does not record on its own, such as the Node.js version a run used. By tagging runs with these values you can easily differentiate runs that were executed against different versions in the same matrix. For example, when testing across multiple Node.js versions in CI you can include the version in the tags:

```
cypress run --record --tag "node-${nodeVersion}"
```

This makes runs that use the same spec set but a different Node.js version (or any other build/environment detail Cypress Cloud does not capture) easy to tell apart in Cypress Cloud.

**App Quality Profiles**: If you use Cypress Cloud's [accessibility](/llm/markdown/accessibility/get-started/introduction.md) and [UI Coverage reporting](/llm/markdown/accessibility/get-started/introduction.md), a run tag can be mapped to [App Quality Profiles](/llm/markdown/accessibility/configuration/profiles.md) to automatically apply different configuration settings for different types of runs.

#### Exit code

Cypress supports two different exit code behaviors. The default behavior is similar to that of Mocha, but is not POSIX compliant: reserved exit codes can be returned for certain conditions. As well, the default behavior can return a false negative when there are a number of tests that fail in multiples of 256: most terminals will apply modulo 256 to any exit code larger than 255.

POSIX compliant exit codes are available via the `--posix-exit-codes` flag. When this flag is passed, additional conditions can be returned that are not possible with the default behavior, including when Cypress fails due to network errors when connections to Cypress Cloud are required, such as in `--record` or `--parallel` runs.

When using POSIX compliant exit codes, the number of failed tests can be determined from the [Module API](/llm/markdown/app/references/module-api.md) or [structured reporter data](/llm/markdown/app/tooling/reporters.md).

| Exit Condition | POSIX Exit Code (with `--posix-exit-codes`) | Default Exit Code (without `--posix-exit-codes`) |
| --- | --- | --- |
| All tests pass | 0 | 0 |
| _n_ tests fail | 1 | _n_ |
| Cypress could not run due to a network error when connections to Cypress Cloud are required | 112 | 1 |
| Cypress could not run for any other reason, including no spec files found | 1 | 1 |

### `cypress open`

Opens Cypress.

```
cypress open [options]
```

#### Options:

Options passed to `cypress open` will automatically be applied to the project you open. These persist on all projects until you quit Cypress. These options will also override values in the Cypress configuration file.

By passing `--browser` and `--e2e` or `--component` when launching a project, you can open Cypress and launch the browser at the same time. If passing the `--browser` flag alone, the browser will launch automatically after being guided through project and/or testing type selection. Otherwise, you will be guided through selecting a browser, project, and/or testing type.

| Option | Description |
| --- | --- |
| `--browser`, `-b` | [Run Cypress in the browser with the given name. If a filesystem path is supplied, Cypress will attempt to use the browser at that path.](#cypress-open-browser-lt-browser-path-gt) |
| `--component` | [Open in component testing mode](/llm/markdown/app/core-concepts/testing-types.md#What-is-Component-Testing) |
| `--config`, `-c` | [Specify configuration](#cypress-open-config-lt-config-gt) |
| `--config-file`, `-C` | [Specify configuration file](#cypress-open-config-file-lt-configuration-file-gt) |
| `--detached`, `-d` | Open Cypress in detached mode |
| `--e2e` | Open in end to end testing mode (default) |
| `--env`, `-e` | [Specify secret environment variables](#cypress-open-env-lt-env-gt) |
| `--expose`, `-x` | [Specify public configuration values](#cypress-open-expose-lt-expose-gt) |
| `--global` | [Open in global mode](#cypress-open-global) |
| `--help`, `-h` | Output usage information |
| `--port`, `-p` | [Override default port](#cypress-open-port-lt-port-gt) |
| `--project`, `-P` | [Path to a specific project](#cypress-open-project-lt-project-path-gt) |

#### `cypress open --browser <browser-path>`

By default, Cypress will automatically find and allow you to use the browsers installed on your system.

The "browser" option allows you to specify the path to a custom browser to use with Cypress:

```
cypress open --browser /usr/bin/chromium
```

If found, the specified browser will be added to the list of available browsers.

Currently, only browsers in the Chrome family (including the new Chromium-based Microsoft Edge and Brave) and Firefox are supported.

[Having trouble launching a browser? Check out our troubleshooting guide](/llm/markdown/app/references/troubleshooting.md#Launching-browsers)

#### `cypress open --config <config>`

Set [configuration](/llm/markdown/app/references/configuration.md) values. Separate multiple values with a comma. The values set here override any values set in your configuration file.

```
cypress open --config pageLoadTimeout=100000,watchForFileChanges=false
```

For more complex configuration objects, you may want to consider passing a [JSON.stringified](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) object.

Here, we're passing in the configuration for component spec files.

```
cypress open --config "{\"watchForFileChanges\":false,\"specPattern\":[\"**/*.cy.js\",\"**/*.cy.ts\"]}"
```

#### `cypress open --config-file <configuration-file>`

You can specify a path to a file where [Cypress configuration](/llm/markdown/app/references/configuration.md) values are set.

```
cypress open --config-file tests/cypress.config.js
```

#### `cypress open --env <env>`

**Security Warning**

Secrets passed via CLI may appear in CI logs. For production use, prefer setting secrets via your CI/CD platform's secret management system.

Set secret [environment variables](/llm/markdown/app/guides/environment-variables.md) for use in your tests via [`cy.env()`](/llm/markdown/api/commands/env.md). See the [Environment Variables & Secrets](/llm/markdown/app/guides/environment-variables.md) guide for more details.

```
cypress open --env apiKey=secret-key-12345
```

Pass several variables using commas and no spaces. Numbers are automatically converted from strings.

```
cypress open --env apiKey=secret-key-12345,apiUrl=https://api.example.com
```

Pass an object as a JSON in a string.

```
cypress open --env credentials='{"apiKey":"secret-key-12345","dbPassword":"secure-password"}'
```

#### `cypress open --expose <expose>`

Set public configuration values for use in your tests via [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md). See the [Environment Variables & Secrets](/llm/markdown/app/guides/environment-variables.md) guide for more details.

```
cypress open --expose apiVersion=v2,featureFlag=true
```

#### `cypress open --global`

Opening Cypress in global mode is useful if you have multiple nested projects but want to share a single global installation of Cypress. In this case you can add each nested project to the Cypress in global mode, thus giving you a nice UI to switch between them.

```
cypress open --global
```

#### `cypress open --port <port>`

```
cypress open --port 8080
```

#### `cypress open --project <project-path>`

By default, Cypress looks for your `cypress.config.js` (or `cypress.config.ts`) in the current working directory. Use `--project` to open Cypress for a project located in a different directory. This is useful when you have multiple Cypress projects in one repository and want to open a specific one without changing your working directory.

```
cypress open --project ./some/nested/folder
```

### `cypress tap` ✨

`cypress tap` is in [beta](/llm/markdown/app/references/release-stages.md#Beta). Its commands and output can still change in any release.

`cypress tap` is a set of Cypress CLI commands that enables you or an agent to interact with an open-mode Cypress session and read its context from the terminal. You can list the specs Cypress can run, start a run, poll its status, read test results the way the Cypress Command Log shows them, and inspect the DOM and accessibility tree of the application under test. It is built for you, or for an AI agent working in your terminal.

To get started, start Cypress in open mode (`cypress open`) in your project, then use the `cypress tap` commands from the same project directory in another terminal.

#### `cypress tap` commands

Below is the list of the commands `cypress tap` exposes. To learn full syntax, options, and output of every command and how to use them, review our [guide to driving Cypress with AI agents](/llm/markdown/app/tooling/cypress-tap.md).

```
cypress tap [command] [args...] [options]
```

| `cypress tap` commands | What it does |
| --- | --- |
| [`sessions`](/llm/markdown/app/tooling/cypress-tap.md#cypress-tap-sessions) | Lists the running Cypress sessions the CLI can reach. |
| [`status`](/llm/markdown/app/tooling/cypress-tap.md#cypress-tap-status) | Reports where a session is in its run lifecycle. |
| [`specs`](/llm/markdown/app/tooling/cypress-tap.md#cypress-tap-specs) | Lists the specs the session can run. |
| [`run`](/llm/markdown/app/tooling/cypress-tap.md#cypress-tap-run) | Runs (or reruns) a spec by its project-relative path. |
| [`reporter`](/llm/markdown/app/tooling/cypress-tap.md#cypress-tap-reporter) | Renders the spec report or a specific tests report. The spec report includes what tests ran and their status. A test's reporter view includes routes, hooks, Command Log, and failure details. |
| [`command`](/llm/markdown/app/tooling/cypress-tap.md#cypress-tap-command) | Prints the details of a specific Command Log entry, including its time travel snapshots and the captured console properties. |
| [`pin`](/llm/markdown/app/tooling/cypress-tap.md#cypress-tap-pin) | Renders a past command's DOM snapshot as the live app under test so the `dom`, `aria`, and `inspect` tap commands can inspect it. |
| [`dom`](/llm/markdown/app/tooling/cypress-tap.md#cypress-tap-dom) | Retrieves the app under test's HTML markup. |
| [`aria`](/llm/markdown/app/tooling/cypress-tap.md#cypress-tap-aria) | Retrieves the accessibility (ARIA) tree of the app under test. |
| [`inspect`](/llm/markdown/app/tooling/cypress-tap.md#cypress-tap-inspect) | Retrieves the specified element's tag, attributes, computed styles, and box model. |

Commands exit with `0` on success and `1` on any failure.

Each subcommand supports a `--help` or `-h` flag to view the options help content in the terminal.

### `cypress info`

Prints information about Cypress and the current environment such as:

*   A list of browsers Cypress detected on the machine.
*   Any environment variables that control [proxy configuration](/llm/markdown/app/references/proxy-configuration.md).
*   Any environment variables that start with the `CYPRESS` prefix (with sensitive variables like [record key](/llm/markdown/cloud/account-management/projects.md#Record-key) masked for security).
*   The location where run-time data is stored.
*   The location where the Cypress binary is cached.
*   Operating system information.
*   System memory including free space.

```
cypress info
Displaying Cypress info...

Detected 2 browsers installed:

1. Chrome
  - Name: chrome
  - Channel: stable
  - Version: 79.0.3945.130
  - Executable: /path/to/google-chrome
  - Profile: /user/profile/folder/for/google-chrome

2. Firefox Nightly
  - Name: firefox
  - Channel: nightly
  - Version: 74.0a1
  - Executable: /path/to/firefox

Note: to run these browsers, pass <name>:<channel> to the '--browser' field

Examples:
- cypress run --browser firefox:nightly
- cypress run --browser chrome

Learn More: https://on.cypress.io/launching-browsers

Proxy Settings: none detected
Environment Variables: none detected

Application Data: /path/to/app/data/cypress/cy/development
Browser Profiles: /path/to/app/data/cypress/cy/development/browsers
Binary Caches: /user/profile/path/.cache/Cypress

Cypress Version: 4.1.0
System Platform: darwin (19.2.0)
System Memory: 17.2 GB free 670 MB
```

**Tip:** set [DEBUG environment variable](/llm/markdown/app/references/troubleshooting.md#Print-DEBUG-logs) to `cypress:launcher:*` when running `cypress info` to troubleshoot browser detection.

### `cypress install`

Installs the Cypress binary that matches the version of the `cypress` npm package into the [global cache](/llm/markdown/app/references/advanced-installation.md#Binary-cache).

*   npm
*   Yarn
*   pnpm
*   Bun

```
npx cypress install
```

```
yarn cypress install
```

```
pnpm cypress install
```

```
bunx cypress install
```

This command normally runs automatically as a `postinstall` step when you add `cypress` with your package manager, so you rarely need to run it yourself. Running it explicitly is useful when the binary was not downloaded during `npm install`, including these scenarios:

*   Your package manager blocks lifecycle scripts (for example with `--ignore-scripts`, or because a security policy disallows `postinstall`), so you install the binary yourself at a later stage instead of granting Cypress install-time script access.
*   You want to download and cache the binary on one machine (such as a CI "install" stage), then skip the download on every subsequent machine that reuses that [cache](/llm/markdown/app/references/advanced-installation.md#Binary-cache).
*   The automatic install was skipped on purpose by setting `CYPRESS_INSTALL_BINARY=0`.
*   You want to [troubleshoot the installation](/llm/markdown/app/references/advanced-installation.md#Troubleshoot-installation) by running the download on its own with [debug logging](/llm/markdown/app/references/troubleshooting.md#Print-DEBUG-logs) enabled.

For example, add `cypress` while skipping the binary download, then run the install on its own with debug logging enabled:

*   npm
*   Yarn
*   pnpm
*   Bun

```
CYPRESS_INSTALL_BINARY=0 npm install cypress --save-dev
```

```
CYPRESS_INSTALL_BINARY=0 yarn add cypress --dev
```

```
CYPRESS_INSTALL_BINARY=0 pnpm add --save-dev cypress
```

```
CYPRESS_INSTALL_BINARY=0 bun add --dev cypress
```

*   npm
*   Yarn
*   pnpm
*   Bun

```
DEBUG=cypress:cli* npx cypress install
```

```
DEBUG=cypress:cli* yarn cypress install
```

```
DEBUG=cypress:cli* pnpm cypress install
```

```
DEBUG=cypress:cli* bunx cypress install
```

The binary that gets installed, the cache location, and the download source can be customized through environment variables. See [Advanced Installation](/llm/markdown/app/references/advanced-installation.md) for details.

#### Options

| Option | Description |
| --- | --- |
| `--force`, `-f` | [Force install the Cypress binary](#cypress-install-force) |
| `--help`, `-h` | Output usage information |

#### `cypress install --force`

By default, `cypress install` does nothing when a binary matching the package version is already present in the [cache](/llm/markdown/app/references/advanced-installation.md#Binary-cache). Pass `--force` to download and reinstall the binary anyway, overwriting any existing installation.

*   npm
*   Yarn
*   pnpm
*   Bun

```
npx cypress install --force
```

```
yarn cypress install --force
```

```
pnpm cypress install --force
```

```
bunx cypress install --force
```

### `cypress verify`

Verify that Cypress is installed correctly and is executable.

```
cypress verify
✔  Verified Cypress! /Users/jane/Library/Caches/Cypress/3.0.0/Cypress.app
```

To change the default timeout of 30 seconds, you can set the environment variable `CYPRESS_VERIFY_TIMEOUT`:

```
export CYPRESS_VERIFY_TIMEOUT=60000 # wait for 60 seconds
cypress verify
```

Note that the `cypress verify` command is executed as part of the `cypress open` and `cypress run` commands. The `CYPRESS_VERIFY_TIMEOUT` environment variable should be provided for those commands if you wish to modify the timeout duration.

You can disable verification by setting the `CYPRESS_SKIP_VERIFY` environment variable to `true`.

### `cypress version`

Prints the installed Cypress binary version, the Cypress package version, the version of Electron used to build Cypress, and the bundled Node version.

In most cases the binary and the package versions will be the same, but they could be different if you have installed a different version of the package and for some reason failed to install the matching binary version.

```
cypress version
Cypress package version: 12.0.0
Cypress binary version: 12.0.0
Electron version: 21.0.0
Bundled Node version: 16.16.0
```

You can print each individual component's version number also.

```
cypress version --component package
12.0.0
cypress version --component binary
12.0.0
cypress version --component electron
21.0.0
cypress version --component node
16.16.0
```

### `cypress cache [command]`

Commands for managing the global Cypress cache. The Cypress cache applies to all installs of Cypress across your machine, global or not.

#### `cypress cache path`

Print the `path` to the Cypress cache folder. You can change the path where the Cypress cache is located by following [these instructions](/llm/markdown/app/references/advanced-installation.md#Binary-cache).

```
cypress cache path
/Users/jane/Library/Caches/Cypress
```

#### `cypress cache list`

Print all existing installed versions of Cypress. The output will be a table with cached versions and the last time the binary was used by the user, determined from the file's access time.

```
cypress cache list
┌─────────┬──────────────┐
│ version │ last used    │
├─────────┼──────────────┤
│ 3.0.0   │ 3 months ago │
├─────────┼──────────────┤
│ 3.0.1   │ 5 days ago   │
└─────────┴──────────────┘
```

You can calculate the size of every Cypress version folder by adding the `--size` argument to the command. Note that calculating the disk size can be slow.

```
cypress cache list --size
┌─────────┬──────────────┬─────────┐
│ version │ last used    │ size    │
├─────────┼──────────────┼─────────┤
│ 5.0.0   │ 3 months ago │ 425.3MB │
├─────────┼──────────────┼─────────┤
│ 5.3.0   │ 5 days ago   │ 436.3MB │
└─────────┴──────────────┴─────────┘
```

#### `cypress cache clear`

Clear the contents of the Cypress cache. This is useful when you want Cypress to clear out all installed versions of Cypress that may be cached on your machine. After running this command, you will need to run `cypress install` before running Cypress again.

```
cypress cache clear
```

#### `cypress cache prune`

Deletes all installed Cypress versions from the cache except for the currently-installed version.

```
cypress cache prune
```

## Debugging commands

### Enable Debug Logs

If you are using macOS, Linux or Windows (Git Bash) and your package manager is npm, you can run Cypress with debug logs using the following CLI command:

```
DEBUG=cypress:* npx cypress run
```

See [Troubleshooting](/llm/markdown/app/references/troubleshooting.md#Print-DEBUG-logs) for more detailed instructions on options to generate debug logs, also with Yarn and pnpm package managers, and with Windows CMD and PowerShell terminal windows.

## History

| Version | Changes |
| --- | --- |
| [15.21.0](/llm/markdown/app/references/changelog.md#15-21-0) | Added the `cypress tap` command |
| [15.11.0](/llm/markdown/app/references/changelog.md#15-11-0) | Added `--pass-with-no-tests` flag to `cypress run` |
| [15.5.0](/llm/markdown/app/references/changelog.md#15-5-0) | Added the 112 exit code scenario when using `--posix-exit-codes` flag |
| [15.4.0](/llm/markdown/app/references/changelog.md#15-4-0) | Added `--auto-cancel-after-failures` flag to `cypress run` |
| [5.4.0](/llm/markdown/app/references/changelog.md) | Added `prune` subcommand to `cypress cache` |
| [5.4.0](/llm/markdown/app/references/changelog.md) | Added `--size` flag to `cypress cache list` subcommand |
| [4.9.0](/llm/markdown/app/references/changelog.md) | Added `--quiet` flag to `cypress run` |