{
  "doc": {
    "id": "app/guides/environment-variables",
    "title": "Environment Variables & Secrets",
    "description": "Learn how to manage environment variables and secrets in Cypress. Understand when to use cy.env(), when to use Cypress.expose(), and how to safely pass values across environments.",
    "section": "app",
    "source_path": "/llm/markdown/app/guides/environment-variables.md",
    "version": "48b03b5502f7aea1d0454750cce208f775403542",
    "updated_at": "2026-05-20T19:00:20.270Z",
    "headings": [
      {
        "id": "app/guides/environment-variables#environment-variables-secrets",
        "text": "Environment Variables & Secrets",
        "level": 1
      },
      {
        "id": "app/guides/environment-variables#secrets-and-sensitive-values",
        "text": "Secrets and sensitive values",
        "level": 2
      },
      {
        "id": "app/guides/environment-variables#public-configuration-values",
        "text": "Public configuration values",
        "level": 2
      },
      {
        "id": "app/guides/environment-variables#set-environment-variables",
        "text": "Set environment variables",
        "level": 2
      },
      {
        "id": "app/guides/environment-variables#1-configuration-file",
        "text": "1. Configuration File",
        "level": 3
      },
      {
        "id": "app/guides/environment-variables#2-cypress-env-json",
        "text": "2. cypress.env.json",
        "level": 3
      },
      {
        "id": "app/guides/environment-variables#3-cypress-environment-variables",
        "text": "3. CYPRESS_* environment variables",
        "level": 3
      },
      {
        "id": "app/guides/environment-variables#4-env-cli-flag",
        "text": "4. --env CLI flag",
        "level": 3
      },
      {
        "id": "app/guides/environment-variables#5-setupnodeevents",
        "text": "5. setupNodeEvents",
        "level": 3
      },
      {
        "id": "app/guides/environment-variables#set-exposed-configuration",
        "text": "Set exposed configuration",
        "level": 2
      },
      {
        "id": "app/guides/environment-variables#1-configuration-file",
        "text": "1. Configuration file",
        "level": 3
      },
      {
        "id": "app/guides/environment-variables#2-expose-cli-flag",
        "text": "2. --expose CLI flag",
        "level": 3
      },
      {
        "id": "app/guides/environment-variables#migrate-from-cypress-env",
        "text": "Migrate from Cypress.env()",
        "level": 2
      },
      {
        "id": "app/guides/environment-variables#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "app/guides/environment-variables#secrets-and-sensitive-values",
      "doc_id": "app/guides/environment-variables",
      "heading": "Secrets and sensitive values",
      "heading_level": 2,
      "content_markdown": "## Secrets and sensitive values\n\n**Use [`cy.env()`](/llm/markdown/api/commands/env.md)** for sensitive values like API keys, passwords, tokens, or credentials.\n\n`cy.env()` retrieves only the values you explicitly request, when you need them, and avoids exposing all environment variables in browser state. This provides privileged access that doesn't automatically serialize values into browser context.\n\n**Examples of secrets:**\n\n*   API keys\n*   Authentication tokens\n*   Passwords\n*   Database credentials\n*   Private service endpoints\n\n```\ncy.env(['apiKey']).then(({ apiKey }) => {  cy.request({    url: 'https://api.example.com/data',    headers: { Authorization: `Bearer ${apiKey}` },  })})\n```\n\nSee the [`cy.env()`](/llm/markdown/api/commands/env.md) command documentation for complete details.\n",
      "section": "app",
      "anchors": [
        "secrets-and-sensitive-values"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 124
    },
    {
      "id": "app/guides/environment-variables#public-configuration-values",
      "doc_id": "app/guides/environment-variables",
      "heading": "Public configuration values",
      "heading_level": 2,
      "content_markdown": "## Public configuration values\n\n**Use [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md)** for public, non-sensitive configuration values.\n\n`Cypress.expose()` provides synchronous access to configuration that is safe to expose in the browser context. Values are accessible to application code, third-party scripts, and browser extensions.\n\n**Examples of public configuration:**\n\n*   Feature flags\n*   API versions\n*   Plugin configuration\n*   Environment labels (staging, prod)\n*   Public service URLs\n\n```\nconst apiVersion = Cypress.expose('apiVersion') // Synchronous accessconst featureFlag = Cypress.expose('featureFlag')if (featureFlag) {  cy.get(`[data-testid=\"feature-${apiVersion}\"]`).should('be.visible')}\n```\n\nSee the [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md) API documentation for complete details.\n",
      "section": "app",
      "anchors": [
        "public-configuration-values"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 109
    },
    {
      "id": "app/guides/environment-variables#set-environment-variables",
      "doc_id": "app/guides/environment-variables",
      "heading": "Set environment variables",
      "heading_level": 2,
      "content_markdown": "## Set environment variables\n\nEnvironment variables for `cy.env()` can be set using several methods:\n\n1.  **Cypress configuration file** - Set in the `env` key of your Cypress configuration\n2.  **`cypress.env.json` file** - Create a `cypress.env.json` file in your project root\n3.  **`CYPRESS_*` environment variables** - Set OS-level environment variables with `CYPRESS_` prefix\n4.  **`--env` CLI flag** - Pass environment variables via command line\n5.  **`setupNodeEvents`** - Set dynamically in the `setupNodeEvents` function\n\n### 1\\. Configuration File\n\nSet environment variables in your Cypress configuration file under the `env` key:\n\n*   cypress.config.js\n*   cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')module.exports = defineConfig({  env: {    apiUrl: 'https://api.example.com',    apiKey: process.env.API_KEY, // From OS environment  },})\n```\n\n```\nimport { defineConfig } from 'cypress'export default defineConfig({  env: {    apiUrl: 'https://api.example.com',    apiKey: process.env.API_KEY, // From OS environment  },})\n```\n\n### 2\\. `cypress.env.json`\n\nCreate a `cypress.env.json` file in your project root. Values here override conflicting environment variables in your Cypress configuration.\n\n```\n{  \"host\": \"veronica.dev.local\",  \"api_server\": \"http://localhost:8888/api/v1/\"}\n```\n\n**Important**: Add `cypress.env.json` to `.gitignore` if it contains sensitive data.\n\n### 3\\. `CYPRESS_*` environment variables\n\nSet OS-level environment variables with the `CYPRESS_` or `cypress_` prefix:\n\n```\nexport CYPRESS_HOST=laura.dev.localexport cypress_api_server=http://localhost:8888/api/v1/\n```\n\nCypress automatically removes the leading `CYPRESS_` or `cypress_` prefix and normalizes the name.\n\nThe environment variable `CYPRESS_INTERNAL_ENV` is reserved and should not be set.\n\n### 4\\. `--env` CLI flag\n\nPass environment variables via the command line. Multiple values must be separated by a comma, not a space. In some shells, like Windows PowerShell, you may need to surround the key/value pair with quotes.\n\n```\ncypress run --env host=kevin.dev.local,api_server=http://localhost:8888/api/v1\n```\n\n### 5\\. setupNodeEvents\n\nSet environment variables dynamically in the `setupNodeEvents` function:\n\n*   cypress.config.js\n*   cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')module.exports = defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      export default defineConfig({        e2e: {          setupNodeEvents(on, config) {            config.env.apiKey = process.env.API_KEY            return config          },        },      })    },  },})\n```\n\n```\nimport { defineConfig } from 'cypress'export default defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      export default defineConfig({        e2e: {          setupNodeEvents(on, config) {            config.env.apiKey = process.env.API_KEY            return config          },        },      })    },  },})\n```\n",
      "section": "app",
      "anchors": [
        "set-environment-variables"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 491
    },
    {
      "id": "app/guides/environment-variables#1-configuration-file",
      "doc_id": "app/guides/environment-variables",
      "heading": "1. Configuration File",
      "heading_level": 3,
      "content_markdown": "### 1\\. Configuration File\n\nSet environment variables in your Cypress configuration file under the `env` key:\n\n*   cypress.config.js\n*   cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')module.exports = defineConfig({  env: {    apiUrl: 'https://api.example.com',    apiKey: process.env.API_KEY, // From OS environment  },})\n```\n\n```\nimport { defineConfig } from 'cypress'export default defineConfig({  env: {    apiUrl: 'https://api.example.com',    apiKey: process.env.API_KEY, // From OS environment  },})\n```\n",
      "section": "app",
      "anchors": [
        "1-configuration-file"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 83
    },
    {
      "id": "app/guides/environment-variables#2-cypress-env-json",
      "doc_id": "app/guides/environment-variables",
      "heading": "2. cypress.env.json",
      "heading_level": 3,
      "content_markdown": "### 2\\. `cypress.env.json`\n\nCreate a `cypress.env.json` file in your project root. Values here override conflicting environment variables in your Cypress configuration.\n\n```\n{  \"host\": \"veronica.dev.local\",  \"api_server\": \"http://localhost:8888/api/v1/\"}\n```\n\n**Important**: Add `cypress.env.json` to `.gitignore` if it contains sensitive data.\n",
      "section": "app",
      "anchors": [
        "2-cypress-env-json"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 51
    },
    {
      "id": "app/guides/environment-variables#3-cypress-environment-variables",
      "doc_id": "app/guides/environment-variables",
      "heading": "3. CYPRESS_* environment variables",
      "heading_level": 3,
      "content_markdown": "### 3\\. `CYPRESS_*` environment variables\n\nSet OS-level environment variables with the `CYPRESS_` or `cypress_` prefix:\n\n```\nexport CYPRESS_HOST=laura.dev.localexport cypress_api_server=http://localhost:8888/api/v1/\n```\n\nCypress automatically removes the leading `CYPRESS_` or `cypress_` prefix and normalizes the name.\n\nThe environment variable `CYPRESS_INTERNAL_ENV` is reserved and should not be set.\n",
      "section": "app",
      "anchors": [
        "3-cypress-environment-variables"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 59
    },
    {
      "id": "app/guides/environment-variables#4-env-cli-flag",
      "doc_id": "app/guides/environment-variables",
      "heading": "4. --env CLI flag",
      "heading_level": 3,
      "content_markdown": "### 4\\. `--env` CLI flag\n\nPass environment variables via the command line. Multiple values must be separated by a comma, not a space. In some shells, like Windows PowerShell, you may need to surround the key/value pair with quotes.\n\n```\ncypress run --env host=kevin.dev.local,api_server=http://localhost:8888/api/v1\n```\n",
      "section": "app",
      "anchors": [
        "4-env-cli-flag"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 60
    },
    {
      "id": "app/guides/environment-variables#5-setupnodeevents",
      "doc_id": "app/guides/environment-variables",
      "heading": "5. setupNodeEvents",
      "heading_level": 3,
      "content_markdown": "### 5\\. setupNodeEvents\n\nSet environment variables dynamically in the `setupNodeEvents` function:\n\n*   cypress.config.js\n*   cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')module.exports = defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      export default defineConfig({        e2e: {          setupNodeEvents(on, config) {            config.env.apiKey = process.env.API_KEY            return config          },        },      })    },  },})\n```\n\n```\nimport { defineConfig } from 'cypress'export default defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      export default defineConfig({        e2e: {          setupNodeEvents(on, config) {            config.env.apiKey = process.env.API_KEY            return config          },        },      })    },  },})\n```\n",
      "section": "app",
      "anchors": [
        "5-setupnodeevents"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 143
    },
    {
      "id": "app/guides/environment-variables#set-exposed-configuration",
      "doc_id": "app/guides/environment-variables",
      "heading": "Set exposed configuration",
      "heading_level": 2,
      "content_markdown": "## Set exposed configuration\n\nExposed configuration for `Cypress.expose()` can be set via:\n\n1.  **Cypress configuration file** - Set in the `expose` key of your Cypress configuration\n2.  **`--expose` CLI flag** - Pass exposed configuration via command line\n\n### 1\\. Configuration file\n\nSet exposed configuration in your Cypress configuration file under the `expose` key:\n\n*   cypress.config.js\n*   cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')module.exports = defineConfig({  expose: {    apiVersion: 'v2',    featureFlag: true,    environment: 'staging',  },})\n```\n\n```\nimport { defineConfig } from 'cypress'export default defineConfig({  expose: {    apiVersion: 'v2',    featureFlag: true,    environment: 'staging',  },})\n```\n\n### 2\\. `--expose` CLI flag\n\nPass exposed configuration via the command line:\n\n```\ncypress run --expose apiVersion=v2,featureFlag=true\n```\n\nSee the [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md) API documentation for complete details on setting exposed configuration.\n",
      "section": "app",
      "anchors": [
        "set-exposed-configuration"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 167
    },
    {
      "id": "app/guides/environment-variables#1-configuration-file",
      "doc_id": "app/guides/environment-variables",
      "heading": "1. Configuration file",
      "heading_level": 3,
      "content_markdown": "### 1\\. Configuration file\n\nSet exposed configuration in your Cypress configuration file under the `expose` key:\n\n*   cypress.config.js\n*   cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')module.exports = defineConfig({  expose: {    apiVersion: 'v2',    featureFlag: true,    environment: 'staging',  },})\n```\n\n```\nimport { defineConfig } from 'cypress'export default defineConfig({  expose: {    apiVersion: 'v2',    featureFlag: true,    environment: 'staging',  },})\n```\n",
      "section": "app",
      "anchors": [
        "1-configuration-file"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 77
    },
    {
      "id": "app/guides/environment-variables#2-expose-cli-flag",
      "doc_id": "app/guides/environment-variables",
      "heading": "2. --expose CLI flag",
      "heading_level": 3,
      "content_markdown": "### 2\\. `--expose` CLI flag\n\nPass exposed configuration via the command line:\n\n```\ncypress run --expose apiVersion=v2,featureFlag=true\n```\n\nSee the [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md) API documentation for complete details on setting exposed configuration.\n",
      "section": "app",
      "anchors": [
        "2-expose-cli-flag"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 40
    },
    {
      "id": "app/guides/environment-variables#migrate-from-cypress-env",
      "doc_id": "app/guides/environment-variables",
      "heading": "Migrate from Cypress.env()",
      "heading_level": 2,
      "content_markdown": "## Migrate from Cypress.env()\n\nIf you're using the deprecated `Cypress.env()` API, migrate to the appropriate modern API:\n\n*   **Sensitive values** → [`cy.env()`](/llm/markdown/api/commands/env.md)\n*   **Public configuration** → [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md)\n\nSee the [Migration Guide](/llm/markdown/app/references/migration-guide.md#Migrating-away-from-Cypressenv) for detailed migration instructions.\n",
      "section": "app",
      "anchors": [
        "migrate-from-cypress-env"
      ],
      "path": "/llm/json/chunked/app/guides/environment-variables.json",
      "token_estimate": 47
    }
  ]
}