---
url: /en/develops/cnb-cli.md
description: >
  CNB CLI is the command-line tool for CNB OpenAPI. A single cnb command exposes
  the full OpenAPI surface.
---
## Overview

[CNB CLI](https://docs.cnb.cool/en/plugin/public/cnbcool/cnb-cli.html) is the command-line tool for the
CNB platform OpenAPI. A single `cnb` command lets you access the platform's full OpenAPI surface,
covering source control, builds, registries, organizations and members, knowledge base and more.

* npm package: [`@cnbcool/cnb-cli`](https://www.npmjs.com/package/@cnbcool/cnb-cli)
* Docker image: [`cnbcool/cnb-cli`](https://hub.docker.com/r/cnbcool/cnb-cli/tags)

## Installation & Usage

### Local install (requires Node.js LTS)

```bash
npm install -g @cnbcool/cnb-cli
cnb --help
```

### Run with Docker (no install required)

```bash
docker run --rm -v $(pwd):$(pwd) -w $(pwd) cnbcool/cnb-cli cnb users get-user-info
```

### Use inside a `.cnb.yml` pipeline

The pipeline injects `CNB_TOKEN` automatically — no login needed:

```yaml
main:
  push:
    - docker:
        image: cnbcool/cnb-cli
      stages:
        - name: get-user-info
          script: cnb users get-user-info
```

## Authentication

For local terminals, OAuth2 device authorization is recommended:

```bash
cnb login
cnb status
cnb logout
```

You can also provide a token via the `CNB_TOKEN` environment variable, which is auto-injected in
CI scenarios.

## Command Examples

```bash
cnb issues list-issues --repo my-org/my-repo
cnb issues create-issue --repo my-org/my-repo --title "Bug" --body "Steps to reproduce..."
cnb pulls merge-pull --repo my-org/my-repo --number 42 --merge-style squash
cnb build start-build --repo my-org/my-repo --branch main
```

When CI is triggered by Issue or PR events, CNB injects `CNB_REPO_SLUG`, `CNB_ISSUE_IID`,
`CNB_PULL_REQUEST_IID` and other environment variables. CLI shortcut commands read them
automatically as `--repo` / `--number`, so you don't need to pass these flags:

```bash
cnb issues get
cnb issues comment --body "..."
cnb pulls get
cnb pulls check-status
```

## Learn More

For the full module list, parameter reference and advanced usage such as the Git Credential Helper,
see the [CNB CLI plugin documentation](https://docs.cnb.cool/en/plugin/public/cnbcool/cnb-cli.html).