How to Use the Cypress TAP CLI

cypress tap lets an AI agent work with an already running Cypress open-mode session. It can discover open sessions, start or rerun a spec, report run status and results, show failure details and the Command Log, and inspect the app’s DOM and accessibility tree. Cypress introduced it in version 15.21.0. To confirm the exact commands and options supported by your installed release, run cypress tap --help.

What Cypress TAP is for

TAP gives an agent a way to interact with a Cypress session that is already open, so it can help run and investigate tests in that session. This is different from asking an agent to operate Cypress without an existing interactive session: the feature is specifically tied to open mode.

The Cypress AI Toolkit describes the cypress-tap skill as requiring Cypress 15.21 or later and a Chromium-family browser. Check the toolkit’s current prerequisites as well as the help output for your installed version before relying on the workflow. Cypress AI Toolkit skills README.

Prerequisites and version check

Install and use Cypress 15.21.0 or later. The feature was introduced in 15.21.0.
Open your project in Cypress open mode and have a compatible session running.
Use a Chromium-family browser for the AI Toolkit’s cypress-tap workflow.
Check the local command surface before scripting it: run cypress tap --help.

For a reproducible workflow, use the project’s local Cypress installation rather than assuming a globally installed executable is the same version. For example, invoke the project’s package script or its local binary according to your package manager, then inspect that executable’s help. The changelog documents the feature and its high-level capabilities, but readers should treat their installed help as authoritative for exact subcommands and arguments. Cypress CLI changelog.

What you can do with cypress tap

The documented tasks fall into five groups:

Discover sessions: list open Cypress sessions so an agent can identify the session to work with.
Run specs: start a spec or rerun one in the open session.
Check progress and results: report a run’s status and results.
Investigate failures: print a failing test’s error and its Command Log.
Inspect the application: examine the app’s DOM and accessibility tree.

This covers a practical debugging loop: locate the open session, run or rerun a spec, check its outcome, and inspect failure or page information. These are capability categories, not a substitute for the installed release’s exact command syntax.

Use the CLI safely: discover the installed syntax first

The official feature summary explicitly directs users to cypress tap --help for the complete subcommand list. Start there rather than copying guessed subcommands or flags from an example written for a different release.

cypress tap --help

Read the output for the available session-listing, spec-run, status/result, failure-detail, and inspection operations. Then use the exact spelling, argument order, and options printed by your installed version. If you are exposing the CLI to an AI agent, give it the local help output or direct it to consult that output before issuing commands.

The feature provides readable output by default. Add --json to request machine-readable JSON; verify where the option belongs in the command using local help. Human-readable output is convenient for a person following a debugging session, while JSON is useful when another program or agent needs to parse results.

A practical run-and-debug workflow

Start Cypress open mode. Open the project and the app under test in a supported browser. Keep the session available while the agent works.
Inspect the command help. Run cypress tap --help with the same Cypress installation that owns the open session. Identify the documented command for listing sessions.
Find the session. Use the documented session-listing operation and select the intended open session if more than one is available.
Run the target spec. Use the local help’s exact syntax to start the spec in that session. For an existing failure, rerun the relevant spec through the documented operation.
Read the result. Request or inspect run status and results. Use readable output for interactive investigation, or the documented --json form when the agent needs structured data.
Inspect a failure. Ask for the failing test’s error and Command Log, then inspect the app’s DOM or accessibility tree when page state is relevant.
Make one change and rerun. After addressing a suspected cause, rerun the spec and check the new result in the same session.

For example, an adjacent Cypress-agent task might be: “Run the checkout spec in my open Cypress session, diagnose the failure, and inspect the app at the failing command.” That prompt describes the desired investigation; the agent still needs to use the subcommands and options actually shown by the installed CLI help.

Output formats and automation

Readable output is the default. --json requests JSON output. Use the default when a developer is reading diagnostics directly. Choose JSON when an agent or script must parse a result, route it to another step, or retain structured output.

Do not assume a JSON schema, field names, or whether every operation supports the same output options unless the installed help or current Cypress documentation says so. A robust consumer should tolerate missing or additional fields and preserve the raw output for diagnosis if parsing fails.

What cypress tap does not establish

The documented feature summary does not provide a complete syntax reference, define every option, or promise that an open session can be discovered from any environment. It also does not establish behavior for non-Chromium browsers or a workflow with no running open-mode session. Check current Cypress documentation and the CLI’s own help for those details instead of inferring them.

Do not confuse this feature with the old standalone cypress-cli npm package. That archived project is deprecated and points users to Cypress’s all-in-one cypress npm package. Archived Cypress CLI repository.

Troubleshooting

Symptom	Likely check	What to do
`cypress tap` is unavailable	The installed Cypress release may predate 15.21.0, when the feature was introduced.	Check the project’s Cypress version and update to a compatible release if appropriate; rerun `cypress tap --help`.
The AI Toolkit workflow does not meet its stated prerequisites	The toolkit says cypress-tap requires Cypress 15.21 or later and a Chromium-family browser.	Check both the version and browser against the current toolkit instructions.
The command syntax in a guide does not work locally	The detailed command surface can vary by installed release, and the feature summary does not spell out each invocation.	Use `cypress tap --help` from the same installation as the open session; follow its subcommand and option spelling.
No useful open session is available	The feature is intended for an existing open-mode session.	Start or confirm the intended Cypress open session, then use the locally documented session-listing operation.
Output is difficult for a script to consume	Readable output is the default.	Use `--json` as documented by local help, and avoid assuming undocumented schema details.
HTTP request lines appear in the open terminal	Cypress 15.21.0 had a version-specific issue in which TAP requests printed lines such as `GET /__cypress/sessions/<id>` in the attached open terminal.	The Cypress changelog records a fix in 15.21.1. Check your version and upgrade if you encounter this specific early-release behavior.

Performance, reliability, and cost

cypress tap operates against a running open-mode session, so the relevant operational concern is session availability: keep the intended session open and confirm it before asking an agent to run or inspect a spec. The sourced feature description does not publish performance benchmarks, resource requirements, or reliability guarantees; do not infer them from the command’s task list.

This is a Cypress CLI capability, not a paid service identified by the research. No separate TAP price or usage charge is documented in the sources used here. Cypress installation and project costs, if any, are outside the facts established by this feature description.

Or skip the browser setup

If the task is simply to capture a page as an image or PDF, ScreenshotNeo offers a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF; its MCP tools let AI agents use take_screenshot, get_page_info, and capture_pdf. This is a separate workflow from running Cypress specs in an open session.

Cookie and consent banners are accepted like a visitor and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Plans include 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Try ScreenshotNeo free: 1,000 screenshots a month, no card required.

FAQ

Is Cypress TAP the same as Cypress’s AI Toolkit?

No. TAP is a Cypress CLI feature for accessing an existing open-mode session. The AI Toolkit documents a skill that can use this capability and states its prerequisites.

Can I use it without opening Cypress?

The documented workflow is for a running open-mode session. The sources here do not establish a no-session mode.

Should I use TAP JSON output for every run?

Use JSON when a program or agent needs structured output. Human-readable output is the default and may be easier to inspect directly.

Where can I find the authoritative list of subcommands?

Run cypress tap --help for the installed release, as directed by the Cypress changelog.