Read your Cypress Test Replay from the terminal, and hand it to your agent

These days, a lot of your day to day work runs through an AI coding agent. It reads your code, writes and runs your tests, and can gather the metadata around a failed CI run: which tests failed, the error, the stack trace.

But the rich detail of what actually happened at the moment a test flaked or failed has stayed with you as a manual process. So you've been the middleman between the full failure context and your agent. You open the Test Replay, reason through what went wrong, and translate it back into the loop by hand, creating a bottleneck between failure and fix.

Today that changes. The Cypress Cloud CLI puts your Cypress Cloud run data and history in your terminal, and it goes deeper, with direct access to Test Replay in a form your agent can read. That widens the context you can hand your agent, so you spend less time in triage and more time shipping.

What is the Cypress Cloud CLI?

The Cloud CLI (cy-cloud) takes the investigation you do manually and turns it into commands that return structured JSON, ready for you or your agent to act on. 

• Find the run you want. Work down from your organizations to projects to runs, and read a run's status and its passed and failed counts.
• Pinpoint the failing test. Drill into the specs and tests in a run, and read a failing test's error and stack trace.
• Inspect the Test Replay. Pull the replay for a test and review its timeline: the commands that ran, the network requests behind them, and the console logs, plus a summary of where the failure occurred.

The same commands work whether you run them yourself, wire them into CI, or hand them to a shell-based agent like Claude Code, Codex CLI, and Copilot CLI. Because the output is structured, you can pipe it through jq or fold it into a script that makes a question like "why did last night's build fail" answerable in a single command. 

An agent rarely stops at one call, so the CLI is built to handle a lot of them. The first time you query a replay, it downloads the replay database for that spec and caches it locally, so later queries about any test in the spec read from the cache and stay fast. 

Wherever it runs, the CLI only reaches data the authenticated account can already see in Cypress Cloud. And your agent never handles a credential to get it, because you authenticate once and the CLI holds it.

How to triage a failing run

Put those commands together and you have the triage loop you could cycle through daily. Let's walk through what triaging a failed nightly run looks like with the Cloud CLI.

Start by finding the latest the failed run on a branch:

cy-cloud run list --projectId <projectId> --branch main --status failed --limit 1

Then pull the list of failed tests for the last failing run: 

cy-cloud test list --projectId <projectId> --runNumber <runNumber> --status failed

You now have all the failing tests. Pull the full details for a specific test your investigating, including the error screenshot that was captured when it failed:

cy-cloud test get <testId> --screenshot='./screenshots'

At this point, you have insight into what the failure was and what the page looked like when it failed. Next can use the replay commands  to determine “when” and “why” it failed from the Test Replay.

cy-cloud replay info --testId <testId>

Then reconstruct the moment of failure. Pull the commands leading up to it, with the network calls and console logs:

cy-cloud replay timeline --testId <testId> --commands --aroundFailure 5 --network --logs

Nothing about the failure is out of reach now. The error, what led to it, and the network and console activity around it are all in your terminal.

Next Step: Point your agent at it

Running the loop yourself is one mode. The other, the one this was built for, is handing it to your agent. If your agent works in a shell, point it at cy-cloud and describe the goal in plain language:

• "Using cy-cloud, investigate the latest run for project ‘et123a’ and give me all failed and flaky tests with root cause analysis."
• "On the latest failed run of ‘main’ for project ‘et123a’, find the failing test, pull its Test Replay timeline, tell me the likely root cause, and propose a fix."
• "List every Cypress command that ran in the ‘can add items to cart’ test on the latest run of main in project ‘et123a’, in order."

To make it repeatable, encode the workflow as a skill or custom instruction in your agent, so it reaches for the CLI the same way every time. Cypress also ships AI Skills for authoring and explaining tests that you can incorporate into your automations to ensure your agent is grounded in Cypress best practices while it works.

Four ways to access your Cypress Cloud data

You’ve seen an example of how to use the CLI to triage a failure. However, it is only one of a few ways to access your Cypress Cloud data. Here is when to reach for each tool: 

• Cypress Cloud (for people): Watch Test Replay, review runs, and read reports in the browser.
• Data Extract API (for analytics ): Pull cross project results into your data warehouse, dashboards, and reporting.
• Cloud MCP (for your editor agent): A remote server your AI client connects to. It surfaces run summaries, flaky test data, and premium data like UI Coverage and Accessibility, shaped for an agent and built for conversational debugging in your editor.
• Cloud CLI (for your terminal, scripts, and shell agents): Access to Test Replay and run data as JSON you can pipe, script, and automate.

Cloud MCP and the Cloud CLI pair especially well. MCP is great for quickly triaging what went wrong and why. If not obvious, reach for the CLI to feed additional context to your agent. 

Get started

Setup is quick. 

1. Enable the integration: An organization admin turns the Cloud CLI on once from the Integrations page in Cypress Cloud. It is available on every Cypress Cloud plan, including the free Starter plan, at no additional cost.
2. Install the CLI package. You need Node.js 22.21.0 or later.

npm install -g @cypress/cloud

2. Authenticate. Run cy-cloud login for a browser-based OAuth sign-in, or set CYPRESS_CLOUD_TOKEN to a personal access token for CI and other non-interactive environments.

cy-cloud login

3. Explore. Run cy-cloud --help to see everything the CLI can do, and add --schema to any command for its Zod-compliant output schema.

The CLI reads the runs you already record to Cypress Cloud, so there is nothing to change in your tests.

Ready to try it?

The fastest way to feel the difference is in your own workflow. Install the Cloud CLI, point your agent at your last failed run, and see how it can accelerate your daily triage loop. We're shaping the Cloud CLI around how teams actually use it while it's in beta, so we want to hear your feedback.

Get started today. Read the Cloud CLI documentation.

Happy testing.