> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/integrations/cli.md).

# 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](/integrations/typescript-sdk.md) when you are building a Node.js or TypeScript integration. Use [Public API](/integrations/public-api.md) when you need direct HTTP API control.

{% embed url="<https://www.npmjs.com/package/@bugbug-io/cli>" %}

## Requirements

You need:

* [Node.js](https://nodejs.org/en/download/) version **24 or newer**
* npm
* a BugBug account
* access to the BugBug project you want to run

## Install via NPM

Install the CLI globally:

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

Or run it without global installation:

```bash
npx @bugbug-io/cli --help
```

## User auth path

For local development, the preferred way to authenticate is OAuth login in the browser:

```bash
bugbug login
```

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:

```bash
bugbug logout
```

### 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:

1. Go to the **Integrations** page.
2. Open the **CLI** tab.
3. Copy the project API token.

Then provide it with a command-line option:

```bash
bugbug --token <api-token> tests list
```

```bash
export BUGBUG_API_TOKEN=<api-token>
```

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:

```bash
bugbug init
```

or

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

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.

1. Open the test or suite in BugBug.
2. Open the menu.
3. Select **Run via CLI or webhook**.
4. Copy the test ID or suite ID.

You can also list tests and suites from the terminal:

```bash
bugbug tests list
bugbug suites list
```

Filter by name:

```bash
bugbug tests list --search "login"
bugbug suites list --search "checkout"
```

## Run tests from terminal

Run a test:

```bash
bugbug tests run <test-id>
```

Run a suite:

```bash
bugbug suites run <suite-id>
```

By default, the CLI waits for the run to finish. To queue the run and exit immediately:

```bash
bugbug tests run <test-id> --no-wait
bugbug suites run <suite-id> --no-wait
```

Run with a profile:

```bash
bugbug tests run <test-id> --profile "Staging"
bugbug suites run <suite-id> --profile "Production"
```

Override [variables](/editing-tests/variables.md) for a single run:

```bash
bugbug tests run <test-id> --variable username=test@example.com --variable plan=pro
```

Generate a JUnit report:

```bash
bugbug tests run <test-id> --reporter junit --output-path report.xml
bugbug suites run <suite-id> --reporter junit --output-path report.xml
```

## Work with existing runs

Show a test run result:

```bash
bugbug testruns show <run-id>
```

Get test run logs:

```bash
bugbug testruns logs <run-id>
```

Stop a running test:

```bash
bugbug testruns stop <run-id>
```

Download a JUnit report for an existing test run:

```bash
bugbug testruns report <run-id> -o report.xml
```

For suite runs:

```bash
bugbug suiteruns show <run-id>
bugbug suiteruns stop <run-id>
bugbug suiteruns report <run-id> -o report.xml
```

## Export and import

Export the whole project:

```bash
bugbug project export
bugbug project export -o bugbug-project.zip
```

Import a project export:

```bash
bugbug project import bugbug-project.zip
```

Export a single test:

```bash
bugbug tests export <test-id> --format yaml
bugbug tests export <test-id> --format zip -o test.zip
```

Import a test:

```bash
bugbug tests import test.yaml
bugbug tests import test.zip
```

{% hint style="warning" %}
Import commands change BugBug project data. Review exported or generated files before importing them.
{% endhint %}

## 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:

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

When the run fails, the command exits with an error so your build can fail.

## Use CLI with AI agents

BugBug CLI can also install BugBug Plugin for supported AI clients. BugBug Plugin installs [BugBug MCP](/ai-testing/mcp.md) and [BugBug Skills](/ai-testing/skills.md).

Install into one supported AI client. The `--agent` option is required:

```bash
npx @bugbug-io/cli plugin --agent=cursor
```

Read more: [BugBug Plugin](/ai-testing/plugin.md).

## 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`  | 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:

```bash
bugbug <command> --help
```

Common commands:

| Command                            | Description                                                                     |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| `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:

| Command                        | Description                     |
| ------------------------------ | ------------------------------- |
| `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

| Option                         | Description                                                                |
| ------------------------------ | -------------------------------------------------------------------------- |
| `-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.                                                                 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bugbug.io/integrations/cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.