CLI reference

The bugmole and bm commands address the same CLI.

Install

npx bugmole --help          # run without installing
npm install -g bugmole      # or install once

The bugmole package installs @bugmole/cli, so npx @bugmole/cli … and npm install -g @bugmole/cli work the same. Installing downloads Chromium, Firefox, WebKit and ffmpeg for runs and videos; set BUGMOLE_SKIP_PLAYWRIGHT_INSTALL=true to skip that (CI skips it automatically), and add Edge with npx playwright install msedge.

Core workflow

bugmole --help lists every mode and flag, and bugmole init --help lists init's.

Options for every mode

Explore

bugmole --mode explore learns the app's screens and journeys from its source. When the source has no route files, as in an Express or plain Node app, pass --base-url <url> and it crawls the running app instead. It records what it finds in spec/journeys.graph.json.

Plan

bugmole --mode plan --journey-id <journey> --actor <role>

The plan is written to spec/plans/, and its ID is made from the journey's ID. For a web app, planning also writes a runnable flow for the journey to spec/flows/journeys/<plan>.yaml. That file is never overwritten, so edit it freely. A draft journey can be planned too; once a run of its plan passes, an agent marks the journey stable with bugmole_journey_stabilize and that run's ID (see Bugmole MCP). A run ID that doesn't exist, didn't pass or ran another journey is refused.

Planning needs no AI model key.

Run

Suite

bugmole --mode suite runs a folder of web flows against a running app.

The process exits 1 if any flow failed or was blocked.

Discover

bugmole --mode discover --base-url <url> --out <dir> clicks through a running app like a first-time visitor and writes a flow for every page and form.

Discovery fills and submits forms and presses buttons, marking everything it types and sends with a fingerprint it prints (and writes to discovery.json with every action it took); it never deletes, signs out, pays or sends anything to people, and lists those it left alone. --read-only makes it only look. It never follows a link that signs out or deletes. With --sign-in, exploration continues in the signed-in session, which is deleted afterwards. The sign-in flow is copied into the output folder as 00-sign-in.yaml, so it runs first, and discovery prints the command to run the flows with --share-session. --open-each-page suits apps whose navigation hides behind a menu on phones.

Serve

bugmole serve prints the dashboard handoff URL and opens it in the default browser. Use bugmole serve --no-open when the URL should only be printed. Open the whole URL, including everything after #: that part lets the dashboard read results kept on this machine and never reaches Bugmole's servers. Without it the dashboard says Waiting for your machine.

Before it takes any work, serve shows the account this folder's machine key belongs to (that's the email the dashboard link signs you in with) and the coding agent that gets approved tasks here, with whether it's installed and signed in. In a terminal it asks which agent to use when this machine hasn't chosen one, or when the chosen one can't run, and it offers to retry tasks that stopped earlier because the agent wasn't signed in. If the agent can't run, serve holds agent tasks rather than spending their attempts; sign the agent in and restart serve. To use this folder with a different account, run bugmole init --switch-account.

bugmole serve --approval manual|auto|extreme makes this worker stricter than the project's approval mode, never looser: it skips tasks its own mode would hold unless a person approved them. It sets BUGMOLE_APPROVAL, which the MCP server and the coding-agent driver in the same process follow too. With --local-registry, which runs a local stand-in for Bugmole's server so you can queue and run tasks without signing in, the same setting decides which finished tasks the stand-in holds for review (it holds none by default).

Coding agents

bugmole serve hands approved tasks (fixes, UI work, investigations) to a coding agent on your machine. bugmole agents shows which agents this machine has and which one gets the tasks:

bugmole agents
bugmole agents use claude

use takes cursor, claude, opencode, codex or simasis. Cursor, Claude Code, OpenCode and Codex run as the programs installed here (cursor-agent, claude, opencode, codex), signed in as you; Codex runs in its own workspace sandbox, so its changes stay in the project; if one isn't installed, use says how to install it. Simasis asks for a personal access token (--simasis-project <id> picks its project). The choice and the token are kept in .bugmole.env, which stays out of git. Restart bugmole serve after changing it. bugmole agents reset goes back to the project's choice.

This choice is for this machine only. To connect an agent for the whole workspace, with a stored credential that every worker uses, an owner or admin uses Manage → Coding agents on the dashboard.

Roles

bugmole roles lists the project's confirmed roles and the suggested ones waiting for a person. bugmole roles suggest <name> --evidence "route /admin" (optionally --description and --source role_gated_route) suggests one, and bugmole roles suggest --from-evidence suggests every role the journey graph, blockers and spec/roles.yaml point at. The CLI only suggests: a person confirms, renames or rejects each role under Settings → Roles, and only confirmed roles are planned for. Suggesting needs BUGMOLE_API_KEY. See Roles.

Proposing test-case changes

bugmole propose sends changes to a project's test cases for review, the same way an agent does with bugmole_propose_test_case:

{
  "caseSetId": "flow-checkout",
  "summary": "Checkout now asks for a phone number",
  "changes": [
    { "caseId": "TC-checkout", "action": "change", "case": { "title": "…", "nodeId": "screen:/checkout", "intent": "…", "steps": ["…"], "expected": ["…"], "confidence": "high", "basis": ["…"] } },
    { "caseId": "TC-guest-note", "action": "retire", "summary": "Guest notes were removed" }
  ]
}

Each change is add, change or retire. The file never names revision numbers: Bugmole reads which revision each change starts from. Every change is checked before any is sent. Once accepted, a change becomes the next revision and the one it replaces is marked obsolete. A project manager accepts or rejects proposals on the Tests page, unless the project's approval mode is Extreme.

Device onboarding

When a machine has no API key, initialization can start device onboarding:

bugmole init

The CLI prints a short-lived pairing code and opens the project registration page. The human code is not the machine credential. After the authorized claim completes, the generated key is written once to .bugmole.env as BUGMOLE_API_KEY.

Init options

bugmole init writes .bugmole/config.yaml and .bugmole.env, and adds .bugmole.env to .gitignore. The configuration it writes works without changes: no AI model key is needed, and with no runtime.env the environment is treated as staging.

Which app a project is

One app is one project. bugmole init finds the web or mobile app it's run in and identifies it by the repository's git remote (without any credentials in it) plus the app's folder; with no remote, a public --app-url identifies it by domain. If that app is already a project in a workspace you belong to, the machine joins that project and .bugmole/config.yaml takes its id.

bugmole serve reports the same identity when it starts. If the project is a different app, it says so; if the project is paused for inactivity, it prints the link to activate it.

Reset safety

bugmole reset is project-scoped and asks you to type a confirmation first; bugmole reset --yes skips that, for scripts and CI. It removes the project's runs, reports, progress, plans, journey graph, audits, saved sign-in sessions and the record of changes coding agents made. It keeps the project's registration, its configuration and your flows.