CLI
Integrate with CI/CD using BugBug Command Line Interface
You can operate BugBug from the terminal with BugBug Command Line Interface (CLI). Use it to run tests or suites from CI/CD pipelines, export or import projects, download reports, and configure BugBug for AI agents.
Use CLI when you want ready-made terminal commands. Use TypeScript SDK when you are building a Node.js or TypeScript integration. Use Public API when you need direct HTTP API control.
Requirements
BugBug CLI requires a Pro or higher BugBug plan.
You need:
Node.js version 24 or newer
npm
a BugBug account
access to the BugBug project you want to run
Install via NPM
Install the CLI globally:
Or run it without global installation:
User auth path
For local development, the preferred way to authenticate is OAuth login in the browser:
This opens BugBug in your browser and stores your user token in the global CLI config. Use this path on your own machine because you do not need to copy or manage a long-lived project token manually.
You can clear the stored login with:
Token auth path
You can also use a project API token. This is the recommended path for CI/CD, non-interactive scripts, shared runners, and other environments where browser OAuth login is not practical.
You will find the project API token in the BugBug web app:
Go to the Integrations page.
Open the CLI tab.
Copy the project API token.
Then provide it with a command-line option:
You can also add it to a local .env file or bugbug.yaml when that is easier for your workflow.
Remember: treat API tokens as secrets. Do not commit them to your repository.
Initialize a project directory
Run this in your project repository when you want linke the current directory with the BugBug project:
or
The command creates a local bugbug.yaml and stores credentials in the global BugBug config.
Find your test or suite ID
To run a specific test or suite, you need its ID.
Open the test or suite in BugBug.
Open the menu.
Select Run via CLI or webhook.
Copy the test ID or suite ID.
You can also list tests and suites from the terminal:
Filter by name:
Run tests from terminal
Run a test:
Run a suite:
By default, the CLI waits for the run to finish. To queue the run and exit immediately:
Run with a profile:
Override variables for a single run:
Generate a JUnit report:
Work with existing runs
Show a test run result:
Get test run logs:
Stop a running test:
Download a JUnit report for an existing test run:
For suite runs:
Export and import
Export the whole project:
Import a project export:
Export a single test:
Import a test:
Import commands change BugBug project data. Review exported or generated files before importing them.
Run tests from your build pipeline
Use a project API token for CI/CD. Store it as BUGBUG_API_TOKEN in your CI/CD secret manager, then install and run the CLI in your pipeline. Do not use browser OAuth login in CI jobs.
Example:
When the run fails, the command exits with an error so your build can fail.
Use CLI with AI agents
The BugBug Plugin is the recommended way to connect an AI coding agent to BugBug. It installs BugBug MCP and BugBug Skills together.
Install it for Cursor, for example:
Supported --agent values are cursor, claude, vscode, codex, and copilot. The plugin installer has no --token option: after installation, the selected AI client completes its own MCP OAuth sign-in flow.
Read more: BugBug Plugin.
Environment variables
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
Set to debug to enable verbose logs.
BUGBUG_TELEMETRY
Set to false to disable telemetry.
DO_NOT_TRACK
Set to 1 or true to disable telemetry.
CI
When true, forces plain non-interactive output.
Available commands
Run bugbug with no arguments for the interactive navigator, or run:
Common commands:
bugbug login
Authenticate and store a user token.
bugbug logout
Clear the stored user token and current project.
bugbug init
Create bugbug.yaml for the current directory.
bugbug tests list
List tests.
bugbug tests run <test-id>
Run a test.
bugbug tests export <test-id>
Export a test as YAML or ZIP.
bugbug tests import <file>
Import a test from YAML or ZIP.
bugbug suites list
List suites.
bugbug suites run <suite-id>
Run a suite.
bugbug testruns show <run-id>
Show test run details.
bugbug testruns logs <run-id>
Get test run logs.
bugbug testruns stop <run-id>
Stop a test run.
bugbug testruns report <run-id>
Download a JUnit report for a test run.
bugbug suiteruns show <run-id>
Show suite run details.
bugbug suiteruns stop <run-id>
Stop a suite run.
bugbug suiteruns report <run-id>
Download a JUnit report for a suite run.
bugbug profiles list
List run profiles.
bugbug project export
Export project data as ZIP.
bugbug project import <file>
Import a project ZIP.
bugbug plugin
Install BugBug Plugin, BugBug MCP, and BugBug Skills into supported AI clients.
Shorthand commands are also available:
bugbug run test <test-id>
Run a test.
bugbug run suite <suite-id>
Run a suite.
bugbug list test
List tests.
bugbug list suite
List suites.
bugbug list profile
List run profiles.
bugbug stop test <run-id>
Stop a test run.
bugbug stop suite <run-id>
Stop a suite run.
bugbug logs test <run-id>
Get test run logs.
bugbug export project
Export project data as ZIP.
bugbug export test <test-id>
Export a test as YAML or ZIP.
bugbug import project <file>
Import a project ZIP.
bugbug import test <file>
Import a test from YAML or ZIP.
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 output, including HTTP request logs.
--ci
CI-friendly output.
--json
Emit JSON output.
--disable-telemetry
Disable telemetry.
-h, --help
Show help.
Last updated
Was this helpful?
