CLI

The BugBug CLI (@bugbug-io/cli) runs and manages BugBug tests from the terminal. Use it to run tests or suites in CI/CD pipelines, download JUnit reports, export and import tests and projects, and install BugBug for AI agents.

Use the CLI when you want ready-made commands. Use the TypeScript SDK to build a Node.js or TypeScript integration, and the Public API for direct HTTP calls.

Quick facts

• Package: @bugbug-io/cli, command: bugbug.

• Requires Node.js 24 or newer and a Pro plan or higher.

• Sign in with bugbug login locally, or use the project API token (BUGBUG_API_TOKEN) in CI.

• bugbug tests run <test-id> and bugbug suites run <suite-id> wait for the result and exit with 0 only when the run passed.

• Runs happen in the BugBug cloud.

https://www.npmjs.com/package/@bugbug-io/cliwww.npmjs.com

Install

You need Node.js 24 or newer and npm 11 or newer.

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

Or run it without a global install:

npx @bugbug-io/cli --help

Sign in

On your own machine: browser login

bugbug login

This opens BugBug in the browser and stores a user token in ~/.bugbug/config.yaml. You don't need to copy a token by hand. bugbug logout removes it.

In CI and scripts: project API token

Use the project API token wherever a browser login isn't possible: CI/CD, shared runners, scripts.

1. Open your project in BugBug.

2. Go to Integrations → API Token.

3. Copy the API Token.

The Integrations → CLI tab shows the same token inside a complete command you can copy.

Pass it in an environment variable, which is the usual way in CI:

export BUGBUG_API_TOKEN=<api-token>
bugbug tests list

or as an option:

bugbug --token <api-token> tests list

The token belongs to one project, so commands run with it always work on that project.

Treat the token like a password. Keep it in your CI's secret store, and don't commit it to the repository, including in .env or bugbug.yaml.

Link a directory to a project

Run bugbug init in your repository to pin it to one BugBug project:

bugbug init

In a non-interactive shell, pass the token and the project ID:

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

init writes the project ID to bugbug.yaml in the current directory and stores the token separately in ~/.bugbug/config.yaml. Commands run from that directory or its subdirectories then use that project.

Find a test or suite ID

In the app, open the test or suite, open its menu and choose Run via CLI or webhook. Or list them in the terminal:

bugbug tests list
bugbug suites list --search "checkout"

bugbug tests show <test-id> and bugbug suites show <suite-id> print the details of one item.

Run tests and suites

bugbug tests run <test-id>
bugbug suites run <suite-id>

The run starts in the cloud. The CLI prints the run ID, shows status changes, and waits for the final result.

Option	What it does
-p, --profile <name>	Run with this profile, by name. Without it, the default profile is used.
--variable <key=value>	Override a variable for this run only. Repeatable. The variable must already exist in the project.
--tag <name>	Assign a tag to the run. Repeatable. Missing tags are created.
--reporter junit	Save a JUnit report when the run ends. The default reporter, inline, prints the result in the terminal.
--output-path <path>	Where to save the JUnit report. Only with --reporter junit. Default: bugbug-test-<run-id>-junit.xml or bugbug-suite-<run-id>-junit.xml.
--timeout <minutes>	How long to wait for the result. Default: 5 minutes for a test, 10 minutes for a suite.
--no-wait	Start the run and exit right away, without waiting for the result.

bugbug suites run <suite-id> \
  --profile "Staging" \
  --variable email=[e-mail] \
  --tag "release-2.4" \
  --reporter junit --output-path reports/bugbug.xml \
  --timeout 30

If the run takes longer than --timeout, the CLI stops waiting and exits with an error, but the run keeps going in the cloud. For long suites, set --timeout to more than the suite usually takes.

Exit codes

Code	Meaning
0	The run passed.
2	The run failed.
3	The run was stopped.
1	Any other result or error: the run ended with an error, the wait timed out, authentication failed, or the command was invalid.

Any code other than 0 fails a CI step, so the build fails when a test fails.

Run in CI/CD

npm install -g @bugbug-io/cli
bugbug --ci suites run <suite-id> --reporter junit --output-path report.xml

• Store the project API token as a secret named BUGBUG_API_TOKEN. Don't use bugbug login in CI.

• --ci gives plain, non-interactive output. It's on automatically when the CI environment variable is true, which most CI services set.

• Use --json to get machine-readable output instead.

• Publish report.xml with your CI's JUnit test report step.

Work with existing runs

bugbug testruns show <run-id>             # result of a test run
bugbug testruns logs <run-id>             # logs of a test run
bugbug testruns stop <run-id>
bugbug testruns report <run-id> -o report.xml   # JUnit; printed to stdout without -o

bugbug suiteruns show <run-id>            # result of a suite run
bugbug suiteruns show <run-id> --compact  # totals and only the failed tests
bugbug suiteruns stop <run-id>
bugbug suiteruns report <run-id> -o report.xml

testruns show and suiteruns show also accept --reporter junit --output-path <path>.

Tags and notes

bugbug tests tags set <test-id> --tag flaky --tag draft
bugbug suites tags set <suite-id> --tag nightly
bugbug testruns tags set <run-id> --tag "Version:1.23"
bugbug suiteruns tags set <run-id> --tag "Version:1.23"

tags set replaces the current tags. Leave out --tag to clear them. See Tags.

bugbug testruns notes set <run-id> "Failed after the staging deployment"
bugbug suiteruns notes set <run-id> "Nightly smoke run"
bugbug testruns notes set <run-id>        # clears the note

Export and import

bugbug tests export <test-id>                        # YAML, saved as bugbug-test-<test-id>.yaml
bugbug tests export <test-id> --format zip -o test.zip
bugbug project export -o bugbug-project.zip

bugbug tests import test.yaml --conflict-mode overwrite
bugbug tests import test.zip --folder-id <folder-id>
bugbug project import bugbug-project.zip

Option	What it does
--conflict-mode overwrite	If a test or component with the same slug already exists, update it.
--conflict-mode skip	If it already exists, leave it unchanged.
--folder-id <id>	Put the imported test in this test folder. Overrides the folder recorded in a ZIP.

• Without --conflict-mode, a test whose slug already exists isn't imported. Always set it in scripts.

• The file must end in .yaml, .yml or .zip.

• project import always creates a new project.

For the file format, ZIP layout and how slugs match existing items, see YAML schema and Importing.

Import changes project data. Review exported or generated files before you import them.

Use the 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:

npx @bugbug-io/cli plugin --agent=<agent>

Supported --agent values are cursor, claude, vscode, codex and copilot. Add --dry-run to see what would be installed without writing files. The plugin installer has no --token option: the AI client signs in to BugBug MCP on its own.

Read more: BugBug Plugin.

Configuration

The CLI looks for the token and project in this order, and uses the first value it finds:

1. Command-line options: --token, --project-id.

2. Environment variables: BUGBUG_API_TOKEN, BUGBUG_PROJECT_ID.

3. bugbug.yaml in the current directory or a parent directory.

4. .env in the current directory or a parent directory.

5. The global config ~/.bugbug/config.yaml, written by bugbug login and bugbug init.

Environment variable	Description
BUGBUG_API_TOKEN	API token used to authenticate.
BUGBUG_PROJECT_ID	Project ID. Needed with a user token from bugbug login when no project is linked or selected.
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.

Global options

Option	Description
-t, --token <token>	API token. Overrides every other source.
-p, --project-id <projectId>	Project ID, when the token isn't tied to one project.
-v, --verbose	Verbose output, including HTTP requests.
--ci	Plain, non-interactive output for CI.
--json	JSON output.
--disable-telemetry	Disable telemetry.
-h, --help	Show help. Works on every command: bugbug tests run --help.

All commands

Run bugbug without arguments in a terminal to open the interactive navigator.

Command	Description
bugbug login / bugbug logout	Sign in with the browser / remove the stored login.
bugbug init	Link the current directory to a project.
bugbug tests list / show <test-id>	List tests / show one test.
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 tests tags set <test-id>	Replace a test's tags.
bugbug suites list / show <suite-id>	List suites / show one suite.
bugbug suites run <suite-id>	Run a suite.
bugbug suites tags set <suite-id>	Replace a suite's tags.
bugbug testruns show/logs/stop/report <run-id>	Show, get logs, stop, or download the JUnit report of a test run.
bugbug testruns tags set / notes set <run-id>	Set a test run's tags / note.
bugbug suiteruns show/stop/report <run-id>	Show, stop, or download the JUnit report of a suite run.
bugbug suiteruns tags set / notes set <run-id>	Set a suite run's tags / note.
bugbug profiles list	List run profiles.
bugbug tags list	List project tags with colors and usage counts.
bugbug project settings	Show project settings.
bugbug project export / import <file>	Export the project as ZIP / import a project ZIP.
bugbug plugin	Install the BugBug Plugin for AI agents.

Shorthands:

Shorthand	Same as
bugbug run test <id> / run suite <id>	tests run / suites run
bugbug list test / suite / profile	tests list / suites list / profiles list
bugbug stop test <run-id> / stop suite <run-id>	testruns stop / suiteruns stop
bugbug logs test <run-id>	testruns logs
bugbug export test <id> / export project	tests export / project export
bugbug import test <file> / import project <file>	tests import / project import

FAQ

Where do I find the API token for the CLI, and is it per project or per user?

In Integrations → API Token in your project. The Integrations → CLI tab shows it inside a ready-to-copy command. It belongs to the project, not to a user. On your own machine you can skip it and use bugbug login, which stores a user token instead.

I used bugbug config set-token and bugbug remote run. What's the equivalent now?

Those commands come from @testrevolution/bugbug-cli, which is deprecated. Install @bugbug-io/cli instead. The equivalents are:

• bugbug config set-token <token> → bugbug login, bugbug init, or the BUGBUG_API_TOKEN variable.

• bugbug remote run test <id> → bugbug tests run <id>.

• bugbug remote run suite <id> → bugbug suites run <id>.

• --result-timeout <minutes> → --timeout <minutes>.

Why does my CI job stop waiting before the suite finishes?

By default the CLI waits 5 minutes for a test and 10 minutes for a suite. Set --timeout <minutes> to wait longer. The run itself keeps going in the cloud.

Which plan do I need for the CLI?

Pro or higher.

How do I import a test that already exists in the project?

Add --conflict-mode overwrite to update the existing test, or --conflict-mode skip to leave it unchanged. BugBug matches tests and components by slug. See Importing.