# CloudBase 命令行工具 ![npm (tag)](https://img.shields.io/npm/v/@cloudbase/cli)

CloudBase CLI 是一个开源的命令行界面交互工具，用于帮助用户快速、方便的部署项目，管理云开发资源。

## 主要功能

- **云开发资源管理**：快速部署项目，管理云函数、数据库、存储等资源
- **AI 开发助手**：集成多种 AI 工具（Claude、Qwen、Codex、Aider 等），提升开发效率
- **MCP 协议支持**：内置 `cloudbase-mcp` 命令，支持 Model Context Protocol，无需额外安装
- **模板下载**：提供多种项目模板，自动配置 IDE 和 MCP 环境

## 安装 CloudBase CLI

### npm

```shell
npm install -g @cloudbase/cli
```

### yarn

```shell
yarn global add @cloudbase/cli
```

安装完成后，你可以使用 `cloudbase -v` 验证是否安装成功，如果输出了类似下面的版本号，则表明 CloudBase CLI 被成功安装到您的计算机中。

```text
2.7.8
```

## 可用命令

- `cloudbase` 或 `tcb`：主要的 CLI 命令
- `cloudbase-mcp`：内置的 MCP 服务器命令，支持 Model Context Protocol

## CloudBase CLI 运行要求

**Node.js 8.6.0+**

## 文档

请访问[教程与文档](https://docs.cloudbase.net/cli/intro.html)了解详细的使用方法。

## 退出码说明

CloudBase CLI 使用结构化退出码帮助 CI/CD 流水线和 AI Agent 精确处理错误：

| 退出码 | 含义 | 典型场景 | 应对策略 |
|--------|------|----------|----------|
| 0 | 成功 | 命令正常执行 | - |
| 1 | 通用错误 | 未分类的异常 | 查看错误信息，手动排查 |
| 2 | 认证失败 | 未登录、token 过期、无权限 | 执行 `tcb login` 重新登录 |
| 3 | 参数错误 | 缺少必填参数、格式非法、枚举值错误 | 检查命令参数，参考 `tcb <cmd> --help` |
| 4 | 资源不存在 | 环境 ID/函数名无效、集合不存在 | 确认资源名称，用 `tcb env list` / `tcb fn list` 验证 |
| 5 | 云 API 错误 | CloudBase API 返回错误、网络超时 | 检查网络连接，查看 API 错误详情，必要时重试 |
| 6 | 本地文件错误 | cloudbaserc.json 缺失/损坏、路径不存在 | 检查配置文件，用 `tcb init` 重新初始化 |

**CI/CD 脚本示例**：

```bash
# 根据退出码自动重试
tcb fn deploy || {
  code=$?
  case $code in
    2) echo "Auth failed, retrying..." && tcb login && tcb fn deploy ;;
    5) echo "API error, retrying in 30s..." && sleep 30 && tcb fn deploy ;;
    *) echo "Unrecoverable error (code $code)" && exit $code ;;
  esac
}
```

完整定义参见：[src/exit-codes.ts](./src/exit-codes.ts)

## 意见反馈

您可以到 GitHub Repo 新建一个 [issue](https://github.com/TencentCloudBase/cloudbase-cli/issues) 反馈您在使用过程中遇到的问题或建议。
