## 背景信息 byted\-supabase\-cli 是 AI 原生 BaaS 平台 Supabase 版为使用 Supabase 引擎的 Workspace 提供的命令行工具，用于在本地终端管理火山引擎上的 Supabase 工作区资源。通过 CLI，你可以完成以下操作： * 登录火山引擎账号，获取并维护本地凭据。 * 查看与管理工作区（Workspace）、数据库分支（Branches）。 * 在本地执行 SQL、部署 Edge Functions、操作 Storage 对象存储。 * 生成 TypeScript 类型定义、获取 API Keys / 连接串。 * 配合 AI Agent（Skills / MCP），通过自然语言操作 Supabase。该 CLI 同时支持以 Skills 形式集成到 Trae、Claude 等 AI 编程助手中，提供命令式与对话式两种使用体验。 ## 前提条件在开始安装与使用前，请确认满足以下条件： * 已开通火山引擎账号，并已开通创建至少一个 Supabase Workspace。 * 本地已安装 **Node.js**（建议 LTS 版本），可使用 npm 与 npx 命令。 * 已准备好用于登录的 **AccessKey / SecretKey**，或可通过浏览器完成 OAuth 登录。 * macOS 用户：若系统拦截二进制运行，需在「系统设置 → 隐私与安全性」中放行。 ## 安装 byted\-supabase\-cli 提供两种安装方式：**一键安装（推荐）** 与 **手动安装**。 ### 一键安装（推荐）推荐使用 npx 一键安装 CLI 与配套 Skills： ```Shell npx @byted-supabase/cli@latest install ``` 该命令会同时完成 CLI 与 Skills 的安装，开箱即用。 ### 手动安装如果只需要安装 CLI 本体，可执行： ```Shell npm install -g @byted-supabase/cli@latest ``` 安装完成后即可使用 byted\-supabase\-cli 命令： ```Shell byted-supabase-cli ``` **macOS 提示**：若执行命令时被系统拦截，请前往「系统设置 → 隐私与安全性」放行后重试。 **手动安装 Skills** 如需单独安装配套 Skills，可访问 [findskill](https://findskill.com/bytedance/agentkit-samples/byted-supabase)。 ### 更新 CLI 当 CLI 检测到本地为旧版本时，会在命令执行过程中给出版本提示。按提示执行，或直接运行： ```Shell byted-supabase-cli update ``` 即可更新到最新版本。 ## 配置 CLI 的核心配置为 **登录鉴权**。完成一次登录后，凭据会写入 ~/.volcengine/config.json，长期复用。 ### 登录鉴权登录方式二选一。 **方式一：交互式登录** ```Shell byted-supabase-cli login --region cn-beijing ``` **方式二：使用 AK/SK 直接配置** ```Shell byted-supabase-cli configure set --access-key --secret-key --region cn-beijing ``` **说明 ** \-\-region 参数可缺省，默认值为 cn\-beijing。如需登录其他地域（例如 cn\-shanghai），显式指定 \-\-region 即可。 ### 绑定默认工作区（可选）为避免每次数据面命令都要手写 \-\-workspace\-id，可将当前目录与某个 Workspace 绑定： ```Shell byted-supabase-cli link --workspace-id ws-xxxxxx ``` 绑定后，在当前目录下执行数据面命令时可省略 \-\-workspace\-id 参数。 ## 使用 ### 自检与查看帮助安装并登录完成后，建议先执行以下命令进行自检： ```Shell byted-supabase-cli projects list ``` 若能正常返回工作区列表，则说明凭据可用。查看帮助： ```Shell byted-supabase-cli --help # 查看全部命令 byted-supabase-cli --help # 查看单个子命令的参数 ``` **说明** 忘记命令时，直接在任意子命令后追加 \-\-help，即可现查参数说明，无需查阅外部文档。 ### 常用命令速查下表汇总日常高频使用的 CLI 命令，便于快速查阅。 |**需求场景** |**命令示例** | |---|---| |列出 / 查看工作区 |projects list ／ projects list \-\-workspace\-id ws\-... \-\-detail | |执行 SQL |db query "select ..." \-\-workspace\-id ws\-... | |管理数据库分支 |branches list ／ branches create ／ branches restart | |Edge Functions |functions new → 编辑 → functions deploy \-\-workspace\-id ws\-... | |Storage 对象存储 |storage buckets list ／ storage cp | |生成 TypeScript 类型 |gen types \-\-lang typescript \-\-workspace\-id ws\-... \-s public | |部署前端静态站点 |pages \-\-help（查看 Pages 子命令） | |获取 API Keys / 连接串 |projects api\-keys \-\-workspace\-id ws\-... ／ endpoints list \-\-workspace\-id ws\-... | ### 配合 AI Agent（Skills / MCP）完成 [Skills 安装](https://www.volcengine.com/docs/87275/2549800#R3czsGGW)后，可在 **Trae、Claude** 等支持 Skills / MCP 的 AI Agent 中，直接使用自然语言操作 Supabase。例如： * “帮我列出当前账号下的所有 Supabase 工作区。” * “在 ws\-xxxxxx 中创建一个名为 feature\-a 的数据库分支。” * “部署 hello\-world 这个 Edge Function。” AI Agent 会自动调用 byted\-supabase\-cli 完成对应操作，并返回结构化结果。