> 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

# Environment Variables Reference

Reference for environment variables that configure Meticulous replay behavior. These are primarily useful when running [local simulations](/docs/how-to/detect-diffs-locally) or debugging replay issues.

Set these in your shell before running [CLI commands](/docs/reference/cli-commands):

```bash
METICULOUS_HOLD_BROWSER_OPEN=true npx @alwaysmeticulous/cli simulate \
  --sessionId="<id>" --appUrl="<url>"
```

---

## Debugging & Inspection

### `METICULOUS_HOLD_BROWSER_OPEN`

**Type**: Boolean (`true`/`false`)

Keep the browser open after a replay completes so you can inspect the final state, open DevTools, and explore the DOM.

```bash
METICULOUS_HOLD_BROWSER_OPEN=true npx @alwaysmeticulous/cli simulate \
  --sessionId="<id>" --appUrl="<url>"
```

---

### `METICULOUS_SHOW_MOUSE_LOCATION`

**Type**: Boolean (`true`/`false`)

Displays the mouse position as a red dot on the page during replay. Helpful for verifying that mouse events are targeting the correct elements.

---

### `METICULOUS_TRACK_UNEXPECTED_EXECUTION`

**Type**: Boolean (`true`/`false`)

Enables tracking and pausing on unexpected JavaScript execution (code running outside of the expected replay timeline). When the replay encounters unexpected execution it will pause in the Chromium debugger.

**Tips**:
- Run `new Error().stack` in the console when paused to get a stack trace
- In the Chromium debugger, tick "Show ignore-listed frames" when viewing stack traces

> **Note**: This must be enabled for `METICULOUS_UNEXPECTED_EXECUTION_AUTO_RESUME` and `METICULOUS_SET_BREAKPOINTS` to take effect.

---

### `METICULOUS_UNEXPECTED_EXECUTION_AUTO_RESUME`

**Type**: Boolean (`true`/`false`)

Automatically resumes when unexpected execution is encountered instead of pausing. Use this when you want to see the logs without manually stepping through each pause.

Requires `METICULOUS_TRACK_UNEXPECTED_EXECUTION=true`.

---

### `METICULOUS_SET_BREAKPOINTS`

**Type**: JSON string

Set breakpoints as a JSON array. You can copy breakpoint strings from the logs when `METICULOUS_TRACK_UNEXPECTED_EXECUTION` is enabled.

Breakpoints can be specified as objects:

```bash
METICULOUS_SET_BREAKPOINTS='[{"scriptId": "<id>", "lineNumber": 10, "columnNumber": 5}]'
```

Or as URL strings:

```bash
METICULOUS_SET_BREAKPOINTS='["https://example.com/script.js:10:5"]'
```

---

### `METICULOUS_DEBUG_DOM_UPDATES`

**Type**: Boolean (`true`/`false`)

Logs details of DOM mutations that occur at unexpected times (e.g. outside of `advanceVirtualTime`), including the HTML of the mutated elements.

---

### `METICULOUS_PAUSE_BEFORE_REDIRECT`

**Type**: String (URL fragment)

Pauses the browser before any redirects whose URL contains the specified fragment. For example, to pause before redirecting to a login page:

```bash
METICULOUS_PAUSE_BEFORE_REDIRECT=login
```

---

## Timing & Timeouts

### `METICULOUS_NO_TIMEOUT`

**Type**: Boolean (`true`/`false`)

Disables all timeouts except for the navigation timeout (which is extended to 60 minutes). Useful when pausing in debuggers or stepping through replay execution.

---

### `METICULOUS_REPLAY_TIMEOUT_MINUTES`

**Type**: Number (minutes)

Sets the replay timeout to the specified number of minutes, overriding the default.

```bash
METICULOUS_REPLAY_TIMEOUT_MINUTES=10
```

---

### `METICULOUS_MAX_DURATION_MS`

**Type**: Number (milliseconds)

Cuts replays short when they reach the specified virtual time. Useful when running a test run and you only want to replay the first portion of each session.

```bash
METICULOUS_MAX_DURATION_MS=30000
```

---

## Browser Configuration

### `METICULOUS_ADDITIONAL_CHROMIUM_FLAGS`

**Type**: String (comma-separated flags)

Passes additional flags to the Chromium browser instance launched for replay.

```bash
METICULOUS_ADDITIONAL_CHROMIUM_FLAGS="--disable-gpu,--no-sandbox"
```

---

## Feature Toggles

### `METICULOUS_DISABLE_SENTRY`

**Type**: Boolean (`true`/`false`)

Disables the customer application's Sentry initialization during replay. This simplifies stack traces and reduces noise when debugging replay issues.

---

### `METICULOUS_DISABLE_RECAPTCHA`

**Type**: Boolean (`true`/`false`)

Disables Google reCAPTCHA script loading during replay. This simplifies stack traces and reduces noise when debugging.

---

### `METICULOUS_DISABLE_WEB_WORKERS`

**Type**: Boolean (`true`/`false`)

Disables Web Workers (`window.Worker`) during replay. Useful if workers are causing replay issues. Leave disabled (or set project setting `disableWebWorkers: false`) when using dedicated worker network recording.

---

### `METICULOUS_DISABLE_SHARED_WORKERS`

**Type**: Boolean (`true`/`false`)

Disables Shared Workers (`window.SharedWorker`) during replay.