checkly

Checkly

CLI 还是 MCP？先确定使用路径

此技能会在 shell 中驱动 npx checkly CLI。Checkly MCP 服务仅覆盖部分功能——实时账户操作：检查状态和结果、测试会话、根本原因分析（RCA）、触发现有检查项以及处理事件。只有 CLI 可以编写、测试和部署 Monitoring as Code。

在运行第一个与 Checkly API 通信的命令之前，先确定使用路径：

1. 无法访问 shell（仅聊天会话）：停止使用此技能；如果已连接 Checkly MCP 工具，则改用它们；否则，告知用户你需要 shell 或 Checkly MCP 服务才能操作 Checkly。
2. 可以访问 shell：运行一次 npx checkly whoami。
   • 成功 → 所有操作都使用 CLI，并继续使用此技能，即使 Checkly MCP 工具也已连接。
   • 因身份验证错误而失败，或打印出 action_required 登录提示（未登录）→ 按任务选择路径：
     • 编写、测试或部署检查项：MCP 无法完成这些操作。通过 CLI 自行登录（见下文“以 Agent 身份登录”），或者，如果用户倾向于使用密钥，请在环境或 .env 中请求 CHECKLY_API_KEY + CHECKLY_ACCOUNT_ID。然后重新运行 whoami。不要绕过缺少登录这一问题。
     • 实时账户操作（状态、结果、测试会话、RCA、触发检查项、处理事件）：如果已连接 Checkly MCP 工具，则改用它们；忽略登录代码。先调用 MCP whoami 工具，并告知用户你正在操作哪个账户。如果 MCP 也未连接，则请用户按上述说明通过 CLI 进行身份验证。

无论如何切换路径，以下两条规则始终适用：

• 账户一致性。 CLI 身份验证和 MCP 会话可能指向不同账户——用户通常属于多个账户。未经确认两者使用相同的账户 ID，切勿在同一任务中混用 CLI 和 MCP 的结果；切换路径后，务必注明账户名称。
• 写入操作仍需确认。 CLI 的确认流程（如下所述）不会随你切换到 MCP。如果因写入操作而切换路径（例如创建事件），请先说明拟进行的更改，并在调用工具前获得用户批准。

以 Agent 身份登录

npx checkly login 无需终端；如果没有存储凭据，任何需要身份验证的命令都会自动启动它，因此你很少需要手动运行。它会打印一行 JSON 后退出；如果是由其他命令启动的，这一行会输出到 stderr。按原样转述输出内容；切勿猜测：

• {"status":"action_required","reason":"login_required","verification_uri_complete":…,"user_code":…,"expires_in":…} — 需要由用户本人批准。向用户提供 URL 和代码（有效期为 expires_in 秒）。没有 Checkly 账户的用户可以在同一页面注册。然后，无需等待用户说已完成，就运行第一个 next 命令（npx checkly login --wait）：用户批准后，该命令会返回，并打印下方所示的行。在后台运行它：它最多可能等待 expires_in 秒，通常会超过 shell 的命令超时时间。如果用户批准前该命令停止运行，请重新运行；同一代码仍然有效。（如果是由其他命令启动登录，之后请重新运行该命令，正如第二个 next 条目所述。）批准前运行时若未使用 --wait，会再次显示代码（或在旧代码即将过期时显示新代码）；始终转述最新的 user_code。登录完成前，不要并行运行多个 Checkly 命令。
  • 如果该行包含 verification_uri，但不包含 user_code，则必须在与 CLI 相同的机器上打开 URL，并且命令会等待打开操作完成，而不是退出：请在后台运行它，以便转述 URL。
  • 如果该行没有 URL，且其 next 不包含 when，请立即在后台运行该命令，转述它的输出，并在用户完成后重新运行原始命令（提前运行只会重复显示这一行）。
• {"status":"action_required","reason":"select_account","choices":[…],"next":[…]} — 密钥已存储，但用户属于多个账户。当前尚未设置默认账户，因此每条命令都会在此处停止，直到用户选择或指定账户。除非用户已经指定，否则请询问用户要选哪个账户：如果用户提供的账户名称或 ID 与 choices 中的某个条目完全匹配，即视为已作出选择。切勿自行选择，即使无法询问用户也不行：停止操作，并告知用户有哪些可用账户。无需进行第二次浏览器操作。然后可以：
  • 运行 npx checkly login --account-id <id>，将其设为后续命令的默认账户；或
  • 在要执行的命令前加上 CHECKLY_ACCOUNT_ID=<id>，仅针对该账户运行此命令（请参阅下文“使用多个账户”）。
• {"status":"success","reason":…,"message":…,"accountId":…,"accountName":…,"defaultAccount":…} — 操作完成。defaultAccount 是已存储的默认账户（未存储时为 null）；如果设置了 CHECKLY_ACCOUNT_ID，命令会改用该账户，正如消息所述。告知用户当前使用的账户。
• {"status":"error","reason":…,"message":…} — 报告该消息；不要循环重试。reason 的取值包括 access_denied、expired_token、code_used（重新运行登录以获取新代码）、account_not_found、no_accounts、invalid_response、network_error（无法连接登录服务器）、api_error、env_credentials（已设置 CHECKLY_API_KEY，因此正在使用 API 密钥凭据；用户必须移除该变量才能登录）或 login_failed。若要以其他用户身份登录，请先运行 npx checkly logout。

在没有浏览器的主机上，设置 CHECKLY_NO_BROWSER=1，这样 CLI 就不会尝试打开浏览器；无论如何都会打印 URL 和代码。标志形式为 --account-id 和 --no-browser。

使用多个账户

checkly login 关联的是用户，而不是某个账户，因此适用于用户所属的所有账户。除非另有指定，否则命令会使用默认账户。

• 列出账户： npx checkly whoami 会显示正在使用的账户、默认账户和用户的其他账户。--output json 会增加 accountSource（login：默认账户；account_override：由 CHECKLY_ACCOUNT_ID 指定账户；environment：通过 CHECKLY_API_KEY 提供的 API 密钥凭据，这类凭据属于一个账户）和 defaultAccount（对于 API 密钥凭据，以及 CHECKLY_ACCOUNT_ID 指定账户但尚未选择默认账户时，值为 null；如果两者都没有，则命令会停在 select_account）。
• 仅为一条命令使用其他账户： 在命令前加上 CHECKLY_ACCOUNT_ID=<id>（CHECKLY_ACCOUNT_ID=<id> npx checkly test-sessions get <id>）。它会使用已存储的登录信息，并保持默认账户不变。若任务涉及默认账户以外的账户（例如，另一个账户中的 CI 测试会话），优先使用这种方式，以免擅自更改用户的默认账户。如果没有已存储的登录信息，命令会先登录（按上述方式转达代码），然后使用该账户，但不会存储默认账户。若指定的 ID 不属于用户的账户，命令会失败，并列出该登录信息适用的账户。
• 在 shell 或 .env 中设置 CHECKLY_ACCOUNT_ID： 如果没有 CHECKLY_API_KEY，那么在取消设置之前，它就像为每条命令都加上前缀一样生效，无论默认账户是什么。此时登录不需要选择账户：命令会使用该账户，也不会存储默认账户。命令行前缀优先于 .env 中的值（.env 不会覆盖已设置的变量）。whoami 会说明这一点；login 和 switch 会警告此设置优先于它们存储的默认账户。如果用户希望使用默认账户，就必须移除该设置（项目可能会有意将其保留在 .env 中，以固定该项目使用的账户）。
• 更改默认账户： 仅在用户提出要求时运行 npx checkly switch --account-id <id>。更改会立即生效（无需确认，也无法撤销，只能切换回去），并输出一行普通文本 Account switched to …；使用 npx checkly whoami 检查。若不提供 --account-id，switch 会输出一行 select_account，其中包含已存储的 defaultAccount（或 null）以及 choices。
• 找不到？ 如果按 ID 查询没有结果，提示信息会注明搜索的账户；使用 --output json 时，错误中还会包含 hint 和 searchedAccount 字段。如果资源可能位于其他账户，请对每个可能的账户使用 CHECKLY_ACCOUNT_ID=<id> 重新运行命令。

始终先加载当前操作列表

必需： 回答任何 Checkly 问题之前，运行 npx checkly skills，获取当前最新的操作列表。不要依赖记忆或之前的上下文——CLI 是唯一可信来源，操作可能会随版本发布而变化。npx checkly skills 在本地运行——无需身份验证或 API 访问权限，因此即使尚未完成上述登录流程，也可以使用。

然后运行 npx checkly skills <action>，加载所需操作的最新详情。

使用 npx checkly skills install 将此技能安装到项目中（支持 Claude Code、Cursor、Codex 等）。

调查已记录的测试会话时，运行 npx checkly skills investigate test-sessions。

通过 npx checkly skills 渐进式披露

该技能采用分层结构，以高效利用上下文：

1. 元数据（约 80 个 token）：frontmatter 中的名称和描述
2. 核心说明（约 1K 个 token）：主 SKILL.md 内容，包含参考命令链接
3. 参考命令（按需加载）：带示例的详细构造说明

Agent 会针对每项任务加载所需内容。

计划感知

配置检查之前，运行 npx checkly account plan --output json，查看当前计划可用的功能、位置和限制。已停用的权益可能包含用于自助结账或联系企业销售的 upgradeUrl。仅当该链接存在时才分享；否则，该权益不可用。

运行 npx checkly skills manage 查看完整参考文档。

确认协议

写入命令（例如 incidents create、deploy、destroy）会返回退出代码 3 和 confirmation_required JSON 封套，而不会执行。始终先向用户展示 changes，并等待用户批准后再运行 confirmCommand。 此规则适用于每条写入命令，更新和解决操作也需要确认，而不仅仅是初次创建。唯一例外是计划没有变更的 checkly deploy：无需批准任何内容，因此它会打印 No changes.、记录部署、除非传入 --schedule-on-deploy --schedule-on-deploy-scope=all，否则不会安排任何检查，并以代码 0 退出。只有传入 --schedule-on-deploy 时，部署才会安排检查：此时仅安排有变更的检查；如果传入 --schedule-on-deploy-scope=all，则安排所有检查。但如果检查数量超过安排阈值（--schedule-on-deploy-threshold，默认由 Checkly 设置），则会跳过运行频率高于部署最小频率的检查（--schedule-on-deploy-min-frequency，默认由 Checkly 设置）。

confirmCommand 是已获批准、可原样运行的命令：它以 npx checkly 开头，因此会运行项目自身的 CLI；它会重复你传入的标志（对于 deploy，还会使用 --plan-token 固定其显示的计划），并且末尾已包含 --force。用户批准后，按原样运行该命令——不要自行给命令添加 --force，不要删掉 npx，也不要添加用户未要求的标志。

运行 npx checkly skills communicate 查看完整协议详情，或运行 npx checkly skills configure 了解 deploy 会确认哪些内容。

输出流和退出代码

stdout 只包含命令结果：结果、--output json 文档（大多数失败也会输出 JSON 错误文档）、API 透传响应正文，以及上述确认／试运行封套。进度、警告、提示、询问和可读错误会输出到 stderr，因此运行 npx checkly <command> --output json | jq 时，看到的只有 JSON。请先检查退出代码，因为有些失败不会向 stdout 输出内容：0 表示成功（降级的检查不会导致运行失败；请查看结果以发现此类情况），1 表示失败，2 表示用法错误，3 表示 confirmation_required，127 表示未知命令。

API 透传（适用于任何端点的回退方式）

如果某个端点没有专用 CLI 命令，请使用 npx checkly api 直接发送经过身份验证的请求。CLI 会自动处理身份验证标头和基础 URL。

npx checkly api /v1/checks
npx checkly api /v1/dashboards -X GET --jq '.[].name'
npx checkly api /v1/checks -X POST -F name=MyCheck -F activated:=true
npx checkly api /v1/checks -X GET -F limit=5

主要标志：-X（方法）、-F（字段——字符串使用 key=value，JSON 使用 key:=value）、-H（标头）、--jq（使用 jq 过滤）、--input（从文件／stdin 读取请求正文）、-i／--include（在 stdout 输出响应状态和标头）、--verbose（在 stderr 输出请求／响应标头）。

嵌套负载

使用 := 在单个字段中发送结构化 JSON：

npx checkly api /v1/checks/<id> -X PATCH \
  -F retryStrategy:='{"type":"LINEAR","maxRetries":2,"baseBackoffSeconds":10}'

对于较大或嵌套层次较深的请求正文，请通过 --input 传入 JSON 文件：

npx checkly api /v1/checks -X POST --input ./new-check.json

分页

checkly api 不会自动遍历分页。请自行处理分页，方式与其他 checkly 列表命令公开分页参数的方式相同。

对读取端点使用 -F 时，务必显式传入 -X GET——任何 -F 标志都会默认使用 POST，除非设置了请求方法；如果省略 -X GET，就会尝试使用分页参数作为请求正文来创建资源。

识别端点使用的分页方式。 首次请求时添加 -i（将响应头输出到标准输出），然后检查返回内容：

• 基于页码 → 响应包含 content-range 标头（例如，0-1/23 表示总共 23 项，其中包含第 0–1 项），通常还包含带有 rel="next" / rel="last" 的 link 标头。响应正文是一个裸数组。递增 -F page=N 遍历，直到覆盖 content-range 中的总数，或 rel="next" 链接消失。
• 基于游标 → 响应正文是类似 { entries: [...], nextId: "...", length: N } 的封装对象。后续请求传入 -F nextId=<value>（或根据端点传入 -F cursor=<value>）。当 nextId 缺失或为 null 时，表示已到末尾。

# Step 1: make the first call with -i and inspect the response shape
npx checkly api /v1/checks -X GET -F limit=100 -i

# If you saw a content-range header → page-based, walk with -F page=N
npx checkly api /v1/checks -X GET -F limit=100 -F page=2 -i

# If the body had a nextId field → cursor-based, walk with -F nextId=<value>
npx checkly api /v1/status-pages -X GET -F limit=50 -F nextId=<nextIdFromPrevResponse>

错误响应

对于非 2xx 响应，响应正文仍会写入标准输出（读取其中的 API 错误消息），CLI 以代码 1 退出。401 响应会输出身份验证提示，403 响应会输出权限提示，404 响应会输出文档 URL——这些内容都输出到标准错误。

端点发现

请参阅Checkly API 参考文档以查看易读的端点目录，或获取 OpenAPI 规范，以便以机器可读的形式查找路径、参数和响应结构。

npx checkly skills initialize

了解如何从头初始化并设置新的 Checkly CLI 项目。

npx checkly skills configure

了解如何使用 Checkly 构造和 CLI 创建及管理监控检查。

npx checkly skills investigate

查看检查和测试会话的状态，分析失败情况，检查尝试记录和资源，并调查错误。

npx checkly skills communicate

通过状态页创建事件并主导客户沟通。

npx checkly skills manage

了解你的账户套餐、权益、功能限制、成员和待处理邀请。