Use the BugMojo CLI to reproduce and verify fixes
Turn a captured bug into a runnable Playwright repro, verify the fix against a real deploy, and brief your AI agent from your terminal or CI.
bugmojo repro <bug-key> # pull + write the Playwright spec, logs, localization
bugmojo verify <bug-key> --url URL # run the repro locally; exit 0 pass / 1 fail
bugmojo fix <bug-key> # print an agent-ready prompt to paste into an AI IDE
bugmojo run [playwright args] # run your Playwright suite, record results + evidence
bugmojo init # teach every coding agent in this repo about BugMojoPackage: @bugmojo/cli on npm (live once the package is published) · Full reference: the README on GitHub.
Install
# run it ad hoc, no install
npx @bugmojo/cli --help
# or add it to a project
pnpm add -D @bugmojo/cli
# or: npm install --save-dev @bugmojo/cli
# or: yarn add -D @bugmojo/cliThe CLI needs Node 20 or newer and ships native ES modules. The examples below use the bugmojo command from an installed package. To run one ad hoc, use npx @bugmojo/cli <command> instead. Only verify needs a browser: @playwright/test is an optional peer dependency, so install it in the project you run verify from.
pnpm add -D @playwright/test
npx playwright install chromiumSet your API key
The CLI reads its configuration from the environment. repro, verify, fix and run need an API key starting with bm_key_. Create one in the BugMojo dashboard under Settings → API Keys. init never needs a key.
export BUGMOJO_API_TOKEN="bm_key_xxxxxxxxxxxxxxxxxxxx"| Variable | Required | What it does |
|---|---|---|
BUGMOJO_API_TOKEN | repro, verify, fix, run | A bm_key_… API key from Settings → API Keys, sent as a Bearer token. |
BUGMOJO_API_URL | no | BugMojo base URL. Defaults to https://www.bugmojo.com. Set your self-hosted URL, or http://localhost:3000 for local development. |
BUGMOJO_CI_SECRET | only for --report | Shared secret for the CI verify webhook. It must match the deployment's CI secret. |
You can also pass --token and --api-url as flags.
Pull a repro for a bug
bugmojo repro WEB-42 # → ./bugmojo-repro/WEB-42/
bugmojo repro WEB-42 --out ./repros # custom directory
bugmojo repro WEB-42 --json # print the raw pack to stdout instead
bugmojo repro WEB-42 --force # overwrite an existing directoryPass the bug key, such as WEB-42. repro writes a self-contained, runnable directory:
| File | Contents |
|---|---|
<slug>.spec.ts | The executable @playwright/test spec. |
logs.md | Console and network signals, errors first. |
localization.md | The React component and candidate source files for the fix. |
pack.json | The raw repro pack, machine-readable. |
README.md | How to run it. |
Brief your AI agent
fix prints an agent-ready prompt (the goal, the localization, the error signals and the failing spec) to paste into Claude Code or Cursor.
bugmojo fix WEB-42 # to stdout
bugmojo fix WEB-42 --out prompt.md # to a file
bugmojo fix WEB-42 | pbcopy # clipboard — macOS
bugmojo fix WEB-42 | clip # clipboard — Windows (cmd)
bugmojo fix WEB-42 | Set-Clipboard # clipboard — Windows (PowerShell)
bugmojo fix WEB-42 | xclip -sel clipboard # clipboard — Linux (X11; Wayland: wl-copy)Verify the fix
verify runs the bug's repro spec with your own @playwright/test install against --url, which becomes Playwright's baseURL. It exits 0 on a pass and 1 on a fail, so CI can gate a merge on it.
bugmojo verify WEB-42 --url https://preview.example.com
bugmojo verify WEB-42 --url https://preview.example.com --json # machine output
bugmojo verify WEB-42 --url https://preview.example.com --report # POST result to CIWith --report and BUGMOJO_CI_SECRET set, the result goes to BugMojo's CI verify webhook. A pass moves the bug from DEV_TESTING to VERIFIED_FIXED, and a fail moves it to REOPENED. Add --keep to keep the temp Playwright project for debugging.
Record your Playwright suite
bugmojo run runs your project's Playwright suite and records the results in BugMojo, so a test run is never just a claim in a chat window. Everything after -- is passed to Playwright. The exit code always reflects Playwright's own result, and recording problems are printed as warnings.
bugmojo run # whole suite, LOCAL runner
bugmojo run --url https://preview.example.com # sets PLAYWRIGHT_BASE_URL + deploy_url
bugmojo run --project WEB --plan-version pv_1 # bind the run to a plan version
bugmojo run --dry-run # run, print the payload, send nothing
bugmojo run -- --grep @smoke --workers=2 # everything after -- goes to playwrightEach test maps to a BugMojo test case by the first of these that matches: a bugmojo annotation (test.info().annotations.push({ type: 'bugmojo', description: 'WEB-42' })), a title tag such as [WEB-42] or @WEB-42, or the spec file name, such as tests/bugmojo/WEB-42.spec.ts. If playwright.config.* already lists @bugmojo/playwright-reporter, run leaves recording to the reporter. See record Playwright runs with the reporter.
Teach your coding agents with init
bugmojo init writes a managed block, between <!-- bugmojo:start --> and <!-- bugmojo:end -->, into each file your coding agents read. It also adds @bugmojo/playwright-reporter to playwright.config.*, with trace and video set to retain-on-failure and screenshot to only-on-failure. If the project depends on @playwright/test but has no config yet, it creates one from a template.
| File | Read by |
|---|---|
AGENTS.md | Codex, Cursor, Copilot, Gemini, Windsurf |
CLAUDE.md | Claude Code |
.github/copilot-instructions.md | GitHub Copilot |
.cursor/rules/bugmojo.mdc | Cursor (a rule with frontmatter) |
GEMINI.md | Gemini CLI |
bugmojo init # all files, hosted MCP URL
bugmojo init --workspace acme --project WEB # pin the workspace, mention the project key
bugmojo init --only claude,playwright # a subset of targets
bugmojo init --dry-run # show what would changeinit is idempotent: a second run reports unchanged. It preserves everything outside the markers, runs offline with no API token, and finishes by printing the connect and login command for the coding agent it detects. Pass --client to choose the client yourself.
Verify fixes in CI
name: Verify bug fix
on:
workflow_dispatch:
inputs:
bug_key:
description: "BugMojo bug key (e.g. WEB-42)"
required: true
preview_url:
description: "Deployed preview URL"
required: true
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm install @bugmojo/cli @playwright/test
- run: npx playwright install --with-deps chromium
- run: npx bugmojo verify "${{ inputs.bug_key }}" --url "${{ inputs.preview_url }}" --report
env:
BUGMOJO_API_TOKEN: ${{ secrets.BUGMOJO_API_TOKEN }}
BUGMOJO_CI_SECRET: ${{ secrets.BUGMOJO_CI_SECRET }}The job fails when the repro fails (exit 1), and --report updates the bug's status in BugMojo either way.
| Exit code | Meaning |
|---|---|
0 | Success, or the repro passed for verify. |
1 | Runtime failure, or the repro failed for verify. |
2 | Usage error: a missing bug key or an unknown command. |
How the CLI keeps secrets safe
Configuration is environment-only, so no secret is ever written to disk or embedded in output. The server-provided spec runs in a temporary project with a minimal, allow-listed environment, and BUGMOJO_API_TOKEN and BUGMOJO_CI_SECRET are never forwarded to the spec process.
Common questions
What does a "Missing API token" error mean?
Set BUGMOJO_API_TOKEN to a key from Settings → API Keys in your BugMojo dashboard, or pass --token. Keys must start with bm_key_.
Why does verify say @playwright/test is not installed?
verify uses the Playwright install of the directory you run it from. Add @playwright/test as a dev dependency there, then run npx playwright install chromium. repro and fix never need a browser.
Why does verify report "No tests executed (all skipped)"?
A skipped or empty run is treated as a failure on purpose, so a repro that never ran cannot mark a bug verified. Inspect the temp project with --keep, and make sure --url points at a reachable build.
What does "The repro pack response is missing a script" mean?
The bug has no session recording to compile into a repro. Capture the bug with the BugMojo browser extension, which records the session, and try again.
Can I point the CLI at a self-hosted or local BugMojo?
Yes. Set BUGMOJO_API_URL to your deployment's base URL, for example http://localhost:3000 for local development. The default is the hosted instance at https://www.bugmojo.com.
Related articles
- Record Playwright runs with the reporterThree lines in playwright.config.ts and two environment variables turn every test run you already do into recorded, provable results.
- The evidence-gated merge checkA GitHub check that maps a pull request's changed files to the test cases behind them, and asks whether they passed with evidence on this commit.
- Install BugMojo in Claude CodeInstall the plugin, finish the browser login, and get nine skills, four subagents and three hooks inside your terminal.
- How AI agents work with BugMojoUnderstand the full loop, from a captured bug to an agent-proposed fix that a human verifies and closes.
- Install the React SDK for React and Next.jsAdd @bugmojo/react to mount the BugMojo widget, catch render errors with their component stack, and file bugs straight from your code.