replayqa

CLI for Replay QA projects, bugs, journeys, explorations, and reverse-proxy setup.

Print the agent-ready workflow guide with either command:

replayqa skill
replayqa skills

Installation

npm install --global replayqa

The npm package contains the forward proxy. On the first replayqa run or replayqa proxy, the CLI downloads the matching pinned frpc release into Replay's private data directory, verifies its official SHA-256 checksum and version, and reuses it on later runs. It does not modify Homebrew, system package managers, or PATH.

Check prerequisites without starting a proxy, or install/repair managed dependencies immediately:

replayqa doctor
replayqa doctor --fix

Authentication

replayqa uses the same Replay login cache as replayio. If you are already signed in with replayio login, you are signed in here too.

replayqa login
# or
replayio login

Without a browser (CI), set REPLAY_QA_API_KEY to a Replay QA API token. app.replay.io API keys are not accepted by Replay QA. Credentials: https://docs.replay.io/reference/api-keys

REPLAY_API_KEY and RECORD_REPLAY_API_KEY are deprecated names for REPLAY_QA_API_KEY. They are read after REPLAY_QA_API_KEY only when they hold a credential Replay QA accepts (an lqa_ token or a Replay access token), and the CLI prints a deprecation notice when it uses one. app.replay.io API keys in them are ignored.

API workflow

replayqa bootstrap http://localhost:3000 "Test checkout, login, and settings"
replayqa context
replayqa status --watch
replayqa bugs --details --save
replayqa bug bug_123
replayqa mark-bug bug_123 fixed

• Bug-type exclusions in the instructions (e.g. "Exclude accessibility.") switch those bug types off project-wide.
  • Accessibility includes text color contrast.
  • The response's run_modifications receipt says what changed. Its notice is printed under "Bug types".
  • Changes apply to all work that has not started yet. Runs already in progress keep their settings.
• To review the bug types before QA starts, create without exploration, then start it:

  replayqa bootstrap https://example.com "Test checkout. Exclude accessibility." --no-start-exploration --public
  replayqa start-exploration "Test checkout"

• --no-start-exploration also applies to create-project, full-qa, and run --create-project.
  • It affects project creation only.

Project ids are resolved in this order:

1. --project <project_id> or a project URL argument
2. REPLAY_QA_PROJECT_ID
3. .replay/config.json key qa-project-id

The generic API escape hatch is available for new endpoints:

replayqa api GET /projects/proj_123/status
replayqa api POST /projects/proj_123/report-missing-bug --data '{"description":"Checkout fails"}'

GitHub Actions pull-request runs

CI integrations should use the PR-aware command so Replay QA keeps the run under the pull request and supersedes any older in-flight revision before starting the replacement:

replayqa ci \
  --project proj_123 \
  --repository replayio/example \
  --pr-number 42 \
  --head-sha abc1234 \
  --branch feature/reminders \
  --workflow-run-id 123456789 \
  --prompt "Exercise the reminders flow"

The command cancels queued or running work for that PR, preserves its history, and creates the new version-backed run with GitHub metadata. A terminating CI job can explicitly clean up only its own revision with:

replayqa ci-cancel \
  --project proj_123 \
  --repository replayio/example \
  --pr-number 42 \
  --head-sha abc1234 \
  --branch feature/reminders \
  --workflow-run-id 123456789

Reverse proxy

Use proxy to connect a local or private app to an existing reverse-proxy-enabled Replay QA project. For a project that only has public environments, pass the local URL once; Replay QA creates its Local environment and enables reverse proxy automatically. In CI, add --ci to create Preview; the CI run's version provenance identifies the concrete pull request:

replayqa proxy --project proj_123
replayqa proxy --project proj_123 --target-url http://localhost:3000
replayqa proxy --project proj_123 --target-url http://localhost:3000 --ci
replayqa proxy --project proj_123 --allow localhost,.api.example.com,cdn.example.com

The command uses your Replay login, installs the compatible managed frpc when needed, starts an allowlisted local forward proxy, and reports health back to Replay QA so tests only start when the full local data path is reachable. It waits up to ten minutes for the tunnel hostname to resolve on the client before starting frpc, then exits with a stale-tunnel recovery message instead of waiting forever. If repeated login retries show a cached negative DNS result after the hostname has become resolvable, the supervisor replaces that stuck process.

Advanced users can opt out of the managed copy with REPLAYQA_FRPC_PATH=/path/to/frpc. doctor reports when that override is missing, not executable, or differs from the pinned server version.

Diagnostics

replayqa doctor checks Node compatibility, Replay authentication, writable local storage, the managed/overridden frpc, the built-in forward proxy, the latest tunnel hostname, and recognizable DNS/authentication/connection errors in the most recent proxy log. Limit log/config inspection to a project with replayqa doctor --project proj_123; add --json for automation. Doctor is read-only with respect to managed dependencies unless --fix is passed (the shared auth helper may refresh an expired Replay login while checking it).

Local app with service emulation

run can place a stable, CLI-owned HTTP/WebSocket wrapper in front of any existing development server. It also supervises the app, optional target-configured emulate services, and the Replay QA proxy as one process:

replayqa run http://localhost:3000 \
  --upstream-url http://127.0.0.1:5173 \
  --app-command "npm run dev -- --host 0.0.0.0 --port 5173" \
  --project proj_123

The browser and FRPC use the stable target URL while the application's normal dev server stays on the upstream URL. This works with Next, Vite, Remix, and other HTTP/WebSocket development servers without adding a wrapper to the application. The upstream must already serve every frontend and API route the target needs; the generic wrapper does not create a backend for a frontend-only server.

run resolves an existing project from --project, REPLAY_QA_PROJECT_ID, or .replay/config.json. It does not create one implicitly. Use replayqa bootstrap or explicitly pass --create-project when project creation is intended.

Optional durable, target-owned setup can live in a manifest:

{
  "qa-project-id": "proj_123",
  "target-url": "http://localhost:3000",
  "upstream-url": "http://127.0.0.1:5173",
  "app-command": "npm run dev -- --host 0.0.0.0 --port 5173",
  "proxy": { "allow": [], "local-port": 8888 }
}

Targets that use emulated dependencies can add their own emulator configuration:

{
  "qa-project-id": "proj_123",
  "target-url": "http://localhost:3000",
  "upstream-url": "http://127.0.0.1:3001",
  "app-command": "npm run dev -- --host 0.0.0.0 --port 3001",
  "emulate": {
    "services": ["auth0", "stripe"],
    "port": 4000,
    "package": "[email protected]",
    "setup-command": "npm run setup:emulate",
    "seed": { "auth0": {}, "stripe": {} },
    "env": { "VITE_AUTH0_DOMAIN": "http://127.0.0.1:4000" }
  },
  "proxy": { "allow": ["localhost"], "local-port": 8888 }
}

Emulator URLs and any additional browser-reachable hosts are target configuration. Applications must read their endpoint override variables; the CLI cannot redirect SDKs that hardcode production hosts. Targets that use a checked-in emulator package can set emulate.setup-command; Replay QA runs it before launching the configured package, so a clean checkout does not depend on prebuilt submodule artifacts.

Releasing

Publishing happens automatically when a version tag is pushed:

npm version patch   # or minor / major
git push --follow-tags

The publish workflow verifies the tag matches package.json, runs typecheck + tests + build, then publishes to npm via trusted publishing (OIDC), so there are no npm tokens to manage or rotate.