{"_id":"589e16259129bd2300ab1f04","parentDoc":null,"project":"568fde81b700ce0d002f4b43","version":{"_id":"56954a94fe18811700c9bfda","project":"568fde81b700ce0d002f4b43","__v":6,"createdAt":"2016-01-12T18:48:52.007Z","releaseDate":"2016-01-12T18:48:52.007Z","categories":["56954a95fe18811700c9bfdb","56954a95fe18811700c9bfdc","56954a95fe18811700c9bfdd","56954a95fe18811700c9bfde","56954a95fe18811700c9bfdf","56954a95fe18811700c9bfe0","56954a95fe18811700c9bfe1","56954a95fe18811700c9bfe2","56954a95fe18811700c9bfe3","56954a95fe18811700c9bfe4","5695649fdcaf0d1700cb8721","5696c1168560a60d00e2c1d6","56a7a32e79395317007c1ad6","5898fc3eec49fb0f004c2663","589cc675ea37da23004e05e1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"foo","version_clean":"0.0.0","version":"0.0"},"category":{"_id":"5696c1168560a60d00e2c1d6","__v":9,"pages":["5696c11aaa12bc0d0050332c","5696c11aaa12bc0d0050332d","5696c11a8400d52d00dd5631","5696c11a59a6692d003fad06","56a007d14583912300b5efcf","56a007d166c8420d00d7fc7c","56a6824e683cfb0d00dc586f","56b383fe3ccec63700a7ac1c","56b3a7de0e4c450d00699d22"],"project":"568fde81b700ce0d002f4b43","version":"56954a94fe18811700c9bfda","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-13T21:26:46.069Z","from_sync":false,"order":5,"slug":"references","title":"References"},"__v":0,"user":"568fffce769f210d0013258f","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-02-10T19:36:05.881Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"# Contents\n\n- :fa-angle-right: [What is the CLI Tool?](#section-what-is-the-cli-tool-)\n- :fa-angle-right: [Installation](#section-installation)\n- :fa-angle-right: [Available Commands](#section-available-commands)\n  - [cypress install](#section--cypress-install-)\n  - [cypress update](#section--cypress-update-)\n  - [cypress run](#section--cypress-run-)\n  - [cypress run --record](cli#section--cypress-run-record-)\n  - [cypress open](#section--cypress-open-)\n  - [cypress get:path](#section--cypress-get-path-)\n  - [cypress verify](#section--cypress-verify-)\n  - [cypress version](#section--cypress-version-)\n\n***\n\n# What is the CLI Tool?\n\nThe CLI Tool is an [`npm package`](https://github.com/cypress-io/cypress-cli) that wraps the Desktop Application.\n\nIt provides a set of commands that can be used to do things like:\n\n- Install Cypress\n- Run Cypress headlessly\n- Record your test runs\n- Output the current installed version\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"You generally install the CLI tool so you can progamatically install and run Cypress. This is commonly used when running Cypress from your CI provider.\"\n}\n[/block]\n\n***\n\n# Installation\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"npm install -g cypress-cli\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\nThis will make the `cypress` command globally available from your command line.\n\nYou can now execute the following commands:\n\n***\n\n# Available Commands\n\n## `cypress install`\n\nInstalls the **Cypress Desktop Application** to the default location for each Operating System.\n\nOS | Path\n:--- | :---\nMac  | `/Applications/Cypress.app`\nLinux  | `/home/<user>/.cypress/Cypress`\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## by default will install the latest version\\ncypress install\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## install a specific version\\ncypress install --cypress-version 0.13.0\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\nAdditionally if you have a `CYPRESS_VERSION` environment variable set, it will automatically download that version. This is most useful when running Cypress in CI.\n\n![cypress-cli](https://cloud.githubusercontent.com/assets/1268976/14435124/4f632278-ffe4-11e5-9dab-0a2d493551b3.gif)\n\n***\n\n## `cypress update`\n\nUpdates Cypress to the latest version. This does the same thing as `cypress install`.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## now we have the latest version\\ncypress update\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## `cypress run`\n\nRuns Cypress headlessly without spawning a browser.\n\nYou can use this command when working locally or when running in [Continuous Integration](https://on.cypress.io/guides/continuous-integration).\n\nCypress will first check to see that the Desktop Application is installed and will automatically install it prior to running (if necessary).\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Want your test runs recorded?\",\n  \"body\": \"You can also have Cypress record your test runs and make them available on our [Dashboard](https://on.cypress.io/guides/dashboard-features).\"\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## by default will use your current path\\ncypress run\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## or you can specify a path to the project\\ncypress run /users/john/projects/TodoMVC\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## specify a port to use which overrides values in cypress.json\\ncypress run --port 8080\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## specify a mocha reporter to use\\ncypress run --reporter json\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## specify options for the mocha reporter\\ncypress run --reporter-options mochaFile=result.xml,toConsole=true\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## specify a file to run instead of running all the tests files\\ncypress run --spec cypress/integration/app_spec.js\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## specify environment variables\\ncypress run --env host=api.dev.local\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## specify configuration values to override cypress.json\\ncypress run --config pageLoadTimeout=100000,watchForFileChanges=false\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\nYou can read more about [environment variables](https://on.cypress.io/environment-variables) and [configuration](https://on.cypress.io/configuration) here.\n\n***\n\n## `cypress run --record`\n\nYou can also have your test runs recorded [once your project is setup to record](https://on.cypress.io/guides/projects).\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"You'd typically record your runs in [Continuous Integration](https://on.cypress.io/guides/continuous-integration), but you can also record when running locally.\"\n}\n[/block]\n\nAfter setting up your project you will recieve a **Record Key**.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cypress run --record --key <record_key>\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\nIf you set this **Record Key** as an environment variable you can omit the `--key` flag.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## you'd typically set this in your CI provider\\nexport CYPRESS_RECORD_KEY=abc-key-123\\n\\n## we can now omit --key\\ncypress run --record\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\nYou can [read more](https://on.cypress.io/how-do-i-record-runs) about recording runs here.\n\n***\n\n## `cypress open`\n\nOpens the Cypress application. This is the same thing as double-clicking the application.\n\nIn Mac you'll see the **cy** icon in the dock and in Linux you'll see the Cypress application window open.\n\nArguments you pass to `cypress open` will automatically be applied to the projects you open. These persist onto all projects until you quit the Cypress Desktop Application.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## specify a port to use which overrides values in cypress.json\\ncypress open --port 8080\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## specify configuration values which override cypress.json\\ncypress open --config pageLoadTimeout=100000,watchForFileChanges=false\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"## specify environment variables\\ncypress open --env host=api.dev.local\\n\",\n            \"language\": \"shell\"\n        }\n    ]\n}\n[/block]\n\n***\n\n## `cypress get:path`\n\nReturns the path Cypress will be installed to. Additionally checks to see if Cypress already exists at that path.\n\n***\n\n## `cypress verify`\n\nVerifies that the Cypress application is found.\n\n***\n\n## `cypress version`\n\nOutputs both the version of the CLI Tool and the installed Cypress application.","excerpt":"Cypress CLI Tool for programmatically interacting with the Desktop Application","slug":"cli","type":"basic","title":"CLI Tool"}

CLI Tool

Cypress CLI Tool for programmatically interacting with the Desktop Application

# Contents - :fa-angle-right: [What is the CLI Tool?](#section-what-is-the-cli-tool-) - :fa-angle-right: [Installation](#section-installation) - :fa-angle-right: [Available Commands](#section-available-commands) - [cypress install](#section--cypress-install-) - [cypress update](#section--cypress-update-) - [cypress run](#section--cypress-run-) - [cypress run --record](cli#section--cypress-run-record-) - [cypress open](#section--cypress-open-) - [cypress get:path](#section--cypress-get-path-) - [cypress verify](#section--cypress-verify-) - [cypress version](#section--cypress-version-) *** # What is the CLI Tool? The CLI Tool is an [`npm package`](https://github.com/cypress-io/cypress-cli) that wraps the Desktop Application. It provides a set of commands that can be used to do things like: - Install Cypress - Run Cypress headlessly - Record your test runs - Output the current installed version [block:callout] { "type": "info", "body": "You generally install the CLI tool so you can progamatically install and run Cypress. This is commonly used when running Cypress from your CI provider." } [/block] *** # Installation [block:code] { "codes": [ { "code": "npm install -g cypress-cli\n", "language": "shell" } ] } [/block] This will make the `cypress` command globally available from your command line. You can now execute the following commands: *** # Available Commands ## `cypress install` Installs the **Cypress Desktop Application** to the default location for each Operating System. OS | Path :--- | :--- Mac | `/Applications/Cypress.app` Linux | `/home/<user>/.cypress/Cypress` [block:code] { "codes": [ { "code": "## by default will install the latest version\ncypress install\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "## install a specific version\ncypress install --cypress-version 0.13.0\n", "language": "shell" } ] } [/block] Additionally if you have a `CYPRESS_VERSION` environment variable set, it will automatically download that version. This is most useful when running Cypress in CI. ![cypress-cli](https://cloud.githubusercontent.com/assets/1268976/14435124/4f632278-ffe4-11e5-9dab-0a2d493551b3.gif) *** ## `cypress update` Updates Cypress to the latest version. This does the same thing as `cypress install`. [block:code] { "codes": [ { "code": "## now we have the latest version\ncypress update\n", "language": "shell" } ] } [/block] *** ## `cypress run` Runs Cypress headlessly without spawning a browser. You can use this command when working locally or when running in [Continuous Integration](https://on.cypress.io/guides/continuous-integration). Cypress will first check to see that the Desktop Application is installed and will automatically install it prior to running (if necessary). [block:callout] { "type": "success", "title": "Want your test runs recorded?", "body": "You can also have Cypress record your test runs and make them available on our [Dashboard](https://on.cypress.io/guides/dashboard-features)." } [/block] [block:code] { "codes": [ { "code": "## by default will use your current path\ncypress run\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "## or you can specify a path to the project\ncypress run /users/john/projects/TodoMVC\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "## specify a port to use which overrides values in cypress.json\ncypress run --port 8080\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "## specify a mocha reporter to use\ncypress run --reporter json\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "## specify options for the mocha reporter\ncypress run --reporter-options mochaFile=result.xml,toConsole=true\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "## specify a file to run instead of running all the tests files\ncypress run --spec cypress/integration/app_spec.js\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "## specify environment variables\ncypress run --env host=api.dev.local\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "## specify configuration values to override cypress.json\ncypress run --config pageLoadTimeout=100000,watchForFileChanges=false\n", "language": "shell" } ] } [/block] You can read more about [environment variables](https://on.cypress.io/environment-variables) and [configuration](https://on.cypress.io/configuration) here. *** ## `cypress run --record` You can also have your test runs recorded [once your project is setup to record](https://on.cypress.io/guides/projects). [block:callout] { "type": "info", "body": "You'd typically record your runs in [Continuous Integration](https://on.cypress.io/guides/continuous-integration), but you can also record when running locally." } [/block] After setting up your project you will recieve a **Record Key**. [block:code] { "codes": [ { "code": "cypress run --record --key <record_key>\n", "language": "shell" } ] } [/block] If you set this **Record Key** as an environment variable you can omit the `--key` flag. [block:code] { "codes": [ { "code": "## you'd typically set this in your CI provider\nexport CYPRESS_RECORD_KEY=abc-key-123\n\n## we can now omit --key\ncypress run --record\n", "language": "shell" } ] } [/block] You can [read more](https://on.cypress.io/how-do-i-record-runs) about recording runs here. *** ## `cypress open` Opens the Cypress application. This is the same thing as double-clicking the application. In Mac you'll see the **cy** icon in the dock and in Linux you'll see the Cypress application window open. Arguments you pass to `cypress open` will automatically be applied to the projects you open. These persist onto all projects until you quit the Cypress Desktop Application. [block:code] { "codes": [ { "code": "## specify a port to use which overrides values in cypress.json\ncypress open --port 8080\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "## specify configuration values which override cypress.json\ncypress open --config pageLoadTimeout=100000,watchForFileChanges=false\n", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "## specify environment variables\ncypress open --env host=api.dev.local\n", "language": "shell" } ] } [/block] *** ## `cypress get:path` Returns the path Cypress will be installed to. Additionally checks to see if Cypress already exists at that path. *** ## `cypress verify` Verifies that the Cypress application is found. *** ## `cypress version` Outputs both the version of the CLI Tool and the installed Cypress application.