Meticulous CLI

The official command-line interface for Meticulous - automated end-to-end testing that eliminates test maintenance. See the documentation for more details.

What is Meticulous?

Meticulous automatically creates and maintains a comprehensive test suite for your web application by recording real user interactions. When you open a pull request, Meticulous replays these user sessions against both the old and new versions of your app, identifying visual and functional differences.

Key Benefits:

• Zero maintenance tests that evolve with your app
• Scale to thousands of tests without writing code
• Catch regressions before they reach production
• Test real user flows, not assumptions

Installation

npm install --save-dev @alwaysmeticulous/cli

Quick Start

To install Meticulous in an application repository, connect the repository to a Meticulous project first, then run:

npx @alwaysmeticulous/cli onboard --project="<ORGANIZATION>/<PROJECT>"

If you are not logged in, onboard opens a browser to sign in. On a remote machine, run npx @alwaysmeticulous/cli auth login --device first.

onboard uses your local Claude Code or Codex account to prepare a pull request with the recorder and CI configuration. See the Onboarding Guide for GitHub, GitLab, and Bitbucket connection instructions and the manual alternative.

Sessions are recordings of user interactions with your application that Meticulous can replay to test for regressions.

1. Record a Session

Record a new session by interacting with your application:

npx @alwaysmeticulous/cli record \
  --apiToken="<API_TOKEN>" \
  --appUrl="http://localhost:3000"

Note: --apiToken is only required if the token is not stored in ~/.meticulous/config.json.

2. Simulate a Session

Simulate a recorded session on your local environment:

npx @alwaysmeticulous/cli simulate \
  --apiToken="<API_TOKEN>" \
  --sessionId="<SESSION_ID>" \
  --appUrl="http://localhost:3000"

3. Run in CI

Add Meticulous to your CI pipeline to automatically test every pull request. See the documentation for detailed CI setup instructions.

CLI Commands

Run npx @alwaysmeticulous/cli --help to see all available commands.

Common commands:

• onboard - Install the recorder and CI configuration using Claude Code or Codex
• record - Record a new session
• simulate - Simulate a recorded session locally
• run-all-tests - Run all replay test cases
• Additional commands available via --help

Configuration

The CLI can be configured using command-line flags or environment variables:

• --apiToken / METICULOUS_API_TOKEN - Your Meticulous API token
• --appUrl / METICULOUS_APP_URL - URL where your app is running
• --sessionId - Specific session ID to replay (for simulate command)

Documentation

• Full Documentation
• Onboarding Guide
• GitHub Repository

Requirements

• Node.js >= 12

Support

• Documentation: app.meticulous.ai/docs
• Issues: GitHub Issues