CLI commands for agents

The Meticulous CLI provides tools which enable agents to interface with Meticulous: get test run diffs, replay details, coverage, and more. We furthermore provide agent skills which compose these tools into higher-level workflows, like a skill to review a PR test run.

Install & update the Meticulous CLI

To install, and update, the Meticulous CLI:

npm install --global @alwaysmeticulous/cli@latest

You can also install it locally per-project instead of globally.

The CLI is under active development with frequent changes and improvements — re-run the same command to update the CLI to the latest version.

Authentication

Authenticate the CLI with your Meticulous account:

meticulous auth login

This will open a browser to sign in, and if you're a member of multiple projects, let you pick a default project to use. This default is saved to your Meticulous account — so it's consistent across machines and available to the MCP server — and you can change it any time from your user settings or by running meticulous auth set-project. Non-interactive versions of both commands are also available, for use in CI or other non-TTY environments:

meticulous auth login --non-interactive --project <organization/project>
meticulous auth set-project --project <organization/project>

set-project is fully unattended. login --non-interactive still completes via a localhost callback, so it only drops the requirement for an interactive TTY — the URL it prints must still be opened on this same machine.

If the CLI is running on a remote or sandboxed machine (SSH session, container, cloud coding agent) where a browser can't reach that machine's localhost, use --device instead: it logs in via the OAuth device flow, printing a URL and code that can be opened and confirmed in a browser on any device.

meticulous auth login --device --project <organization/project>

Command reference

Global command options

meticulous <command> --json               # output in JSON format on stdout instead of default format
meticulous <command> --jsonArgs="<json>"  # pass all options as a JSON string
meticulous <command> --verbose            # also print progress to stderr (instead of just warnings)
meticulous <command> --dryRun             # print what a mutating command would do, without doing it

Authentication

meticulous auth login          # force a fresh browser login, then select a project (interactive)
meticulous auth login --non-interactive --project="{org}/{proj}"  # same, but non-interactive
meticulous auth login --device --project="{org}/{proj}"  # same, but OAuth device flow
meticulous auth whoami         # show how you're currently authenticated
meticulous auth logout         # clear stored tokens
meticulous auth get-project    # print your default project
meticulous auth set-project    # choose your default project (interactive)
meticulous auth set-project --project="{org}/{proj}"  # same, but non-interactive
meticulous auth list-projects  # list the projects you can access

Discover the CLI surface

meticulous schema           # full schema
meticulous schema simulate  # narrow to a single command or group

Look up the test run for a commit

meticulous agent test-run-for-commit                      # latest run for the current git HEAD
meticulous agent test-run-for-commit --commitSha="<sha>"  # …or for a specific commit
meticulous agent test-run-for-commit --dontWaitForTestRunToComplete  # don't block on in-progress runs
meticulous agent test-run-for-commit --project="{org}/{proj}"  # override default project for this call

Retrieve diffs for a test run

meticulous agent test-run-diffs                       # diffs for test run on current commit
meticulous agent test-run-diffs --testRunId="<id>"    # …or for an explicit test run
meticulous agent test-run-diffs --commitSha="<sha>"   # …or for a specific commit
meticulous agent test-run-diffs --dontWaitForTestRunToComplete  # don't block on in-progress runs
meticulous agent test-run-diffs --includeReplayIds    # include base and head replay IDs per diff
meticulous agent test-run-diffs --includeMismatchFraction  # include the fraction of changed pixels
meticulous agent test-run-diffs --includeReviews        # add decision and comment count per diff
meticulous agent test-run-diffs --includeDomDiffIds   # include DOM-diff IDs per screenshot
meticulous agent test-run-diffs --includeAllDiffs     # every diff, not just the selected set
meticulous agent test-run-diffs --onlyUnreviewed      # only diffs awaiting review
meticulous agent test-run-diffs --onlyRejected        # all rejected diffs
meticulous agent test-run-diffs --onlyWithComments    # only diffs with open review comments
meticulous agent test-run-diffs --orderByReplayDiffs  # group by replay diff instead of priority order
meticulous agent test-run-diffs --project="{org}/{proj}"  # override default project for this call
meticulous agent test-run-diffs --counts              # just the total counts, not the full diff list

Investigate a diff in more detail

# Download screenshots to ~/.meticulous/agent-images/, or get image URLs
meticulous agent image-files --replayDiffId="<id>" --screenshotName="<name>"
meticulous agent image-urls --replayDiffId="<id>" --screenshotName="<name>"

# DOM diff for a single replay-diff screenshot
meticulous agent dom-diff --replayDiffId="<id>" --screenshotName="<name>"

# Timeline diff for a replay diff
meticulous agent timeline-diff --replayDiffId="<id>"

Review diffs

meticulous agent diff-comments --replayDiffId="<id>" --screenshotName="<name>"
meticulous agent diff-comments ... --includeResolved  # include resolved comments
meticulous agent reject-diff ... --reason="..." --x=0.5 --y=0.5
meticulous agent ignore-diff ... --reason="..." --x=0.5 --y=0.5
meticulous agent create-diff-comment ... --text="..." --x=0.4 --y=0.6
meticulous agent reply-to-diff-comment --commentId="<id>" --text="..."

Retrieve a non-visual check report

meticulous agent test-run-check --checkId="accessibility"  # builtin check for the current commit
meticulous agent test-run-check --checkId="network-requests" --testRunId="<id>"  # …or an explicit run
meticulous agent test-run-check --checkId="accessibility" --commitSha="<sha>"  # …or a specific commit
meticulous agent test-run-check --checkType="custom" --checkId="my-check"  # customer-reported check

# List available check IDs
meticulous agent test-run-check --availableIds  # for the current commit
meticulous agent test-run-check --availableIds --testRunId="<id>"  # …or an explicit run
meticulous agent test-run-check --availableIds --commitSha="<sha>"  # …or a specific commit

Inspect JS code coverage

meticulous agent js-coverage                           # coverage for current commit
meticulous agent js-coverage --testRunId="<id>"        # …or for an explicit test run
meticulous agent js-coverage --commitSha="<sha>"       # …or for a specific commit
meticulous agent js-coverage --latestForProject        # …or project's preferred latest successful run
meticulous agent js-coverage --project="{org}/{proj}"  # override default project for this call
meticulous agent js-coverage --replayId="<id>"         # coverage for a single replay
meticulous agent js-coverage --replayId="<id>" --screenshotName="<name>"  # or a single screenshot
meticulous agent js-coverage-diff --replayDiffId="<id>"  # coverage diff for a replay diff
meticulous agent js-coverage-diff --replayDiffId="<id>" --screenshotName="<name>"

# Filter rows
meticulous agent js-coverage --includeAllFiles                 # not just ones with coverage
meticulous agent js-coverage --globFilter="src/components/**"  # only matching repo paths

# Choose which columns to emit, and which rows to include (test-run only)
meticulous agent js-coverage --includeExecutedRanges      # executed line ranges (default)
meticulous agent js-coverage --includeExecutableRanges    # line ranges that could be executed
meticulous agent js-coverage --includeUncoveredRanges     # executable ranges that were not executed
meticulous agent js-coverage --includeCoveragePercentage  # % of executable lines executed
meticulous agent js-coverage --prDiffOnly                 # restrict to files changed in the PR diff

# Aggregated coverage for multiple test runs (same project + commit; test-run only)
meticulous agent js-coverage --headPlusTestRunIds="<id1>,<id2>"  # in addition to the current commit
meticulous agent js-coverage --testRunIds="<id1>,<id2>,<id3>"    # list of runs to combine

# Complete a base run
meticulous agent complete-base-run                        # replay the rest of the current commit's base run
meticulous agent complete-base-run --testRunId="<id>"     # …or of an explicit run
meticulous agent complete-base-run --commitSha="<sha>"    # …or of a specific commit's run
meticulous agent complete-base-run --project="{org}/{proj}"  # override default project for this call
meticulous agent complete-base-run --dontWaitForTestRunToComplete  # return once the replays are scheduled

Find recently created sessions

meticulous agent sessions                               # 100 most recently created sessions
meticulous agent sessions --project="{org}/{proj}"      # override default project for this call
meticulous agent sessions --createdSince="2026-07-01"   # only sessions created at/after this date
meticulous agent sessions --recordedSince="2026-07-01"  # only sessions originally recorded at/after
meticulous agent sessions --recordedBy="user@example.com"  # only sessions recorded by this identity
meticulous agent sessions --excludeSyntheticSessions    # drop patched/sliced/mutated sessions
meticulous agent sessions --visitedUrlFilter="*/checkout*"  # only sessions that visited a matching URL
meticulous agent sessions --includeDurationSeconds      # add a durationSeconds column
meticulous agent sessions --includeNumberUserEvents     # add a numberUserEvents column
meticulous agent sessions --includeNumberUrlsVisited    # add a numberUrlsVisited column
meticulous agent sessions --includeStartUrl             # add a startUrl column
meticulous agent sessions --includeAbandonedReason      # add an abandonedReason column
meticulous agent sessions --limit=25 --offset=50        # override count / page through results

# Identify sessions that exercise your branch's code changes
meticulous local relevant-sessions --format=multi-file --minimum-times-to-cover-each-line=1

Upload a build and trigger a test run

# Upload a static build, or a container image, and capture the deploymentId
meticulous agent upload-build --appDirectory="<path-to-build>"
meticulous agent upload-build --localImageTag="<image-tag>" --commitSha="<sha>"

# Trigger a run against that deployment (infers a diff against local HEAD)
meticulous agent trigger-test-run --deploymentId="<id>"
meticulous agent trigger-test-run --project="{org}/{proj}"  # override default project for this call

# …and pin an explicit base (diffs against local HEAD)
meticulous agent trigger-test-run --deploymentId="<id>" --baseSha="<sha>"

# …or pass a diff yourself, instead of inferring one locally
meticulous agent trigger-test-run --deploymentId="<id>" --baseSha="<sha>" --gitDiffOutput="<diff>"

# …or skip the upload step and target an already-uploaded deployment for a commit
meticulous agent trigger-test-run
meticulous agent trigger-test-run --commitSha="<sha>"

# Replay only specific sessions, instead of the auto-selected golden set
meticulous agent trigger-test-run --sessionIds="<id1>,<id2>"

Submit feedback about Meticulous

# Tell the Meticulous team whether Meticulous helped, and what would have made your task easier
meticulous agent submit-feedback --message="<one or two sentences>"
meticulous agent submit-feedback --message="<…>" --outcome="helped"       # or "neutral" / "hindered"
meticulous agent submit-feedback --message="<…>" --testRunId="<id>"       # tie it to a test run
meticulous agent submit-feedback --message="<…>" --skill="meticulous-review"  # workflow being followed
meticulous agent submit-feedback --message="<…>" --agentName="claude-code" --agentModel="<model>"

Set up an AI-ready debug workspace

# Download all replay data into a structured local debug workspace in ~/.meticulous
meticulous debug replay <replayId>           # debug a single replay, optionally with --baseReplayId
meticulous debug replay-diff <replayDiffId>  # debug a specific replay diff
meticulous debug clean                       # clean up old debug workspaces

Run Agent review (beta)

Agent review uploads a build and lets a Meticulous-hosted agent explore and test it. The Agent review page reports the test-case results and screenshots, and the discovered flows are saved as additional sessions for the PR. This is an opt-in beta: your project must be enabled before ci agent-test can launch.

meticulous ci agent-test \
  --assetsDir="build" \
  --commitSha="<pr-head-sha>" \
  --instructionsFile=".github/agent-review/instructions.md"

Use exactly one of --assetsDir, --assetsUploadId, or --localImageTag. For a staging backend, add --backendUrl; --backendProxyPaths defaults to /api. If the frontend makes absolute cross-origin API or auth requests, add repeatable --trustedOrigins https://… flags. Uploaded assets are served at http://localhost:8000 by default; pass --appPort to override. Do not combine --backendUrl with --enableLocalMocks.

For a container build, use --containerPort, repeatable --containerEnv NAME=value options, and --containerHealthCheckEndpoint when the defaults do not fit your image. Use --enableLocalMocks to mock the container's network traffic from relevant recorded sessions. See Set up Agent review for the prerequisites, CI workflow, and staging-backend setup.

Replay a single session locally

meticulous simulate --sessionId="<id>" --appUrl="<appUrl>"
meticulous simulate --sessionId="<id>" --appUrl="<appUrl>" --baseReplayId="<id>"  # diff against base
meticulous simulate --sessionId="<id>" --appUrl="<appUrl>" --screenshot  # capture screenshots
meticulous simulate --sessionId="<id>" --appUrl="<appUrl>" --headless    # run in headless mode
meticulous simulate --sessionId="<id>" --appUrl="<appUrl>" --devtools    # open Chromium DevTools
meticulous simulate --sessionId="<id>" --appUrl="<appUrl>" --maxDurationMs=<ms>  # set max virtual time

Download artefacts

# Downloads to ~/.meticulous/ by default (override with --dataDir)
meticulous download session --sessionId="<id>"
meticulous download replay --replayId="<id>"
meticulous download test-run --testRunId="<id>"