# How to Programmatically Access Cypress Configuration: Runtime API Guide

> Access Cypress configuration programmatically at runtime using the Cypress.config() API. Read specific values or override settings for your tests.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: api-reference
- Published: 2026-06-21

---

**Use the global `Cypress.config()` API to read or modify configuration values at runtime by calling it with no arguments for the full config object, with a key string to read a specific value, or with key-value pairs to override settings for the current test execution.**

The cypress-io/cypress repository provides a robust configuration system that allows developers to programmatically access Cypress configuration during test execution. Whether you need to inspect the current `baseUrl`, adjust timeouts mid-run, or retrieve file paths like `downloadsFolder`, the `Cypress.config()` method offers runtime access to the resolved configuration object stored in the driver's state.

## Using the Cypress.config() API in Tests

The global `Cypress.config()` method serves as both a getter and setter for the test runner's configuration state.

### Reading Configuration Values

To retrieve configuration data, call `Cypress.config()` with no arguments to return the entire resolved configuration object, or pass a specific key to access individual properties.

```typescript
// Read a single config value
const baseUrl = Cypress.config('baseUrl')

// Read the entire resolved config object
const fullConfig = Cypress.config()
console.log('Running in', fullConfig.browser?.name)

```

### Modifying Configuration at Runtime

Update settings dynamically by passing a key and value pair, or provide an object containing multiple configuration changes. These modifications apply only to the current test execution and do not persist to your [`cypress.config.js`](https://github.com/cypress-io/cypress/blob/main/cypress.config.js) or [`cypress.config.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.config.ts) files.

```typescript
// Override a config option for the rest of the run
Cypress.config('defaultCommandTimeout', 15000)

// Set multiple options at once
Cypress.config({
  video: false,
  viewportWidth: 1200,
})

```

## Configuration Architecture and Source Files

Understanding how Cypress handles configuration internally helps explain why runtime changes behave as they do. The configuration system spans two main packages: `@packages/config` handles parsing and resolution, while `@packages/driver` manages runtime access.

When Cypress loads, the configuration is parsed from your project files, merged with defaults, and stored in the driver's state management system. Specifically, the implementation resides in:

- **[`packages/config/src/index.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/index.ts)** – Entry point that re-exports configuration helpers including `addToCypressConfig` and `defineConfig`
- **[`packages/config/src/utils.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/utils.ts)** – Core utilities for resolving environment variables, validating options, and merging configuration objects
- **[`packages/driver/src/util/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/util/config.ts)** – Runtime bridge that forwards `Cypress.config()` calls to the resolved config stored in `Cypress.state('config')`
- **[`packages/driver/src/cypress/cy.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/cypress/cy.ts)** – Sets up the global `Cypress` namespace and binds the `config` method to the driver

## Practical Code Examples

Here are practical patterns for working with Cypress configuration in your test code and Node scripts.

### Accessing Config Values Inside Tests

Use `Cypress.config()` to retrieve dynamic paths or settings within your test logic:

```typescript
it('reads a file from the downloads folder', () => {
  cy.readFile(`${Cypress.config('downloadsFolder')}/records.csv`)
    .should('contain', 'id,name')
})

```

### Programmatic Access from Node Scripts

When running Cypress from a custom CLI or build script, pass configuration options programmatically:

```typescript
import cypress from 'cypress'

cypress.run({
  config: {
    baseUrl: 'http://localhost:3000',
    defaultCommandTimeout: 8000,
  },
}).then((results) => {
  console.log('Tests finished with status', results.totalFailed)
})

```

## Runtime Behavior and Limitations

Changes made via `Cypress.config()` affect only the in-memory configuration for the current test run. Because the config object is stored in `Cypress.state('config')` within the driver, modifications do not write back to disk or alter your project's configuration files. This design ensures test isolation while allowing dynamic adjustments based on runtime conditions.

## Summary

- The `Cypress.config()` global API provides runtime read and write access to the resolved configuration object
- Configuration is managed by the `@packages/config` package and exposed through the driver in [`packages/driver/src/util/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/util/config.ts)
- Read values by calling `Cypress.config()` with no arguments or a specific key string
- Modify values by passing key-value pairs or an options object, but note that changes are temporary and execution-specific
- Access configuration programmatically from Node scripts using the `cypress.run()` method with a `config` option

## Frequently Asked Questions

### How do I read the entire configuration object in Cypress?

Call `Cypress.config()` with no arguments to receive the complete resolved configuration object containing all merged defaults, environment variables, and user settings from your [`cypress.config.js`](https://github.com/cypress-io/cypress/blob/main/cypress.config.js) file.

### Can I permanently change Cypress configuration from within a test?

No. Changes made using `Cypress.config()` inside tests only modify the in-memory configuration for the current test execution. To permanently change configuration, edit your [`cypress.config.js`](https://github.com/cypress-io/cypress/blob/main/cypress.config.js) or [`cypress.config.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.config.ts) file directly.

### Where does Cypress store the configuration at runtime?

Internally, Cypress stores the resolved configuration in `Cypress.state('config')`, which is managed by the driver package in [`packages/driver/src/util/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/util/config.ts). The `Cypress.config()` method serves as the public API to access this internal state.

### How do I pass custom configuration when running Cypress programmatically from Node?

Use the `cypress.run()` method from the Cypress npm module, passing a `config` object in the options. This allows you to programmatically set values like `baseUrl` or `defaultCommandTimeout` when triggering test runs from build scripts or CI pipelines.