CLI Reference

A list of all the commands and arguments supported by the BrowserStack-Cypress CLI

Here is a list of all the CLI args you can use to run tests, stop the ones that are running, and retrieve build information:

To experience all the supported CLI arguments, we recommend you to use the latest version of CLI. To ensure that you are using the latest version, use npm i -g browserstack-cypress-cli.

Command / Arg	Purpose
`init`	To generate configuration file
`run`	To start running your tests
`generate-report`	To generate build report
`build-info`	To get the build information
`build-stop`	To stop a running build
`--disable-usage-reporting`	To disable usage reporting

Generate configuration file

Use the init command to generate a sample browserstack.json configuration file.

You can optionally specify the filename you want to use for the BrowserStack configuration file.

For example:

Command Line

# Create a sample configuration file for configurations and capabilities
browserstack-cypress init

# Create a sample configuration file as browserstack.staging.json
browserstack-cypress init browserstack.staging.json

Additional arguments that are available with the init command are:

Arg	Accepted values
`--path`	Path to the directory or folder where you need the `browserstack.json` file to be generated. Make sure that the specified folder exists before using this parameter. Default: `./` (the current directory)

Run tests

You can start running your test build using the following command.

Command Line

browserstack-cypress run

Additional arguments that are available with the run command are:

Argument	Shorthand	Syntax	Accepted values
`--browser` CLI v1.11.0 and above	N/A	`--browser "<browser> @ <browser_version>:<os>"`	Accepts a comma-separated list. Your build will be run only on the list of specified browsers. For example `--browser "chrome@latest:Windows 10","firefox@latest-1:OS X Catalina"`. You can also omit specifying `os` in which case, your tests would run in any one of the OSes.
`--build-name`	`-b`	`-b <build_name>`	The build name to use for this build
`--ci-build-id` CLI v1.11.0 and above	N/A		You can also use this for specifying the build name
`--config` CLI v1.11.0 and above	`-c`		Comma-separated list of any/all config options supported by Cypress.
`--config-file`	`--cf`	`--cf <path-to-browserstack.json>`	Path to the BrowserStack config file. Default: `./browserstack.json`
`--cypress-config-file`	`--ccf`		Path (absolute or relative to browserstack.json) to the Cypress configuration file
`--env`	N/A		Comma separated key=value pairs of the environment variables to set before running your tests
`--home-directory`	N/A	`--home-directory <path-to-home-directory`	Path to the home directory. Read more about how to specify home directory.
`--exclude`	`-e`	`-e <exact_path>`	Comma separated patterns (an exact path or a regex) of the files you want to exclude. Read about more ways of specifying environment variables.
`--headed`	N/A		Optionally, pass this to run your tests in a browser in headed mode as opposed to headless (with some performance degradation)
`--timezone`	N/A	`--timezone=London`	Pass this to configure your tests to run on a custom timezone. Read more about configuring timezones.
`--nodeVersion`	`--nv`	`--nodeVersion <node_version>`	Pass the required node version to run your Cypress tests. Supported node versions are `14.19.1`, `16.15.0` and `18.17.0`
`--parallels`, or `--parallel`	`-p`		The integer number of parallels to use while running the build
`--projectID`		`--projectId "<your_cypress_project_id>"`	Used together only with the `record` and `record-key` arguments. `projectId` generated for the project as defined on Cypress dashboard. You can also specify the `projectId` in the `cypress.json` file of your project.
`--record`		`--record --record-key "<your_record-key>" --projectId "<your_cypress_project_id>`	Used together only with the `projectID` and `record-key` arguments. Set to send test results to the Cypress.io dashboard.
`--record-key`		`--record-key "<your_record-key>"`	Used together only with the `record` and `projectID` arguments. You need to specify the `record-key` generated for the project as defined on Cypress.io dashboard to be able to use the Cypress.io dashboard
`--reporter` CLI v1.10.1 and above	`-r`		As supported by Cypress (See Cypress docs). You would need to specify download folder to be able to download the reports. Read more about downloading Cypress custom reports or other build artifacts.
`--reporter-options` CLI v1.10.1 and above	`-o`		As supported by Cypress (See Cypress docs). You would need to specify download folder to be able to download the reports. Read more about downloading Cypress custom reports or other build artifacts.
`--specs`	`-s`		Comma separated patterns (an exact path or a regex) for your spec files
`--async` CLI v1.11.0 and above	N/A		No values required. Use this flag to run the tests asynchronously. In the previous versions `--async` was the default argument, and `--sync` had to be specified to run tests synchronously. `--sync` is the default argument from v1.11.0
`--no-wrap`	N/A	`--no-wrap`	In case of a smaller terminal window, pass this argument to wrap the spec names in sync mode.
`--username`	`-u`	`-u <browserstack_username>`	Your BrowserStack username
`--key`	`-k`	`-k <browserstack_access_key>`	Your BrowserStack access key

Values of CLI arguments take precedence over the same argument’s values if specified in the browserstack.json file.

Example:

Command Line

browserstack-cypress --cf <path-to-browserstack.json> run --sync --parallels 5 <any-other-args>

Generate build report

If you didn’t run the build in sync mode (using --sync), the HTML and JSON files with the build run summary are not automatically created. You can use the generate-report command to generate the HTML and JSON instead.

Command Line

browserstack-cypress generate-report <build-id>

Additional arguments that are available with the generate-report command are:

Arg	Shorthand	Accepted values
`--username`	`-u`	Your BrowserStack username
`--key`	`-k`	Your BrowserStack access key
`--config-file`	`--cf`	Path to the BrowserStack config file. Default: `./browserstack.json`

Example:

Command Line

browserstack-cypress --cf <path-to-browserstack.json> generate-report <build-id>

Generate build artifacts

If you didn’t run the build in sync mode (using --sync), the specified build artifacts to be downloaded will not be downloaded after the build completion automatically. You can use the generate-downloads command to generate all the specified downloads after the build has completed. You can learn more about downloading custom reports and build artifacts.

Command Line

browserstack-cypress generate-downloads <build-id>

Get the build information

In case you want to get information on the build you can use the build-info command:

Command Line

browserstack-cypress build-info <buildId>

Sample response

[2/20/2020, 3:01:52 PM]  Getting information for buildId 06f28ce423d10314b32e98bb6f68e10b0d02a49a
[2/20/2020, 3:01:52 PM]  Reading browserstack.json from /browserstack.json
[2/20/2020, 3:01:54 PM]  Build info for build id:
 {
  "build_id": "06f28ce423d10314b32e98bb6f68e10b0d02a49a",
  "framework": "cypress",
  "status": "done",
  "input_capabilities": {
    "devices": [
      "OS X Catalina-chrome69",
      "OS X Catalina-chrome66"
    ],
    "testSuite": "15f90b540b8cbc47929782f35bb7db20fe1c4709",
    "customBuildName": "cypress build",
    "local": false,
    "localIdentifier": null,
    "callbackURL": null,
    "projectNotifyURL": null,
    "project": "test"
  },
  "start_time": "2020-02-20 09:28:35 UTC",
  "device_statuses": {
    "success": {
      "OS X Catalina-chrome69": "Success",
      "OS X Catalina-chrome66": "Success"
    },
    "error": {}
  },
  "test_suite_details": {
    "url": "bs://15f90b540b8cbc47929782f35bb7db20fe1c4709",
    "name": "tests.zip",
    "size": 354
  },
  "duration": "33 seconds",
  "devices": {
    "OS X Catalina-chrome69": {
      "session_id": "3b4038cbbc55d34c1b33c930f3417c7c534c25dd",
      "status": "done",
      "test_status": {
        "failed": 0,
        "success": 3,
        "queued": 0,
        "ignored": 0
      }
    },
    "OS X Catalina-chrome66": {
      "session_id": "fbda8eb5a9eeb7823a9ef7be1a42213c568197e8",
      "status": "done",
      "test_status": {
        "failed": 0,
        "success": 3,
        "queued": 0,
        "ignored": 0
      }
    }
  }
}

Note that each browser version represents a session. It is advised to validate your account’s parallel limit before running multiple versions.

Additional arguments that are available with the build-info command are:

Arg	Shorthand	Accepted values
`--config-file`	`--cf`	Path to the BrowserStack config file. Default: `./browserstack.json`

Example:

Command Line

browserstack-cypress --cf <path-to-browserstack.json> build-info <buildId>

Stop a running build

In case you want to stop a running build, you can use the build-stop command:

Command Line

browserstack-cypress build-stop <buildId>

Additional arguments that are available with the build-stop command are:

Arg	Shorthand	Accepted values
`--config-file`	`--cf`	Path to the BrowserStack config file. Default: `./browserstack.json`

Example:

Command Line

browserstack-cypress --config-file <path-to-browserstack.json> build-stop <buildId>

Disable usage reporting

The CLI collects anonymized usage data including the command-line arguments used, system details and errors that you get so that we can improve the way you run your Cypress tests on BrowserStack. Usage reporting is enabled by default - you can disable usage reporting by using the --disable-usage-reporting flag. You can also do this by setting the disable_usage_reporting option to "true" in browserstack.json.

Command Line

browserstack-cypress --disable-usage-reporting <your-commands>

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!