@superwall/cli 1.4.0 → 1.6.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.
- package/README.md +21 -5
- package/dist/{actions-EfP8phmb.js → actions-Dt35nIi8.js} +3 -2
- package/dist/{api-CEwXCCoC.js → api-BOR-uXZe.js} +9 -9
- package/dist/{app-D8mEVlQo.js → app-BU27SLPX.js} +9 -9
- package/dist/{asa-BFWehnTA.js → asa-2ykGnjaV.js} +11 -11
- package/dist/{asc-DJqQmtmR.js → asc-r3xmFT0L.js} +14 -14
- package/dist/{auth-CT2DWX8r.js → auth-BWZfguI8.js} +9 -9
- package/dist/auth.js +2 -2
- package/dist/{billing-BzEnVPD2.js → billing-BsQgXXYh.js} +1 -1
- package/dist/{bind-BZxVyt9P.js → bind-BSTAinn6.js} +5 -4
- package/dist/{command-DP96_gmP.js → command-DMoMn7uc.js} +39 -16
- package/dist/{create-Q8TqqjZt.js → create-CSo6XjSm.js} +118 -91
- package/dist/dev-B0MF6z3L.js +21 -0
- package/dist/{dev-DlCcwFu5.js → dev-CuXa3J4Z.js} +29 -24
- package/dist/{doctor-CJsjHpCZ.js → doctor-DXJaDqsx.js} +10 -10
- package/dist/{drivers-UT36AnOw.js → drivers-Cr252DOJ.js} +3 -3
- package/dist/entry.js +84 -50
- package/dist/{existing-Cak1WxWB.js → existing-Ckx_g7Be.js} +6 -3
- package/dist/{feedback-DDRzoqPx.js → feedback-Dt5yebMS.js} +6 -6
- package/dist/{hosted-CEH78QVn.js → hosted-Cjekn8oJ.js} +2 -2
- package/dist/{integrate-D8jyhDzk.js → integrate-DVqhvPVq.js} +25 -66
- package/dist/{login-kneYhhk0.js → login-Bjj8QvIN.js} +6 -6
- package/dist/migrate-qmvOtp3l.js +283 -0
- package/dist/open-studio-CpHqjovS.js +1299 -0
- package/dist/{org-Cg25bcsj.js → org-CV8c849b.js} +3 -3
- package/dist/{output-csAtR6kJ.js → output-CiELrN8w.js} +15 -2
- package/dist/{pipeline-DAeI9tHs.js → pipeline-DSCHL9KA.js} +482 -9
- package/dist/{print-skill-BHVPP9cX.js → print-skill-CaHRJ8xW.js} +7 -7
- package/dist/{promote-Boek5K2d.js → promote-UMTh8Q33.js} +17 -18
- package/dist/publish-DWX8S9yZ.js +34 -0
- package/dist/push-Dox4_5Dq.js +34 -0
- package/dist/{query-B8G6T8Ba.js → query-CnSsDZ7Q.js} +10 -10
- package/dist/reports-C0xHCLnt.js +27 -0
- package/dist/{resource-DjsWVka-.js → resource-5bgyyL9B.js} +15 -15
- package/dist/{resources-s64mBHaC.js → resources-Bf9O1JNM.js} +28 -2
- package/dist/{run-BtcQJCP8.js → run-BVeZWbXx.js} +39 -22
- package/dist/{scan-DJixvuHn.js → scan-CAObNRgc.js} +44 -4
- package/dist/skills/superwall/SKILL.md +146 -0
- package/dist/skills/superwall/references/api.md +275 -0
- package/dist/skills/superwall/references/asa.md +160 -0
- package/dist/skills/superwall/references/asc.md +96 -0
- package/dist/skills/superwall/references/dashboard-links.md +57 -0
- package/dist/skills/superwall/references/data-analytics.md +893 -0
- package/dist/skills/superwall/references/docs.md +51 -0
- package/dist/skills/superwall/references/sdk-integration.md +105 -0
- package/dist/skills/superwall/references/sdk-source.md +18 -0
- package/{skills/superwall-dashboard/SKILL.md → dist/skills/superwall/workflows/dashboard/playbook.md} +3 -9
- package/{skills/superwall-dashboard/references → dist/skills/superwall/workflows/dashboard}/setup.md +1 -3
- package/dist/skills/superwall/workflows/integrate/android.md +292 -0
- package/{skills/superwall-integrate/SKILL.md → dist/skills/superwall/workflows/integrate/playbook.md} +16 -11
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/adapty.md +4 -4
- package/{skills/superwall-migrate/SKILL.md → dist/skills/superwall/workflows/migrate/playbook.md} +4 -10
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/qonversion.md +4 -4
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/revenuecat.md +4 -4
- package/dist/skills/superwall/workflows/placements/android.md +175 -0
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/expo.md +1 -1
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/flutter.md +1 -1
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md +1 -1
- package/{skills/superwall-placements/SKILL.md → dist/skills/superwall/workflows/placements/playbook.md} +6 -10
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/react-native.md +2 -2
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/strategy.md +4 -3
- package/dist/skills/superwall/workflows/review/android.md +120 -0
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md +1 -1
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md +1 -1
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md +1 -1
- package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md} +2 -7
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/react-native.md +1 -1
- package/dist/skills/superwall-framework/SKILL.md +253 -0
- package/dist/skills/superwall-framework/references/cli.md +340 -0
- package/dist/skills/superwall-framework/references/examples.md +123 -0
- package/dist/skills/superwall-framework/references/layout.md +295 -0
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +208 -0
- package/dist/skills/superwall-framework/references/migrate-from-native.md +193 -0
- package/dist/skills/superwall-framework/references/mobile-design.md +371 -0
- package/dist/skills/superwall-framework/references/native/android.md +83 -0
- package/dist/skills/superwall-framework/references/native/flutter.md +65 -0
- package/dist/skills/superwall-framework/references/native/ios.md +77 -0
- package/dist/skills/superwall-framework/references/native/react-native.md +67 -0
- package/dist/skills/superwall-framework/references/responsive.md +162 -0
- package/dist/{skills-CRG1xk0G.js → skills-Cu41i-Az.js} +12 -12
- package/dist/{skills-CODut1Hn.js → skills-grTDuHlc.js} +134 -36
- package/dist/{spinner-B9dT3DBY.js → spinner-DFctF_Jw.js} +1 -1
- package/dist/{telemetry-BtkMdT-5.js → telemetry-BuCbmoux.js} +3 -3
- package/dist/{token-hM7V1KMG.js → token-mju3Q-vc.js} +3 -3
- package/dist/{ui-Lqt_zFOr.js → ui-4gLyfrgl.js} +76 -46
- package/dist/{update-CeylIjx5.js → update-DnGfpCD7.js} +2 -2
- package/dist/{upgrade-DRqUfCBT.js → upgrade-PMoj3yqJ.js} +6 -6
- package/package.json +8 -7
- package/prompts/actions/paywall-migrate.xml +24 -0
- package/prompts/actions/screen-migrate.xml +26 -0
- package/dist/git-ZwA3Mx8m.js +0 -433
- package/dist/migrate-D_x1oyTk.js +0 -114
- package/dist/publish-C-zEUnO9.js +0 -35
- package/dist/push-DUDQG-EO.js +0 -35
- package/skills/README.md +0 -118
- /package/dist/{api-output-D9ggXQIr.js → api-output-CEhN-U_N.js} +0 -0
- /package/dist/{asc-products-C6MvSy8H.js → asc-products-1e1DoGeL.js} +0 -0
- /package/dist/{params-B1zeElGa.js → params-BxgTuCzr.js} +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/expo.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/flutter.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/ios.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/react-native.md +0 -0
- /package/dist/{storekit-DPonXSwe.js → storekit-Dlpbq5Wv.js} +0 -0
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
# CLI Reference
|
|
2
|
+
|
|
3
|
+
Everything is available through the `superwall` CLI. Install it globally, then
|
|
4
|
+
use `superwall login` once for device-flow OAuth. The saved session lives in
|
|
5
|
+
`~/.superwall`.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install --global superwall
|
|
9
|
+
superwall login # device-flow OAuth (opens browser); acts as you
|
|
10
|
+
superwall login --api-key <key> # headless, for CI - a dashboard org key, à la STRIPE_API_KEY
|
|
11
|
+
superwall whoami --json # show the logged-in account / org
|
|
12
|
+
superwall logout --json
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Add `--help` / `-h` to any command for its flags.
|
|
16
|
+
|
|
17
|
+
## Data hierarchy
|
|
18
|
+
|
|
19
|
+
Organization → Projects → Applications. Each application has a `platform` (ios,
|
|
20
|
+
android, flutter, react_native, web), a `bundle_id`, and a `public_api_key`
|
|
21
|
+
(the `pk_…` key used for SDK initialization - distinct from the OAuth session
|
|
22
|
+
used for CLI/REST calls). Projects own products + entitlements; applications own
|
|
23
|
+
campaigns + paywalls.
|
|
24
|
+
|
|
25
|
+
## Scoping
|
|
26
|
+
|
|
27
|
+
Commands auto-scope only when exactly one project/app exists. With several, rich
|
|
28
|
+
interactive mode prompts; JSON and noninteractive modes require explicit scope:
|
|
29
|
+
|
|
30
|
+
- `--project <id>` - scope to a project.
|
|
31
|
+
- `--app <id|name>` - scope to an application. `superwall apps use <id|name>` sets
|
|
32
|
+
the rich UI's default, but automation still passes scope explicitly.
|
|
33
|
+
|
|
34
|
+
**Everything is org-scoped.** The session pins one active organization, and every
|
|
35
|
+
command runs against it: resource listings and creates, `query` (that org's
|
|
36
|
+
ClickHouse data), the `asc` proxy (that org's App Store Connect key vault), and
|
|
37
|
+
the `asa` proxy (that org's apps' Apple Search Ads credentials).
|
|
38
|
+
Single-org accounts resolve it automatically and never think about it. Multi-org
|
|
39
|
+
accounts are prompted once in rich mode; automation runs
|
|
40
|
+
`superwall orgs use <id|name>` once to persist the choice. The switch is global
|
|
41
|
+
and sticky (stored in the session) - to work in another org, switch, run the
|
|
42
|
+
commands, and switch back. `superwall whoami --json` shows the active org.
|
|
43
|
+
|
|
44
|
+
**Agent contract:** always pass `--json` to resource, ASC, ASA, raw API, query,
|
|
45
|
+
`bootstrap`, `whoami`, and `doctor` commands. JSON is the stable machine contract,
|
|
46
|
+
uses two-space indentation, never prompts, and returns errors as `{ "error": {
|
|
47
|
+
"code", "message", "status"? } }`. `--dry-run` plans a create without writing.
|
|
48
|
+
|
|
49
|
+
## Resources
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
superwall orgs list --json
|
|
53
|
+
superwall orgs use <id|name> # persist the org for org-scoped commands (multi-org accounts)
|
|
54
|
+
superwall apps list --json
|
|
55
|
+
superwall products list --project <id> --json
|
|
56
|
+
superwall entitlements list --project <id> --json
|
|
57
|
+
superwall campaigns list --project <id> --app <id> --json
|
|
58
|
+
superwall paywalls list --project <id> --app <id> --json
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`apps list` nests apps under their projects - there is no separate projects
|
|
62
|
+
command; `--project <id>` is how you scope when it matters.
|
|
63
|
+
|
|
64
|
+
### Create
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# Apps: an app is a platform of a project. Without --project a new project is spun
|
|
68
|
+
# up for it; each project allows one app per platform.
|
|
69
|
+
superwall apps create "My App" --platform ios [--bundle com.acme.app] [--project <projectId>] --json
|
|
70
|
+
|
|
71
|
+
# Entitlements
|
|
72
|
+
superwall entitlements create pro --project <id> --json
|
|
73
|
+
|
|
74
|
+
# Products (identifier is required; the rest is a full definition, mainly for agents)
|
|
75
|
+
superwall products create com.acme.pro.monthly \
|
|
76
|
+
--name "Pro Monthly" \
|
|
77
|
+
--price 9.99 --currency USD \
|
|
78
|
+
--period month --period-count 1 \
|
|
79
|
+
--trial-days 7 \
|
|
80
|
+
--entitlement pro \
|
|
81
|
+
--project <id> --json # repeatable: grant multiple entitlements
|
|
82
|
+
|
|
83
|
+
# Campaigns (the create arg is a description)
|
|
84
|
+
superwall campaigns create "Onboarding paywall" onboarding_complete --project <id> --app <id> --json
|
|
85
|
+
|
|
86
|
+
# Placements: attach a placement (event name) to a campaign
|
|
87
|
+
superwall campaigns placement <campaignId> onboarding_complete --project <id> --app <id> --json
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Projects aren't created directly - add the first platform with `apps create` and
|
|
91
|
+
a project is created for you.
|
|
92
|
+
|
|
93
|
+
### StoreKit config
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
superwall products storekit --project <id> [--out Superwall.storekit] --json
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## App Store Connect
|
|
100
|
+
|
|
101
|
+
Superwall proxies the App Store Connect API with a signed request - no `.p8`
|
|
102
|
+
file or JWT to manage locally. First connect ASC credentials (uploaded to
|
|
103
|
+
Superwall's vault, nothing sensitive stored locally):
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
superwall asc keys set --key-id <id> --issuer <id> --key-file ./AuthKey.p8 [--name "My Team"] --json
|
|
107
|
+
superwall asc keys list --json
|
|
108
|
+
superwall asc keys rm <team_id> --json
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Then call ASC through the proxy:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# Shortcuts
|
|
115
|
+
superwall asc apps --json
|
|
116
|
+
superwall asc products <bundle-id | asc-app-id> --json
|
|
117
|
+
superwall asc subscriptions com.acme.app --json
|
|
118
|
+
|
|
119
|
+
# Raw API - a verb + path, or just a path (defaults to GET)
|
|
120
|
+
superwall asc get /v1/apps --json
|
|
121
|
+
superwall asc /v1/apps --json
|
|
122
|
+
superwall asc post /v1/... -d key=value -d count:=3 --json
|
|
123
|
+
|
|
124
|
+
# Multiple connected teams
|
|
125
|
+
superwall asc apps --team <teamId> --json
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Request schema & docs — do this before every write
|
|
129
|
+
|
|
130
|
+
The proxy is schema-aware, backed by Apple's own OpenAPI spec. **Before any
|
|
131
|
+
`post`/`patch`, look up the exact schema — never guess a body:**
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
superwall asc docs # catalog: every resource root
|
|
135
|
+
superwall asc docs "introductory offer" # find endpoints by keyword
|
|
136
|
+
superwall asc docs /v1/subscriptions post # required fields, enums, relationships, example
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Pass flat `-d` params — the proxy builds the JSON:API envelope for you
|
|
140
|
+
(`data.type`, `attributes`, `relationships`) and casts values by declared type:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
superwall asc post /v1/subscriptions -d name=Pro -d productId=com.acme.pro -d group=<subscriptionGroups id> --json
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
A malformed body is rejected locally with the exact fix (missing required field,
|
|
147
|
+
invalid enum value) before it ever reaches Apple's opaque errors. Pass `--force`
|
|
148
|
+
to skip validation and send as-is.
|
|
149
|
+
|
|
150
|
+
For end-to-end recipes (creating a subscription with prices and offers) and the
|
|
151
|
+
full workflow, see the [App Store Connect reference](asc.md).
|
|
152
|
+
|
|
153
|
+
## Apple Search Ads
|
|
154
|
+
|
|
155
|
+
Superwall proxies the Apple Ads Campaign Management API v5 with the credentials
|
|
156
|
+
connected in the dashboard (app → Integrations → Apple Search Ads → Advanced).
|
|
157
|
+
Nothing is stored locally; the CLI picks the connected iOS app itself, or takes
|
|
158
|
+
`--app <id>`:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
superwall asa keys list --json # which apps are connected
|
|
162
|
+
|
|
163
|
+
# Resources: asa <resource> <action> [id], scoped with --campaign / --adgroup / --adam-id
|
|
164
|
+
superwall asa campaigns list --json
|
|
165
|
+
superwall asa campaigns get <id> --json
|
|
166
|
+
superwall asa campaigns find --field status --op EQUALS --values ENABLED --all --json
|
|
167
|
+
superwall asa adgroups list --campaign <id> --json
|
|
168
|
+
superwall asa keywords list --campaign <id> --adgroup <id> --all --json
|
|
169
|
+
superwall asa reports campaigns --start 2025-01-01 --end 2025-01-31 --json
|
|
170
|
+
|
|
171
|
+
# Raw API - a verb + path, or just a path (defaults to GET); /api/v5 is implied
|
|
172
|
+
superwall asa get /campaigns --json
|
|
173
|
+
superwall asa /campaigns --json
|
|
174
|
+
superwall asa post /campaigns/find --body '{"conditions":[]}' --json
|
|
175
|
+
|
|
176
|
+
# Several Apple Search Ads orgs behind one API user
|
|
177
|
+
superwall asa campaigns list --org-id <appleOrgId> --json
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Request schema & docs — do this before every write
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
superwall asa docs # catalog: every endpoint, grouped
|
|
184
|
+
superwall asa docs keywords # one resource: usage, flags, Apple links
|
|
185
|
+
superwall asa docs campaigns create # Apple's own page: fields, enums, examples
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Writes take typed flags (money flags resolve the account's currency from
|
|
189
|
+
`/acls`, or pass `--currency`), `-d key=value` / `key:=json` for any other
|
|
190
|
+
field, or `--body <json|@file|@->` for the whole payload:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
superwall asa campaigns create --name "Launch" --adam-id <adamId> --countries US,CA \
|
|
194
|
+
--daily-budget 50 --supply-sources APPSTORE_SEARCH_RESULTS --ad-channel-type SEARCH --json
|
|
195
|
+
superwall asa keywords update <id> --campaign <id> --adgroup <id> --bid 2 --json
|
|
196
|
+
superwall asa keywords delete <id,id,id> --campaign <id> --adgroup <id> --json
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Apple's validation errors come back as `Apple Search Ads rejected …` with each
|
|
200
|
+
field and message code. For the full resource list and recipes, see the
|
|
201
|
+
[Apple Search Ads reference](asa.md).
|
|
202
|
+
|
|
203
|
+
## Raw API access - any endpoint
|
|
204
|
+
|
|
205
|
+
`bootstrap` prints the account overview; the verb commands hit any V2 endpoint
|
|
206
|
+
with the CLI's session auth (like `stripe get /v1/...`):
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
superwall bootstrap --json # complete account tree
|
|
210
|
+
|
|
211
|
+
superwall get /v2/products -d project_id=25607 --json
|
|
212
|
+
superwall get /v2/campaigns -d project_id=25607 -d limit=10 --json
|
|
213
|
+
superwall post /v2/entitlements -d project_id=25607 -d identifier=pro --json
|
|
214
|
+
superwall patch /v2/projects/25607 -d name=Renamed --json
|
|
215
|
+
superwall delete /v2/... --json # careful
|
|
216
|
+
|
|
217
|
+
# -d key=value sends a string; key:=value sends typed JSON; nesting via key[sub]
|
|
218
|
+
superwall post /v2/products -d 'price[amount]:=4999' -d 'price[currency]=USD' --json
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Raw paths need explicit scope params (`project_id`, ...) - the nicely-named
|
|
222
|
+
resource commands above resolve scope for you; the verbs do not.
|
|
223
|
+
|
|
224
|
+
## Data query - ClickHouse SQL
|
|
225
|
+
|
|
226
|
+
`query` runs read-only SQL against the logged-in organization's ClickHouse
|
|
227
|
+
analytics data. Use it for analysis, custom dashboards, scheduled reports, and
|
|
228
|
+
agent workflows. Prefer `--json` when another tool or agent will consume the
|
|
229
|
+
result; it returns ClickHouse's native JSON envelope (`meta`, `data`, `rows`, and
|
|
230
|
+
statistics).
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
superwall query "SELECT applicationId, name FROM sw.applications_rep FINAL LIMIT 20" --json
|
|
234
|
+
superwall query "SELECT count() AS active FROM sw.subscription_status_rep FINAL WHERE applicationId = 123 AND isSandbox = 0" --json
|
|
235
|
+
superwall query --file daily-report.sql --json
|
|
236
|
+
printf 'SHOW TABLES FROM sw' | superwall query --json
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
Pass SQL in exactly one place: as a quoted argument, with `--file <query.sql>`,
|
|
240
|
+
or on stdin. With `--json`, omit the SQL `FORMAT` clause because the CLI requests
|
|
241
|
+
ClickHouse JSON. Without `--json`, any explicit ClickHouse `FORMAT` clause is
|
|
242
|
+
preserved.
|
|
243
|
+
|
|
244
|
+
The CLI supplies the current organization ID and authenticated session. The
|
|
245
|
+
credential must have `data:read` access. See `data-analytics.md` for exposed
|
|
246
|
+
tables, query patterns, and performance guardrails.
|
|
247
|
+
|
|
248
|
+
## Utilities
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
superwall doctor --json # health-check the integration
|
|
252
|
+
superwall skills # install the Superwall agent skills into your agent
|
|
253
|
+
superwall upgrade # update the CLI to the latest version
|
|
254
|
+
superwall feedback "..." # send feedback about the CLI to the Superwall team
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
## Agent workflows
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
superwall integrate # first-time SDK + dashboard setup
|
|
261
|
+
superwall migrate # move from RevenueCat / Adapty / Qonversion
|
|
262
|
+
superwall review # audit an existing setup end to end
|
|
263
|
+
superwall review --fix # apply verified, safe findings from the review
|
|
264
|
+
superwall <workflow> --skill # print the project-specific playbook for an agent
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
`review` covers SDK configuration, purchase/subscription ownership, identity,
|
|
268
|
+
deep links, conditional Web Checkout readiness, placements, products,
|
|
269
|
+
entitlements, campaigns, paywalls, and analytics. It is not a placement-only
|
|
270
|
+
inventory. Agents should use `--skill` and follow the playbook themselves rather
|
|
271
|
+
than spawning a nested agent.
|
|
272
|
+
|
|
273
|
+
Responses are cursor-paginated: pass `limit` (1-100), `starting_after`, or
|
|
274
|
+
`ending_before` as query params and follow `has_more`. Prefer a CLI command
|
|
275
|
+
whenever one exists - reach for curl only for genuinely uncovered routes.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# Apple Search Ads — the full Apple Ads API via Superwall's proxy
|
|
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.
|
|
9
|
+
|
|
10
|
+
## Which app
|
|
11
|
+
|
|
12
|
+
Credentials are per Superwall app (iOS). The CLI picks the one connected app
|
|
13
|
+
itself; with several connected, pass `--app <id|name>`.
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
superwall asa keys list --json # every iOS app + whether Apple Search Ads is connected
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Not connected → the dashboard does it: open the app → Integrations → Apple
|
|
20
|
+
Search Ads → Advanced, paste Superwall's public key into Apple's Account
|
|
21
|
+
Settings → API, then enter the Client ID, Team ID and Key ID. `asa keys set`
|
|
22
|
+
is deliberately not a CLI command (Superwall generates the key pair).
|
|
23
|
+
|
|
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.
|
|
27
|
+
|
|
28
|
+
## Docs access — do this before every write
|
|
29
|
+
|
|
30
|
+
Never guess a request body. `asa docs` is the catalog, and for a specific
|
|
31
|
+
command it fetches Apple's own page live (fields, required flags, enums,
|
|
32
|
+
examples):
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
superwall asa docs # every endpoint, grouped by resource
|
|
36
|
+
superwall asa docs keywords # one resource: usage, flags → Apple field names, links
|
|
37
|
+
superwall asa docs campaigns create # Apple's page for that call, plus the body object's fields
|
|
38
|
+
superwall asa docs "impression" # search by keyword
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Command shape
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
superwall asa <resource> <action> [id] [--campaign <id>] [--adgroup <id>] [--adam-id <id>] --json
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
| Resource | Actions |
|
|
48
|
+
|---|---|
|
|
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 |
|
|
63
|
+
|
|
64
|
+
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.
|
|
66
|
+
|
|
67
|
+
## Reading
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
superwall asa campaigns list --limit 50 --json
|
|
71
|
+
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
|
|
76
|
+
```
|
|
77
|
+
|
|
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.
|
|
83
|
+
|
|
84
|
+
## Writing
|
|
85
|
+
|
|
86
|
+
Typed flags map to Apple's field names (`asa docs <resource>` shows the
|
|
87
|
+
mapping). Money flags (`--budget`, `--daily-budget`, `--bid`, `--default-bid`,
|
|
88
|
+
`--cpa-goal`) become `{ amount, currency }`; the currency comes from
|
|
89
|
+
`--currency` or the account's `/acls` entry. Anything else goes through
|
|
90
|
+
`-d key=value` (`key:=value` for numbers/booleans/JSON, `key[sub]` nesting) or
|
|
91
|
+
`--body`.
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
# Campaign (Apple requires supplySources and adChannelType alongside the budget)
|
|
95
|
+
superwall asa campaigns create --name "Launch" --adam-id <adamId> --countries US,CA \
|
|
96
|
+
--daily-budget 50 --supply-sources APPSTORE_SEARCH_RESULTS --ad-channel-type SEARCH \
|
|
97
|
+
--billing-event TAPS --json
|
|
98
|
+
|
|
99
|
+
# Pause it
|
|
100
|
+
superwall asa campaigns update <id> --status PAUSED --json
|
|
101
|
+
|
|
102
|
+
# Ad group
|
|
103
|
+
superwall asa adgroups create --campaign <id> --name "Exact match" --default-bid 1.50 \
|
|
104
|
+
--start 2025-06-01T00:00:00.000 --search-match=false --json
|
|
105
|
+
|
|
106
|
+
# Keywords are bulk: one from flags, or many from --body
|
|
107
|
+
superwall asa keywords create --campaign <id> --adgroup <id> --text "grammar checker" --match-type EXACT --bid 1.25 --json
|
|
108
|
+
superwall asa keywords create --campaign <id> --adgroup <id> \
|
|
109
|
+
--body '[{"text":"grammar","matchType":"BROAD","bidAmount":{"amount":"1","currency":"USD"}},{"text":"spell check","matchType":"EXACT"}]' --json
|
|
110
|
+
superwall asa keywords update <id> --campaign <id> --adgroup <id> --bid 2 --json
|
|
111
|
+
superwall asa keywords delete <id> --campaign <id> --adgroup <id> --json # one → DELETE
|
|
112
|
+
superwall asa keywords delete <id,id,id> --campaign <id> --adgroup <id> --json # several → bulk
|
|
113
|
+
|
|
114
|
+
# Negative keywords: campaign level, or ad group level with --adgroup
|
|
115
|
+
superwall asa negative-keywords create --campaign <id> --text free --match-type BROAD --json
|
|
116
|
+
superwall asa negative-keywords create --campaign <id> --adgroup <id> --text free --json
|
|
117
|
+
|
|
118
|
+
# Creative + ad (custom product page)
|
|
119
|
+
superwall asa creatives create --adam-id <adamId> --type CUSTOM_PRODUCT_PAGE --product-page-id <ppId> --name "Holiday" --json
|
|
120
|
+
superwall asa ads create --campaign <id> --adgroup <id> --creative-id <creativeId> --name "Holiday ad" --json
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Apple's validation failures come back as
|
|
124
|
+
`Apple Search Ads rejected asa campaigns create (400): • field: message (CODE)`.
|
|
125
|
+
Read the field, fix the flag, retry.
|
|
126
|
+
|
|
127
|
+
## Reports
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
superwall asa reports campaigns --start 2025-01-01 --end 2025-01-31 --json
|
|
131
|
+
superwall asa reports campaigns --start 2025-01-01 --end 2025-01-31 --granularity WEEKLY --group-by countryOrRegion --json
|
|
132
|
+
superwall asa reports adgroups --campaign <id> --start 2025-01-01 --end 2025-01-31 --json
|
|
133
|
+
superwall asa reports keywords --campaign <id> [--adgroup <id>] --start 2025-01-01 --end 2025-01-31 --json
|
|
134
|
+
superwall asa reports searchterms --campaign <id> --start 2025-01-01 --end 2025-01-31 --json
|
|
135
|
+
superwall asa reports ads --campaign <id> --start 2025-01-01 --end 2025-01-31 --json
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Defaults: `DAILY` granularity (search terms: none, since Apple allows row
|
|
139
|
+
totals or granularity but not both), rows sorted by `localSpend` descending,
|
|
140
|
+
`timeZone` UTC. `--selector` replaces the sort/filter; `--time-zone ORTZ` uses
|
|
141
|
+
the org's time zone. Impression share is asynchronous:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
superwall asa impression-share create --name weekly --start 2025-01-01 --end 2025-01-07 \
|
|
145
|
+
--granularity DAILY --dimensions appName,countryOrRegion --metrics lowImpressionShare,highImpressionShare --json
|
|
146
|
+
superwall asa impression-share get <id> --json # downloadUri once state is COMPLETED
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## Discovery
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
superwall asa apps search "grammar checker" --owned --json # find adamIds
|
|
153
|
+
superwall asa apps eligibility <adamId> --json
|
|
154
|
+
superwall asa product-pages list --adam-id <adamId> --json
|
|
155
|
+
superwall asa geo search "New York" --entity Locality --json
|
|
156
|
+
superwall asa geo get "US|CA|Cupertino" --entity Locality --json
|
|
157
|
+
superwall asa product-pages countries --json
|
|
158
|
+
superwall asa acls --json
|
|
159
|
+
superwall asa me --json
|
|
160
|
+
```
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# App Store Connect — the full ASC API via the signed proxy
|
|
2
|
+
|
|
3
|
+
`superwall asc` proxies the **entire** App Store Connect API through Superwall's
|
|
4
|
+
signed request — no `.p8` file or JWT locally. It is schema-aware: it builds
|
|
5
|
+
JSON:API request bodies from flat params and validates them against Apple's own
|
|
6
|
+
OpenAPI spec before anything reaches App Store Connect. This lets an agent create
|
|
7
|
+
and manage subscriptions, IAPs, prices, and offers directly.
|
|
8
|
+
|
|
9
|
+
## Docs access — do this before every write
|
|
10
|
+
|
|
11
|
+
Never guess a request body. Before any `asc post` / `asc patch`, look up the
|
|
12
|
+
exact schema:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
superwall asc docs # catalog: every resource root
|
|
16
|
+
superwall asc docs "introductory offer" # find endpoints by keyword
|
|
17
|
+
superwall asc docs /v1/subscriptions post # exact schema: required fields, enums, relationships, example
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
If you send a malformed body, the proxy **blocks it locally** and returns the
|
|
21
|
+
precise fix — a missing required field, an invalid enum value — before it ever
|
|
22
|
+
hits Apple's opaque errors. Read the correction and retry. `--force` skips
|
|
23
|
+
validation and sends as-is.
|
|
24
|
+
|
|
25
|
+
The schema is fetched from Apple on first use (a one-time few-second load),
|
|
26
|
+
cached under `~/.superwall`, and refreshed automatically in the background when
|
|
27
|
+
stale. Force an update with `superwall asc docs refresh`.
|
|
28
|
+
|
|
29
|
+
## Flat params, not hand-written JSON:API
|
|
30
|
+
|
|
31
|
+
Pass flat `-d key=value`; the proxy assembles the JSON:API envelope
|
|
32
|
+
(`data.type` / `attributes` / `relationships`), casts values by declared type,
|
|
33
|
+
and wraps each relationship id. A relationship value is just the target id.
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
superwall asc post /v1/subscriptions \
|
|
37
|
+
-d name="Premium Monthly" -d productId=com.acme.pro.monthly \
|
|
38
|
+
-d subscriptionPeriod=ONE_MONTH -d group=<subscriptionGroups id> --json
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
An already-enveloped body (`-d data[type]=…`) is passed through untouched.
|
|
42
|
+
|
|
43
|
+
## Recipe: create a subscription end to end
|
|
44
|
+
|
|
45
|
+
App Store Connect requires these in order; each step's returned id feeds the
|
|
46
|
+
next. Run `asc docs <path> post` for the full schema of any step.
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
# 1. Subscription group (one per app)
|
|
50
|
+
superwall asc post /v1/subscriptionGroups \
|
|
51
|
+
-d referenceName="Premium" -d app=<ascAppId> --json
|
|
52
|
+
|
|
53
|
+
# 2. Subscription, inside that group
|
|
54
|
+
superwall asc post /v1/subscriptions \
|
|
55
|
+
-d name="Premium Monthly" -d productId=com.acme.pro.monthly \
|
|
56
|
+
-d subscriptionPeriod=ONE_MONTH -d group=<groupId> --json
|
|
57
|
+
|
|
58
|
+
# 3. Discover a price point (Apple's fixed tiers, per territory)
|
|
59
|
+
superwall asc /v1/subscriptions/<subId>/pricePoints --json
|
|
60
|
+
|
|
61
|
+
# 4. Set the price
|
|
62
|
+
superwall asc post /v1/subscriptionPrices \
|
|
63
|
+
-d subscription=<subId> -d subscriptionPricePoint=<pricePointId> \
|
|
64
|
+
-d territory=USA --json
|
|
65
|
+
|
|
66
|
+
# 5. (Optional) Introductory offer — e.g. a one-week free trial
|
|
67
|
+
superwall asc post /v1/subscriptionIntroductoryOffers \
|
|
68
|
+
-d subscription=<subId> -d duration=ONE_WEEK -d offerMode=FREE_TRIAL \
|
|
69
|
+
-d numberOfPeriods=1 -d subscriptionPricePoint=<pricePointId> --json
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Territory ids are three-letter store regions (`USA`, `GBR`, …). Whether
|
|
73
|
+
`territory` is required on a given call is marked by `asc docs` — don't assume.
|
|
74
|
+
|
|
75
|
+
## Convenience shortcuts (formatted reads)
|
|
76
|
+
|
|
77
|
+
For the common reads there are hand-built shortcuts (not raw endpoints):
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
superwall asc apps --json # ASC apps for the team
|
|
81
|
+
superwall asc products <bundle-id | asc-app-id> --json
|
|
82
|
+
superwall asc subscriptions com.acme.app --json
|
|
83
|
+
superwall asc iaps com.acme.app --json
|
|
84
|
+
superwall asc apps --team <teamId> --json # if the org has multiple teams
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Everything else — every one of Apple's endpoints — goes through the raw proxy
|
|
88
|
+
(`asc get|post|patch|delete /v1/…`), which is where validation applies.
|
|
89
|
+
|
|
90
|
+
## Connecting ASC credentials (one-time)
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
superwall asc keys set --key-id <id> --issuer <id> --key-file ./AuthKey.p8 [--name "My Team"] --json
|
|
94
|
+
superwall asc keys list --json
|
|
95
|
+
superwall asc keys rm <team_id> --json
|
|
96
|
+
```
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Dashboard Links
|
|
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:
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
https://superwall.com/select-application?pathname=/applications/:app/{page}
|
|
9
|
+
```
|
|
10
|
+
|
|
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` |
|
|
24
|
+
|
|
25
|
+
## With applicationId
|
|
26
|
+
|
|
27
|
+
When you know the applicationId (from `GET /v2/projects`), link directly:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
https://superwall.com/applications/{applicationId}/{page}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Same pages as above - swap `:app` for the actual ID (e.g. `https://superwall.com/applications/40581/settings`).
|
|
34
|
+
|
|
35
|
+
## Deep-linking to a specific paywall
|
|
36
|
+
|
|
37
|
+
Use the editor route for paywall links:
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
https://superwall.com/editor/#/applications/{applicationId}/paywalls/{paywallId}/latest
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Example:
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
https://superwall.com/editor/#/applications/40690/paywalls/201147/latest
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Do not use `https://superwall.com/applications/{applicationId}/paywalls/{paywallId}`; that is a legacy route.
|
|
50
|
+
|
|
51
|
+
## Deep-linking to a specific user
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
https://superwall.com/applications/{applicationId}/users/v2/{userId}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`{userId}` can be a Superwall alias (e.g. `$SuperwallAlias:31FC167B-55CF-4197-9DF2-E5200C6A2E67`) or any user identifier.
|