cypress-cloud-cli

Cypress Cloud CLI

直接使用 cy-cloud 调查 Cypress Cloud。执行命令、检查其 JSON，并根据返回的数据报告结论。如果 CLI 能回答问题，就不要让用户转到 Cloud UI。

安全地开始

已发布的二进制文件要求 Node.js 版本为 22.21.0 或更高。

仅在首次使用、环境未知或安装或身份验证出错后运行以下检查。如果 cy-cloud 在本次会话中已经成功运行，请直接执行调查命令，不要再花一个回合重新检查设置。

node --version
cy-cloud status
cy-cloud --help

假设 cy-cloud 已安装且可通过 PATH 调用。从用户当前工作区运行；不要定位、克隆、构建或依赖 cloud-cli 源代码仓库。如果找不到该命令，请停止并报告缺少的前置条件。用户可以通过以下方式安装：

npm install -g @cypress/cloud

如果尚未通过身份验证，请让用户选择一种身份验证方式：

cy-cloud login                 # interactive OAuth
cy-cloud login --token "$PAT"  # persist a Personal Access Token

对于 CI 或现有环境，CYPRESS_CLOUD_TOKEN 的优先级高于已存储的凭据，且不会写入凭据文件。

绝不要打印、回显、读回或提交令牌。绝不要检查 ~/.config/cy-cloud/auth.json 或 cypress.env.json；请使用 cy-cloud status。

组织必须启用 Cypress Cloud CLI 集成。如果响应指出未启用，则需要组织管理员采取行动；无法通过另一条 CLI 命令解决。

探索，而非猜测

每条命令都支持：

cy-cloud --help
cy-cloud <command> --help
cy-cloud <command> --schema

将 cy-cloud --help 视为可用命令的权威来源，将各命令的 --help 视为参数的权威来源，并将 --schema 视为预期的响应约定。当命令、标志或字段不确定时，先使用这些选项，再构造查询。不要记忆本指南中的命令清单；已安装的 CLI 版本可能比这些说明更新或更旧。

也要验证实际响应：run get 可能会返回小数形式的 duration，而 replay info.failedAt 可能会返回小数形式的 epoch，即使架构声明其为整数。请将这些值视为数字；如果架构不匹配会造成影响，则报告这一点，不要丢弃或四舍五入这些数据。

成功的数据命令会将 JSON 写入 stdout。请直接解析该 JSON；不要为了运行本指南而安装 JSON 工具。Replay 下载进度会写入 stderr，因此解析 JSON 前绝不要将 stderr 与 stdout 合并：

cy-cloud replay timeline --testId <uuid> --attempt <failedAttemptNumber> 2>/dev/null

如果命令失败，请在不抑制 stderr 的情况下重新运行。参数验证错误可能出现在 stdout 上；命令执行错误则出现在 stderr 上。两者的退出状态均为 1。

即使 status 等本地命令能够成功，安全沙箱也可能阻止从 Cloud 获取数据。运行 Cloud 数据命令时，请允许网络访问。如果获取失败并提示沙箱或网络拒绝，请在诊断 CLI、身份验证或 Cloud 问题之前，使用更广泛的网络权限重试同一条命令。

Replay 下载会缓存在磁盘上。请通过 cy-cloud cache info（.location）确认缓存位置，并运行 Cloud 命令，确保该目录可写且在本次会话后续仍然存在。无法持久化缓存的临时沙箱会重新下载 replay 数据，或导致缓存验证失败，即使是原本只需本地执行的命令也会如此。不要将缓存移到用户项目中。

Cloud API 调用按用户进行速率限制。请审慎、有条理地发起请求：重用 URL 或先前响应中已有的标识符；已知 ID 时跳过组织和项目发现；分页不要超过问题所需范围。针对某项测试首次下载 replay 后，replay info 和 replay timeline 会使用本地缓存运行，不计入该限制，因此后续查询可以更频繁。如果命令报告超出速率限制，请停止发起 Cloud 数据请求并报告该限制；不要在短时间内反复重试。

标识符和分页

对于 projectId，使用 Cloud URL 中已有的项目标识符；项目/运行查询和按运行范围查询规范/测试列表均接受短 slug 和项目 UUID。不要仅为了将 UUID 替换为 slug 而执行组织和项目发现。runNumber 是项目内的运行编号。specId 和 testId 是 UUID。尝试次数从 1 开始计数，与 Cypress Cloud 一致。

Cloud 列表响应包含 .pagination；如果问题不限于第一页，请请求更多页面。

按任务选择参考资料

仅阅读当前任务所需的参考资料：

• 查找组织、项目、运行、规范或测试，或打开 Cloud URL： 阅读 调查。
• 检查尝试、偶发失败或失败截图： 阅读 调查。
• 查询 Test Replay： 阅读 调查 和 Test Replay。
• 检查测试某一时刻的应用本身（DOM、ARIA、计算样式、实时截图），或查找哪个命令更改了某个元素： 阅读 Replay 视图。
• 诊断记录的测试失败原因： 阅读 调查、 Test Replay；如果仅凭时间线无法解释该现象，则阅读 Replay 视图，并阅读 诊断。

缓存和常见恢复方法

cy-cloud cache info
cy-cloud cache cleanup
cy-cloud cache clear

日常维护请使用 cache cleanup。仅当 Replay 解析似乎过期或损坏时才使用 cache clear，因为它会强制重新下载后续 Replay。如果每条命令都会重新下载 Replay，则说明缓存目录未持久化；请重试，并使用能够写入 cache info 所报告位置的沙盒。

常见结果：

• 缺少预期字段：检查该命令的 --schema。
• JSON 解析失败：确保未将 stderr 合并到 stdout。
• 沙盒导致缓存验证或写入错误：重试，并确保缓存目录可写且持久化；不要将缓存复制到项目中。
• cy-cloud version 报告 "status": "Unknown"，本身并不意味着安装损坏或版本过旧。请比较 version 和 latestVersion；仅当这些值或明确的兼容性错误表明需要升级时才升级。
• 超出速率限制：停止发送由 Cloud 支持的请求并报告该限制；不要循环重试。下载成功后，缓存的 Replay 查询不受此限制。
• Replay 特定错误：阅读 Test Replay。