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

# CloudBeat CLI

Command line interface for CloudBeat - run tests from CI/CD pipelines, manage projects and deliver code

The CloudBeat CLI (`@cloudbeat/cli`) lets you use CloudBeat from a terminal, a CI/CD pipeline or an AI coding agent:

* [Running tests](/references/cloudbeat-cli/running-tests.md) - start a test case or suite, wait for it to finish, and get a JUnit XML report.
* [Projects and code delivery](/references/cloudbeat-cli/projects-and-code-delivery.md) - create projects, synchronize them with Git, upload code, and install the [AI-assisted setup wizard](/get-started/ai-assisted-project-setup.md).

## Installation

Node.js 18 or newer is required.

```bash
npm install -g @cloudbeat/cli
```

Without a global installation, every command can also be run with `npx @cloudbeat/cli <command>`.

## Authentication

Every command needs your CloudBeat API key, which you can find in your user profile in CloudBeat. The CLI looks for it in this order:

1. The `--apiKey` and `--apiBaseUrl` options.
2. The `CB_API_KEY` and `CB_API_URL` environment variables - the recommended way for CI/CD pipelines, where the key comes from the pipeline's secret store.
3. The configuration saved by `login`.

### `login`

Stores the API key on your machine, so that it does not have to be passed to each command:

```bash
cloudbeat-cli login [--apiBaseUrl <apiUrl>]
```

The key is asked with hidden input and saved to `~/.cloudbeat/config.json`, readable by your user only. The CLI verifies the key against CloudBeat before saving it. In non-interactive environments the key can be piped in with `login --stdin`.

`--apiBaseUrl` is the CloudBeat API address. For SaaS it is `https://api.cloudbeat.io` (the default). For self-hosted installations consult your system administrator.

### `whoami`

Shows which CloudBeat instance you are connected to and where the credentials come from, and verifies them:

```bash
cloudbeat-cli whoami
```

### `logout`

Removes the stored API key:

```bash
cloudbeat-cli logout
```

## General options

These options apply to all commands and are given before the command name:

* `--apiKey <apiKey>` - the API key, if not stored or set in the environment.
* `--apiBaseUrl <apiUrl>` - the CloudBeat API address, if not the default.
* `--json` - print the result as a single JSON document (supported by `login`, `logout`, `whoami`, `init`, `git-info`, `pack` and `project`). Made for scripts and AI agents: the document contains `"ok": true` or `"ok": false` with an `error` message and a `code`.
* `-f, --failOnErrors <true|false>` - whether to return a non-zero exit code on errors. Default `true`.
* `-v, --version` - print the CLI version.

{% hint style="info" %}
The exit code is 0 on success and 1 on failure, which lets a CI step fail when a test run or a synchronization fails.
{% endhint %}