--- id: api/commands/env title: env | Cypress Documentation description: >- Securely read environment variables in Cypress tests using cy.env(). Learn syntax, examples, security benefits, and how to migrate from Cypress.env(). section: api source_path: docs/api/commands/env.mdx version: 29b099a83033817a9072f7deec58409720b52bc4 updated_at: '2026-05-03T15:21:58.370Z' --- # env Securely read environment variables set in your Cypress configuration, `cypress.env.json`, or `CYPRESS_*` environment variables from within Cypress tests. **Read-Only Command** `cy.env()` is **read-only** and can only retrieve environment variables. It cannot set or modify environment variables. To set environment variables, use one of the supported methods described in the [Environment Variables & Secrets](/llm/markdown/app/guides/environment-variables.md) guide. ## Syntax ``` cy.env(keys)cy.env(keys, options) ``` ### Usage **Correct Usage** * cypress.config.js * cypress.config.ts ``` const { defineConfig } = require('cypress')module.exports = defineConfig({ env: { apiUrl: 'https://api.example.com', apiKey: 'secret-key-12345', }, expose: { environment: 'staging', // Public configuration value },}) ``` ``` import { defineConfig } from 'cypress'export default defineConfig({ env: { apiUrl: 'https://api.example.com', apiKey: 'secret-key-12345', }, expose: { environment: 'staging', // Public configuration value },}) ``` ``` // Get a single environment variablecy.env(['apiUrl']).then(({ apiUrl }) => { cy.request(`${apiUrl}/users`).its('status').should('eq', 200)})// Get multiple environment variablescy.env(['apiUrl', 'apiKey']).then(({ apiUrl, apiKey }) => { cy.request({ url: `${apiUrl}/users`, headers: { Authorization: `Bearer ${apiKey}` }, }) .its('status') .should('eq', 200)})// With optionscy.env(['apiUrl'], { log: false }).then(({ apiUrl }) => { // Use apiUrl}) ``` ### Arguments **keys _(String\[\])_** An array of environment variable keys to retrieve from Cypress. These environment variables can be set via any of the methods described in the [Environment Variables & Secrets](/llm/markdown/app/guides/environment-variables.md) guide. Environment variables cannot be set using [test configuration](/llm/markdown/app/references/configuration.md#Test-Configuration) when `allowCypressEnv` is set to `false`. If a variable is not defined, its value will return `undefined` in the returned object. **options _(Object)_** Pass an options object to change the default behavior of `cy.env()`. | Option | Default | Description | | --- | --- | --- | | `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log). **Only variable names are logged, never values.** | | `timeout` | 4000 | Time to wait for `cy.env()` to resolve before timing out. | ### Yields [Learn about subject management](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management) `cy.env()` yields an object with the values found for the environment variable keys requested. ``` cy.env(['apiUrl', 'apiKey']).then((env) => { // env = { apiUrl: 'https://api.example.com', apiKey: 'secret-key-12345' }}) ``` ## Examples ### Single Variable Get a single environment variable: ``` cy.env(['apiUrl']).then(({ apiUrl }) => { cy.visit(apiUrl)}) ``` ### Multiple Variables Get multiple environment variables at once: ``` cy.env(['apiUrl', 'apiKey', 'timeout']).then(({ apiUrl, apiKey, timeout }) => { cy.request({ url: `${apiUrl}/users`, headers: { Authorization: `Bearer ${apiKey}` }, timeout: timeout || 5000, })}) ``` ### Use environment variables across tests Store environment variables for use across multiple tests by using a `before()` hook: ``` describe('API tests', () => { let apiBaseUrl before(() => { cy.env(['apiBaseUrl']).then(({ apiBaseUrl: url }) => { apiBaseUrl = url }) }) it('can make requests', () => { cy.request(`${apiBaseUrl}/users`).its('status').should('eq', 200) })}) ``` ### Handle required vs optional variables Variables that are not set will be `undefined`: ``` cy.env(['requiredVar', 'optionalVar']).then(({ requiredVar, optionalVar }) => { if (requiredVar === undefined) { throw new Error('requiredVar must be set in Cypress configuration') } // Use optionalVar only if it's defined if (optionalVar) { // Use optionalVar }}) ``` ### Chaining with other commands ``` cy.env(['baseUrl']).then(({ baseUrl }) => { cy.visit(baseUrl) cy.get('h1').should('be.visible')}) ``` ### Use cy.env in custom commands Create custom commands that use `cy.env()`: ``` // cypress/support/commands.jsCypress.Commands.add('apiRequest', (endpoint, options = {}) => { cy.env(['apiUrl', 'apiKey']).then(({ apiUrl, apiKey }) => { cy.request({ url: `${apiUrl}${endpoint}`, headers: { Authorization: `Bearer ${apiKey}`, ...options.headers, }, ...options, }) })})// In your testcy.apiRequest('/users').its('status').should('eq', 200) ``` ### Suppress command logging Hide the command from the command log: ``` cy.env(['apiKey'], { log: false }).then(({ apiKey }) => { // The command and variable name won't appear in command log}) ``` ## Why use cy.env()? `cy.env()` was introduced to replace the deprecated `Cypress.env()` API. ### Secure access to sensitive values Unlike [`Cypress.env()`](/llm/markdown/api/cypress-api/env.md), which hydrates **all** environment variables into the browser: * `cy.env()` only exposes the variables you explicitly request * Variables are not automatically serialized into browser state * Only requested variables are passed into `cy.origin()` contexts * Sensitive data is easier to audit and control This reduces accidental exposure and limits the blast radius of secrets. ### When to use cy.env() vs Cypress.expose() Both [`cy.env()`](/llm/markdown/api/commands/env.md) and [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md) provide access to configuration values in Cypress, but they serve different security and execution needs. Choosing the right API helps avoid accidental exposure of sensitive data and keeps configuration intent clear. #### Use Cypress.expose() for public configuration Recommended when: * **Values are public or non-sensitive** - Examples include feature flags, API versions, environment labels, or plugin configuration that is safe to appear in browser state. * **Synchronous access is needed** - `Cypress.expose()` returns values immediately, without requiring Cypress command chaining. #### Use `cy.env()` for sensitive or secret values Choose `cy.env()` when security, scoping, and controlled access matter. Recommended when: * **Values are sensitive** - API keys, passwords, tokens, or any data that should not be broadly exposed to the browser. * **Security is a priority** - `cy.env()` only exposes the variables you explicitly request and does not automatically serialize them into browser state. * **You're already working within Cypress command chains**: `cy.env()` is asynchronous and designed to be used inside Cypress tests and hooks. **Example: choosing the right API** ``` // ✅ Use cy.env() for sensitive valuescy.env(['apiKey']).then(({ apiKey }) => { cy.request({ url: 'https://api.example.com/users', headers: { Authorization: `Bearer ${apiKey}` }, })})// ✅ Use Cypress.expose() for public configurationconst apiVersion = Cypress.expose('apiVersion') // Synchronous, public valueconst featureFlag = Cypress.expose('featureFlag') // Safe to expose in browser ``` See [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md) for more details. ## Migrate from Cypress.env() `cy.env()` replaces the deprecated [`Cypress.env()`](/llm/markdown/api/cypress-api/env.md) API. After migrating all usages, you can prevent future use of `Cypress.env()` by disabling it in Cypress configuration using the `allowCypressEnv` option: * cypress.config.js * cypress.config.ts ``` const { defineConfig } = require('cypress')module.exports = defineConfig({ allowCypressEnv: false,}) ``` ``` import { defineConfig } from 'cypress'export default defineConfig({ allowCypressEnv: false,}) ``` See the [Migration Guide](/llm/markdown/app/references/migration-guide.md#Migrating-away-from-Cypressenv) for detailed migration instructions. ## Notes ### Read-only behavior `cy.env()` is **read-only** and cannot set environment variables at runtime. See the [Environment Variables & Secrets](/llm/markdown/app/guides/environment-variables.md) guide for more details on setting environment variables. ### Test configuration overrides Environment variables cannot be set using [test configuration](/llm/markdown/app/references/configuration.md#Test-Configuration) when `allowCypressEnv` is set to `false`. This is a security feature to prevent exposing sensitive data through test configuration. ### Case sensitivity Variable names are case-sensitive and must match exactly how they are defined in your configuration: ``` // Configuration{ env: { apiUrl: 'https://api.example.com', }}// In testcy.env(['apiUrl']) // ✅ Gets 'https://api.example.com'cy.env(['APIURL']) // ❌ Returns undefined ``` ## History | Version | Changes | | --- | --- | | [15.10.0](/llm/markdown/app/references/changelog.md#15-10-0) | `cy.env()` command added | ## See also * [`Cypress.env()`](/llm/markdown/api/cypress-api/env.md) (deprecated) * [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md) * [Configuration](/llm/markdown/app/references/configuration.md) * [Migration Guide: migrating away from `Cypress.env()`](/llm/markdown/app/references/migration-guide.md#Migrating-away-from-Cypressenv)