alwaysmeticulous 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-updateskill 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
| Command | Purpose |
|---|---|
agent |
Read, analyse, and trigger test runs — the agent-facing commands, also exposed on the MCP server |
auth |
Authenticate with Meticulous (login, whoami, logout, project selection) |
debug |
Set up AI-ready debug workspaces for investigating replay diffs and replays |
download |
Download sessions, replays, and test runs locally |
local |
Find sessions relevant to the current branch's code changes |
project |
Inspect the project you're authenticated against |
simulate / replay |
Replay a recorded session against a URL |
schema |
Output the CLI command schema as JSON (for agent/programmatic use) |
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:
| Option | Type | Default | Description |
|---|---|---|---|
--logLevel |
string | info |
Log verbosity: trace, debug, info, warn, error, silent |
--dataDir |
string | ~/.meticulous |
Directory where sessions, replays, and other data are stored |
--jsonArgs |
string | — | Pass all options as a JSON string (useful for programmatic/agent invocation) |
--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