BugBug CLI

Requirements

• Node.js v24 or higher
• BugBug account or API token

Install the CLI

npm install -g @bugbug-io/cli
bugbug --help

Or run it without a global install:

npx @bugbug-io/cli --help

CLI and MCP access require a BugBug Pro plan or higher. The bundled BugBug skills are available on all plans.

Sign in and run your first test

bugbug login
bugbug tests run <testId>

bugbug login opens a browser and stores CLI credentials. For CI or scripted use, provide an API token with --token or BUGBUG_API_TOKEN.

Link a repo to a BugBug project

Run bugbug init inside your repository to pin that directory to one BugBug project:

bugbug init

Interactively it asks how to authenticate - browser login, or a pasted project or organization API token - and then lets you pick the project to link. The authentication step is skipped if you already ran bugbug login. In CI or any non-interactive shell, pass both values instead:

bugbug --token <api-token> --project-id <project-id> init

bugbug project init is the same command.

Init writes projectId into a bugbug.yaml in the current directory and stores the token separately in the global config at ~/.bugbug/config.yaml, keyed by that project. Commands run from that directory - or any subdirectory - then resolve the project and token on their own, so bugbug tests list needs no flags. bugbug.yaml is safe to commit; the token is never written to it.

Environment Variables

| Variable | Description | | ------------------- | --------------------------------------------------------------------- | | BUGBUG_API_TOKEN | API token used to authenticate requests | | BUGBUG_PROJECT_ID | Project ID (required for organization tokens in non-interactive mode) | | BUGBUG_LOG_LEVEL | Log level; set to debug to enable verbose logging | | BUGBUG_TELEMETRY | Set to false to disable telemetry | | DO_NOT_TRACK | Standard opt-out; set to 1/true to disable telemetry | | CI | When true, forces plain (non-interactive) output |

Commands

Run bugbug with no arguments for the interactive navigator, or bugbug <command> --help for details on any command.

Auth

bugbug login          # Authenticate and store a user token in the global config
bugbug logout         # Clear the stored user token and current project

Project

bugbug init                       # Create bugbug.yaml pinning this directory to a project
bugbug project export             # Export project as a ZIP (bugbug-project-export-<timestamp>.zip)
bugbug project export -o out.zip  # Export to a specific file
bugbug project import out.zip     # Import a project from a ZIP archive

Tests

bugbug tests list                 # List tests
bugbug tests list -s "login"      # Filter tests by name
bugbug tests show <testId>         # Show test details
bugbug tests run <testId>          # Run a test (waits for completion by default)
bugbug tests run <testId> --profile "Production"
bugbug tests run <testId> --variable FOO=bar --variable BAZ=qux
bugbug tests run <testId> --no-wait        # Queue the run and exit immediately
bugbug tests run <testId> --reporter junit --output-path report.xml
bugbug tests export <testId> --format yaml
bugbug tests export <testId> --format zip -o test.zip
bugbug tests import test.yaml             # Import a test from YAML or ZIP

Test Runs

bugbug testruns show <runId>               # Show the result of a test run
bugbug testruns logs <runId>               # Get logs for a test run
bugbug testruns stop <runId>               # Stop a running test run
bugbug testruns report <runId> -o out.xml  # Get the JUnit XML report

Suites

bugbug suites list                # List suites
bugbug suites list -s "checkout"  # Filter suites by name
bugbug suites show <suiteId>       # Show suite details
bugbug suites run <suiteId>        # Run a suite (waits for completion by default)
bugbug suites run <suiteId> --profile "Production" --variable FOO=bar
bugbug suites run <suiteId> --no-wait

Suite Runs

bugbug suiteruns show <runId>              # Show the result of a suite run
bugbug suiteruns stop <runId>              # Stop a running suite run
bugbug suiteruns report <runId> -o out.xml # Get the JUnit XML report

Profiles

bugbug profiles list              # List run profiles

AI Clients (plugin: MCP + Skills)

bugbug plugin --agent=<agent>
bugbug plugin --agent=<agent> --dry-run  # Show what would be installed, writing nothing

Supported --agent values: cursor, claude, vscode, codex, copilot.

Shorthands

Verb-first shorthands map onto the namespaced commands above:

bugbug run test <testId>
bugbug run suite <suiteId>
bugbug list test
bugbug list suite
bugbug list profile
bugbug stop test <runId>
bugbug stop suite <runId>
bugbug report test <runId>
bugbug report suite <runId>
bugbug logs test <runId>
bugbug export project
bugbug export test <testId>
bugbug import project export.zip
bugbug import test test.yaml

Global Options

• -t, --token <token>: API token for BugBug (overrides config)
• -p, --project-id <projectId>: Project ID (required only for organization tokens in non-interactive mode)
• -v, --verbose: Enable verbose logging including HTTP requests
• --ci: CI-friendly output (plain logs, no interactive UI, exit 1 on failure)
• --json: Emit JSON output (implies non-interactive)
• --disable-telemetry: Disable telemetry
• -h, --help: Show help information

License

MIT