# Where to Find Cypress API Definitions in the Monorepo: Complete File Guide for Contributors

> Locate Cypress API definitions within the cypress-io/cypress monorepo. Find Node.js CLI types in cli/types/ and browser types in packages/driver/types/. Essential guide for contributors.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: internals
- Published: 2026-08-06

---

**Cypress API definitions are located in two main directories:** `cli/types/` for the Node.js CLI and npm API, and `packages/driver/types/` for the browser-side command chain (`cy.*` and `Cypress.*` globals).

When contributing to cypress-io/cypress or extending its TypeScript interfaces, you need to know exactly where each API surface is declared. This guide maps every major definition file in the monorepo so you can navigate the codebase efficiently and submit precise pull requests.

---

## CLI API Definitions (Node.js Side)

The **CLI types** live in `cli/types/` and define the programmatic interface used when you `import cypress` in Node.js scripts or configure the test runner from the command line.

### Main CLI Entry Point: [`cypress.d.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.d.ts)

The primary source for Cypress CLI API definitions is **[[`cli/types/cypress.d.ts`](https://github.com/cypress-io/cypress/blob/main/cli/types/cypress.d.ts)](https://github.com/cypress-io/cypress/blob/develop/cli/types/cypress.d.ts)**. This file exports:

- **`cypress run`** options (headed mode, browser selection, spec filtering, record flags)
- **`cypress open`** configuration
- **`cypress.verify`** and other commands
- Core interfaces like `CypressRunResult`, `Cypress FailedTestsAttempt`

All programmatic usage of the `cypress` npm package resolves through this declaration file.

### Automation Layer: [`cypress-automation.d.ts`](https://github.com/cypress-io/cypress/blob/main/cypress-automation.d.ts)

For the **`CypressCommandLine`** namespace used by internal automation, see **[[`cli/types/cypress-automation.d.ts`](https://github.com/cypress-io/cypress/blob/main/cli/types/cypress-automation.d.ts)](https://github.com/cypress-io/cypress/blob/develop/cli/types/cypress-automation.d.ts)**. This defines:

- `CypressCommandLine.start(options)`
- `CypressCommandLine.run(options)`
- Internal automation state types

### Helper Modules

Two additional files augment the CLI API:

| File | Purpose |
|------|---------|
| [**[`cli/types/cypress-type-helpers.d.ts`](https://github.com/cypress-io/cypress/blob/main/cli/types/cypress-type-helpers.d.ts)**](https://github.com/cypress-io/cypress/blob/develop/cli/types/cypress-type-helpers.d.ts) | Utility types and generic helpers |
| [**[`cli/types/cypress-npm-api.d.ts`](https://github.com/cypress-io/cypress/blob/main/cli/types/cypress-npm-api.d.ts)**](https://github.com/cypress-io/cypress/blob/develop/cli/types/cypress-npm-api.d.ts) | Wrappers for npm-specific API surfaces |

---

## Driver API Definitions (Browser Side)

The **driver types** in `packages/driver/types/` define what you access inside test files—the global `cy` object, `Cypress` utilities, and command-chain behavior.

### Primary Command Chain: [`spec-types.d.ts`](https://github.com/cypress-io/cypress/blob/main/spec-types.d.ts)

The most important file for Cypress API definitions is **[[`packages/driver/types/spec-types.d.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/types/spec-types.d.ts)](https://github.com/cypress-io/cypress/blob/develop/packages/driver/types/spec-types.d.ts)**. This declares:

- The **`Cypress`** namespace with all chainable commands
- **`cy.visit()`**, **`cy.get()`**, **`cy.type()`**, **`cy.click()`** signatures
- Command options interfaces and overloads
- Chainable interface extensions for custom commands

Every `cy.*` method your tests use originates here.

### Internal Driver State: [`internal-types.d.ts`](https://github.com/cypress-io/cypress/blob/main/internal-types.d.ts)

Low-level implementation types are in **[[`packages/driver/types/internal-types.d.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/types/internal-types.d.ts)](https://github.com/cypress-io/cypress/blob/develop/packages/driver/types/internal-types.d.ts)**:

- Remote state management
- Log handling internals
- Driver helper types

These are **not** part of the public API but are essential for understanding driver internals.

### Log and Console APIs

Logging functionality is split across two focused files:

| File | Exports |
|------|---------|
| [**[`packages/driver/types/cypress/log.d.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/types/cypress/log.d.ts)**](https://github.com/cypress-io/cypress/blob/develop/packages/driver/types/cypress/log.d.ts) | `Cypress.log()`, log entry interfaces, LogConfig options |
| [**[`packages/driver/types/cy/logGroup.d.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/types/cy/logGroup.d.ts)**](https://github.com/cypress-io/cypress/blob/develop/packages/driver/types/cy/logGroup.d.ts) | `cy.log()`, `cy.group()`, `cy.groupEnd()` and grouped log helpers |

---

## How TypeScript Resolves These Definitions

The Cypress monorepo uses **workspace-scoped type resolution**. Here's how it works:

1. **Root [`tsconfig.json`](https://github.com/cypress-io/cypress/blob/main/tsconfig.json)** references each package's `types` folder via `typeRoots` or path mapping
2. **Declaration merging** combines all `declare namespace Cypress { ... }` blocks into a single global
3. **No import required** in spec files—the global `Cypress` and `cy` are ambiently available

Run **`yarn type-check`** or **`yarn lint`** to validate your changes across all definition files.

---

## Practical Examples

### Using CLI Types (Node.js Script)

```typescript
// Resolved from cli/types/cypress.d.ts
import { run } from 'cypress'

run({
  spec: 'cypress/e2e/auth.cy.ts',
  headed: true,
  browser: 'chrome',
  config: {
    baseUrl: 'http://localhost:3000',
    video: false
  }
}).then((results) => {
  console.log(`Total failed: ${results.totalFailed}`)
  console.log(`Run URL: ${results.runUrl}`)
})

```

### Using Driver Types (Test Spec)

```typescript
// Types resolved from packages/driver/types/spec-types.d.ts
// No import needed—globals are ambient

cy.visit('/login', { timeout: 10000 })

cy.get('[data-testid="email"]')
  .should('be.visible')
  .type('admin@example.com')

cy.get('form').submit()

// Custom command with proper type inference
Cypress.Commands.add('login', (email: string, password: string) => {
  cy.session([email, password], () => {
    cy.request('POST', '/api/login', { email, password })
  })
})

```

---

## Summary

- **CLI API definitions** live in `cli/types/`, with [`cypress.d.ts`](https://github.com/cypress-io/cypress/blob/main/cypress.d.ts) as the main entry point for npm package consumers
- **Driver API definitions** live in `packages/driver/types/`, with [`spec-types.d.ts`](https://github.com/cypress-io/cypress/blob/main/spec-types.d.ts) containing all `cy.*` and `Cypress.*` globals
- **Automation layer** has dedicated types in [`cli/types/cypress-automation.d.ts`](https://github.com/cypress-io/cypress/blob/main/cli/types/cypress-automation.d.ts)
- **Logging APIs** are split between [`cypress/log.d.ts`](https://github.com/cypress-io/cypress/blob/main/cypress/log.d.ts) and [`cy/logGroup.d.ts`](https://github.com/cypress-io/cypress/blob/main/cy/logGroup.d.ts)
- TypeScript merges all `declare namespace Cypress` blocks automatically—no manual imports needed in test files

---

## Frequently Asked Questions

### Where is `cy.get()` defined in the Cypress source?

**`cy.get()` is defined in [[`packages/driver/types/spec-types.d.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/types/spec-types.d.ts)](https://github.com/cypress-io/cypress/blob/develop/packages/driver/types/spec-types.d.ts)**. This file contains the complete `Cypress` namespace with all chainable command signatures, including selector queries, traversal methods, and assertion interfaces.

### How do I add types for a custom Cypress command?

Extend the `Cypress` namespace in your own [`.d.ts`](https://github.com/cypress-io/cypress/blob/main/.d.ts) file using **declaration merging**. Import or reference [`packages/driver/types/spec-types.d.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/types/spec-types.d.ts), then add your command to the `Chainable<Subject>` interface. The TypeScript compiler will merge your augmentation with the built-in definitions.

### What's the difference between `cli/types/` and `packages/driver/types/`?

**`cli/types/`** defines the Node.js API used when you `import cypress` programmatically or run CLI commands. **`packages/driver/types/`** defines the browser-side globals (`cy`, `Cypress`) available inside test specs. They are compiled separately and serve different execution environments.

### Where can I find the `Cypress.run()` return type?

The **`CypressRunResult`** interface is exported from [**[`cli/types/cypress.d.ts`](https://github.com/cypress-io/cypress/blob/main/cli/types/cypress.d.ts)**](https://github.com/cypress-io/cypress/blob/develop/cli/types/cypress.d.ts). This includes properties like `totalFailed`, `totalPassed`, `runUrl`, and `runs[]` containing per-spec results.