关于 meticulous-cli
meticulous-cli 是用于记录用户会话并重放以发现视觉回归的命令行工具，面向测试人员和 Agent 工作流。它提供认证、调试、会话下载、差异分析和重放等命令，也可通过托管 MCP 服务调用 Agent 命令。
主要功能
- 01记录并重放用户会话
- 02分析测试运行和视觉差异
- 03下载会话、重放和测试运行
- 04按代码变更查找相关会话
- 05输出命令结构 JSON
适用场景
- 01在本地重放录制会话
- 02检查测试运行中的视觉差异
- 03在 CI 中使用 API token 认证
- 04通过 Agent 工作流触发测试运行
MCP 相关
托管 MCP 服务在 https://app.meticulous.ai/api/mcp 暴露 agent 命令供 MCP 客户端调用。连接时使用端点 URL；调用时需显式传入 CLI 不会推断的 git 上下文。
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/meticulous-cli确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/agent.mdauth.mddebug.mddownload.mdlocal.mdproject.mdschema.mdsimulate.md详细介绍
Meticulous CLI
meticulous CLI 会记录用户会话并重放，以捕获视觉回归。它作为 @alwaysmeticulous/cli 的一部分安装。
开始之前，请运行
meticulous-cli-update技能，确保 Meticulous CLI 和技能均为最新版本——除非它已在本次对话的前文中运行过；若已运行，请跳过。
调用
meticulous <command> [options]
这些技能假设 meticulous 已位于 PATH 中。如果尚未安装，meticulous-cli-update 技能会通过 npm install --global @alwaysmeticulous/cli@latest 全局安装。若按项目本地安装，也可以通过 npx @alwaysmeticulous/cli 调用。
命令组
| 命令 | 用途 |
|---|---|
agent | 读取、分析并触发测试运行——面向 Agent 的命令，也可通过 MCP 服务使用 |
auth | 使用 Meticulous 进行身份验证（登录、whoami、登出、选择项目） |
debug | 设置适用于 AI 的调试工作区，以调查重放差异和重放 |
download | 在本地下载会话、重放和测试运行 |
local | 查找与当前分支代码变更相关的会话 |
project | 检查你已通过身份验证连接的项目 |
simulate / replay | 针对某个 URL 重放已记录的会话 |
schema | 以 JSON 格式输出 CLI 命令架构（供 Agent 或程序调用） |
如需了解完整选项详情，请参阅各命令组的参考文档：
- references/agent.md
- references/auth.md
- references/debug.md
- references/download.md
- references/local.md
- references/project.md
- references/simulate.md
- references/schema.md
全局选项
每个命令都接受以下选项：
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--logLevel | string | info | 日志详细程度：trace、debug、info、warn、error、silent |
--dataDir | string | ~/.meticulous | 存储会话、重放和其他数据的目录 |
--jsonArgs | string | — | 将所有选项作为 JSON 字符串传入（适用于程序或 Agent 调用） |
--rawJson 是已弃用的 --jsonArgs 别名。--dryRun 不是全局选项——它仅适用于执行操作的命令（例如触发 ci / agent 运行和上传的命令，以及 simulate）；请查看对应命令的参考文档，或运行 meticulous schema <command>。
身份验证
命令通过 OAuth 进行身份验证。登录令牌会存储在磁盘上，并在不同会话间重复使用——在交互式终端中，需要身份验证的命令会自动打开浏览器进行登录；没有 TTY 时（通常是 Agent 场景），命令会失败，并提示你运行 meticulous auth login。运行 meticulous auth whoami 查看当前状态。项目级命令还需要设置默认项目，可在登录时设置，也可使用 meticulous auth set-project 设置。请参阅 references/auth.md。
也支持使用 API 令牌进行身份验证（通过 --apiToken 或 METICULOUS_API_TOKEN 环境变量，令牌限定于特定组织／项目），这是在 CI 等非交互式环境中进行身份验证的方式。有些 Agent 平台会改为向发往 app.meticulous.ai 的请求注入 bearer 凭据；这种方式同样可用，并且 auth whoami 会将其报告为 credentials injected at request time。
MCP 服务
agent 命令也作为工具公开在托管的 MCP 服务 https://app.meticulous.ai/api/mcp 上，因此启用了 MCP 的客户端（Claude Code、Cursor、Codex）可以直接调用这些工具，而不必通过 Shell 调用 CLI。大多数读取／分析命令都对应一个 get_<command> 工具，返回的数据与 CLI 命令的 --json 输出相同——例如，agent test-run-diffs ⇄ get_test_run_diffs、agent dom-diff ⇄ get_dom_diff，以及 download session ⇄ get_session_data。两个会修改数据的命令（upload-build、trigger-test-run）也有对应的 MCP 工具，但并非一一对应——完整映射请参阅 references/agent.md，其中说明了这一重要区别。只需使用端点 URL 即可连接（首次使用时通过浏览器 OAuth 登录）。技能文档以 CLI 为基础编写；如果已连接 MCP 服务，请在注明处替换为对应工具——但请注意，MCP 工具不会像 CLI 那样推断 Git 上下文（commitSha／baseSha／差异），因此使用 MCP 时务必显式传入这些参数。
示例
# Print schema for all commands (agent use)
meticulous schema
# Run a single replay locally
meticulous simulate --sessionId=<id> --appUrl=http://localhost:3000