> Meticulous records real user sessions from a web app and replays them against each commit to catch visual regressions.
>
> Full AI-readable docs index (complete project setup journey + every page as markdown): https://app.meticulous.ai/llms.txt

# 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](/docs/agents/skills) which compose these tools into higher-level workflows, like a skill to review a PR test run.

- [Install & update the Meticulous CLI](#install-update-the-meticulous-cli)
- [Authentication](#authentication)
- [Command reference](#command-reference)

---

## Install & update the Meticulous CLI

To install, and update, the Meticulous CLI:

```bash
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:

```bash
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](/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:

```bash
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.

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

#### Alternative: using an API token

Select the project below that contains the sessions you wish to work with, then copy the token:

```
METICULOUS_API_TOKEN:
<API_TOKEN>
```

*Be very careful with this API token, since it allows the holder access to your recorded sessions.*

Pass it to the CLI in one of two ways:

- Set the `METICULOUS_API_TOKEN` environment variable:

  ```bash
  export METICULOUS_API_TOKEN="<paste-token-here>"
  ```

- Or store it in `~/.meticulous/config.json`:

  ```json
  { "apiToken": "<paste-token-here>" }
  ```

---

## Command reference

### Global command options

```bash
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

```bash
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

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

---

### Look up the test run for a commit

```bash
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

```bash
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

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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.

```bash
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](/docs/agents/agent-review) for the prerequisites, CI workflow, and staging-backend setup.

---

### Replay a single session locally

```bash
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

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