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.
For self-hosted MCP clients, see bearer token setup.
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 settings # Read project settings
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> --tag smoke --tag critical
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 tags set <testId> --tag smoke # Replace test tags by name
bugbug tests tags set <testId> # Clear test tags
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 (--folder-id <id> to choose a test folder)
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
bugbug testruns tags set <runId> --tag flaky
bugbug testruns tags set <runId> # Clear directly assigned run tags
bugbug testruns notes set <runId> "Retried successfully"
bugbug testruns notes set <runId> # Clear run notes
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> --tag smoke
bugbug suites run <suiteId> --no-wait
bugbug suites tags set <suiteId> --tag regression
bugbug suites tags set <suiteId> # Clear suite tags
Suite Runs
bugbug suiteruns show <runId> # Show the result of a suite run (--compact: failed tests only)
bugbug suiteruns stop <runId> # Stop a running suite run
bugbug suiteruns report <runId> -o out.xml # Get the JUnit XML report
bugbug suiteruns tags set <runId> --tag nightly
bugbug suiteruns tags set <runId> # Clear directly assigned run tags
bugbug suiteruns notes set <runId> "Nightly follow-up"
bugbug suiteruns notes set <runId> # Clear run notes
Profiles
bugbug profiles list # List run profiles
Tags
bugbug tags list # List tags in the active project
bugbug --json tags list # Emit tag details as JSON
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