CLI commands for agents

A curated tour of the meticulous CLI commands the agent skills compose into higher-level workflows.

For the full reference, see CLI commands. For setup (installing the CLI, authenticating, configuring agent permissions), see the setup guide.

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

login --non-interactive drops the TTY requirement entirely: it prints the login URL instead of opening a browser, so an agent can start the flow and hand the URL to a human to complete on the same machine.

login --device also drops the TTY requirement, but uses the OAuth device flow instead: the CLI prints a URL and code that can be opened and confirmed in a browser on any device, not just the one running the CLI. Use this on remote or sandboxed machines (SSH sessions, containers, cloud coding agents) where a browser can't reach this machine's localhost.

If you'd rather authenticate without a browser at all, set METICULOUS_API_TOKEN in your environment or in ~/.meticulous/config.json — see the setup guide for how to grab a token.

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                       # curated 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 --includeReviewDecisions  # add the PR review decision 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 curated set
meticulous agent test-run-diffs --onlyUnreviewed      # only diffs still awaiting review
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>"

Inspect JS code coverage

meticulous agent js-coverage                             # coverage for test run on 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

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 --includeStartUrl --includeAbandonedReason  # add optional columns
meticulous agent sessions --limit=25 --offset=50        # override count / page through results

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

Find sessions that cover your change

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

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>"