Skip to main content

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.

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>

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






Thank you for your valuable feedback

Is this page helping you?

Yes
No

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






Thank you for your valuable feedback!

Talk to an Expert
Download Copy