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 whoami         # show how you're currently authenticated
meticulous auth list-projects  # list the projects you can access
meticulous auth set-project    # pick which project to use (interactive)
meticulous auth set-project --project="{org}/{proj}"  # same, but non-interactive
meticulous auth logout         # clear stored tokens

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.

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

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 --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 --includeMatches      # include matches (implies --includeAllDiffs)
meticulous agent test-run-diffs --orderByReplayDiffs  # order by replay + event instead of priority

Investigate a diff in more detail

# Download screenshots to ~/.meticulous/agent-images/
meticulous agent image-files --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 --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

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

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

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