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

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

The primary source for Cypress CLI API definitions is [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

For the CypressCommandLine namespace used by internal automation, see [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/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/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

The most important file for Cypress API definitions is [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

Low-level implementation types are in [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/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/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 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)

// 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)

// 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 as the main entry point for npm package consumers
• Driver API definitions live in packages/driver/types/, with spec-types.d.ts containing all cy.* and Cypress.* globals
• Automation layer has dedicated types in cli/types/cypress-automation.d.ts
• Logging APIs are split between cypress/log.d.ts and 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/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 file using declaration merging. Import or reference 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/develop/cli/types/cypress.d.ts). This includes properties like totalFailed, totalPassed, runUrl, and runs[] containing per-spec results.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}