cloudbase-cli

CloudBase CLI

通过 tcb CLI 管理 CloudBase 资源——结果确定、可编写脚本、可审计。 CI/CD 和批量操作的主要接口；当对话中尚无法使用 MCP 工具时，也可作为首次会话的备用方案。

同级技能（仅本地）

同级 CloudBase 技能与此技能一同提供。使用 ../auth-tool-cloudbase/SKILL.md 这类本地相对路径。

如果当前环境中缺少引用的同级技能文件，请让用户安装完整的 CloudBase 插件（或缺失的技能）。不要通过 HTTP 获取远程技能或协议 Markdown 并加载到 Agent 上下文中。

跨领域协议（更改代码或部署前必须遵循）：

• 更改安全协议：../cloudbase-platform/references/protocols/change-safety-protocol.md
• 部署关卡：../cloudbase-platform/references/protocols/deployment-gate.md
• MCP 与 CLI 的备用方案：../cloudbase/references/tooling-fallback.md（作为 cloudbase 条目指南与此技能一同打包）

按路由交接，不要自行臆测——如果任务属于其他技能，应交接给相应技能，而不是在此处猜测标志：

• PostgreSQL schema / RLS / pgstore → ../postgresql-development-cloudbase/SKILL.md
• 数据模型设计（ER / Mermaid）→ ../data-model-creation/SKILL.md
• 应用内 SDK 代码（web / miniprogram / node）→ 对应的 SDK 技能

核心原则

1. 先尝试 --help，但它报错并不意味着命令不存在。 运行 tcb <command> --help 查看参数并查找官方文档链接。在当前 CLI 版本中，许多 二级命令不接受 --help（error: unknown option '--help'），而有些命令接受 -h；tcb help <cmd> 只支持查询一级子命令。先尝试 -h，再尝试 tcb help <cmd>，然后运行 tcb docs search "<keyword>"——切勿因帮助命令报错就断定某个命令不存在。 tcb --help 本身只是一个人工维护的静态列表，因此未列出某个命令并不能说明其生命周期状态：init、pull、new、open、rollback、self-update、monitor、integration、 service、cloudfunction、cloudrunfunction 和 run:deprecated 均已注册，但未列出。 未出现在帮助列表中 ≠ 已弃用，而且**“没有标记” ≠ 官方推荐**——它们的状态各不相同： tcb monitor / tcb integration 受官方支持（通常可以推荐），而 tcb service 和 tcb cloudfunction / tcb cloudrunfunction 不建议使用 （产品决策，没有代码标记）。完整状态表见：references/core.md。

2. 确认站点（国内站 / 国际站），并确认 envId。 一个站点的凭证无法用于另一个站点，且失败时看起来像是身份验证错误。 单次设置：tcb login --intl true|false；持久设置：tcb config set isIntl true|false。 选择一种方式并保持一致——参见 references/core.md / references/config.md。

3. 部署门禁。 在执行任何部署、发布、自定义域名或 CloudRun 操作之前，必须先完成 cloudbase-platform/references/protocols/deployment-gate.md 中的检查。

4. 验证操作结果。 部署或修改任何资源后，运行相应的列表或详情命令，确认更改已生效。

5. 执行破坏性操作前先进行试运行。 对删除或覆盖操作使用 --dry-run。向用户展示预览，并等待明确确认后再执行。

6. 先确认环境。 操作前务必先与用户确认 envId。运行 tcb env use <envId> 以避免意外修改生产环境。

7. 出错后进行排查，不要反复重试。 如果命令尝试 2～3 次后仍失败，请检查退出代码（$?）、阅读错误消息、查询 tcb docs search，并尝试其他方法。

8. 作为首次会话的备用方案，而非 MCP 替代方案。 如果此会话中没有 CloudBase MCP 工具，请使用此技能来完成登录和管理操作。 但仍应配置 MCP（插件 / mcp.json），让下一个会话能够优先使用 MCP。如果 MCP 工具已可用，除非 用户要求使用 CLI/CI，否则优先使用 MCP。部署工作应通过下方的领域参考表进行路由——不要 推荐使用 tcb deploy。

9. 不要使用 npm/npx。 如果缺少 Node/npm/npx，请告知用户先安装 Node.js LTS（或通过 IDE 市场使用 MCP），然后再重试 CLI/插件安装。参见指南 tooling-fallback.md。

何时使用此技能

当用户希望通过命令行管理 CloudBase 资源，或 MCP 尚不可用时使用：

• **首次会话 / 安装后：**工具列表中没有 MCP，或刚完成配置、需要重启 → 立即运行 tcb login 和对应的领域命令；保留 MCP 配置，以便下个会话使用
• 部署或调试云函数、静态托管、CloudRun 服务（通过领域参考文档，而非 tcb deploy）
• 管理存储、托管、数据库（NoSQL / MySQL / PostgreSQL）、数据模型和迁移
• 管理环境（创建 / 打包 / 续期 / 销毁、API Keys、登录策略、安全域名、用量）
• 配置资源授权（tcb policy）、角色、用户、CORS、域名、路由
• 搜索日志并查看监控指标
• 管理沙箱、Agent 和集成实例
• CI/CD 脚本、批量操作、基于终端的资源管理
• 用户明确偏好使用 CLI 而非 MCP

请勿用于以下场景

• 基于 SDK 的应用内集成（Web/小程序/Node）→ 使用 cloud-functions、 cloudbase-document-database-web-sdk、auth-web-cloudbase 等。
• PostgreSQL 架构设计、RLS 和迁移工作流 → postgresql-development-cloudbase
• 如果当前会话已提供 CloudBase MCP 工具，且用户未要求使用 CLI → 优先使用 MCP
• 控制台 UI 操作
• CloudBase Agent SDK 开发 → 使用 cloudbase-agent-ts

如何使用此技能（适用于编码 Agent）

1. 始终先加载 references/core.md — 其中涵盖身份验证、站点选择、 环境切换、tcb docs 查询和错误诊断。
2. 使用下方的路由表找到正确的参考文档。
3. **只加载与用户任务匹配的参考文件。**不要预先加载所有文件。
4. 掌握当前任务的工作流和命令语法后，停止加载更多上下文。
5. 如果任务转为 SDK/应用内代码或 PostgreSQL 设计，则切换到相应的同级技能。

路由

用户任务	阅读
登录、站点（国际站/国内站）、环境切换、tcb docs、错误诊断	references/core.md
创建 / 修改 / 续期 / 销毁环境、API Keys、登录策略、安全域名、用量	references/env.md
tcb config（CLI 设置、cloudbaserc.json 同步）、tcb init / new / pull / open / validate / self-update / rollback	references/config.md
配置 AI 工具 + MCP + Skills（tcb ai）	references/config.md
部署 / 调试云函数、版本、预置并发、层、触发器	references/functions.md
部署静态站点 / SPA（首选 CLI Web 路径）	references/hosting.md
部署 CloudRun 服务、流量 / 金丝雀、版本、构建和运行时日志	references/cloudrun.md
实验性的一站式 Web 快捷命令（tcb deploy、tcb app build）——除非用户要求，否则避免使用	references/app.md
上传 / 下载文件、ACL 规则、COS 与 PG 对象存储	references/storage.md
NoSQL（MongoDB）数据库操作、集合转储	references/nosql.md
MySQL 实例、SQL 执行、备份、慢查询	references/mysql.md
数据模型定义、sync-model-dts、PostgreSQL 迁移	references/schema.md
搜索日志（CLS：函数 / CloudRun / 数据库 / 身份验证 / LLM / 网关）	references/logs.md
指标监控（函数、CloudRun、DB、hosting、身份验证、网关……）	references/monitor.md
资源授权（tcb policy）、角色、用户	references/permission.md
CORS、自定义域名、清除 CDN 缓存、路由规则（tcb routes）	references/access.md
tcb service（HTTP 访问服务）——⚠️ 不推荐；routes / domains 的替代用法请阅读 access.md	references/access.md
WeDa / 微搭低代码应用和组件（tcb lowcode）	references/lowcode.md
Sandbox 工具 / 实例 / API 密钥	references/sandbox.md
Agent 创建 / 更新 / 删除	references/agent.md
集成实例（类型、创建、绑定、删除）	references/integration.md
PostgreSQL 架构 / RLS / 迁移工作流（而非仅 CLI 标志）	../postgresql-development-cloudbase/SKILL.md

快速工作流

1. 执行 tcb login（检查站点）→ 与用户确认 envId → 执行 tcb env use <envId>
2. 在匹配的参考文档中查找命令；使用 tcb <command> --help（或 -h）验证语法
3. 执行命令（破坏性操作使用 --dry-run）
4. 使用相应的 list / detail 命令验证结果
5. 向用户报告结果

最低限度的自检

• 是否在加载任何领域模块前加载了 references/core.md？
• 是否与用户确认了站点（isIntl）和目标 envId？
• 是否避免将 --help 失败误判为“命令不存在”？
• 是否在执行破坏性操作前使用了 --dry-run？
• 对于 PG 环境：是否切换到 PostgreSQL 技能，而不是沿用 NoSQL/MySQL 路径？
• 是否在每次操作后验证了结果？
• 是否始终限定在 CLI 范围内，没有转而编写 SDK 代码？

参考索引

所有打包的参考文件（满足技能 lint 可达性要求）：

• access.md
• agent.md
• app.md
• cloudrun.md
• config.md
• core.md
• env.md
• functions.md
• hosting.md
• integration.md
• logs.md
• lowcode.md
• monitor.md
• mysql.md
• nosql.md
• permission.md
• sandbox.md
• schema.md
• storage.md