SkillsAdd

alwaysmeticulous/skills

meticulous-cli

Overview of the Meticulous CLI tool and its global options. Use when asking about the meticulous CLI in general, available commands, or global flags that apply to all commands.

All-time #2448 Trending #1102 Hot #4477 First seen Mar 16, 2026
8-week activity · all time api

Installation

$ npx skills add alwaysmeticulous/skills --skill meticulous-cli
View on skills.sh ↗ GitHub repository ↗

Also in this package

Other skills from alwaysmeticulous/skills · top by installs.

npx skills add alwaysmeticulous/skills
meticulous-simulate-and-diff 5.8K meticulous-iterative-dev 5.8K meticulous-cli-update 5.8K meticulous-use-session-data 5.8K meticulous-test 5.8K meticulous-review 5.8K meticulous-zero-diff-task 1.8K meticulous-fix 1.8K meticulous-increase-coverage 6 test-with-meticulous 28

Browse all from alwaysmeticulous/skills

More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Declared
Cursor Declared
Codex Declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Not declared

Repository health

Stars 10
License LICENSE
Default branch main
Status Active

Skill metadata

Parsed from SKILL.md frontmatter.

Declared agents claude-code cursor codex

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 5,743 B
  • docs SUMMARY.md 195 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 5,944 installs

SKILL.md

Meticulous CLI

The meticulous CLI records user sessions and replays them to catch visual regressions. It is installed as part of @alwaysmeticulous/cli.

Before starting, run the meticulous-cli-update skill to ensure the Meticulous CLI and skills are up to date — unless it has already run earlier in this conversation, in which case skip it.

Invocation

meticulous <command> [options]

The skills assume meticulous is on PATH. The meticulous-cli-update skill installs it globally via npm install --global @alwaysmeticulous/cli@latest if missing. It can also be invoked as npx @alwaysmeticulous/cli when installed locally per-project.

Command Groups

Command Purpose
agent Read, analyse, and trigger test runs — the agent-facing commands, also exposed on the MCP server
auth Authenticate with Meticulous (login, whoami, logout, project selection)
debug Set up AI-ready debug workspaces for investigating replay diffs and replays
download Download sessions, replays, and test runs locally
local Find sessions relevant to the current branch's code changes
project Inspect the project you're authenticated against
simulate / replay Replay a recorded session against a URL
schema Output the CLI command schema as JSON (for agent/programmatic use)

See the reference for each group for full option details:

  • [references/agent.md](references/agent.md)
  • [references/auth.md](references/auth.md)
  • [references/debug.md](references/debug.md)
  • [references/download.md](references/download.md)
  • [references/local.md](references/local.md)
  • [references/project.md](references/project.md)
  • [references/simulate.md](references/simulate.md)
  • [references/schema.md](references/schema.md)

Global Options

These options are accepted by every command:

Option Type Default Description
--logLevel string info Log verbosity: trace, debug, info, warn, error, silent
--dataDir string ~/.meticulous Directory where sessions, replays, and other data are stored
--jsonArgs string — Pass all options as a JSON string (useful for programmatic/agent invocation)

--rawJson is a deprecated alias for --jsonArgs. --dryRun is not global — it is available only on the commands that perform actions (e.g. the ci / agent run-triggering and upload commands, and simulate); check the command's reference or meticulous schema <command>.

Authentication

Commands authenticate via OAuth. The login token is stored on disk and reused across sessions — in an interactive terminal, a command that needs auth opens a browser sign-in automatically; without a TTY (the usual agent case) it fails and tells you to run meticulous auth login. Run meticulous auth whoami to see the current state. Project-scoped commands also need a default project, set at login or with meticulous auth set-project. See [references/auth.md](references/auth.md).

An API token (via --apiToken or the METICULOUSAPITOKEN environment variable, scoped to a specific organization/project) is also supported, and is the way to authenticate in non-interactive contexts such as CI. Some agent platforms instead inject a bearer credential into outbound requests to app.meticulous.ai; that works too, and auth whoami reports it as credentials injected at request time.

MCP server

The agent commands are also exposed as tools on a hosted MCP server at https://app.meticulous.ai/api/mcp, so an MCP-enabled client (Claude Code, Cursor, Codex) can call them directly rather than shelling out to the CLI. Most read/analysis commands map to a get<command> tool that returns the same data as the CLI command's --json output — for example agent test-run-diffs ⇄ gettestrundiffs, agent dom-diff ⇄ getdomdiff, and download session ⇄ getsessiondata. The two mutating commands (upload-build, trigger-test-run) also have MCP tools, but not 1:1 — see [references/agent.md](references/agent.md) for the full mapping, including that important difference. Connect with just the endpoint URL (browser OAuth on first use). The skills are written in terms of the CLI; substitute the matching tool where noted if you have the MCP server connected — but note MCP tools never infer git context (commitSha/baseSha/diff), unlike the CLI, so always pass those explicitly when using MCP.

Example

# Print schema for all commands (agent use)
meticulous schema

# Run a single replay locally
meticulous simulate --sessionId=<id> --appUrl=http://localhost:3000