---
url: /zh/develops/cnb-cli.md
description: |
  CNB CLI 是 CNB OpenAPI 的命令行工具，通过一条 cnb 命令即可调用平台所有 OpenAPI 能力。
---
## 概述

[CNB CLI](https://docs.cnb.cool/zh/plugin/public/cnbcool/cnb-cli.html) 是 CNB 平台 OpenAPI 的命令行工具，
通过一条 `cnb` 命令即可访问 CNB 平台的全部 OpenAPI 能力，覆盖代码托管、构建、制品库、组织成员、知识库等场景。

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

## 安装与使用

### 本地安装（需要 Node.js LTS）

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

### 使用 Docker（无需安装）

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

### 在 `.cnb.yml` 流水线中使用

流水线会自动注入 `CNB_TOKEN`，无需登录：

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

## 鉴权

本地终端推荐使用 OAuth2 设备授权登录：

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

也可通过环境变量 `CNB_TOKEN` 提供令牌，CI 场景下会自动注入。

## 命令示例

```bash
cnb issues list-issues --repo my-org/my-repo
cnb issues create-issue --repo my-org/my-repo --title "Bug" --body "复现步骤..."
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
```

当 CI 由 Issue 或 PR 事件触发时，CNB 会注入 `CNB_REPO_SLUG`、`CNB_ISSUE_IID`、`CNB_PULL_REQUEST_IID` 等环境变量。
CLI 快捷命令会自动读取这些变量作为 `--repo` / `--number` 参数，无需手动传入：

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

## 更多用法

完整模块清单、参数说明、Git Credential Helper 等高级用法，详见
[CNB CLI 插件文档](https://docs.cnb.cool/zh/plugin/public/cnbcool/cnb-cli.html)。