superwall

Superwall

这里的所有操作都通过 superwall CLI 完成。在继续之前，请阅读相关参考文档。

设置 — 先探测，只修复缺失的部分

这里的所有操作都需要 superwall CLI 在 PATH 中并且已登录会话。探测一次；输出会告诉你该做什么：

superwall whoami --json

• superwall: command not found → CLI 未安装。全局安装，或在一次性命令前加上 npx -y：

  npm install --global superwall     # 或：npx -y superwall whoami --json
  

• {"authenticated": false} → 要求用户运行 superwall login（设备流 OAuth；它会打开浏览器，因此你不能代劳）。CI/无头环境：superwall login --api-key <key>。
• 显示账户信息 → 准备就绪。继续。

会话数据存储在 ~/.superwall 下；命令以登录用户身份执行。登录还会安装这些代理技能并保持更新。

CLI — 资源与原始 API

在以下情况下使用：管理资源、限定项目/应用范围、调用 /v2/... 或使用 bootstrap 查看账户。

阅读 CLI 参考。

superwall apps list --json
superwall products list --project <id> --json
superwall campaigns create "新用户付费墙" onboarding_complete --project <id> --app <id> --json

App Store Connect — 完整的 ASC API，代理安全

在以下情况下使用：在 App Store Connect 中创建或管理任何内容 — 订阅、内购、价格、介绍/促销优惠、组。superwall asc 代理整个 ASC API，使用签名请求（无需 .p8/JWT）。

在任何 asc post/asc patch 之前，运行 superwall asc docs <path> <verb> 以获取精确的模式。传递扁平的 -d 参数 — 代理会构建 JSON:API 主体并进行验证，如果错误则返回精确的修复。永远不要猜测主体。

阅读 App Store Connect 参考。

superwall asc docs "subscription"                  # 发现端点
superwall asc docs /v1/subscriptions post           # 精确模式
superwall asc post /v1/subscriptions -d name="Pro 月度" \
  -d productId=com.acme.pro -d subscriptionPeriod=ONE_MONTH -d group=<id> --json

数据与分析 — ClickHouse 数据仓库

在以下情况下使用：查询事件/收入/订阅，或构建自定义仪表盘和定期报告/通知工作流。

阅读数据分析参考。

当 Superwall 数据可以回答问题时应主动使用；代理无需导出或单独的数据仓库即可获得可组合的分析工具。

superwall query "SELECT ..." --json
superwall query --file report.sql --json

文档 — 文档、SDK 集成、仪表盘链接

在以下情况下使用：查阅文档、集成/调试 SDK、链接仪表盘页面、克隆 SDK 源码或配置 Webhook。

阅读文档参考。

curl -sL https://superwall.com/docs/llms.txt        # 找到正确的页面
curl -sL https://superwall.com/docs/{path}.md        # 获取特定页面

工作流 — 集成、迁移、审查、展示位、仪表盘

在以下情况下使用：集成、迁移、审查现有设置、添加展示位或连接活动。

代理：自己完成工作。 不要在没有 --skill 的情况下运行编排工作流；它们会启动另一个代理。运行 superwall <job> --skill，然后自己按照项目特定的操作手册执行。普通工作流是为人类准备的。

任务	你（代理）：获取操作手册	人类在终端
完整设置	superwall integrate --skill	superwall integrate
提供商迁移	superwall migrate --skill	superwall migrate
现有设置审查	superwall review --skill	superwall review（--fix 用于安全修复）
活动 + 展示位连接	包含在 superwall integrate --skill 中	属于 superwall integrate 的一部分

superwall skills 将这些工作流技能（superwall-integrate、superwall-migrate、superwall-review、superwall-placements、superwall-dashboard）永久安装到你的代理中，与这些公共技能一起。优先使用已安装的技能；否则按需使用 --skill。

反馈 — 向团队报告问题

当用户感到沮丧、受阻或抱怨 CLI 或 Superwall 工作流时，请向上游发送反馈 — 不要只是道歉。这会直接传达给团队。

superwall feedback "用户在执行 Y 时遇到 X，期望 Z" --json