@superwall/cli 1.7.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/README.md +192 -52
  2. package/dist/{setup-Bxj22rYi.js → apple-CkKlHBZ9.js} +82 -76
  3. package/dist/auth.d.ts +4 -19
  4. package/dist/auth.js +4 -2
  5. package/dist/{actions-B7ym3oVS.js → billing-XCZU_T46.js} +98 -28
  6. package/dist/{bind-YrJvuRF9.js → bind-drne__Ys.js} +38 -33
  7. package/dist/{build-DLoCW5Ri.js → build-Gpdq5QXP.js} +20 -26
  8. package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
  9. package/dist/client-DP6Rc0t_.js +176 -0
  10. package/dist/config-BO1Y87kV.js +105 -0
  11. package/dist/{notification-url-DuKF2659.js → create-BBrtgUgS.js} +235 -539
  12. package/dist/{create-pkANt1Gs.js → create-Cwc3SRWJ.js} +194 -168
  13. package/dist/create-Yvf2gStM.js +19 -0
  14. package/dist/doctor-C9ldpPFC.js +83 -0
  15. package/dist/{drivers-Qx9LxmRN.js → drivers-DNrx4LWA.js} +185 -172
  16. package/dist/entry.d.ts +0 -5
  17. package/dist/entry.js +28073 -1134
  18. package/dist/environment-DF1qKlny.js +58 -0
  19. package/dist/{existing-AVEfZu2A.js → existing-78LWSsqS.js} +12 -6
  20. package/dist/held-Cy8Wl4D1.js +1112 -0
  21. package/dist/held-Ddw1XSsr.js +16 -0
  22. package/dist/input-vi0bou04.js +42 -0
  23. package/dist/{integrate-brmhPG-S.js → integrate-DcJhpXy8.js} +277 -254
  24. package/dist/kinds-GFXB3sYu.js +11 -0
  25. package/dist/log-NVhVe_oe.js +62 -0
  26. package/dist/login-B2TsCE2H.js +53 -0
  27. package/dist/login-BoBe8Psl.js +16 -0
  28. package/dist/{login-Do4wFuLv.js → login-D0lh3_JI.js} +118 -55
  29. package/dist/lookup-D-nmmAbw.js +71 -0
  30. package/dist/migrate-Cfec564E.js +274 -0
  31. package/dist/notification-url-YDbq6FMA.js +100 -0
  32. package/dist/{open-studio-DOw-6ydc.js → open-Ba2vBl1_.js} +34 -43
  33. package/dist/org-D0g_q3mv.js +35 -0
  34. package/dist/output-Ggzq5_-t.js +122 -0
  35. package/dist/paths-DxSLdpOI.js +29 -0
  36. package/dist/playbook-DIeb7hne.js +53 -0
  37. package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
  38. package/dist/promote-COD4fYdz.js +91 -0
  39. package/dist/push-CncywhkQ.js +482 -0
  40. package/dist/push-CtD4FZQV.js +22 -0
  41. package/dist/registry-DSrosOYs.js +10228 -0
  42. package/dist/{reports-CfJqoava.js → reports-DdPq4blM.js} +7 -6
  43. package/dist/{resources-Bf9O1JNM.js → resources-Dqr01Dep.js} +150 -55
  44. package/dist/{run-DsVZ5snL.js → run-C9qg_QlC.js} +16 -22
  45. package/dist/scan-Cv5uOwVY.js +4 -0
  46. package/dist/{scan-zKsddO72.js → scan-DLrsrFS9.js} +48 -37
  47. package/dist/scope-V336uz8j.js +198 -0
  48. package/dist/screenshot-file-0UETadF8.js +16 -0
  49. package/dist/{selection-CxZoX4NT.js → selection-Rdw-ZUoG.js} +94 -51
  50. package/dist/send-BxD9yf6F.js +150 -0
  51. package/dist/{dev-DmB3XqaJ.js → server-D0tGG8C4.js} +82 -92
  52. package/dist/server-z1LH94R_.js +22 -0
  53. package/dist/session-1AV_Bs_d.js +6 -0
  54. package/dist/session-CFAmMhem.js +40 -0
  55. package/dist/session-D_nEWKXT.js +768 -0
  56. package/dist/skills/animate-onboarding/SKILL.md +467 -0
  57. package/dist/skills/animate-onboarding/references/engine.md +494 -0
  58. package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
  59. package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
  60. package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
  61. package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
  62. package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  63. package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
  64. package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
  65. package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  66. package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
  67. package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
  68. package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
  69. package/dist/skills/animate-onboarding/references/performance.md +41 -0
  70. package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
  71. package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  72. package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  73. package/dist/skills/index.json +37 -0
  74. package/dist/skills/mobile-design/SKILL.md +447 -0
  75. package/dist/skills/mobile-design/references/responsive.md +162 -0
  76. package/dist/skills/onboarding-questions/SKILL.md +231 -0
  77. package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
  78. package/dist/skills/onboarding-questions/references/craft.md +142 -0
  79. package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
  80. package/dist/skills/superwall/SKILL.md +82 -9
  81. package/dist/skills/superwall/references/api.md +153 -37
  82. package/dist/skills/superwall/references/apple-setup.md +316 -0
  83. package/dist/skills/superwall/references/asc.md +74 -38
  84. package/dist/skills/superwall/references/data-analytics.md +55 -21
  85. package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
  86. package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
  87. package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
  88. package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
  89. package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
  90. package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
  91. package/dist/skills/superwall/workflows/placements/android.md +2 -2
  92. package/dist/skills/superwall/workflows/placements/expo.md +2 -2
  93. package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
  94. package/dist/skills/superwall/workflows/placements/ios.md +2 -2
  95. package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
  96. package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
  97. package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
  98. package/dist/skills/superwall/workflows/review/playbook.md +1 -1
  99. package/dist/skills/superwall-editor/SKILL.md +61 -0
  100. package/dist/skills/superwall-editor/references/cli.md +135 -0
  101. package/dist/skills/superwall-editor/references/design.md +51 -0
  102. package/dist/skills/superwall-editor/references/native-elements.md +171 -0
  103. package/dist/skills/superwall-editor/references/workflow.md +65 -0
  104. package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
  105. package/dist/skills/superwall-framework/SKILL.md +78 -28
  106. package/dist/skills/superwall-framework/references/cli.md +58 -28
  107. package/dist/skills/superwall-framework/references/examples.md +4 -3
  108. package/dist/skills/superwall-framework/references/layout.md +30 -8
  109. package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
  110. package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
  111. package/dist/skills/wwdc/SKILL.md +22 -0
  112. package/dist/skills/wwdc/references/docs.md +52 -0
  113. package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
  114. package/dist/{skills-DPzlnfCK.js → skills-BvFOa4y6.js} +99 -122
  115. package/dist/skills-DMG4bpKk.js +14 -0
  116. package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
  117. package/dist/spinner-CneRK5rk.js +294 -0
  118. package/dist/storage-DYvmIOHa.d.ts +16 -0
  119. package/dist/storage-s2Dnz-yl.js +31 -0
  120. package/dist/storekit-DafAnGkM.js +16 -0
  121. package/dist/storekit-yY_kS2iR.js +47 -0
  122. package/dist/telemetry-DtG92m5O.js +56 -0
  123. package/dist/theme-DUsCh-Vd.js +25 -0
  124. package/dist/timing-BVxPrYq3.js +5 -0
  125. package/dist/{token-C0it-Xh7.js → token-DzRh7dI1.js} +6 -38
  126. package/dist/tools.d.ts +96 -0
  127. package/dist/tools.js +11178 -0
  128. package/dist/ui-D_qf3Gvw.js +53 -0
  129. package/dist/upgrade-Bt4Ouw1y.js +117 -0
  130. package/dist/upgrade-Cqy5orjb.js +7 -0
  131. package/package.json +10 -5
  132. package/dist/api-CZzirVMj.js +0 -151
  133. package/dist/api-output-aJNw7Syy.js +0 -20
  134. package/dist/app-DH6U8yuI.js +0 -190
  135. package/dist/asa-C-sQzPPn.js +0 -1194
  136. package/dist/asc-1ZBJ6DwS.js +0 -778
  137. package/dist/auth-YRhlV3DE.js +0 -140
  138. package/dist/billing-CCYHdApx.js +0 -80
  139. package/dist/bundle-id-CKxl_026.js +0 -121
  140. package/dist/command-CMIz81Da.js +0 -301
  141. package/dist/dev-DZy6pOnB.js +0 -22
  142. package/dist/doctor-H-hf-Yww.js +0 -88
  143. package/dist/feedback-CKf-rpBW.js +0 -152
  144. package/dist/hosted-CXe9TrWx.js +0 -32
  145. package/dist/migrate-C9ERDR6y.js +0 -284
  146. package/dist/org-sj7uyvp-.js +0 -40
  147. package/dist/output-C4o2gJ1K.js +0 -146
  148. package/dist/params-l3CrvRtR.js +0 -51
  149. package/dist/pipeline-BqzqZhX1.js +0 -977
  150. package/dist/print-skill-ZojRSybs.js +0 -74
  151. package/dist/promote-BG8X4Nv_.js +0 -88
  152. package/dist/publish-sxLh-G4G.js +0 -35
  153. package/dist/push-bQ6Vxtg8.js +0 -35
  154. package/dist/query-_FbybaH-.js +0 -53
  155. package/dist/resource-CGIwSd29.js +0 -323
  156. package/dist/revenue-provider-ebsRINY8.js +0 -100
  157. package/dist/scope-BvzD-kO4.js +0 -223
  158. package/dist/skills-D_R-lEsK.js +0 -64
  159. package/dist/spinner-TWa0hia6.js +0 -18
  160. package/dist/storekit-Cj9Cpjcz.js +0 -29
  161. package/dist/telemetry-DeA1mvnT.js +0 -169
  162. package/dist/ui-Dy0b-9L8.js +0 -27738
  163. package/dist/update-B2fWIc4q.js +0 -59
  164. package/dist/upgrade-BmzkTKrh.js +0 -72
  165. /package/dist/{devtools-8EgLo86w.js → devtools-ByZ6XYnn.js} +0 -0
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: superwall
3
- description: Use local files, Superwall docs, and the `superwall` CLI in a coding agent for SDK integration, migration, review, App Store Connect, and Apple Search Ads. Also use it for account apps, products, entitlements, campaigns, paywalls, webhooks, and analytics when the MCP connector is unavailable. When available, use MCP tools directly for account tasks.
3
+ description: Use local files, Superwall docs, and the `superwall` CLI in a coding agent for SDK integration, migration, review, App Store Connect (including connecting its keys, server notifications and revenue provider), and Apple Search Ads. Also use it for account apps, products, entitlements, campaigns, paywalls, webhooks, and analytics when the MCP connector is unavailable. When available, use MCP tools directly for account tasks.
4
4
  ---
5
5
 
6
6
  # Superwall
@@ -11,6 +11,26 @@ and current documentation; account commands need the `superwall` CLI. When the
11
11
  Superwall MCP connector is available, use its tools directly for account data
12
12
  and configuration. Use the CLI for capabilities the connector does not expose.
13
13
 
14
+ ## MCP tools - the same commands, without a terminal
15
+
16
+ Every MCP tool is a CLI command: its name is the command's words joined by
17
+ `_` (`apps_get`, `campaigns_placements_create`, `asc_subscriptions_create`,
18
+ `query`, `api_docs`), its input is the command's arguments and flags in
19
+ `snake_case` (`--event-name` is `event_name`), and it returns the command's
20
+ `--json` output. Everything this skill says about a command applies to its tool.
21
+ There is no `whoami` tool; `apps_list` shows what the user can reach. Each call
22
+ acts as the signed-in user, with their dashboard role. Destructive tools run
23
+ without the CLI's own confirmation, so the same approval rules apply before
24
+ calling them.
25
+
26
+ Work that needs the user's machine has no tool. Ask the user to run it in a
27
+ terminal (`npx superwall <command>`, after `npx superwall login`): `integrate`,
28
+ `review`, `migrate`, `setup apple`, `asc keys create`, `asc keys update`,
29
+ `asc screenshots upload`, `products storekit`, `apps use`, `login`, `logout`,
30
+ `whoami`, `doctor`, `skills`, `upgrade`, `feedback`, and on the `next`
31
+ channel the paywall-as-code commands (`create`, `dev`, `build`, `push`,
32
+ `promote`, `publish`).
33
+
14
34
  ## CLI prerequisite — use the installed version
15
35
 
16
36
  CLI tasks require a one-time user installation:
@@ -20,7 +40,8 @@ npm install --global superwall
20
40
  ```
21
41
 
22
42
  Use `superwall ...` directly once it is installed. Do not automatically install
23
- or upgrade the CLI, or use a download-and-run fallback. Ask the user to install
43
+ or upgrade the CLI, or use a download-and-run fallback, with one exception:
44
+ before reporting a bug, upgrade and retry (see Feedback below). Ask the user to install
24
45
  it if a requested CLI task cannot proceed. Bundled playbooks, references, local
25
46
  SDK review, and documentation tasks remain available without the CLI.
26
47
 
@@ -39,19 +60,26 @@ superwall whoami --json
39
60
  use, have the user configure authentication privately using `superwall login --help`.
40
61
  - **account shown** → ready. Proceed.
41
62
 
63
+ These playbooks use the 2.x command syntax (`apps get`, `create --identifier`,
64
+ `campaigns placements create`, `asc keys import`). If `superwall --version` is
65
+ below 2.0.0, ask the user to run `superwall upgrade` before account commands; an
66
+ older CLI rejects these commands rather than guessing.
67
+
42
68
  The session lives under `~/.superwall`; account commands act as the logged-in
43
69
  user. A plugin installation already includes these skills, so use its bundled
44
70
  files rather than assuming a separate standalone skill installation is needed.
45
71
 
46
72
  ## Authorization and data boundaries
47
73
 
48
- Act only on the user's requested task. Confirm the active organization and
49
- explicit project/application IDs before account operations. Listing examples
74
+ Act only on the user's requested task. Confirm the explicit
75
+ project/application IDs before account operations. Listing examples
50
76
  are documentation, not permission to execute writes.
51
77
 
52
78
  - Let the user complete OAuth and credential setup in the official browser or
53
79
  dashboard. Never request passwords, private keys, API tokens, OTPs, or session
54
- files in conversation; never read or display saved credentials.
80
+ files in conversation; never read or display saved credentials. One narrow
81
+ exception: Apple's verification code for an Apple sign-in the user asked you
82
+ to run, as described in the [Apple setup reference](references/apple-setup.md).
55
83
  - Before deletion, credential changes, permission expansion, production writes,
56
84
  or advertising spend, show the exact resources, proposed changes, and monetary
57
85
  limits and obtain the user's specific approval. Follow host confirmation rules.
@@ -71,10 +99,22 @@ viewing the account with `bootstrap`.
71
99
 
72
100
  [Read the CLI reference](references/api.md).
73
101
 
102
+ Commands follow the API, Stripe-style: `superwall <resource> [nested]
103
+ <operation> [ids] [--field value]`, with `list · get · create · update · delete`
104
+ everywhere the API has them. **Run `superwall <resource> --help` for its
105
+ operations and `superwall <resource> <operation> --help` for the exact flags**
106
+ (read from the live API reference) - never guess a flag. For an endpoint no
107
+ resource covers, find it with `superwall api docs` and call it with the raw
108
+ `get|post|patch|delete /v2/...` verbs.
109
+
74
110
  ```bash
75
111
  superwall apps list --json
76
- superwall products list --project <id> --json
77
- superwall campaigns create "New user paywall" onboarding_complete --project <id> --app <id> --json
112
+ superwall apps get <app> --json # everything about one app
113
+ superwall apps update <app> --bundle-id com.acme.app --json
114
+ superwall paywalls list --app <id|dashboard link> --search onboarding --json
115
+ superwall campaigns create --description "New user paywall" --placement onboarding_complete --app <id> --json
116
+ superwall campaigns audiences --help # what a nested resource can do
117
+ superwall api docs variant # an endpoint no resource covers
78
118
  ```
79
119
 
80
120
  ## App Store Connect - App Store Connect API
@@ -96,6 +136,25 @@ superwall asc post /v1/subscriptions -d name="Pro Monthly" \
96
136
  -d productId=com.acme.pro -d subscriptionPeriod=ONE_MONTH -d group=<id> --json
97
137
  ```
98
138
 
139
+ ## Apple setup - bundle ID, keys, server notifications, revenue provider
140
+
141
+ Use when: setting an app's bundle ID or package name, connecting an iOS app to
142
+ App Store Connect, getting Apple's server notifications to Superwall (directly,
143
+ through RevenueCat, or from the user's server), or reading or changing the
144
+ revenue provider. Each step is one command;
145
+ the reference is the order to run them in. Look before you change anything,
146
+ import a key before creating one, never create a second key, and never change
147
+ the revenue provider without the user's decision.
148
+
149
+ [Read the Apple setup reference](references/apple-setup.md).
150
+
151
+ ```bash
152
+ superwall apps get <app> --json # bundle ID, SDK reports, keys, URL, revenue provider
153
+ superwall asc keys import --app <app> --json # reuse a key the organization has
154
+ superwall asc notification-url check --app <app> --json # what Apple has, and whose it is
155
+ superwall apps update <app> --revenue-provider <p> # only after the user decides
156
+ ```
157
+
99
158
  ## Apple Search Ads - Apple Ads API
100
159
 
101
160
  Use when: reading or managing Apple Search Ads - campaigns, ad groups,
@@ -129,9 +188,14 @@ the connector does not expose the needed capability.
129
188
 
130
189
  ```bash
131
190
  superwall query "SELECT ..." --json
132
- superwall query --file report.sql --json
191
+ superwall query --file report.sql --app <id> --json
133
192
  ```
134
193
 
194
+ For anything about revenue, pass `--app` and filter by the app's revenue
195
+ provider with the `{revenue_integrations:Array(String)}` parameter it fills, or
196
+ the numbers double-count apps that send revenue from both the store and
197
+ RevenueCat (see the reference).
198
+
135
199
  ## Docs - documentation, SDK integration, dashboard links
136
200
 
137
201
  Use when: looking up docs, integrating/debugging an SDK, linking dashboard pages,
@@ -172,6 +236,15 @@ When the user asks you to send feedback about the CLI or a Superwall workflow,
172
236
  summarize the issue and send it upstream with `superwall feedback`. Do not send
173
237
  feedback to the team based only on a complaint in conversation.
174
238
 
239
+ Before reporting a bug, make sure it still happens on the latest CLI: it may
240
+ already be fixed.
241
+
242
+ 1. Compare `superwall --version` with `npm view superwall version`.
243
+ 2. If the installed version is older, run `superwall upgrade`, then repeat
244
+ the exact command that failed.
245
+ 3. Fixed by the upgrade → tell the user which version fixed it and send
246
+ nothing. Still broken → report it, with the version you reproduced it on.
247
+
175
248
  ```bash
176
- superwall feedback "user hit X running Y; expected Z" --json
249
+ superwall feedback "user hit X running Y; expected Z (superwall 2.0.1)" --json
177
250
  ```
@@ -7,12 +7,17 @@ lives in `~/.superwall`.
7
7
 
8
8
  ```bash
9
9
  superwall login # device-flow OAuth (opens browser); acts as you
10
- superwall whoami --json # show the logged-in account / org
10
+ superwall whoami --json # show the logged-in account
11
11
  superwall logout --json
12
12
  ```
13
13
 
14
14
  Add `--help` / `-h` to any command for its flags.
15
15
 
16
+ `SUPERWALL_API_KEY` is only ever the organization's secret key (`sk_…`), which
17
+ CI uses to push and promote without a login. It is never the app's public key:
18
+ `superwall integrate` takes that (`pk_…`) from `--api-key`, or finds it in the
19
+ project. Never read, print or move either key.
20
+
16
21
  ## Data hierarchy
17
22
 
18
23
  Organization → Projects → Applications. Each application has a `platform` (ios,
@@ -27,18 +32,25 @@ Commands auto-scope only when exactly one project/app exists. With several, rich
27
32
  interactive mode prompts; JSON and noninteractive modes require explicit scope:
28
33
 
29
34
  - `--project <id>` - scope to a project.
30
- - `--app <id|name>` - scope to an application. `superwall apps use <id|name>` sets
35
+ - `--app <id|name|dashboard link>` - scope to an application. An id or a dashboard
36
+ link (`https://app.superwall.com/<org>/<app>/…`) opens any app the API serves,
37
+ in any organization, with no `--project` and no org switch; the link also
38
+ finds apps that have no paywalls yet. `superwall apps use <id|name|link>` sets
31
39
  the rich UI's default, but automation still passes scope explicitly.
32
40
 
33
- **Everything is org-scoped.** The session pins one active organization, and every
34
- command runs against it: resource listings and creates, `query` (that org's
35
- ClickHouse data), the `asc` proxy (that org's App Store Connect key vault), and
36
- the `asa` proxy (that org's apps' Apple Search Ads credentials).
37
- Single-org accounts resolve it automatically and never think about it. Multi-org
38
- accounts are prompted once in rich mode; automation runs
39
- `superwall orgs use <id|name>` once to persist the choice. The switch is global
40
- and sticky (stored in the session) - to work in another org, switch, run the
41
- commands, and switch back. `superwall whoami --json` shows the active org.
41
+ **There are no organizations to pick.** Every app belongs to one organization,
42
+ and the CLI reads it off the app, so no command takes an org and nothing is
43
+ saved. App- and project-scoped commands find their target through `--app`,
44
+ `--project` or `superwall.lock`. Org-wide endpoints use the org of that same
45
+ app: `query` (its ClickHouse data), `asc` (its App Store Connect keys), `asa`
46
+ (its Apple Search Ads credentials). When your apps span several organizations
47
+ and no app is named, they ask in rich mode and fail in automation with "pass
48
+ --app". A new project goes to your only organization, or asks.
49
+ `superwall apps list` lists every project and app you can open, grouped by
50
+ organization (`organization: { id, name, member }` on each `--json` row). It
51
+ includes organizations you aren't a member of but have opened through `--app`,
52
+ `--project`, a dashboard link or a lock, marked `member: false`; they appear once opened. Never conclude "no access" from `apps list` alone: pass the app's id or
53
+ dashboard link.
42
54
 
43
55
  **Agent contract:** always pass `--json` to resource, ASC, ASA, raw API, query,
44
56
  `bootstrap`, `whoami`, and `doctor` commands. JSON is the stable machine contract,
@@ -47,31 +59,72 @@ uses two-space indentation, never prompts, and returns errors as `{ "error": {
47
59
 
48
60
  ## Resources
49
61
 
62
+ Commands follow the API, Stripe-style: `superwall <resource> [nested] <operation>
63
+ [ids] [--field value]`. Resources: `apps`, `products`, `entitlements` (+
64
+ `grants`), `campaigns` (+ `placements`, `audiences`, `variants`), `paywalls`,
65
+ `users`, `webhooks`, `events`. Each has `list`, `get`, `create`, `update`,
66
+ `delete` where the API does, plus actions the API names (`archive`, `publish`,
67
+ `duplicate`, `readout`, `rotate-secret`, ...). **Run `superwall <resource>
68
+ --help` to see its operations and `superwall <resource> <operation> --help` for
69
+ an operation's flags** - they are read from the live API reference.
70
+
50
71
  ```bash
51
- superwall orgs list --json
52
- superwall orgs use <id|name> # persist the org for org-scoped commands (multi-org accounts)
53
- superwall apps list --json
72
+ superwall apps list --json # every app you can open, grouped by organization
73
+ superwall apps get <app> --json # one app: bundle ID, Apple team, keys, notification URL, SDK reports, revenue provider
54
74
  superwall products list --project <id> --json
55
75
  superwall entitlements list --project <id> --json
56
76
  superwall campaigns list --project <id> --app <id> --json
77
+ superwall campaigns get <campaignId> --json
57
78
  superwall paywalls list --project <id> --app <id> --json
79
+ superwall users subscriptions <appUserId> --app <id> --json
80
+ superwall webhooks list --app <id> --json
81
+ ```
82
+
83
+ - **A flag is a request field.** `--event-name x` sends `event_name`; anything
84
+ else goes in with `-d key=value` (`key:=json` for numbers and objects). A flag
85
+ the endpoint doesn't take is refused before anything is sent.
86
+ - **`--app` fills the ids.** Project, app and organization ids in a path or
87
+ body come from `--app` (or `superwall.lock`); positionals are only the ids of
88
+ the thing itself (`<campaignId> <audienceId>`).
89
+ - **`--dry-run` prints the request instead of sending it.** Deleting,
90
+ archiving, resetting and rotating ask first, and need `--yes` outside a
91
+ terminal: get a person's agreement before passing it.
92
+ - **One way to change a thing.** An app's fields (bundle ID, Apple team ID, URL
93
+ scheme, support URL, revenue provider) are all `apps update` flags:
94
+
95
+ ```bash
96
+ superwall apps update <app> --team-id <teamId> --json
97
+ superwall apps update <app> --bundle-id com.acme.app --json # warns when reported builds would run in test mode
98
+ superwall apps update <app> --revenue-provider open_revenue --json # a person's decision; needs --yes outside a terminal
99
+ superwall campaigns placements create <campaignId> --event-name paywall_trigger --json
100
+ superwall campaigns audiences readout <campaignId> <audienceId> --json
58
101
  ```
59
102
 
60
- `apps list` nests apps under their projects - there is no separate projects
61
- command; `--project <id>` is how you scope when it matters.
103
+ There is no `projects` command: `apps list` nests apps under their projects,
104
+ and `--project <id>` only narrows `--app`.
105
+
106
+ **Large accounts.** Every `list` takes `--search <text>` (matches id, name,
107
+ identifier or bundle id, case-insensitively) and `--limit <n>`. With `--json` a
108
+ list returns every row unless `--limit` caps it; in a terminal it shows 50 and
109
+ says how many more. Search instead of paging through a thousand paywalls:
110
+ `superwall paywalls list --app <id> --search winback --json`. `apps list --search`
111
+ keeps a matching project whole and otherwise only its matching apps. When a
112
+ command can't tell which project or app you mean, the error names the first ten
113
+ with their ids. `bootstrap --app <id>` (or `--project <id>`) loads one project's
114
+ tree instead of the whole account.
62
115
 
63
116
  ### Create
64
117
 
65
118
  ```bash
66
119
  # Apps: an app is a platform of a project. Without --project a new project is spun
67
120
  # up for it; each project allows one app per platform.
68
- superwall apps create "My App" --platform ios [--bundle com.acme.app] [--project <projectId>] --json
121
+ superwall apps create --name "My App" --platform ios [--bundle-id com.acme.app] [--project <projectId>] --json
69
122
 
70
123
  # Entitlements
71
- superwall entitlements create pro --project <id> --json
124
+ superwall entitlements create --identifier pro --project <id> --json
72
125
 
73
126
  # Products (identifier is required; the rest is a full definition, mainly for agents)
74
- superwall products create com.acme.pro.monthly \
127
+ superwall products create --identifier com.acme.pro.monthly \
75
128
  --name "Pro Monthly" \
76
129
  --price 9.99 --currency USD \
77
130
  --period month --period-count 1 \
@@ -79,15 +132,16 @@ superwall products create com.acme.pro.monthly \
79
132
  --entitlement pro \
80
133
  --project <id> --json # repeatable: grant multiple entitlements
81
134
 
82
- # Campaigns (the create arg is a description)
83
- superwall campaigns create "Onboarding paywall" onboarding_complete --project <id> --app <id> --json
135
+ # Campaigns: a description and the placement that triggers it
136
+ superwall campaigns create --description "Onboarding paywall" --placement onboarding_complete --project <id> --app <id> --json
84
137
 
85
- # Placements: attach a placement (event name) to a campaign
86
- superwall campaigns placement <campaignId> onboarding_complete --project <id> --app <id> --json
138
+ # Placements: trigger an existing campaign on another event
139
+ superwall campaigns placements create <campaignId> --event-name onboarding_complete --project <id> --app <id> --json
87
140
  ```
88
141
 
89
- Projects aren't created directly - add the first platform with `apps create` and
90
- a project is created for you.
142
+ `create` always takes flags, never positionals. Projects aren't created
143
+ directly - add the first platform with `apps create` and a project is created
144
+ for you.
91
145
 
92
146
  ### StoreKit config
93
147
 
@@ -98,10 +152,30 @@ superwall products storekit --project <id> [--out Superwall.storekit] --json
98
152
  ## App Store Connect
99
153
 
100
154
  Superwall proxies the App Store Connect API with a signed request - no `.p8`
101
- file or JWT to manage locally. Use credentials the user has already connected
102
- privately. If missing, have the user consult `superwall asc keys set --help`
103
- at their own terminal and complete setup themselves. Do not request, inspect,
104
- or upload private key files or secrets as an agent.
155
+ file or JWT to manage locally. It uses the key the organization has for the
156
+ Apple team. Connecting keys, Apple's server notifications and the revenue
157
+ provider are in the [Apple setup reference](apple-setup.md). Do not request,
158
+ inspect, or upload private key files or secrets as an agent.
159
+
160
+ ```bash
161
+ superwall apps get <app> --json # bundle ID, Apple keys, notification URL, SDK reports, revenue provider
162
+ superwall asc keys import --app <app> --json # reuse a key the organization already has
163
+ superwall asc notification-url check --app <app> --json # what Apple has, and whose it is
164
+ ```
165
+
166
+ An app's own keys are managed with `asc keys`; `superwall apps get <app>` shows
167
+ which it has:
168
+
169
+ ```bash
170
+ superwall asc keys list --app <id> --json # the app's keys
171
+ superwall asc keys import --app <id> --json # reuse a key the organization already has
172
+ superwall asc keys import api_key --app <id> --from <app> --json # ...from that app
173
+ superwall asc keys sources --app <id> --json # keys import could use
174
+ superwall asc keys create api_key --app <id> # signs in to Apple: a person runs this
175
+ superwall asc keys delete purchase_key --app <id> --json
176
+ superwall asc notification-url check --app <id> --json # whose URL Apple sends purchase events to
177
+ superwall asc notification-url set --app <id> --json # set it where Apple has none
178
+ ```
105
179
 
106
180
  Then call ASC through the proxy:
107
181
 
@@ -109,11 +183,10 @@ Then call ASC through the proxy:
109
183
  # Shortcuts
110
184
  superwall asc apps --json
111
185
  superwall asc products <bundle-id | asc-app-id> --json
112
- superwall asc subscriptions com.acme.app --json
186
+ superwall asc subscriptions list com.acme.app --json
113
187
 
114
- # Raw API - a verb + path, or just a path (defaults to GET)
188
+ # Raw API - a verb + path
115
189
  superwall asc get /v1/apps --json
116
- superwall asc /v1/apps --json
117
190
  superwall asc post /v1/... -d key=value -d count:=3 --json
118
191
 
119
192
  # Multiple connected teams
@@ -142,8 +215,10 @@ A malformed body is rejected locally with the exact fix (missing required field,
142
215
  invalid enum value) before it ever reaches Apple's opaque errors. Fix the payload
143
216
  using the reported schema; keep validation enabled.
144
217
 
145
- For end-to-end recipes (creating a subscription with prices and offers) and the
146
- full workflow, see the [App Store Connect reference](asc.md).
218
+ For the resource commands (subscription groups, subscriptions, in-app purchases,
219
+ localizations, prices, offers, availability, review screenshots, submissions)
220
+ and releases (versions, builds, metadata, release), see the
221
+ [App Store Connect reference](asc.md).
147
222
 
148
223
  ## Apple Search Ads
149
224
 
@@ -153,7 +228,7 @@ Nothing is stored locally; the CLI picks the connected iOS app itself, or takes
153
228
  `--app <id>`:
154
229
 
155
230
  ```bash
156
- superwall asa keys list --json # which apps are connected
231
+ superwall asa keys --json # which apps are connected
157
232
 
158
233
  # Resources: asa <resource> <action> [id], scoped with --campaign / --adgroup / --adam-id
159
234
  superwall asa campaigns list --json
@@ -197,11 +272,30 @@ field and message code. For the full resource list and recipes, see the
197
272
 
198
273
  ## Raw API access - any endpoint
199
274
 
275
+ The Superwall API is much bigger than the resource commands: campaigns with
276
+ their audiences, variants and traffic weights, users and their entitlements,
277
+ webhooks, charts, surveys, retention messaging, assets, audit logs. **Find the
278
+ endpoint and its body in `superwall api docs` before calling it.** It reads the
279
+ live OpenAPI spec (cached a day, `--refresh` to fetch now) and needs no login:
280
+
281
+ ```bash
282
+ superwall api docs # every group, with endpoint counts
283
+ superwall api docs variant # search: summary, path, group, description
284
+ superwall api docs experiment # agent words map to API words (experiment → variant, audience)
285
+ superwall api docs /v2/campaigns/123/audiences/9/variants post # one endpoint: params, body, scope, returns
286
+ superwall api docs variant --json # the same, as data
287
+ ```
288
+
289
+ A raw request that fails with a 4xx names the reference entry to read: the
290
+ endpoint's body, the methods its path does take, or a search for a path that
291
+ doesn't exist.
292
+
200
293
  `bootstrap` prints the account overview; the verb commands hit any V2 endpoint
201
294
  with the CLI's session auth (like `stripe get /v1/...`):
202
295
 
203
296
  ```bash
204
297
  superwall bootstrap --json # complete account tree
298
+ superwall bootstrap --app <id> --json # one project's tree
205
299
 
206
300
  superwall get /v2/products -d project_id=25607 --json
207
301
  superwall get /v2/campaigns -d project_id=25607 -d limit=10 --json
@@ -236,8 +330,30 @@ or on stdin. With `--json`, omit the SQL `FORMAT` clause because the CLI request
236
330
  ClickHouse JSON. Without `--json`, any explicit ClickHouse `FORMAT` clause is
237
331
  preserved.
238
332
 
239
- The CLI supplies the current organization ID and authenticated session. The
240
- credential must have `data:read` access. See `data-analytics.md` for exposed
333
+ The CLI supplies the organization ID and authenticated session. The credential
334
+ must have `data:read` access.
335
+
336
+ ### Revenue: always use the app's revenue provider
337
+
338
+ Many apps receive revenue from both the store and RevenueCat, so the same
339
+ purchase can arrive twice. Each app's **revenue provider** decides which one its
340
+ dashboard figures count, and every revenue query must count the same rows or
341
+ its numbers won't match the dashboard. Pass `--app <id>`: the query then gets
342
+ the provider as ClickHouse parameters, `{app:UInt64}`,
343
+ `{revenue_provider:String}` (`open_revenue`, `revenue_cat`, or empty) and
344
+ `{revenue_integrations:Array(String)}`. Filter revenue exactly like this:
345
+
346
+ ```sql
347
+ -- superwall query --file revenue.sql --app <id> --json
348
+ SELECT sum(price) AS revenue
349
+ FROM open_revenue.attributed_events_by_ts_rep FINAL
350
+ WHERE applicationId = {app:UInt64}
351
+ AND (integration IN {revenue_integrations:Array(String)} OR source = 'sdk')
352
+ AND NOT (coalesce(integration, '') = 'revenue_cat' AND store = 'STRIPE')
353
+ ```
354
+
355
+ `--param name=value` adds any other parameter (`{from:Date}`). One query covers
356
+ one app's provider; query apps with different providers separately. See `data-analytics.md` for exposed
241
357
  tables, query patterns, and performance guardrails.
242
358
 
243
359
  ## Utilities