Environment Variables Reference

Reference for environment variables that configure Meticulous replay behavior. These are primarily useful when running local simulations or debugging replay issues.

Set these in your shell before running CLI commands:

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

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.

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

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.

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.

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.

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:

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

Or as URL strings:

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

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.

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:

METICULOUS_PAUSE_BEFORE_REDIRECT=login

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.

Type: Number (minutes)

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

METICULOUS_REPLAY_TIMEOUT_MINUTES=10

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.

METICULOUS_MAX_DURATION_MS=30000

Type: String (comma-separated flags)

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

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

Type: Boolean (true/false)

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

Type: Boolean (true/false)

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

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.

Type: Boolean (true/false)

Disables Shared Workers (window.SharedWorker) during replay.