@superwall/cli 2.6.0-beta.2 → 2.6.1

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 (152) hide show
  1. package/README.md +47 -16
  2. package/dist/{apple-Dc5pOPms.js → apple-BE1GBJFP.js} +17 -19
  3. package/dist/{approve-BSbdmOez.js → approve-yRZmvkCj.js} +9 -11
  4. package/dist/{assets-C_RjojkK.js → assets-DTAgbWw0.js} +3 -3
  5. package/dist/auth.d.ts +11 -4
  6. package/dist/auth.js +4 -5
  7. package/dist/base-zc1wl_9b.js +82 -0
  8. package/dist/{billing-B6HK-F_a.js → billing-C1LV4-BN.js} +3 -3
  9. package/dist/{build-DK88pTMW.js → build-CQd-pf7O.js} +35 -16
  10. package/dist/{client-x08fpvay.js → config-DCqRQTJ4.js} +162 -15
  11. package/dist/create-CSHGZDfB.js +18 -0
  12. package/dist/{create-kpqEhqkk.js → create-Costu6UT.js} +9 -9
  13. package/dist/{create-B6-Dr3GZ.js → create-wlCp83IH.js} +41 -41
  14. package/dist/{doctor-DYbm8IKQ.js → doctor-Bd9ffg51.js} +50 -10
  15. package/dist/entry.js +45 -40
  16. package/dist/{environment-BFNzLLPN.js → environment-Dn7irhZr.js} +1 -1
  17. package/dist/{drivers-Dyi-y9Jn.js → existing-BQMB_2AG.js} +305 -8
  18. package/dist/framework-DW5fqjh4.js +65 -0
  19. package/dist/{source-BccdO4aL.js → git-Hf9Wc7Hp.js} +34 -92
  20. package/dist/{held-sKq3xrsT.js → held-D5wSX2Mf.js} +9 -9
  21. package/dist/held-Dmf5SR3p.js +15 -0
  22. package/dist/{install-DsIsif39.js → install-CxyqfKFe.js} +15 -17
  23. package/dist/{integrate-B8eA676b.js → integrate-MkyDDzI5.js} +33 -38
  24. package/dist/{login-BlpfYapG.js → login-B7IqDafm.js} +3 -3
  25. package/dist/{login-Blhxi20A.js → login-BMHDhxAx.js} +8 -9
  26. package/dist/login-Cp0-BgDZ.js +13 -0
  27. package/dist/{lookup-Dg55W9S7.js → lookup-DkcT4E-5.js} +28 -4
  28. package/dist/{migrate-DoRb9jmA.js → migrate-CdFoZipj.js} +66 -45
  29. package/dist/{notification-url-D82msWF5.js → notification-url-D6KKeXnk.js} +4 -4
  30. package/dist/{open-BAqLpTSI.js → open-COJE6ryI.js} +2 -2
  31. package/dist/{org-C4G7WjTV.js → org-BV8wwxwc.js} +4 -4
  32. package/dist/{organization-CmuQwcKN.js → organization-9R_1PJKk.js} +4 -4
  33. package/dist/{orgs-1OzwUtpT.js → orgs-ltP8H0Nl.js} +1 -2
  34. package/dist/{paths-gBbqgkS7.js → paths-Cb1RfjaX.js} +1 -1
  35. package/dist/{playbook-BKqlv77S.js → playbook-CVGolez9.js} +10 -14
  36. package/dist/{products-Cqq59DBQ.js → products-CJq_iXv5.js} +1 -1
  37. package/dist/{promote-D0i8A0CO.js → promote-B_HnFEbX.js} +27 -28
  38. package/dist/{pull-DgQ_UmGv.js → pull-DF4KYVcP.js} +72 -26
  39. package/dist/pull-JxiMyRwY.js +30 -0
  40. package/dist/{pull-CiIrJ5ik.js → pull-lYRULo4v.js} +33 -39
  41. package/dist/push-B5py7h5y.js +29 -0
  42. package/dist/{push-7N4XIVtg.js → push-BZN1Qpkq.js} +23 -12
  43. package/dist/{push-BWsXO7FN.js → push-BnllH2Rd.js} +8 -7
  44. package/dist/push-DHlUMkbf.js +21 -0
  45. package/dist/registry-BGEYCWyD.js +22 -0
  46. package/dist/{registry-aAR_8VOw.js → registry-CqePfigB.js} +1287 -902
  47. package/dist/{resolve-CcOpO_5s.js → resolve-B4bd3Qjl.js} +4 -4
  48. package/dist/{resources-DNwvf8rg.js → resources-BaURbSpY.js} +15 -2
  49. package/dist/{run-tVYJ3V5j.js → run-Bme4Egyl.js} +15 -17
  50. package/dist/{scan-dv0rrY4C.js → scan-DugxddUU.js} +1 -1
  51. package/dist/scan-J2DILUNE.js +4 -0
  52. package/dist/{scope-ehZ7L1nj.js → scope-Cg1AdAfO.js} +33 -3
  53. package/dist/{scope-BXoQo30_.js → scope-DDYLQeZw.js} +24 -18
  54. package/dist/screenshot-file-Dix2Qynm.js +127 -0
  55. package/dist/{sdk-DEfQttek.js → sdk-BFunw4Hc.js} +1 -1
  56. package/dist/{framework-JFLjmD5Y.js → selection-C439nEhn.js} +4 -54
  57. package/dist/{series-D2ZpZ8cx.js → series-B8NJK4yS.js} +1 -1
  58. package/dist/{server-CcZGdYjE.js → server-C_aMxzvS.js} +40 -18
  59. package/dist/server-Cif9w5lM.js +33 -0
  60. package/dist/{session-dHBtgSN0.js → session-B7frlXXQ.js} +1 -1
  61. package/dist/{base-83ZTv6up.js → session-CfG3gzko.js} +8 -83
  62. package/dist/session-DvaPyOuH.js +5 -0
  63. package/dist/{migration-BUedsREQ.js → setup-DQEasPhx.js} +290 -28
  64. package/dist/skills/index.json +5 -0
  65. package/dist/skills/superwall/SKILL.md +37 -10
  66. package/dist/skills/superwall/references/api.md +66 -21
  67. package/dist/skills/superwall/references/asa.md +109 -64
  68. package/dist/skills/superwall/references/dashboard-links.md +65 -28
  69. package/dist/skills/superwall/references/data-analytics.md +1 -1
  70. package/dist/skills/superwall/workflows/dashboard/setup.md +15 -5
  71. package/dist/skills/superwall/workflows/integrate/flutter.md +9 -7
  72. package/dist/skills/superwall-framework/SKILL.md +248 -36
  73. package/dist/skills/superwall-framework/references/cli.md +98 -7
  74. package/dist/skills/superwall-framework/references/examples.md +2 -2
  75. package/dist/skills/superwall-framework/references/layout.md +30 -2
  76. package/dist/skills/superwall-framework/references/migrate-from-editor.md +5 -0
  77. package/dist/skills/superwall-framework/references/migrate-from-native.md +5 -0
  78. package/dist/skills/teleport/SKILL.md +154 -0
  79. package/dist/skills/teleport/references/experiments.md +328 -0
  80. package/dist/skills/teleport/references/setup.md +157 -0
  81. package/dist/{skills-Q7xB784d.js → skills-DnegE1A6.js} +139 -9
  82. package/dist/{skills-Bqz2l_bx.js → skills-MmF7IyTg.js} +8 -12
  83. package/dist/source-DQs6iLtC.js +82 -0
  84. package/dist/{source-push-CG948HrX.js → source-push-MbJjh4Ki.js} +38 -14
  85. package/dist/{spinner-IA6hV8nI.js → spinner-Dcr-Dqdi.js} +7 -5
  86. package/dist/{starter-BtUUQWhd.js → starter-BlJ_InZJ.js} +2 -2
  87. package/dist/{status-CB_MrFu5.js → status-DHRxg1ZA.js} +9 -11
  88. package/dist/{output-Ggzq5_-t.js → storage-DdIAHolY.js} +40 -1
  89. package/dist/storekit-De998QOt.js +203 -0
  90. package/dist/storekit-iBCWmeKn.js +15 -0
  91. package/dist/{bind-DcWIIPgk.js → theme-BrUrye-c.js} +29 -6
  92. package/dist/token-CKCBQ4I8.js +100 -0
  93. package/dist/tools-skills/animate-onboarding/SKILL.md +1 -1
  94. package/dist/tools-skills/mobile-design/SKILL.md +1 -1
  95. package/dist/tools-skills/onboarding-questions/SKILL.md +1 -1
  96. package/dist/tools-skills/superwall/SKILL.md +43 -17
  97. package/dist/tools-skills/superwall/references/api.md +74 -24
  98. package/dist/tools-skills/superwall/references/asa.md +109 -64
  99. package/dist/tools-skills/superwall/references/dashboard-links.md +65 -28
  100. package/dist/tools-skills/superwall/references/data-analytics.md +1 -1
  101. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +4 -3
  102. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +21 -8
  103. package/dist/tools-skills/superwall/workflows/integrate/flutter.md +9 -7
  104. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +4 -3
  105. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +2 -2
  106. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +4 -3
  107. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +4 -3
  108. package/dist/tools-skills/superwall-editor/SKILL.md +2 -3
  109. package/dist/tools-skills/teleport/SKILL.md +154 -0
  110. package/dist/tools-skills/teleport/references/experiments.md +328 -0
  111. package/dist/tools-skills/teleport/references/setup.md +157 -0
  112. package/dist/tools.d.ts +1 -1
  113. package/dist/tools.js +1232 -746
  114. package/dist/{try-CS3jLyoP.js → try-C8QQbG0b.js} +17 -19
  115. package/dist/{lock-DgSx-p8Y.js → types-Dc9U_4kp.js} +86 -80
  116. package/dist/upgrade-CYFdpVpi.js +27 -0
  117. package/dist/upgrade-D0thxCA4.js +348 -0
  118. package/package.json +11 -3
  119. package/dist/config-CGcG7GOt.js +0 -113
  120. package/dist/create-Du8Fx7W5.js +0 -20
  121. package/dist/existing-WQ3pz94o.js +0 -97
  122. package/dist/held-DmOhszHR.js +0 -17
  123. package/dist/log-C0MDCfA2.js +0 -62
  124. package/dist/login-D9jfRO8w.js +0 -17
  125. package/dist/pull-CO5HlqBe.js +0 -36
  126. package/dist/push-BIhGDNpL.js +0 -30
  127. package/dist/push-BgqTddLA.js +0 -22
  128. package/dist/run-B-YoyB-a.js +0 -100
  129. package/dist/scan-BU41gcQY.js +0 -4
  130. package/dist/screenshot-file-XAS0Xy0e.js +0 -16
  131. package/dist/server-BemmM1FV.js +0 -29
  132. package/dist/session-4aITGsF1.js +0 -6
  133. package/dist/setup-m94dpT3t.js +0 -217
  134. package/dist/spawn-DmmmHIP-.js +0 -71
  135. package/dist/storage-pR0Wb0d9.js +0 -41
  136. package/dist/storekit-BMxyYAHj.js +0 -17
  137. package/dist/storekit-CQnwlpKV.js +0 -47
  138. package/dist/telemetry-DU56L7Cy.js +0 -56
  139. package/dist/theme-DUsCh-Vd.js +0 -25
  140. package/dist/token-BbUeExGJ.js +0 -70
  141. package/dist/upgrade-CKn88PZD.js +0 -206
  142. package/dist/upgrade-DfD3-ClG.js +0 -7
  143. /package/dist/{browser-Bp3yRKlU.js → browser-BVjaf98V.js} +0 -0
  144. /package/dist/{client-BJQXl62Q.js → client-BwYhzITp.js} +0 -0
  145. /package/dist/{design-lint-CiFc78aM.js → design-lint-mgO-2SGS.js} +0 -0
  146. /package/dist/{devtools-ByZ6XYnn.js → devtools-B6Vp6HMy.js} +0 -0
  147. /package/dist/{input-MDd67UIp.js → input-DOT_2Zvb.js} +0 -0
  148. /package/dist/{project-NoMtbMyl.js → project-BomArwSj.js} +0 -0
  149. /package/dist/{reports-HYVp169R.js → reports-hbxsd3Zo.js} +0 -0
  150. /package/dist/{storage-Bdz5AmqS.d.ts → storage-Bh3wT1Rn.d.ts} +0 -0
  151. /package/dist/{timing-Ca0TXY-A.js → timing-BKEEIBij.js} +0 -0
  152. /package/dist/{ui-D_qf3Gvw.js → ui-hFgji1e8.js} +0 -0
@@ -1,8 +1,10 @@
1
1
  # CLI Reference
2
2
 
3
3
  CLI commands use the installed `superwall` binary. The user installs it once
4
- with `npm install --global superwall`; agents must not automatically install or
5
- upgrade it. Use `superwall login` once for device-flow OAuth. The saved session
4
+ with `npm install --global superwall`; agents must not install or upgrade it on
5
+ their own. The one exception is the upgrade prompt the CLI prints on stderr
6
+ (`Update available X → Y · run <command>`, or a `Major update available`
7
+ block): see SKILL.md › When the CLI prints an upgrade prompt. Use `superwall login` once for device-flow OAuth. The saved session
6
8
  lives in `~/.superwall`.
7
9
 
8
10
  ```bash
@@ -98,8 +100,19 @@ superwall apps update <app> --bundle-id com.acme.app --json # warns when repor
98
100
  superwall apps update <app> --revenue-provider open_revenue --json # a person's decision; needs --yes outside a terminal
99
101
  superwall campaigns placements create <campaignId> --event-name paywall_trigger --json
100
102
  superwall campaigns audiences readout <campaignId> <audienceId> --json
103
+ superwall campaigns audiences reorder <campaignId> -d 'audience_ids:=[<audienceId>,<audienceId>]' --json # match order; existing users may switch audience
104
+ superwall campaigns variants weights <campaignId> <audienceId> -d 'weights:=[{"variant_id":"<variantId>","percentage":100}]' --json
101
105
  ```
102
106
 
107
+ `campaigns variants weights` replaces all of an audience's treatment-variant
108
+ weights in one call. Every treatment must be in `weights`, each `percentage` a
109
+ whole number; the holdout, if any, is auto-balanced to 100 minus their sum. It
110
+ changes live traffic. To move a treatment to 100%, send this one call instead
111
+ of patching each variant's percentage in turn, which takes several calls in the
112
+ right order (holdout to 0 first) and leaves the split half-changed in between.
113
+ `campaigns audiences reorder` sets the order audiences are matched in; pass
114
+ every audience id, first match first.
115
+
103
116
  There is no `projects` command: `apps list` nests apps under their projects,
104
117
  and `--project <id>` only narrows `--app`.
105
118
 
@@ -130,8 +143,8 @@ tree instead of the whole account.
130
143
  # up for it; each project allows one app per platform.
131
144
  superwall apps create --name "My App" --platform ios [--bundle-id com.acme.app] [--project <projectId>] --json
132
145
 
133
- # Entitlements
134
- superwall entitlements create --identifier pro --project <id> --json
146
+ # Entitlements: --app puts it on that app, so products on the same app can grant it
147
+ superwall entitlements create --identifier pro --app <id> --json
135
148
 
136
149
  # Products (identifier is required; the rest is a full definition, mainly for agents)
137
150
  superwall products create --identifier com.acme.pro.monthly \
@@ -140,7 +153,23 @@ superwall products create --identifier com.acme.pro.monthly \
140
153
  --period month --period-count 1 \
141
154
  --trial-days 7 \
142
155
  --entitlement pro \
143
- --project <id> --json # repeatable: grant multiple entitlements
156
+ --app <id> --json # repeatable: grant multiple entitlements
157
+
158
+ # --entitlement takes an entitlement id or identifier on the product's app; a
159
+ # mismatch is refused with the fix. CLI 2.2.1 and older take only the numeric
160
+ # id from `superwall entitlements list --json`; run `superwall upgrade` once a
161
+ # newer CLI is out.
162
+
163
+ # --price is in the currency's main unit (9.99 USD, 1200 JPY); the CLI sends the
164
+ # API whole minor units (999, 1200). A raw `superwall post /v2/products` takes
165
+ # `price[amount]` in minor units already: 'price[amount]:=999', never 9.99.
166
+
167
+ # Custom store products: --app takes the custom store's id or name, or
168
+ # --store custom uses the project's default custom store. CLI 2.5.2 and older
169
+ # can't find a custom store by --app; there, post /v2/products with
170
+ # -d store=custom -d application_id=<store id>.
171
+ superwall products create --identifier pro_monthly --app <custom store id> \
172
+ --price 9.99 --period month --json
144
173
 
145
174
  # Campaigns: a description and the placement that triggers it
146
175
  superwall campaigns create --description "Onboarding paywall" --placement onboarding_complete --project <id> --app <id> --json
@@ -159,6 +188,13 @@ for you.
159
188
  superwall products storekit --project <id> [--out Superwall.storekit] --json
160
189
  ```
161
190
 
191
+ `--json` answers `{ path, products, skipped: [{ id, identifier, reason }] }`:
192
+ `products` is how many were written, `id` is the Superwall product id, and
193
+ `reason` is `other_store`, `no_price` or `no_identifier`. Price a `no_price`
194
+ product with
195
+ `superwall products update <id> --price '{"amount":<minor units>,"currency":"USD"}'`
196
+ (the warning prints that command for each one), then export again.
197
+
162
198
  ## App Store Connect
163
199
 
164
200
  Superwall proxies the App Store Connect API with a signed request - no `.p8`
@@ -232,29 +268,36 @@ and releases (versions, builds, metadata, release), see the
232
268
 
233
269
  ## Apple Search Ads
234
270
 
235
- Superwall proxies the Apple Ads Campaign Management API v5 with the credentials
236
- connected in the dashboard (app → Integrations → Apple Search Ads → Advanced).
237
- Nothing is stored locally; the CLI picks the connected iOS app itself, or takes
238
- `--app <id>`:
271
+ Superwall proxies the Apple Ads Platform API v1 (`api.ads.apple.com/v1`) with
272
+ the credentials connected in the dashboard (app → Integrations → Apple Search
273
+ Ads → Advanced). Nothing is stored locally; the CLI picks the connected iOS app
274
+ itself, or takes `--app <id>`:
239
275
 
240
276
  ```bash
241
- superwall asa keys --json # which apps are connected
277
+ superwall asa keys list --json # which apps are connected
242
278
 
243
- # Resources: asa <resource> <action> [id], scoped with --campaign / --adgroup / --adam-id
279
+ # Resources: asa <resource> <action> [id]. Resources are top level; on lists,
280
+ # --campaign / --adgroup / --adam-id are filters.
244
281
  superwall asa campaigns list --json
245
282
  superwall asa campaigns get <id> --json
246
- superwall asa campaigns find --field status --op EQUALS --values ENABLED --all --json
283
+ superwall asa campaigns list --field status --op EQUALS --values ENABLED --order-by name:asc --all --json
247
284
  superwall asa adgroups list --campaign <id> --json
248
- superwall asa keywords list --campaign <id> --adgroup <id> --all --json
285
+ superwall asa keywords list --adgroup <id> --all --json
286
+ superwall asa keywords update <id>,<id> --status PAUSED --json # ids only, no --campaign/--adgroup
249
287
  superwall asa reports campaigns --start 2025-01-01 --end 2025-01-31 --json
250
288
 
251
- # Raw API - a verb + path, or just a path (defaults to GET); /api/v5 is implied
252
- superwall asa get /campaigns --json
253
- superwall asa /campaigns --json
254
- superwall asa post /campaigns/find --body '{"conditions":[]}' --json
289
+ # Full QueryRequest: filters, sorting, pagination {offset, pageSize}
290
+ superwall asa campaigns list --query '{"filters":[{"field":"status","operator":"EQUALS","value":"ENABLED"}],"pagination":{"offset":0,"pageSize":100}}' --json
291
+
292
+ # Raw API - a verb + path, or just a path (defaults to GET). /v1 is added;
293
+ # a path starting with /v1 or /api/ passes through as written.
294
+ superwall asa get /campaigns/<id> --json
295
+ superwall asa /me --json
296
+ superwall asa post /campaigns/query --body '{"filters":[]}' --json
255
297
 
256
- # Several Apple Search Ads orgs behind one API user
257
- superwall asa campaigns list --org-id <appleOrgId> --json
298
+ # Several ad accounts behind one API user (sends X-AP-Context: adAccountId=).
299
+ # Without it the only account the key reaches is used; with several, it asks.
300
+ superwall asa campaigns list --ad-account-id <adAccountId> --json
258
301
  ```
259
302
 
260
303
  ### Request schema & docs — do this before every write
@@ -266,14 +309,15 @@ superwall asa docs campaigns create # Apple's own page: fields, enums, e
266
309
  ```
267
310
 
268
311
  Writes take typed flags (money flags resolve the account's currency from
269
- `/acls`, or pass `--currency`), `-d key=value` / `key:=json` for any other
312
+ the ad account in `/v1/acls`, or pass `--currency`), `-d key=value` / `key:=json` for any other
270
313
  field, or `--body <json|@file|@->` for the whole payload:
271
314
 
272
315
  ```bash
273
316
  superwall asa campaigns create --name "Launch" --adam-id <adamId> --countries US,CA \
274
- --daily-budget 50 --supply-sources APPSTORE_SEARCH_RESULTS --ad-channel-type SEARCH --json
275
- superwall asa keywords update <id> --campaign <id> --adgroup <id> --bid 2 --json
276
- superwall asa keywords delete <id,id,id> --campaign <id> --adgroup <id> --json
317
+ --daily-budget 50 --supply-sources APPSTORE --supply-placements APPSTORE_SEARCH_RESULTS \
318
+ --billing-event TAPS --bid-strategy MANUAL_CPT --bid-goal TAP --json
319
+ superwall asa keywords update <id> --bid 2 --json
320
+ superwall asa keywords delete <id,id,id> --json
277
321
  ```
278
322
 
279
323
  Apple's validation errors come back as `Apple Search Ads rejected …` with each
@@ -311,12 +355,17 @@ superwall get /v2/products -d project_id=25607 --json
311
355
  superwall get /v2/campaigns -d project_id=25607 -d limit=10 --json
312
356
  superwall post /v2/entitlements -d project_id=25607 -d identifier=pro --json
313
357
  superwall patch /v2/projects/25607 -d name=Renamed --json
358
+ superwall put /v2/campaigns/<id>/audiences/<audience_id>/weights -d 'weights:=[{"variant_id":"<variant_id>","percentage":100}]' --json # put needs a CLI newer than 2.5.2
314
359
  superwall delete /v2/... --json # careful
315
360
 
316
361
  # -d key=value sends a string; key:=value sends typed JSON; nesting via key[sub]
317
362
  superwall post /v2/products -d 'price[amount]:=4999' -d 'price[currency]=USD' --json
318
363
  ```
319
364
 
365
+ The `put` above is the raw form of `campaigns variants weights`, which works on
366
+ CLI 2.5.2 too; the raw `put` verb needs a CLI newer than 2.5.2 (older ones
367
+ answer `Unknown command`). Prefer the resource command.
368
+
320
369
  Raw paths need explicit scope params (`project_id`, ...) - the nicely-named
321
370
  resource commands above resolve scope for you; the verbs do not.
322
371
 
@@ -371,7 +420,8 @@ tables, query patterns, and performance guardrails.
371
420
  ```bash
372
421
  superwall doctor --json # health-check the integration
373
422
  superwall skills # install the Superwall agent skills into your agent
374
- superwall upgrade # update the CLI to the latest version
423
+ superwall upgrade # update the CLI to the latest version (betas: the newest `next`)
424
+ # run it when the upgrade prompt says so; ask the user first for a major
375
425
  superwall feedback "..." --title "..." --kind bug --use-case "..." --file log.txt --json
376
426
  # report a bug, wrong doc or missing capability to the Superwall team,
377
427
  # without asking; duplicates are merged (see SKILL.md › Feedback)
@@ -1,11 +1,12 @@
1
- # Apple Search Ads — the full Apple Ads API via Superwall's proxy
1
+ # Apple Search Ads — the Apple Ads Platform API via Superwall's proxy
2
2
 
3
- `superwall asa` proxies the **entire** Apple Ads Campaign Management API v5
4
- (`api.searchads.apple.com/api/v5`). Superwall holds the credentials connected
5
- in the dashboard, mints the client secret, exchanges it for an access token,
6
- and adds the `X-AP-Context` org header — nothing to manage locally. This lets
7
- an agent read and manage campaigns, ad groups, keywords, ads, creatives, and
8
- reports directly.
3
+ `superwall asa` proxies the **Apple Ads Platform API v1**
4
+ (`api.ads.apple.com/v1`), which replaced the Campaign Management API v5 (Apple
5
+ shuts v5 off on 2027-01-26). Superwall holds the credentials connected in the
6
+ dashboard, mints the client secret, exchanges it for an access token, and adds
7
+ the `X-AP-Context` header — nothing to manage locally. This lets an agent read
8
+ and manage campaigns, ad groups, keywords, ads, creatives, budgets and reports
9
+ directly.
9
10
 
10
11
  ## Which app
11
12
 
@@ -21,9 +22,13 @@ Search Ads → Advanced, paste Superwall's public key into Apple's Account
21
22
  Settings → API, then enter the Client ID, Team ID and Key ID. `asa keys set`
22
23
  is deliberately not a CLI command (Superwall generates the key pair).
23
24
 
24
- If the Apple API user can reach several Apple Search Ads orgs, pass
25
- `--org-id <appleOrgId>` (`superwall asa acls --json` lists them); otherwise the
26
- proxy uses the API user's parent org.
25
+ ## Which ad account
26
+
27
+ Every request is scoped to one Apple Ads ad account. Pass
28
+ `--ad-account-id <id>` to choose it (sent as `X-AP-Context: adAccountId=<id>`;
29
+ `superwall asa acls --json` lists the accounts the key reaches). Without it,
30
+ the only ad account the key reaches is used; when it reaches several, the
31
+ command fails and asks for `--ad-account-id`.
27
32
 
28
33
  ## Docs access — do this before every write
29
34
 
@@ -41,89 +46,115 @@ superwall asa docs "impression" # search by keyword
41
46
  ## Command shape
42
47
 
43
48
  ```
44
- superwall asa <resource> <action> [id] [--campaign <id>] [--adgroup <id>] [--adam-id <id>] --json
49
+ superwall asa <resource> <action> [id] --json
45
50
  ```
46
51
 
52
+ Resources are top level, as in v1: a keyword, ad or ad group is addressed by
53
+ its own id, never through its campaign. On lists, `--campaign`, `--adgroup` and
54
+ `--adam-id` are filters, not path parts.
55
+
47
56
  | Resource | Actions |
48
57
  |---|---|
49
- | `campaigns` | `list`, `get <id>`, `find`, `create`, `update <id>`, `delete <id>` |
50
- | `adgroups` | same, scoped with `--campaign` (`find` without `--campaign` searches the whole org) |
51
- | `keywords` | `list`, `get`, `find` (`--campaign`, optional `--adgroup`), `create`, `update [id]`, `delete <id[,id…]>` |
52
- | `negative-keywords` | same; `--adgroup` switches from campaign-level to ad-group-level; `find --adgroup-level` |
53
- | `ads` | `list`, `get`, `find`, `create`, `update`, `delete` (`--campaign --adgroup`; `find` scopes down to org level) |
54
- | `creatives` | `list`, `get`, `find`, `create` |
55
- | `product-pages` | `list --adam-id`, `get <id> --adam-id`, `locales <id> --adam-id`, `countries`, `device-sizes` |
56
- | `ad-rejections` | `find`, `get <id>`, `assets --adam-id` |
57
- | `reports` | `campaigns`, `adgroups`, `keywords`, `searchterms`, `ads` (`--start --end`, `--campaign`, optional `--adgroup`) |
58
- | `impression-share` | `list`, `get <id>`, `create` |
59
- | `apps` | `search <query>`, `eligibility <adam-id>`, `get <adam-id>`, `localized <adam-id>` |
60
- | `geo` | `search <query>`, `get <id> --entity <Country\|AdminArea\|Locality>` |
61
- | `budget-orders` | `list`, `get <id>`, `create --body`, `update <id> --body` |
62
- | `acls`, `me` | the API user's orgs and identity |
58
+ | `campaigns` | `list`, `get <id>`, `create`, `update <id>`, `delete <id>`, `limited-reasons <id>` |
59
+ | `adgroups` | `list [--campaign]`, `get <id>`, `create --campaign`, `update <id>`, `delete <id>` |
60
+ | `keywords` | `list [--campaign] [--adgroup]`, `get <id>`, `create --adgroup`, `update <id[,id…]>`, `delete <id[,id…]>` |
61
+ | `negative-keywords` | same; `create --campaign` for campaign level, add `--adgroup` for ad group level |
62
+ | `ads` | `list [--campaign] [--adgroup]`, `get <id>`, `create --adgroup`, `update <id>`, `delete <id>` |
63
+ | `creatives` | `list`, `get <id>`, `create`, `update <id>`, `delete <id>` |
64
+ | `assets` | `list [--adam-id]`, `get <id>`, `delete <id>` |
65
+ | `product-pages` | `list --adam-id`, `get <id>`, `locales <id>` |
66
+ | `ad-rejections` | `list [--adam-id]`, `get <id>` |
67
+ | `reports` | `campaigns`, `adgroups`, `keywords`, `searchterms`, `ads` (`--start --end`; all but `campaigns` need `--campaign`) |
68
+ | `brand-reports` | the same five, for Apple Maps (business brand) campaigns |
69
+ | `insights` | `impression-share`, `search-term-popularity` |
70
+ | `apps` | `search <query>`, `eligibility <adam-id>`, `get <adam-id>`, `localized <adam-id>`, `languages` |
71
+ | `geo` | `search <query>`, `get <id[,id…]> --entity <Country\|AdminArea\|Locality>` |
72
+ | `budget-orders` | `list`, `get <id>`, `create`, `update <id>`, `delete <id>` |
73
+ | `recommendations` | `target-cpas`, `daily-budgets`, and `apply-…` / `dismiss-…` for each |
74
+ | `suggestions` | `keywords`, `phrases`, `categories`, `target-cpa` |
75
+ | `change-history` | `list`, `get <id>` |
76
+ | `brands` | `list`, `get <id>`, `categories`, `category <id>`, `rejections` |
77
+ | `ad-accounts` | `get <id>`, `create`, `update <id>`, `resources` |
78
+ | `orgs`, `acls`, `me` | the organization, the ad accounts the key reaches, the API user |
63
79
 
64
80
  Raw escape hatch for anything else: `superwall asa get|post|put|delete /path
65
- [-d k=v] [--body json]`, or `superwall asa /path` (GET). `/api/v5` is implied.
81
+ [-d k=v] [--body json]`, or `superwall asa /path` (GET). `/v1` is added to the
82
+ path; a path that already starts with `/v1` or `/api/` is sent as written.
83
+
84
+ ```bash
85
+ superwall asa /me --json
86
+ superwall asa post /campaigns/query --body '{"filters":[]}' --json
87
+ ```
66
88
 
67
89
  ## Reading
68
90
 
91
+ Every list is a `POST …/query` with Apple's QueryRequest (`filters`,
92
+ `sorting`, `pagination { offset, pageSize }`). Build it with the one-filter
93
+ shorthand `--field/--op/--values`, sort with `--order-by field[:asc|desc]`,
94
+ page with `--limit`/`--offset`, or pass the whole request with
95
+ `--query <json|@file|@->`. Shorthand, scope flags and `--query` filters are
96
+ combined. `--all` walks every page until Apple's `totalCount`; the output is
97
+ `{ result: [...], pagination }` like a single page.
98
+
69
99
  ```bash
70
100
  superwall asa campaigns list --limit 50 --json
71
101
  superwall asa campaigns list --all --json # walks every page
72
- superwall asa campaigns find --field status --op EQUALS --values ENABLED --json
73
- superwall asa campaigns find --selector '{"conditions":[{"field":"name","operator":"STARTSWITH","values":["US"]}],"orderBy":[{"field":"name","sortOrder":"ASCENDING"}]}' --all --json
74
- superwall asa campaigns get <id> --fields id,name,status --json
75
- superwall asa keywords find --campaign <id> --field matchType --op EQUALS --values EXACT --all --json
102
+ superwall asa campaigns list --field status --op EQUALS --values ENABLED --order-by name:desc --json
103
+ superwall asa campaigns list --query '{"filters":[{"field":"name","operator":"STARTS_WITH","value":"US"}],"sorting":[{"field":"name","order":"ASC"}]}' --all --json
104
+ superwall asa campaigns get <id> --json
105
+ superwall asa adgroups list --campaign <id> --json
106
+ superwall asa keywords list --adgroup <id> --field matchType --op EQUALS --values EXACT --all --json
76
107
  ```
77
108
 
78
- `find` takes Apple's selector: `--selector <json|@file|@->` for the whole
79
- thing, or the one-condition shorthand `--field/--op/--values` plus
80
- `--order-by field[:asc|desc]`, `--fields`, `--limit`, `--offset`. `--all` pages
81
- until Apple's `totalResults` is reached; the output is `{ data: [...],
82
- pagination }` like a single page.
109
+ `asa docs <resource> list` links Apple's page, which lists the fields each
110
+ query can filter and sort on, with their operators.
83
111
 
84
112
  ## Writing
85
113
 
86
- Before writes, confirm the exact account, campaign and ad group. Changes to
114
+ Before writes, confirm the exact ad account, campaign and ad group. Changes to
87
115
  budgets, bids, billing or enabled campaigns can spend money: show the proposed
88
116
  change, currency and spending limit and obtain specific user approval. Ask for
89
117
  specific approval before deletions or access changes. Examples below are not
90
118
  permission to execute those actions.
91
119
 
92
120
  Typed flags map to Apple's field names (`asa docs <resource>` shows the
93
- mapping). Money flags (`--budget`, `--daily-budget`, `--bid`, `--default-bid`,
94
- `--cpa-goal`) become `{ amount, currency }`; the currency comes from
95
- `--currency` or the account's `/acls` entry. Anything else goes through
96
- `-d key=value` (`key:=value` for numbers/booleans/JSON, `key[sub]` nesting) or
97
- `--body`.
121
+ mapping, including nested ones such as `--daily-budget` → `dailyBudget.value`).
122
+ Money flags (`--daily-budget`, `--bid`, `--amount`) become
123
+ `{ amount, currency }`; the currency comes from `--currency` or the ad
124
+ account's `/acls` entry. Anything else goes through `-d key=value`
125
+ (`key:=value` for numbers/booleans/JSON, `key[sub]` nesting) or `--body`.
126
+ Campaign and budget order creates take the ad account id from
127
+ `--ad-account-id`, or the only account the key reaches.
98
128
 
99
129
  ```bash
100
- # Campaign (Apple requires supplySources and adChannelType alongside the budget)
130
+ # Campaign
101
131
  superwall asa campaigns create --name "Launch" --adam-id <adamId> --countries US,CA \
102
- --daily-budget 50 --supply-sources APPSTORE_SEARCH_RESULTS --ad-channel-type SEARCH \
103
- --billing-event TAPS --json
132
+ --daily-budget 50 --supply-sources APPSTORE --supply-placements APPSTORE_SEARCH_RESULTS \
133
+ --billing-event TAPS --bid-strategy MANUAL_CPT --bid-goal TAP --json
104
134
 
105
135
  # Pause it
106
136
  superwall asa campaigns update <id> --status PAUSED --json
107
137
 
108
- # Ad group
109
- superwall asa adgroups create --campaign <id> --name "Exact match" --default-bid 1.50 \
138
+ # Ad group (--bid is the default bid)
139
+ superwall asa adgroups create --campaign <id> --name "Exact match" --pricing-model CPT --bid 1.50 \
110
140
  --start 2025-06-01T00:00:00.000 --search-match=false --json
111
141
 
112
- # Keywords are bulk: one from flags, or many from --body
113
- superwall asa keywords create --campaign <id> --adgroup <id> --text "grammar checker" --match-type EXACT --bid 1.25 --json
114
- superwall asa keywords create --campaign <id> --adgroup <id> \
115
- --body '[{"text":"grammar","matchType":"BROAD","bidAmount":{"amount":"1","currency":"USD"}},{"text":"spell check","matchType":"EXACT"}]' --json
116
- superwall asa keywords update <id> --campaign <id> --adgroup <id> --bid 2 --json
117
- superwall asa keywords delete <id> --campaign <id> --adgroup <id> --json # one → DELETE
118
- superwall asa keywords delete <id,id,id> --campaign <id> --adgroup <id> --json # several → bulk
142
+ # Keywords: one from flags, or many from --body (sent to bulk-create as items)
143
+ superwall asa keywords create --adgroup <id> --text "grammar checker" --match-type EXACT --bid 1.25 --json
144
+ superwall asa keywords create \
145
+ --body '[{"adGroupId":<id>,"text":"grammar","matchType":"BROAD"},{"adGroupId":<id>,"text":"spell check","matchType":"EXACT"}]' --json
146
+ superwall asa keywords update <id> --bid 2 --json # one → PUT /keywords/{id}
147
+ superwall asa keywords update <id,id> --status PAUSED --json # several → bulk-update
148
+ superwall asa keywords delete <id> --json # one → DELETE
149
+ superwall asa keywords delete <id,id,id> --json # several → bulk-delete
119
150
 
120
151
  # Negative keywords: campaign level, or ad group level with --adgroup
121
152
  superwall asa negative-keywords create --campaign <id> --text free --match-type BROAD --json
122
- superwall asa negative-keywords create --campaign <id> --adgroup <id> --text free --json
153
+ superwall asa negative-keywords create --campaign <id> --adgroup <id> --text free --match-type BROAD --json
123
154
 
124
155
  # Creative + ad (custom product page)
125
156
  superwall asa creatives create --adam-id <adamId> --type CUSTOM_PRODUCT_PAGE --product-page-id <ppId> --name "Holiday" --json
126
- superwall asa ads create --campaign <id> --adgroup <id> --creative-id <creativeId> --name "Holiday ad" --json
157
+ superwall asa ads create --adgroup <id> --creative-id <creativeId> --name "Holiday ad" --json
127
158
  ```
128
159
 
129
160
  Apple's validation failures come back as
@@ -136,20 +167,21 @@ Read the field, fix the flag, retry.
136
167
  superwall asa reports campaigns --start 2025-01-01 --end 2025-01-31 --json
137
168
  superwall asa reports campaigns --start 2025-01-01 --end 2025-01-31 --granularity WEEKLY --group-by countryOrRegion --json
138
169
  superwall asa reports adgroups --campaign <id> --start 2025-01-01 --end 2025-01-31 --json
139
- superwall asa reports keywords --campaign <id> [--adgroup <id>] --start 2025-01-01 --end 2025-01-31 --json
170
+ superwall asa reports keywords --campaign <id> --adgroup <id> --start 2025-01-01 --end 2025-01-31 --json
140
171
  superwall asa reports searchterms --campaign <id> --start 2025-01-01 --end 2025-01-31 --json
141
172
  superwall asa reports ads --campaign <id> --start 2025-01-01 --end 2025-01-31 --json
173
+ superwall asa brand-reports campaigns --start 2025-01-01 --end 2025-01-31 --json # Apple Maps
142
174
  ```
143
175
 
144
- Defaults: `DAILY` granularity (search terms: none, since Apple allows row
145
- totals or granularity but not both), rows sorted by `localSpend` descending,
146
- `timeZone` UTC. `--selector` replaces the sort/filter; `--time-zone ORTZ` uses
147
- the org's time zone. Impression share is asynchronous:
176
+ Reports send a `timeRange` (`start`, `end`, `granularity`, `timeZone`):
177
+ granularity defaults to `DAILY` and the time zone to `UTC` (`--time-zone ORTZ`
178
+ uses the account's). Filters, `--order-by` and `--query` work as on lists.
179
+
180
+ Insights are queries too, answered right away:
148
181
 
149
182
  ```bash
150
- superwall asa impression-share create --name weekly --start 2025-01-01 --end 2025-01-07 \
151
- --granularity DAILY --dimensions appName,countryOrRegion --metrics lowImpressionShare,highImpressionShare --json
152
- superwall asa impression-share get <id> --json # downloadUri once state is COMPLETED
183
+ superwall asa insights impression-share --adam-id <adamId> --start 2025-01-01 --end 2025-01-07 --json
184
+ superwall asa insights search-term-popularity --start 2025-01-01 --end 2025-01-07 --json
153
185
  ```
154
186
 
155
187
  ## Discovery
@@ -160,7 +192,20 @@ superwall asa apps eligibility <adamId> --json
160
192
  superwall asa product-pages list --adam-id <adamId> --json
161
193
  superwall asa geo search "New York" --entity Locality --json
162
194
  superwall asa geo get "US|CA|Cupertino" --entity Locality --json
163
- superwall asa product-pages countries --json
195
+ superwall asa suggestions keywords --adam-id <adamId> --json
196
+ superwall asa recommendations daily-budgets --json
197
+ superwall asa change-history list --json
164
198
  superwall asa acls --json
165
199
  superwall asa me --json
166
200
  ```
201
+
202
+ ## Not on v1
203
+
204
+ These v5 commands have no Platform API equivalent and are gone:
205
+ ad-group-level negative keyword search, `product-pages countries` and
206
+ `device-sizes`. There is no `find` action: every `list` takes the filters, a
207
+ full query goes in `--query`, and the ad account is `--ad-account-id`.
208
+ `impression-share` moved to
209
+ `insights impression-share` (synchronous now) and `ad-rejections assets` to
210
+ `assets list`. Asset upload (`POST /v1/assets/upload`) takes form data, which
211
+ the proxy doesn't pass, so it isn't available.
@@ -1,57 +1,94 @@
1
1
  # Dashboard Links
2
2
 
3
- ## Without applicationId
4
-
5
- When you don't know the applicationId, use the `select-application` redirect - the user picks their app, then lands on the target page:
3
+ The dashboard lives at `https://app.superwall.com`. Every page of an app is
4
+ under its organization and application:
6
5
 
7
6
  ```
8
- https://superwall.com/select-application?pathname=/applications/:app/{page}
7
+ https://app.superwall.com/{orgId}/{applicationId}/{page}
9
8
  ```
10
9
 
11
- | Page | URL |
12
- |------|-----|
13
- | Settings | `https://superwall.com/select-application?pathname=/applications/:app/settings` |
14
- | API Keys | `https://superwall.com/select-application?pathname=/applications/:app/settings/api-keys` |
15
- | Integrations | `https://superwall.com/select-application?pathname=/applications/:app/integrations` |
16
- | Users | `https://superwall.com/select-application?pathname=/applications/:app/users/v2` |
17
- | Surveys | `https://superwall.com/select-application?pathname=/applications/:app/surveys` |
18
- | Products | `https://superwall.com/select-application?pathname=/applications/:app/products/v2` |
19
- | Demand Score | `https://superwall.com/select-application?pathname=/applications/:app/demand-score` |
20
- | Charts | `https://superwall.com/select-application?pathname=/applications/:app/charts/v2` |
21
- | Campaigns | `https://superwall.com/select-application?pathname=/applications/:app/rules` |
22
- | Paywalls | `https://superwall.com/select-application?pathname=/applications/:app/paywalls` |
23
- | Templates | `https://superwall.com/select-application?pathname=/applications/:app/templates` |
10
+ The old `superwall.com` dashboard pages (`/applications/{applicationId}/…`
11
+ and the `/select-application?pathname=…` redirect) are the legacy
12
+ dashboard. Do not give them.
24
13
 
25
- ## With applicationId
14
+ ## Finding the ids
26
15
 
27
- When you know the applicationId (from `GET /v2/projects`), link directly:
16
+ - **applicationId**: `superwall.lock` (`apps.<platform>`) in a framework
17
+ project, or `applications[].id` in `GET /v2/projects`.
18
+ - **orgId**: `organization_id` of the project that holds the app, in
19
+ `GET /v2/projects`. A dashboard link the user pasted carries both:
20
+ `https://app.superwall.com/{orgId}/{applicationId}/…`.
21
+ - **paywallId**: `superwall.lock` (`paywalls.<name>.<platform>.paywallId`) in
22
+ a framework project, or `id` in `GET /v2/paywalls`.
23
+
24
+ When you can't find the ids, link the organization picker; the user picks
25
+ their organization and app, then opens the page from the sidebar:
28
26
 
29
27
  ```
30
- https://superwall.com/applications/{applicationId}/{page}
28
+ https://app.superwall.com/select-organization
31
29
  ```
32
30
 
33
- Same pages as above - swap `:app` for the actual ID (e.g. `https://superwall.com/applications/40581/settings`).
31
+ ## Pages
32
+
33
+ | Page | Path after `/{orgId}/{applicationId}` |
34
+ |------|-----|
35
+ | Paywalls | `/paywalls` |
36
+ | Design system | `/paywalls/design-system` |
37
+ | Templates (where a new paywall starts) | `/templates` |
38
+ | Campaigns | `/campaigns` |
39
+ | One campaign | `/campaigns/{campaignId}` |
40
+ | Products | `/products` |
41
+ | Charts | `/charts` |
42
+ | Users | `/users` |
43
+ | Surveys | `/surveys` |
44
+ | Demand Score | `/demand-score` |
45
+ | Integrations | `/integrations` |
46
+ | Settings | `/settings` |
47
+ | API Keys | `/settings/api-keys` |
48
+
49
+ Example: `https://app.superwall.com/1203/40581/settings/api-keys`.
34
50
 
35
51
  ## Deep-linking to a specific paywall
36
52
 
37
- Use the editor route for paywall links:
53
+ The link depends on how the paywall was built. A paywall row from
54
+ `GET /v2/paywalls` says so in `headless`.
55
+
56
+ **Built with the framework (code-first, `headless: true`)**: its studio.
38
57
 
39
58
  ```
40
- https://superwall.com/editor/#/applications/{applicationId}/paywalls/{paywallId}/latest
59
+ https://app.superwall.com/{orgId}/{applicationId}/paywalls/{paywallId}/studio
41
60
  ```
42
61
 
43
- Example:
62
+ Give this link whenever you push, promote or publish a framework paywall,
63
+ and whenever the user asks where to see one.
64
+
65
+ **A new code-first paywall** (the builder, before any push):
44
66
 
45
67
  ```
46
- https://superwall.com/editor/#/applications/40690/paywalls/201147/latest
68
+ https://app.superwall.com/{orgId}/{applicationId}/paywalls/new/studio
47
69
  ```
48
70
 
49
- Do not use `https://superwall.com/applications/{applicationId}/paywalls/{paywallId}`; that is a legacy route.
71
+ **Built in the visual editor (`headless: false`)**: the legacy editor, the
72
+ only place those paywalls open.
73
+
74
+ ```
75
+ https://superwall.com/editor/#/applications/{applicationId}/paywalls/{paywallId}/latest
76
+ ```
77
+
78
+ Never give a code-first paywall the editor link; it cannot edit one. When
79
+ you can't tell the kind, link the paywalls page,
80
+ `https://app.superwall.com/{orgId}/{applicationId}/paywalls`, which opens
81
+ each paywall the right way.
50
82
 
51
83
  ## Deep-linking to a specific user
52
84
 
53
85
  ```
54
- https://superwall.com/applications/{applicationId}/users/v2/{userId}
86
+ https://app.superwall.com/{orgId}/{applicationId}/users/{userId}
55
87
  ```
56
88
 
57
- `{userId}` can be a Superwall alias (e.g. `$SuperwallAlias:31FC167B-55CF-4197-9DF2-E5200C6A2E67`) or any user identifier.
89
+ `{userId}` can be a Superwall alias (e.g. `$SuperwallAlias:31FC167B-55CF-4197-9DF2-E5200C6A2E67`) or any user identifier; URL-encode it.
90
+
91
+ ## Staging
92
+
93
+ Superwall's own staging dashboard is `https://app.superwall.dev`, same paths.
94
+ Use it only when the CLI or API points at staging.
@@ -896,7 +896,7 @@ sw.applications_rep (applicationId)
896
896
 
897
897
  1. Search `sw.applications_rep` by name
898
898
  2. If multiple results, check `sw.events_hr_agg` for recent event counts
899
- 3. Show `applicationId` + link: `superwall.com/applications/:applicationId`
899
+ 3. Show `applicationId` + link: `https://app.superwall.com/{orgId}/{applicationId}/charts`, with `orgId` from `organization_id` in `GET /v2/projects` ([dashboard-links.md](dashboard-links.md))
900
900
 
901
901
  ```sql
902
902
  SELECT applicationId, name, platform
@@ -28,17 +28,18 @@ placement (in code) → campaign (routes it) → audience (who) → paywal
28
28
 
29
29
  1. **Find the app.** `superwall apps list --json`. Match the app by its `public_api_key`
30
30
  (the `pk_…` in the app's `configure()` call). Note its `id` → pass `--app <id>` to
31
- campaign/paywall commands, `--project <id>` to product/entitlement commands. Always pass
31
+ campaign/paywall and entitlement/product create commands (so the entitlement and the products
32
+ granting it land on the same app), `--project <id>` to list commands. Always pass
32
33
  these ids; JSON mode never guesses when multiple scopes exist.
33
34
  2. **Find registered placements.** Grep the app for `register(`, `registerPlacement(`,
34
35
  `usePlacement(`, `Superwall.shared.register` - collect the exact event-name strings.
35
36
  3. **Ensure an entitlement.** `superwall entitlements list --project <id> --json`; reuse an existing one, else
36
- `superwall entitlements create --identifier pro --project <id> --json`. Default to a single `pro` entitlement unless the
37
+ `superwall entitlements create --identifier pro --app <id> --json`. Default to a single `pro` entitlement unless the
37
38
  app clearly has tiers.
38
39
  4. **Ensure products.** `superwall products list --project <id> --json` first. If none:
39
40
  - App Store Connect connected (`superwall asc keys list --json`) → import (see `setup.md` beside this file).
40
41
  - Otherwise create with real pricing:
41
- `superwall products create --identifier pro_yearly --price 39.99 --period year --trial-days 7 --entitlement pro --project <id> --json`
42
+ `superwall products create --identifier pro_yearly --price 39.99 --period year --trial-days 7 --entitlement pro --app <id> --json`
42
43
  5. **Carry each placement.** `superwall campaigns list --project <id> --app <id> --json`. For each placement not already on
43
44
  a campaign: `superwall campaigns create --description "<description>" --placement <placement> --project <id> --app <id> --json` (campaigns require an initial placement; it seeds a 100% holdout audience), or add more with `superwall campaigns placements create <campaignId> --event-name <placement> --project <id> --app <id> --json`.
44
45