{
  "doc": {
    "id": "api/commands/exec",
    "title": "exec | Cypress Documentation",
    "description": "Execute a system command in Cypress.",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/exec.md",
    "version": "48b03b5502f7aea1d0454750cce208f775403542",
    "updated_at": "2026-05-20T19:00:20.270Z",
    "headings": [
      {
        "id": "api/commands/exec#exec",
        "text": "exec",
        "level": 1
      },
      {
        "id": "api/commands/exec#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/exec#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/exec#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/exec#yields-learn-about-subject-management",
        "text": "Yields Learn about subject management",
        "level": 3
      },
      {
        "id": "api/commands/exec#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/exec#command",
        "text": "Command",
        "level": 3
      },
      {
        "id": "api/commands/exec#run-a-build-command",
        "text": "Run a build command",
        "level": 4
      },
      {
        "id": "api/commands/exec#seed-the-database-and-assert-it-was-successful",
        "text": "Seed the database and assert it was successful",
        "level": 4
      },
      {
        "id": "api/commands/exec#run-an-arbitrary-script-and-assert-its-output",
        "text": "Run an arbitrary script and assert its output",
        "level": 4
      },
      {
        "id": "api/commands/exec#write-to-a-file-to-create-a-fixture-from-response-body",
        "text": "Write to a file to create a fixture from response body",
        "level": 4
      },
      {
        "id": "api/commands/exec#options",
        "text": "Options",
        "level": 3
      },
      {
        "id": "api/commands/exec#change-the-timeout",
        "text": "Change the timeout",
        "level": 4
      },
      {
        "id": "api/commands/exec#choose-to-not-fail-on-non-zero-exit-and-assert-on-code-and-stderr",
        "text": "Choose to not fail on non-zero exit and assert on code and stderr",
        "level": 4
      },
      {
        "id": "api/commands/exec#specify-system-environment-variables",
        "text": "Specify system environment variables",
        "level": 4
      },
      {
        "id": "api/commands/exec#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/commands/exec#commands-must-exit",
        "text": "Commands Must Exit",
        "level": 3
      },
      {
        "id": "api/commands/exec#commands-that-do-not-exit-are-not-supported",
        "text": "Commands that do not exit are not supported",
        "level": 4
      },
      {
        "id": "api/commands/exec#reset-timeout-via-cypress-config",
        "text": "Reset timeout via Cypress.config()",
        "level": 3
      },
      {
        "id": "api/commands/exec#set-timeout-in-the-test-configuration",
        "text": "Set timeout in the test configuration",
        "level": 3
      },
      {
        "id": "api/commands/exec#rules",
        "text": "Rules",
        "level": 2
      },
      {
        "id": "api/commands/exec#requirements-learn-about-chaining-commands",
        "text": "Requirements Learn about chaining commands",
        "level": 3
      },
      {
        "id": "api/commands/exec#assertions-learn-about-assertions",
        "text": "Assertions Learn about assertions",
        "level": 3
      },
      {
        "id": "api/commands/exec#timeouts-learn-about-timeouts",
        "text": "Timeouts Learn about timeouts",
        "level": 3
      },
      {
        "id": "api/commands/exec#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/exec#history",
        "text": "History",
        "level": 2
      },
      {
        "id": "api/commands/exec#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "api/commands/exec#syntax",
      "doc_id": "api/commands/exec",
      "heading": "Syntax",
      "heading_level": 2,
      "content_markdown": "## Syntax\n\n```\ncy.exec(command)cy.exec(command, options)\n```\n\n### Usage\n\n**Correct Usage**\n\n```\ncy.exec('npm run build')\n```\n\n### Arguments\n\n**command _(String)_**\n\nThe system command to be executed from the project root (the directory that contains the [Cypress configuration file](/llm/markdown/app/references/configuration.md)).\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `cy.exec()`.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |\n| `env` | `{}` | Object of environment variables to set before the command executes (e.g. `{USERNAME: 'johndoe'}`). Will be merged with existing system environment variables |\n| `failOnNonZeroExit` | `true` | whether to fail if the command exits with a non-zero code |\n| `timeout` | [`execTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `cy.exec()` to resolve before [timing out](#Timeouts) |\n\n### Yields [Learn about subject management](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management)\n\n`cy.exec()` yields an object with the following properties:\n\n*   `exitCode`\n*   `stdout`\n*   `stderr`\n",
      "section": "api",
      "anchors": [
        "syntax"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 211
    },
    {
      "id": "api/commands/exec#arguments",
      "doc_id": "api/commands/exec",
      "heading": "Arguments",
      "heading_level": 3,
      "content_markdown": "### Arguments\n\n**command _(String)_**\n\nThe system command to be executed from the project root (the directory that contains the [Cypress configuration file](/llm/markdown/app/references/configuration.md)).\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `cy.exec()`.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |\n| `env` | `{}` | Object of environment variables to set before the command executes (e.g. `{USERNAME: 'johndoe'}`). Will be merged with existing system environment variables |\n| `failOnNonZeroExit` | `true` | whether to fail if the command exits with a non-zero code |\n| `timeout` | [`execTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `cy.exec()` to resolve before [timing out](#Timeouts) |\n",
      "section": "api",
      "anchors": [
        "arguments"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 164
    },
    {
      "id": "api/commands/exec#examples",
      "doc_id": "api/commands/exec",
      "heading": "Examples",
      "heading_level": 2,
      "content_markdown": "## Examples\n\n### Command\n\n`cy.exec()` provides an escape hatch for running arbitrary system commands, so you can take actions necessary for your test outside the scope of Cypress. This is great for:\n\n*   Running build scripts\n*   Seeding your test database\n*   Starting processes\n*   Killing processes\n\n#### Run a build command\n\n```\ncy.exec('npm run build').then((result) => {  // yields the 'result' object  // {  //   exitCode: 0,  //   stdout: \"Files successfully built\",  //   stderr: \"\"  // }})\n```\n\n#### Seed the database and assert it was successful\n\n```\ncy.exec('rake db:seed').its('exitCode').should('eq', 0)\n```\n\n#### Run an arbitrary script and assert its output\n\n```\ncy.exec('npm run my-script')  .its('stdout')  .should('contain', 'Done running the script')\n```\n\n#### Write to a file to create a fixture from response body\n\n```\ncy.intercept('POST', '/comments').as('postComment')cy.get('.add-comment').click()cy.wait('@postComment').then(({ response }) => {  cy.exec(    `echo ${JSON.stringify(response.body)} >cypress/fixtures/comment.json`  )  cy.fixture('comment.json').should('deep.eq', response.body)})\n```\n\n### Options\n\n#### Change the timeout\n\nYou can increase the time allowed to execute the command, although _we don't recommend executing commands that take a long time to exit_.\n\nCypress will _not_ continue running any other commands until `cy.exec()` has finished, so a long-running command will drastically slow down your test cycle.\n\n```\n// will fail if script takes longer than 20 seconds to finishcy.exec('npm run build', { timeout: 20000 })\n```\n\n#### Choose to not fail on non-zero exit and assert on code and stderr\n\n```\ncy.exec('man bear pig', { failOnNonZeroExit: false }).then((result) => {  expect(result.exitCode).to.eq(1)  expect(result.stderr).to.contain('No manual entry for bear')})\n```\n\n#### Specify system environment variables\n\n```\ncy.exec('echo $USERNAME', { env: { USERNAME: 'johndoe' } })  .its('stdout')  .should('contain', 'johndoe')\n```\n",
      "section": "api",
      "anchors": [
        "examples"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 349
    },
    {
      "id": "api/commands/exec#command",
      "doc_id": "api/commands/exec",
      "heading": "Command",
      "heading_level": 3,
      "content_markdown": "### Command\n\n`cy.exec()` provides an escape hatch for running arbitrary system commands, so you can take actions necessary for your test outside the scope of Cypress. This is great for:\n\n*   Running build scripts\n*   Seeding your test database\n*   Starting processes\n*   Killing processes\n\n#### Run a build command\n\n```\ncy.exec('npm run build').then((result) => {  // yields the 'result' object  // {  //   exitCode: 0,  //   stdout: \"Files successfully built\",  //   stderr: \"\"  // }})\n```\n\n#### Seed the database and assert it was successful\n\n```\ncy.exec('rake db:seed').its('exitCode').should('eq', 0)\n```\n\n#### Run an arbitrary script and assert its output\n\n```\ncy.exec('npm run my-script')  .its('stdout')  .should('contain', 'Done running the script')\n```\n\n#### Write to a file to create a fixture from response body\n\n```\ncy.intercept('POST', '/comments').as('postComment')cy.get('.add-comment').click()cy.wait('@postComment').then(({ response }) => {  cy.exec(    `echo ${JSON.stringify(response.body)} >cypress/fixtures/comment.json`  )  cy.fixture('comment.json').should('deep.eq', response.body)})\n```\n",
      "section": "api",
      "anchors": [
        "command"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 184
    },
    {
      "id": "api/commands/exec#run-a-build-command",
      "doc_id": "api/commands/exec",
      "heading": "Run a build command",
      "heading_level": 4,
      "content_markdown": "#### Run a build command\n\n```\ncy.exec('npm run build').then((result) => {  // yields the 'result' object  // {  //   exitCode: 0,  //   stdout: \"Files successfully built\",  //   stderr: \"\"  // }})\n```\n",
      "section": "api",
      "anchors": [
        "run-a-build-command"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 43
    },
    {
      "id": "api/commands/exec#options",
      "doc_id": "api/commands/exec",
      "heading": "Options",
      "heading_level": 3,
      "content_markdown": "### Options\n\n#### Change the timeout\n\nYou can increase the time allowed to execute the command, although _we don't recommend executing commands that take a long time to exit_.\n\nCypress will _not_ continue running any other commands until `cy.exec()` has finished, so a long-running command will drastically slow down your test cycle.\n\n```\n// will fail if script takes longer than 20 seconds to finishcy.exec('npm run build', { timeout: 20000 })\n```\n\n#### Choose to not fail on non-zero exit and assert on code and stderr\n\n```\ncy.exec('man bear pig', { failOnNonZeroExit: false }).then((result) => {  expect(result.exitCode).to.eq(1)  expect(result.stderr).to.contain('No manual entry for bear')})\n```\n\n#### Specify system environment variables\n\n```\ncy.exec('echo $USERNAME', { env: { USERNAME: 'johndoe' } })  .its('stdout')  .should('contain', 'johndoe')\n```\n",
      "section": "api",
      "anchors": [
        "options"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 163
    },
    {
      "id": "api/commands/exec#change-the-timeout",
      "doc_id": "api/commands/exec",
      "heading": "Change the timeout",
      "heading_level": 4,
      "content_markdown": "#### Change the timeout\n\nYou can increase the time allowed to execute the command, although _we don't recommend executing commands that take a long time to exit_.\n\nCypress will _not_ continue running any other commands until `cy.exec()` has finished, so a long-running command will drastically slow down your test cycle.\n\n```\n// will fail if script takes longer than 20 seconds to finishcy.exec('npm run build', { timeout: 20000 })\n```\n",
      "section": "api",
      "anchors": [
        "change-the-timeout"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 93
    },
    {
      "id": "api/commands/exec#choose-to-not-fail-on-non-zero-exit-and-assert-on-code-and-stderr",
      "doc_id": "api/commands/exec",
      "heading": "Choose to not fail on non-zero exit and assert on code and stderr",
      "heading_level": 4,
      "content_markdown": "#### Choose to not fail on non-zero exit and assert on code and stderr\n\n```\ncy.exec('man bear pig', { failOnNonZeroExit: false }).then((result) => {  expect(result.exitCode).to.eq(1)  expect(result.stderr).to.contain('No manual entry for bear')})\n```\n",
      "section": "api",
      "anchors": [
        "choose-to-not-fail-on-non-zero-exit-and-assert-on-code-and-stderr"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 41
    },
    {
      "id": "api/commands/exec#notes",
      "doc_id": "api/commands/exec",
      "heading": "Notes",
      "heading_level": 2,
      "content_markdown": "## Notes\n\n### Commands Must Exit\n\n#### Commands that do not exit are not supported\n\n`cy.exec()` does not support commands that don't exit, such as:\n\n*   Starting a `rails server`\n*   A task that runs a watch\n*   Any process that needs to be manually interrupted to stop\n\nA command must exit within the `execTimeout` or Cypress will kill the command's process and fail the current test.\n\n### Reset timeout via `Cypress.config()`\n\nYou can change the timeout of `cy.exec()` for the remainder of the tests by setting the new values for `execTimeout` within [Cypress.config()](/llm/markdown/api/cypress-api/config.md).\n\n```\nCypress.config('execTimeout', 30000)Cypress.config('execTimeout') // => 30000\n```\n\n### Set timeout in the test configuration\n\nYou can configure the `cy.exec()` timeout within a suite or test by passing the new configuration value within the [test configuration](/llm/markdown/app/references/configuration.md#Test-Configuration).\n\nThis will set the timeout throughout the duration of the tests, then return it to the default `execTimeout` when complete.\n\n```\ndescribe('has data available from database', { execTimeout: 90000 }, () => {  before(() => {    cy.exec('rake db:seed')  })  // tests  after(() => {    cy.exec('rake db:reset')  })})\n```\n",
      "section": "api",
      "anchors": [
        "notes"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 236
    },
    {
      "id": "api/commands/exec#commands-must-exit",
      "doc_id": "api/commands/exec",
      "heading": "Commands Must Exit",
      "heading_level": 3,
      "content_markdown": "### Commands Must Exit\n\n#### Commands that do not exit are not supported\n\n`cy.exec()` does not support commands that don't exit, such as:\n\n*   Starting a `rails server`\n*   A task that runs a watch\n*   Any process that needs to be manually interrupted to stop\n\nA command must exit within the `execTimeout` or Cypress will kill the command's process and fail the current test.\n",
      "section": "api",
      "anchors": [
        "commands-must-exit"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 87
    },
    {
      "id": "api/commands/exec#commands-that-do-not-exit-are-not-supported",
      "doc_id": "api/commands/exec",
      "heading": "Commands that do not exit are not supported",
      "heading_level": 4,
      "content_markdown": "#### Commands that do not exit are not supported\n\n`cy.exec()` does not support commands that don't exit, such as:\n\n*   Starting a `rails server`\n*   A task that runs a watch\n*   Any process that needs to be manually interrupted to stop\n\nA command must exit within the `execTimeout` or Cypress will kill the command's process and fail the current test.\n",
      "section": "api",
      "anchors": [
        "commands-that-do-not-exit-are-not-supported"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 81
    },
    {
      "id": "api/commands/exec#reset-timeout-via-cypress-config",
      "doc_id": "api/commands/exec",
      "heading": "Reset timeout via Cypress.config()",
      "heading_level": 3,
      "content_markdown": "### Reset timeout via `Cypress.config()`\n\nYou can change the timeout of `cy.exec()` for the remainder of the tests by setting the new values for `execTimeout` within [Cypress.config()](/llm/markdown/api/cypress-api/config.md).\n\n```\nCypress.config('execTimeout', 30000)Cypress.config('execTimeout') // => 30000\n```\n",
      "section": "api",
      "anchors": [
        "reset-timeout-via-cypress-config"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 45
    },
    {
      "id": "api/commands/exec#set-timeout-in-the-test-configuration",
      "doc_id": "api/commands/exec",
      "heading": "Set timeout in the test configuration",
      "heading_level": 3,
      "content_markdown": "### Set timeout in the test configuration\n\nYou can configure the `cy.exec()` timeout within a suite or test by passing the new configuration value within the [test configuration](/llm/markdown/app/references/configuration.md#Test-Configuration).\n\nThis will set the timeout throughout the duration of the tests, then return it to the default `execTimeout` when complete.\n\n```\ndescribe('has data available from database', { execTimeout: 90000 }, () => {  before(() => {    cy.exec('rake db:seed')  })  // tests  after(() => {    cy.exec('rake db:reset')  })})\n```\n",
      "section": "api",
      "anchors": [
        "set-timeout-in-the-test-configuration"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 101
    },
    {
      "id": "api/commands/exec#rules",
      "doc_id": "api/commands/exec",
      "heading": "Rules",
      "heading_level": 2,
      "content_markdown": "## Rules\n\n### Requirements [Learn about chaining commands](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands)\n\n*   `cy.exec()` requires being chained off of `cy`.\n*   `cy.exec()` requires the executed system command to eventually exit.\n*   `cy.exec()` requires that the exit code be `0` when `failOnNonZeroExit` is `true`.\n\n### Assertions [Learn about assertions](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions)\n\n*   `cy.exec()` will only run assertions you have chained once, and will not [retry](/llm/markdown/app/core-concepts/retry-ability.md).\n\n### Timeouts [Learn about timeouts](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Timeouts)\n\n*   `cy.exec()` can time out waiting for the system command to exist.\n",
      "section": "api",
      "anchors": [
        "rules"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 100
    },
    {
      "id": "api/commands/exec#requirements-learn-about-chaining-commands",
      "doc_id": "api/commands/exec",
      "heading": "Requirements Learn about chaining commands",
      "heading_level": 3,
      "content_markdown": "### Requirements [Learn about chaining commands](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands)\n\n*   `cy.exec()` requires being chained off of `cy`.\n*   `cy.exec()` requires the executed system command to eventually exit.\n*   `cy.exec()` requires that the exit code be `0` when `failOnNonZeroExit` is `true`.\n",
      "section": "api",
      "anchors": [
        "requirements-learn-about-chaining-commands"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 49
    },
    {
      "id": "api/commands/exec#command-log",
      "doc_id": "api/commands/exec",
      "heading": "Command Log",
      "heading_level": 2,
      "content_markdown": "## Command Log\n\n**_List the contents of your package.json file_**\n\n```\nif (Cypress.platform === 'win32') {  cy.exec('type package.json').its('stderr').should('be.empty')} else {  cy.exec('cat package.json').its('stderr').should('be.empty')}\n```\n\nThe command above will display in the Command Log as:\n\nWhen clicking on the `exec` command within the command log, the console outputs the following:\n",
      "section": "api",
      "anchors": [
        "command-log"
      ],
      "path": "/llm/json/chunked/api/commands/exec.json",
      "token_estimate": 64
    }
  ]
}