pp-supabase

Supabase — Printing Press CLI

前提条件：安装 CLI

此技能使用 supabase-pp-cli 二进制文件。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装：

   npx -y @mvanhorn/printing-press-library install supabase --cli-only
   

2. 验证：supabase-pp-cli --version
3. 确保 $GOPATH/bin（或 $HOME/go/bin）位于 $PATH 中。

如果此 CLI 尚未拥有公开库类别，且 npx 安装失败，请先安装 Node，或在发布后使用特定类别的 Go 后备方案。

如果安装后 --version 报告“command not found”，说明安装步骤未将二进制文件放入 $PATH。验证成功前，请勿继续执行此技能中的命令。

何时使用此 CLI

当 Agent 需要跨组织扫描 Management API 实体、从本地 SQLite 缓存运行跨项目查询（secrets where-name、functions inventory、branches drift、projects estate）、按电子邮件查找 Auth 用户（auth-admin lookup）、汇总 Storage 存储桶用量（storage usage），或获取单个项目的 PostgREST 架构以进行类型化查询规划（pgrst schema）时，请使用此 CLI。

对于本地 Docker 和迁移工作流（supabase start、supabase db push、supabase gen types），请使用官方 Supabase CLI。对于 PostgREST 行增删改查、Storage 对象生命周期操作（上传／下载／签名）、Auth Admin 用户修改，以及 Edge Function 运行时调用，请使用 supabase-js——这些都是此 CLI 首次发布版本中已记录的已知缺口（参见 README 中的 ## Known Gaps）。

独特功能

这些功能在任何其他用于此 API 的工具中都不可用。

跨项目汇总

• secrets where-name — 查找所有（跨组织）持有指定名称密钥的项目，并显示每个项目上次同步的时间。

  当 Agent 需要了解跨项目的安全状况（“哪些客户端有 STRIPE_KEY”“这个密钥名称是否在任何地方泄露”）时使用。supabase-community MCP 无法在不逐个项目查询的情况下回答这些问题。

  supabase-pp-cli secrets where-name STRIPE_KEY --json
  

• functions inventory — 按项目和组织汇总所有边缘函数，包括 slug、版本、状态和上次部署时间。

  在部署审查（“哪些项目部署了 stripe-webhook？”）或过期函数审计（“哪些函数在过去 90 天内没有重新部署？”）期间使用。

  supabase-pp-cli functions inventory --org acme --json
  

• branches drift — 列出超过 N 天且尚未合并或删除的预览分支，并按父项目分组。

  在每周清理时使用，以避免预览分支泛滥、造成数据库资源消耗。

  supabase-pp-cli branches drift --older-than 7d --json
  

• projects estate — 每个项目一行，汇总函数数量、分支数量、API 密钥数量、密钥名称数量和上次同步时间。

  在周一早晨的项目资产审查中使用；一屏即可取代 12 个仪表板标签页。

  supabase-pp-cli projects estate --json
  

• auth-admin recent — 遍历已同步的项目，逐个调用 Auth Admin，并将指定时间范围内创建的用户汇总到一张表中。

  用于每周审查整个组织项目组合的用户增长情况。

  supabase-pp-cli auth-admin recent --since 7d --json
  

特定服务模式

• auth-admin lookup — 遍历文档中列出的 Auth Admin 用户分页，仅返回一个完全匹配的标准化电子邮件地址；也可以选择联接一个以用户名命名的 PostgREST 上下文表，并按 user_id 关联。

  如果没有匹配项、存在重复匹配、页面格式错误或重复、遍历不完整，或发生提供方错误，查找将安全失败；绝不会打印不相关的用户记录。

  supabase-pp-cli auth-admin lookup [email protected] --context-table profiles --context-key user_id --json
  

• pgrst schema — 从 Management API 获取单个项目的 PostgREST OpenAPI，并列出表、列、类型和检测到的索引，以进行类型化查询规划。

  在编写类型化查询前使用，让 Agent 无需反复尝试即可了解表的列类型和约束。

  supabase-pp-cli pgrst schema --table profiles --json
  

• storage usage — 列出每个存储桶中的对象，并汇总文件数量、总字节数和最大对象。

  当 Agent 需要回答“存储空间离上限还有多远”或“哪个存储桶最大”时使用。

  supabase-pp-cli storage usage --bucket avatars --json
  

命令参考

branches — 管理分支

• supabase-pp-cli branches delete-a-branch — 删除指定的数据库分支。默认情况下会立即删除。使用 force=false 可安排删除……
• supabase-pp-cli branches get-a-branch-config — 获取指定数据库分支的配置
• supabase-pp-cli branches update-a-branch-config — 更新指定数据库分支的配置

oauth — OAuth 相关端点

• supabase-pp-cli oauth authorize-project-claim — 为指定的提供方发起 OAuth 授权流程。成功通过身份验证后，用户可以……
• supabase-pp-cli oauth authorize-user — [Beta] 通过 oauth 授权用户
• supabase-pp-cli oauth exchange-token — [Beta] 将 auth code 兑换为用户的 access 和 refresh token
• supabase-pp-cli oauth revoke-token — [Beta] 撤销 oauth 应用授权及其对应的令牌

organizations — 组织相关端点

• supabase-pp-cli organizations create-an — 创建组织
• supabase-pp-cli organizations get-an — 获取组织信息
• supabase-pp-cli organizations list-all — 返回你当前所属组织的列表。

projects — 项目相关端点

• supabase-pp-cli projects create-a — 创建项目
• supabase-pp-cli projects delete-a — 删除指定项目
• supabase-pp-cli projects get — 获取经过身份验证的用户所属的指定项目
• supabase-pp-cli projects get-available-regions — [Beta] 获取可用于新项目的区域列表
• supabase-pp-cli projects list-all — 返回你此前创建的所有项目的列表。
• supabase-pp-cli projects update-a — 更新指定项目

snippets — 管理代码片段

• supabase-pp-cli snippets get-a — 获取指定 SQL 代码片段
• supabase-pp-cli snippets list-all — 列出已登录用户的 SQL 代码片段

supabase-profile — 管理 supabase 个人资料

• supabase-pp-cli supabase-profile — 获取用户的个人资料

查找合适的命令

知道要做什么，但不确定该用哪个命令时，可以直接询问 CLI：

supabase-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中匹配最佳命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项——可改用 --help，或使用更具体的查询。

使用示例

跨项目机密审计

supabase-pp-cli sync && supabase-pp-cli secrets where-name STRIPE_KEY --json

同步本地存储，然后列出所有组织中每个包含名为 STRIPE_KEY 的机密的项目——只需一次 shell 调用，即可完成周一早上的安全检查。

支持工单分流

supabase-pp-cli auth-admin lookup [email protected] --context-table profiles --context-key user_id --agent --select user.id,user.email,user.last_sign_in_at,context.tier

使用文档说明的分页方式遍历 Auth Admin，要求电子邮件地址精确匹配（不区分大小写），然后关联该用户的 profiles 行；--select 会将精确匹配结果缩小到支持工作流所需的字段。

过期的预览分支

supabase-pp-cli branches drift --older-than 14d --json

找出超过 14 天且尚未合并或删除的预览分支，并按父项目分组——这就是周二的清理目标列表。

存储上限检查

supabase-pp-cli storage usage --json | jq '.[] | select(.total_bytes > 100000000)'

列出所有超过 100MB 的存储桶；通过管道传给 jq，按字节阈值筛选。

查询前查看 PostgREST 架构

supabase-pp-cli pgrst schema --table orders --agent --select tables.columns.name,tables.columns.type,tables.columns.nullable

从通过 Management-API 路由的架构端点，仅获取 orders 表的列类型，以便 Agent 无需反复试错即可编写类型明确的 PostgREST 查询。

身份验证设置

Supabase 在两个 API 主机上提供三种凭据类型。api.supabase.com 上的 Management API 使用 Personal Access Token（SUPABASE_ACCESS_TOKEN，请求头为 Authorization: Bearer <PAT>）。<ref>.supabase.co 上的项目 API 使用 apikey: 请求头 — 对于遵循 RLS 的调用，请设置 SUPABASE_PUBLISHABLE_KEY（或旧版 SUPABASE_ANON_KEY）；对于绕过 RLS 并启用 Auth Admin 端点的服务端调用，请设置 SUPABASE_SERVICE_ROLE_KEY（或新版 SUPABASE_SECRET_KEY）。同时设置 SUPABASE_URL=https://<ref>.supabase.co。Edge Functions 的注意事项：密钥必须放在 apikey: 中，绝不要使用 Authorization: Bearer。

运行 supabase-pp-cli doctor 以验证设置。

Agent 模式

在任何命令中添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于冗长的 API，这对于控制上下文大小至关重要：

  supabase-pp-cli projects get mock-value --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不发送

• 支持离线 — 如果本地 SQLite 存储可用，同步/搜索命令可以使用它

• 非交互式 — 从不提示输入，每项输入都是一个标志

• 显式重试 — 只有当已存在的创建结果应视为成功时才使用 --idempotent；只有当缺失的删除目标应视为成功时才使用 --ignore-missing

响应封装

从本地存储或 API 读取数据的命令会将输出封装在一个来源信息对象中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 以获取数据，并查看 .meta.source 以判断数据来自实时 API 还是本地存储。只有当 stdout 是终端时，才会将人类可读的 N results (live) 摘要打印到 stderr — 管道/Agent 使用者在 stdout 上只会收到纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有任何不对劲之处时，请记录下来：

supabase-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
supabase-pp-cli feedback --stdin < notes.txt
supabase-pp-cli feedback list --json --limit 10

条目会保存在本地的 ~/.supabase-pp-cli/feedback.jsonl。只有在设置了 SUPABASE_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 SUPABASE_FEEDBACK_AUTO_SEND=true 时，条目才会通过 POST 发送。默认行为仅保存在本地。

写下让你感到意外的地方，而不是 bug 报告。简短、具体、一行即可：这部分会不断累积价值。

输出传递

每个命令都接受 --deliver <sink>。除 stdout 之外，或用指定的目标替代 stdout，将输出发送到该目标，因此 Agent 无需手动通过管道传递即可路由命令结果。支持三种目标：

目标	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子写入 <path>（tmp + rename）
webhook:<url>	将输出正文 POST 到该 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回列出受支持方案的结构化错误。Webhook 失败时会返回非零状态，并在 stderr 中记录 URL 和 HTTP 状态。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。如果定时 Agent 每次运行都以相同配置调用同一命令，就可以使用配置 — 这是 HeyGen 的 “Beacon” 模式。

supabase-pp-cli profile save briefing --json
supabase-pp-cli --profile briefing projects get mock-value
supabase-pp-cli profile list --json
supabase-pp-cli profile show briefing
supabase-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便进行自省的 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求受限（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 supabase-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并添加 --agent）

MCP 服务安装

从此 CLI 发布的公共库条目或预构建版本安装 MCP 二进制文件，然后进行注册：

claude mcp add supabase-pp-mcp -- supabase-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which supabase-pp-cli 如果未找到，请提供安装选项（参见本技能顶部的“先决条件”）。
2. 根据上方的“独特功能”和“命令参考”，为用户查询匹配最佳命令。
3. 使用 --agent 标志执行：

   supabase-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，可进一步查看子命令帮助：supabase-pp-cli <command> --help。