BrowserStack Cypress CLI

1.36.4 · active · verified Wed Apr 22

The `browserstack-cypress-cli` is a command-line interface (CLI) tool designed by BrowserStack to enable running Cypress end-to-end tests on BrowserStack's cloud infrastructure. This allows developers to execute their Cypress test suites across a wide array of remote browsers and operating systems, which significantly expands testing coverage beyond local environments. Currently in public beta, the package (latest stable release v1.36.4 as of April 2026) receives frequent updates, often on a weekly or bi-weekly basis, with recent releases focusing on bug fixes, improved logging for Cucumber-Cypress tests, and enhanced dependency management. Its primary differentiator is providing seamless integration with BrowserStack Automate, offering features like parallel test execution, localhost tunneling, and comprehensive test reporting, which are crucial for CI/CD pipelines.

Common errors

```
Cannot find module 'cypress'
```
cause The BrowserStack environment does not automatically install dependencies from your project's `package.json`.

fix You must explicitly list Cypress (and any other test-specific npm packages) within the `npm_dependencies` object in your `browserstack.json` file.
```
EAADRINUSE: address already in use ...
```
cause This error typically occurs during multiple spec file executions when a port is not properly released, especially on certain operating systems or configurations.

fix Upgrade `browserstack-cypress-cli` to v1.36.0 or newer, which includes a fix for 'address already in use' issues during multi-spec executions.
```
https-proxy-agent library exceptions
```
cause Conflict or incompatibility with the `https-proxy-agent` dependency within the CLI's dependency tree.

fix Upgrade `browserstack-cypress-cli` to v1.36.1 or newer, which contains a fix addressing these exceptions.
```
Invalid gridName for Automate TurboScale sessions
```
cause Incorrectly specified `gridName` parameter when attempting to use Automate TurboScale features.

fix Verify the `gridName` value in your `browserstack.json` matches the accepted values for Automate TurboScale sessions. A warning log was added in v1.32.8 to help debug this.
```
Tests are not running on BrowserStack or capabilities are incorrect.
```
cause Misconfiguration in the `browserstack.json` file, such as incorrect `auth` credentials, `browsers` settings, or `run_settings`.

fix Carefully review your `browserstack.json` file, ensuring `username` and `access_key` are correct (preferably using environment variables), and that `browsers` and `run_settings` define valid configurations as per BrowserStack documentation.

Warnings

gotcha The product is currently in 'Public Beta' status. While functional and actively developed, users should be aware of potential changes or ongoing refinements to features and behavior.
Fix: Review the official BrowserStack Cypress documentation regularly for the latest updates and best practices during the beta phase.
breaking Cypress tests running on BrowserStack require explicit declaration of `npm_dependencies` within the `browserstack.json` configuration file, even if they are already in `package.json`. BrowserStack does not use `package.json` for dependencies on its remote machines, leading to 'Cannot find module' errors if not specified.
Fix: Add a `npm_dependencies` object under `run_settings` in `browserstack.json`, listing all required npm packages and their versions for your Cypress tests. Example: `"npm_dependencies": { "cypress": "13.x.x", "lodash": "^4.17.21" }`.
gotcha Older versions of Cypress (pre-v10) might require different setup or face compatibility issues. Specific support for Cypress logs and steps was added for Cypress v13+.
Fix: Ensure you are using a recent version of `browserstack-cypress-cli` and Cypress v13+ for optimal logging and feature support. Check the documentation for specific Cypress version compatibility.
breaking Capability conflicts could arise with `auto_import_dev_dependencies`, leading to unexpected behavior during test execution. This was addressed in v1.36.2.
Fix: Upgrade `browserstack-cypress-cli` to v1.36.2 or newer to resolve conflicts related to `auto_import_dev_dependencies`.
breaking Issues with the `https-proxy-agent` library could cause exceptions, especially when multiple breaking versions are present in the dependency tree. This was fixed in v1.36.1.
Fix: Upgrade `browserstack-cypress-cli` to v1.36.1 or newer to mitigate `https-proxy-agent` library exceptions.

Install

npm install browserstack-cypress-cli npm
yarn add browserstack-cypress-cli yarn
pnpm add browserstack-cypress-cli pnpm

Quickstart

Demonstrates how to install the CLI, initialize the configuration, and execute Cypress tests on BrowserStack's cloud platform.

# Install the BrowserStack Cypress CLI globally
npm install -g browserstack-cypress-cli

# Navigate to your Cypress project directory
cd my-cypress-project

# Generate a sample browserstack.json configuration file
browserstack-cypress init

# Edit browserstack.json to add your BrowserStack credentials and desired capabilities
# Example partial browserstack.json content:
/*
{
  "auth": {
    "username": "$BROWSERSTACK_USERNAME",
    ""access_key": "$BROWSERSTACK_ACCESS_KEY"
  },
  "browsers": [
    {
      "browser": "chrome",
      "os": "Windows 10",
      "versions": ["latest"]
    }
  ],
  "run_settings": {
    "cypress_config_file": "cypress.config.js",
    "npm_dependencies": {},
    "headless": true
  }
}
*/

# Run your Cypress tests on BrowserStack
browserstack-cypress run

view raw JSON →