@bugmojo/cli

Turn a captured BugMojo bug into a runnable Playwright repro, verify the fix against a real deploy, and brief an AI agent — from your terminal or CI.

Why

BugMojo captures bugs with full context — an rrweb session recording, console logs, and network requests. This CLI closes the verified loop: it compiles that capture into an executable @playwright/test spec (via BugMojo's server-side repro compiler), runs it against your patched build, and reports the result — a bug is only verified fixed when its own repro passes. There is no BugMojo-hosted browser runner: your machine or CI runs the test, exactly like the rest of your suite.

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 BugMojo

Install

Run it ad-hoc with npx (no install):

npx @bugmojo/cli --help

…or add it to a project:

pnpm add -D @bugmojo/cli
npm  install --save-dev @bugmojo/cli
yarn add -D @bugmojo/cli

Only verify needs a browser. @playwright/test is an optional peer dependency — install it in the project you run verify from:

pnpm add -D @playwright/test
npx playwright install chromium

Quickstart

# 1. Get an API key: BugMojo Dashboard → Settings → API Keys (starts with bm_key_)
export BUGMOJO_API_TOKEN="bm_key_xxxxxxxxxxxxxxxxxxxx"

# 2. Pull the repro pack for a bug:
npx @bugmojo/cli repro WEB-42
#    → ./bugmojo-repro/WEB-42/  (spec, logs.md, localization.md, pack.json, README.md)

# 3. Hand the fix to your AI agent (Claude Code / Cursor):
npx @bugmojo/cli fix WEB-42 | pbcopy        # macOS  (Windows: | clip · Linux: | xclip -selection clipboard)

# 4. Verify the fix against a preview deploy and report it:
npx @bugmojo/cli verify WEB-42 --url https://preview.example.com --report
#    → PASSED ✓ → the bug flips DEV_TESTING → VERIFIED_FIXED

Features

• One-command repro — a self-contained, runnable @playwright/test project written to disk from a bug key.
• Real verification — the repro runs on your build with your Playwright install; exit 0/1 so CI can gate merges on it.
• CI status reporting — verify --report flips the bug DEV_TESTING → VERIFIED_FIXED (pass) or REOPENED (fail) via the CI verify webhook.
• Agent-ready prompts — fix renders goal + localization + error signals + the failing spec, ready to paste into Claude Code or Cursor.
• Secrets stay secret — config is env-only, and the server-provided spec runs in a temp project with a minimal allow-listed environment; BUGMOJO_API_TOKEN / BUGMOJO_CI_SECRET are never forwarded to the spec process.
• Embeddable — import { run } from '@bugmojo/cli' exposes the dispatcher and pure helpers with no side effects at import time.

Configuration (environment)

| Variable | Required | Description | | ------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- | | BUGMOJO_API_TOKEN | repro/verify/fix/run | A bm_key_… API key (Dashboard → Settings → API Keys). Sent as a Bearer token. init never needs it. | | BUGMOJO_API_URL | no | BugMojo base URL. Default https://www.bugmojo.com (hosted). 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 (must match the deployment's CI secret). |

No secret is ever written to disk or embedded in output — everything is read from the environment at runtime. You can also pass --token / --api-url as flags.

Commands

bugmojo repro <bug-key>

Pulls the repro pack for a bug and writes a self-contained repro directory.

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 directory

| Option | Description | | ----------------- | ----------------------------------------------------------------- | | -o, --out <dir> | Output directory (default ./bugmojo-repro/<bug-key>). | | --force | Overwrite existing files in the output dir. | | --json | Print the raw repro pack JSON to stdout instead of writing files. |

Writes:

| File | Contents | | ----------------- | ----------------------------------------------------- | | <slug>.spec.ts | The executable @playwright/test spec. | | logs.md | Errors-first console + network signals. | | localization.md | React component + candidate source files for the fix. | | pack.json | The raw repro pack (machine-readable). | | README.md | How to run it. |

bugmojo verify <bug-key> --url <deployed-url>

Runs the bug's repro spec locally with your @playwright/test install against --url (which becomes Playwright's baseURL). Prints pass/fail and exits 0 on pass, 1 on fail so CI can gate 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 CI

| Option | Description | | ----------------- | --------------------------------------------------------------------------- | | -u, --url <url> | Deployed URL to run the repro against (sets Playwright's baseURL). | | --report | POST the pass/fail result to the CI verify webhook (needs BUGMOJO_CI_SECRET). | | --keep | Keep the temp Playwright project dir (debugging). | | --json | Also print the raw run result as JSON. |

With --report (and BUGMOJO_CI_SECRET set) the result is POSTed to BugMojo's CI verify webhook, which flips the bug's status: DEV_TESTING → VERIFIED_FIXED on pass, DEV_TESTING → REOPENED on fail.

A skipped-only or empty run is not a pass — at least one test must actually execute and pass, so a bug is never marked verified by a repro that didn't run.

bugmojo fix <bug-key>

Prints an agent-ready prompt bundle — goal, localization, error signals, and the failing spec — ready to paste into Claude Code / 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)

| Option | Description | | ------------------ | ------------------------------------------- | | -o, --out <file> | Write the prompt to a file instead of stdout. |

bugmojo run [playwright args]

Runs your project's Playwright suite (playwright test, resolved from the current project) and records the results in BugMojo, so a test run is never just a claim in a chat window.

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 playwright

| Option | Description | | --------------------- | ---------------------------------------------------------------------------------------- | | -u, --url <url> | Base URL for the run (PLAYWRIGHT_BASE_URL); recorded as the run's deploy_url. | | --project <key> | BugMojo project key to record against. | | --suite <id> | Regression suite id to attach the run to. | | --plan-version <id> | Test plan version the run executes. | | --commit <sha> | Commit SHA (default: GITHUB_SHA / VERCEL_GIT_COMMIT_SHA / ..., then git rev-parse HEAD). | | --deploy-url <url> | Deploy URL recorded on the run (default: --url). | | --dry-run | Run the tests, print the payload, do not send it. | | --no-record | Run the tests, do not send results. | | --json | Also print the payload that was sent. |

How a test maps to a BugMojo test case (first match wins):

1. a Playwright annotation: test.info().annotations.push({ type: 'bugmojo', description: 'WEB-42' })
2. a title tag test('[WEB-42] double click does not duplicate', ...) or the tag @WEB-42
3. the spec file name: tests/bugmojo/WEB-42.spec.ts

When playwright.config.* already lists @bugmojo/playwright-reporter (see bugmojo init), run does not pass --reporter (a CLI reporter flag would replace yours and silence it) and lets the reporter record results and upload trace / video / screenshots itself. Otherwise run adds the JSON reporter, maps the report and POSTs it to POST /api/v1/test-runs/results. Recording problems are printed as warnings; the exit code always reflects Playwright's own result.

bugmojo init

Teaches every coding agent that opens this repository about BugMojo. Writes a managed block (<!-- bugmojo:start --> ... <!-- bugmojo:end -->) into:

| 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 (rule with frontmatter) | | GEMINI.md | Gemini CLI |

and adds ['@bugmojo/playwright-reporter'] plus trace: 'retain-on-failure', video: 'retain-on-failure', screenshot: 'only-on-failure' to playwright.config.* (created from a template when the project depends on @playwright/test but has no config yet).

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 change

| Option | Description | | -------------------- | ------------------------------------------------------------------------------ | | --workspace <slug> | Pin the hosted MCP URL to a workspace (?workspace=...). | | --project <key> | Mention the BugMojo project key in the block. | | --mcp-url <url> | Override the hosted MCP URL entirely. | | --api-url <url> | BugMojo base URL (default https://www.bugmojo.com). | | --only <list> | Comma list of agents,claude,copilot,cursor,gemini,playwright. | | --playwright | Create playwright.config.ts even if @playwright/test is not a dependency. | | --skip-playwright | Leave playwright.config.* alone. | | --client <name> | Force the printed next step for one client instead of detecting it: claude, codex, cursor, copilot, gemini, windsurf. | | --dry-run | Show what would change without writing. |

Guarantees:

• Idempotent. Running it twice produces byte-identical files; the second run reports unchanged for everything.
• Yours stays yours. Everything outside the markers is preserved verbatim (CRLF files stay CRLF). A newer block template replaces only the managed region. In playwright.config.* an existing trace / video / screenshot choice is respected; only missing keys are added.
• Offline. init needs no API token and never touches the network.
• Tells you what to do next. It detects which coding agent is running it (from the environment — CLAUDECODE, CURSOR_TRACE_ID, CODEX_SANDBOX, GEMINI_CLI, TERM_PROGRAM, ...) and prints the connect + login command for that client. --client <name> overrides the guess; when nothing matches it prints the neutral instructions, including the headless Authorization: Bearer bm_key_... path.

bugmojo help [command] / bugmojo version

help shows the top-level screen or one command's help (-h/--help work everywhere); version (or -v/--version) prints the CLI version.

CI: verify a fix on every preview deploy

# .github/workflows/verify-bug.yml
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 flips the bug's status in BugMojo either way.

API contract consumed

• GET /api/v1/bugs/{bug-key}/repro → { issue_id, bug_key, repro_pack } (auth: Authorization: Bearer $BUGMOJO_API_TOKEN). Backed server-side by the same compiler path as the get_repro_pack MCP tool. {bug-key} accepts the human key (WEB-42) or the raw issue id.
• POST /api/webhooks/ci (auth: X-CI-Secret: $BUGMOJO_CI_SECRET) — used by verify --report. Body: { bug_key, passed, proof_url? } (the --url you verified against is sent as the proof link).
• POST /api/v1/test-runs/results (auth: Bearer) — used by bugmojo run when @bugmojo/playwright-reporter is not configured. Body: the run-results payload (RecordRunResultsRequest: runner, commit, deploy URL, per-test status / duration / retries / error / attachments and the resolved test-case key). Reply: { run_id, url?, result_ids?, evidence_upload_slots? }.

ESM-only. The CLI requires Node >= 20 and ships native ES modules. The bugmojo bin works everywhere; programmatic consumers on CommonJS should use dynamic import('@bugmojo/cli') (or Node >= 20.19, where require(esm) works).

Exit codes

| Code | Meaning | | ---- | ------------------------------------------------ | | 0 | Success (or repro passed for verify). | | 1 | Runtime failure (or repro failed for verify). | | 2 | Usage error (missing bug key / unknown command). |

Troubleshooting / FAQ

"Missing API token" error. Set BUGMOJO_API_TOKEN to a bm_key_… key from your BugMojo dashboard (Settings → API Keys), or pass --token. Keys must start with bm_key_.

"@playwright/test is not installed in this project" when running verify. verify uses the Playwright install of the directory you run it from. Fix: pnpm add -D @playwright/test && npx playwright install chromium. repro and fix never need a browser.

verify reports "No tests executed (all skipped)". A skipped/empty run is deliberately treated as a failure — otherwise a repro that never ran could mark a bug verified. Check the spec (run with --keep to inspect the temp project) and make sure --url points at a reachable build.

I'm self-hosting BugMojo / developing locally. Set BUGMOJO_API_URL to your deployment's base URL (e.g. https://bugs.your-company.com or http://localhost:3000). The default is the hosted instance at https://www.bugmojo.com.

"The repro pack response is missing a script". 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.

Related packages

| Package | Use it for | | ------- | ---------- | | @bugmojo/widget | Framework-agnostic on-site feedback + capture widget core | | @bugmojo/react | React / Next.js SDK — provider, error boundary, hooks | | @bugmojo/react-native | React Native + Expo SDK — shake-to-report | | @bugmojo/mcp-server | Connect AI coding agents (Claude Code, Cursor) to BugMojo |

License

MIT © Softech Infra — docs & issues at viveksinra/bugmojo-sdk.