Meticulous CLI

The meticulous CLI records user sessions and replays them to catch visual regressions. It is installed as part of @alwaysmeticulous/cli.

Before starting, run the meticulous-cli-update skill to ensure the Meticulous CLI and skills are up to date — unless it has already run earlier in this conversation, in which case skip it.

Invocation

meticulous <command> [options]

The skills assume meticulous is on PATH. The meticulous-cli-update skill installs it globally via npm install --global @alwaysmeticulous/cli@latest if missing. It can also be invoked as npx @alwaysmeticulous/cli when installed locally per-project.

Command Groups

See the reference for each group for full option details:

• references/agent.md
• references/auth.md
• references/debug.md
• references/download.md
• references/local.md
• references/project.md
• references/simulate.md
• references/schema.md

Global Options

These options are accepted by every command:

--rawJson is a deprecated alias for --jsonArgs. --dryRun is not global — it is available only on the commands that perform actions (e.g. the ci / agent run-triggering and upload commands, and simulate); check the command's reference or meticulous schema <command>.

Authentication

Commands authenticate via OAuth. The login token is stored on disk and reused across sessions — in an interactive terminal, a command that needs auth opens a browser sign-in automatically; without a TTY (the usual agent case) it fails and tells you to run meticulous auth login. Run meticulous auth whoami to see the current state. Project-scoped commands also need a default project, set at login or with meticulous auth set-project. See references/auth.md.

An API token (via --apiToken or the METICULOUS_API_TOKEN environment variable, scoped to a specific organization/project) is also supported, and is the way to authenticate in non-interactive contexts such as CI. Some agent platforms instead inject a bearer credential into outbound requests to app.meticulous.ai; that works too, and auth whoami reports it as credentials injected at request time.

MCP server

The agent commands are also exposed as tools on a hosted MCP server at https://app.meticulous.ai/api/mcp, so an MCP-enabled client (Claude Code, Cursor, Codex) can call them directly rather than shelling out to the CLI. Most read/analysis commands map to a get_<command> tool that returns the same data as the CLI command's --json output — for example agent test-run-diffs ⇄ get_test_run_diffs, agent dom-diff ⇄ get_dom_diff, and download session ⇄ get_session_data. The two mutating commands (upload-build, trigger-test-run) also have MCP tools, but not 1:1 — see references/agent.md for the full mapping, including that important difference. Connect with just the endpoint URL (browser OAuth on first use). The skills are written in terms of the CLI; substitute the matching tool where noted if you have the MCP server connected — but note MCP tools never infer git context (commitSha/baseSha/diff), unlike the CLI, so always pass those explicitly when using MCP.

Example

# Print schema for all commands (agent use)
meticulous schema

# Run a single replay locally
meticulous simulate --sessionId=<id> --appUrl=http://localhost:3000