> 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 # What's new Unless a change is specific to one surface, changes listed here apply equally to the CLI and the corresponding MCP tools. ### August 17, 2026 — get real coverage for a base commit - `meticulous agent complete-base-run` **(new)** replays the rest of a base run's selected sessions, to complete its coverage information. - `meticulous agent js-coverage` now refuses a base run whose selected set hasn't fully replayed, saying how many sessions are missing, rather than reporting an understated total. ```bash meticulous agent complete-base-run meticulous agent js-coverage ``` --- ### August 11, 2026 — discover available check IDs, and a renamed check command - `meticulous agent test-run-checks` is renamed to `meticulous agent test-run-check`, since it operates on a single check. - The new `--availableIds` flag (MCP: `get_test_run_check_available_ids`) lists the check IDs that have reported results for a test run. ```bash meticulous agent test-run-check --availableIds --testRunId="" meticulous agent test-run-check --checkId="accessibility" --testRunId="" ``` --- ### August 10, 2026 — agent diff reviews and review comment writes - `meticulous agent reject-diff` records a rejection with a review comment explaining why. - `meticulous agent ignore-diff` says a diff looks like an unrelated variant / flake, currently as a comment only. - The new `create-diff-comment` and `reply-to-diff-comment` commands let agents start and continue review threads independently of a decision. - `meticulous agent diff-comments` gained an `isAgentAuthored` attribute, distinguishing agent-written comments from human ones. ```bash meticulous agent reject-diff --replayDiffId="" --screenshotName="" --reason="..." --x=0.5 --y=0.5 meticulous agent reply-to-diff-comment --commentId="" --text="..." ``` --- ### August 7, 2026 — non-visual check reports, session activity counts, and see and change which project you're querying - `meticulous agent test-run-checks` retrieves the Markdown report for a non-visual check. For customer-reported checks, use `--checkType="custom"`. - `meticulous agent sessions` gained `--includeNumberUserEvents` and `--includeNumberUrlsVisited` for adding the recorded user-event and URL-visit counts to each session, and `--includeDurationSeconds` for adding each session's duration in seconds (omitted for sessions where a duration couldn't be computed, e.g. recorded before this was tracked). - The MCP server gained `whoami`, `list_projects`, `get_project` and `set_project`, matching the existing `meticulous auth` commands — so an agent can now check which project its calls resolve to, and change it, without leaving the connection. `meticulous auth get-project` and `set-project` also gained `--json`. - Relatedly, an empty test-run or session lookup now names the project it searched and how to change it, rather than just reporting nothing found: a default project lives on your user account, so it is shared across machines and sessions and an unexpectedly empty result is usually the wrong project rather than missing data. ```bash meticulous agent test-run-checks --checkId="accessibility" meticulous agent test-run-checks --checkId="network-requests" --testRunId="" meticulous agent sessions --includeDurationSeconds meticulous agent sessions --includeNumberUserEvents meticulous agent sessions --includeNumberUrlsVisited meticulous auth get-project --json ``` --- ### August 4, 2026 — filter and focus test-run diffs - `meticulous agent test-run-diffs --onlyWithComments` filters to screenshot diffs with at least one open review comment. - The `--only*` row filters now combine as a union, so passing several returns the diffs matching any of them. - `meticulous agent test-run-diffs` returns all diffs when there are at most five; above that, a selected representative subset in priority order. Full-diff results no longer include an `isSelected` field. `--onlyRejected`/`--onlyWithComments` are unaffected by this cap, they always return every matching diff. - `meticulous agent test-run-diffs --counts` now also reports `numWithOpenComments`. --- ### August 3, 2026 — review comments, rejected diffs, and leaner test-run-diffs output - `meticulous agent test-run-diffs --includeReviews` adds `decision` (previously `--includeReviewDecisions`) and `openComments` to each diff. - `meticulous agent diff-comments --replayDiffId="" --screenshotName=""` retrieves the corresponding open comments with nested replies. - `meticulous agent test-run-diffs --onlyRejected` returns every screenshot diff already marked rejected, across every difference rather than only the selected subset. - `meticulous agent test-run-diffs` no longer returns `index` or `outcome`, and now returns `mismatchFraction` only with `--includeMismatchFraction`. ```bash meticulous agent test-run-diffs --includeReviews meticulous agent diff-comments --replayDiffId="" --screenshotName="" meticulous agent test-run-diffs --onlyRejected meticulous agent test-run-diffs --includeMismatchFraction ``` --- ### July 24, 2026 — submit feedback about Meticulous - `meticulous agent submit-feedback` **(new)** lets an agent send free-form feedback to the Meticulous team — whether Meticulous helped catch or debug a problem, what was confusing, and what information would have made the task easier. Optionally tag it with `--outcome` (`helped`/`neutral`/`hindered`), the related `--testRunId`, the `--skill` being followed, and `--agentName`/`--agentModel`. ```bash meticulous agent submit-feedback --message="Caught a real regression in the checkout flow" --outcome="helped" --testRunId="" --skill="meticulous-review" ``` --- ### July 21, 2026 — OAuth device flow login and project-level JS coverage - `meticulous auth login --device` **(new)** logs in via the [OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628): the CLI prints a URL and code you can open and confirm in a browser on any device, then polls until the grant is confirmed. Use this on remote or sandboxed machines (SSH sessions, containers, cloud coding agents) where a browser can't reach the CLI's localhost — unlike `--non-interactive`, which still requires opening the printed URL on the same machine as the CLI. - `meticulous agent js-coverage` gained `--latestForProject`, which returns per-file coverage from the project's preferred latest successful test run. --- ### July 20, 2026 — list a project's recently recorded sessions - `meticulous agent sessions` **(new)** lists a project's most recently created sessions, newest first — useful, for instance, for finding the id of a session you just recorded. - `meticulous agent trigger-test-run` gained `--maxDurationSeconds` (or `none` for unlimited) to override the replay engine's duration cap on runs with pinned `--sessionIds` — useful, for instance, to prevent agent-recorded sessions from being cut at the default 5min cap. ```bash meticulous agent sessions meticulous agent sessions --createdSince="2026-07-01" --createdUntil="2026-07-10" meticulous agent sessions --recordedBy="user@example.com" --visitedUrlFilter="*/checkout*" meticulous agent sessions --recordedSince 2026-07-10 --excludeSyntheticSessions --limit 10 meticulous agent trigger-test-run --sessionIds="," --maxDurationSeconds=none ``` --- ### July 16, 2026 — MCP server for agents The Meticulous MCP server exposes the agent CLI's read and analysis commands as tools your coding agent can call directly — see the [MCP server](/docs/agents/mcp-server) page for setup and the full list of available tools. Every read-only `agent` command has a matching tool; the two mutating ones, `upload-build` and `trigger-test-run`, aren't exposed yet but are coming soon. --- ### July 13, 2026 — review-state aware test-run-diffs, diff counts, and per-account default project - `meticulous agent test-run-diffs` now understands PR review state, and can report totals without the full list: | Flag | What it does | |------|--------------| | `--includeReviewDecisions` | Add a `decision` column with each diff's PR review decision (`accepted`/`rejected`/`ignored`/`unreviewed`; `unreviewed` when undecided or there's no PR) | | `--onlyUnreviewed` | Return only the diffs still awaiting review — everything left to look at, across every difference (implies `--includeAllDiffs`, so the `isSelected` column is included) | | `--counts` | Print just the aggregate totals — number of replays, number of differences, and the review-decision breakdown (approved / ignored / rejected / unreviewed) — instead of the per-diff list | - Your default project is now a per-account setting, too: - `meticulous auth set-project` now persists your default project on your Meticulous account instead of a local file — so it's consistent across machines and available to the MCP server. `meticulous auth logout` leaves it untouched. - `meticulous auth get-project` **(new)** prints your default project, which you can also view and change from your user settings in the web app. - `meticulous agent test-run-for-commit`, `test-run-diffs`, `js-coverage`, and `trigger-test-run` gained `--project` — a one-off override (id, `organization/name` slug, or unique bare name) for that call only, which doesn't change your stored default. ```bash meticulous auth set-project --project="my-org/my-project" meticulous auth get-project meticulous agent js-coverage --project="my-org/my-project" ``` --- ### July 10, 2026 — test-run-diffs is differences-only `meticulous agent test-run-diffs` no longer returns matching screenshots — it reports only genuine visual differences, the same set Meticulous counts and displays everywhere else. The `--includeMatches` flag is removed. --- ### July 7, 2026 — get combined coverage from multiple test runs `meticulous agent js-coverage` gained `--headPlusTestRunIds` and `--testRunIds` for unioning coverage across several test runs (same project, same commit) — e.g. combining a run's head coverage with a separate run triggered via `agent trigger-test-run --sessionIds=""` to assess how these sessions improve coverage. ```bash meticulous agent js-coverage --headPlusTestRunIds="," meticulous agent js-coverage --testRunIds=",," ``` --- ### July 6, 2026 — consistent machine-readable output for agent & auth - `agent` and `auth` commands gained `--json` for JSON-structured output instead of default format. - `agent` and `auth` commands also gained `--verbose`, which prints additional progress logs on stderr. - `--rawJson` is renamed to `--jsonArgs` (old name still works, now deprecated). ```bash meticulous agent js-coverage --json meticulous auth whoami --json ``` --- ### July 1, 2026 — more coverage info, session pinning, and non-interactive login - `meticulous agent js-coverage` gained new flags for richer per-file coverage data: `--includeExecutableRanges`, `--includeUncoveredRanges`, `--includeCoveragePercentage`, and `--prDiffOnly` (test-run queries only), plus `--includeAllFiles` and `--globFilter` (also for replay and replay-diff queries). - `meticulous agent trigger-test-run` can now run with no arguments at all — it infers the already-uploaded deployment for your local HEAD commit. - `meticulous agent trigger-test-run` now accepts `--sessionIds`, a comma-separated list of session IDs to replay for both the base and the head, instead of the project's auto-selected golden set. - `meticulous agent trigger-test-run` now also accepts `--commitSha` as an alternative to `--deploymentId`, resolving to the most recently uploaded deployment for that commit — useful for re-triggering a run against a commit that has already gone through Meticulous. - `meticulous auth login --non-interactive` lets the login flow run without a TTY: it prints the login URL instead of opening a browser. ```bash meticulous agent js-coverage --includeCoveragePercentage --prDiffOnly meticulous agent trigger-test-run meticulous agent trigger-test-run --deploymentId="" --baseSha="" --sessionIds="," meticulous agent trigger-test-run --commitSha="" --baseSha="" meticulous auth login --non-interactive --project="my-org/my-project" ``` --- ### June 29, 2026 — separate build upload from triggering a test run Two new agent commands, `upload-build` and `trigger-test-run`, give agents their own counterparts to the CI upload commands (`ci upload-assets` / `ci upload-container`) — and split building and uploading your app from kicking off a test run. You can now upload a build once, capture its deployment ID, and trigger one or more runs against it independently. Git options such as the commit SHA are resolved automatically from your local repository. ```bash # Upload a static build (or a container image) and capture the deploymentId meticulous agent upload-build --appDirectory="" meticulous agent upload-build --localImageTag="" # Trigger a run against an uploaded build meticulous agent trigger-test-run --deploymentId="" ``` --- ### June 24, 2026 — smoother authentication and non-interactive project selection Authentication is easier to drive from scripts and agents, and a stored login is no longer shadowed by a stale token. - A logged-in OAuth session now takes precedence over a stale `METICULOUS_API_TOKEN` or `~/.meticulous/config.json` token, so you won't get silently stuck on an expired credential. - `meticulous auth login` **(new)** forces a fresh browser login and then selects a project. - `meticulous auth whoami` now also reports which credential is actually in use. - `meticulous auth logout` now also clears the selected project, and warns if an environment-variable or config-file token will keep being used. - `meticulous auth list-projects` **(new)** lists the projects you can access. - Argument `--project org/project` **(new)** on `login` / `set-project` lets you select a project non-interactively. ```bash meticulous auth login --project="my-org/my-project" meticulous auth list-projects ``` --- ### June 19, 2026 — richer, curated test-run-diffs output By default, `meticulous agent test-run-diffs` now returns a curated, priority-ordered set of the most relevant visual differences as a single flat list. New flags let you control what comes back: | Flag | What it does | |------|--------------| | `--includeDomDiffIds` | Include DOM-diff IDs for each screenshot | | `--includeAllDiffs` | Return every diff, not just the curated set (adds an `isSelected` column) | | `--includeMatches` | Include matching and known-flaky screenshots too, not just differences (implies `--includeAllDiffs`) | | `--orderByReplayDiffs` | Order by replay then event index instead of priority | Polling output is also quieter, and runs that can't produce diffs now fail fast with a clear message. --- ### June 12, 2026 — JavaScript coverage and lookup by commit New agent commands surface the JavaScript code coverage captured during replays, and let you resolve a test run straight from a commit — so an agent can go from local git context to the right run without tracking run IDs. ```bash meticulous agent js-coverage # coverage for a test run (defaults to the current git HEAD) meticulous agent js-coverage-diff # base-vs-head coverage diff for a replay diff meticulous agent test-run-for-commit # the latest test run for the current commit ```