@superwall/cli 1.6.2 → 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.
- package/README.md +281 -34
- package/dist/apple-CkKlHBZ9.js +195 -0
- package/dist/auth.d.ts +4 -19
- package/dist/auth.js +4 -2
- package/dist/{actions-H7f6knyY.js → billing-XCZU_T46.js} +98 -28
- package/dist/{bind-BIzaGq8K.js → bind-drne__Ys.js} +38 -33
- package/dist/{build-B7BS1rF2.js → build-Gpdq5QXP.js} +20 -26
- package/dist/client-BZ1UbpXz.js +66 -0
- package/dist/client-DP6Rc0t_.js +176 -0
- package/dist/config-BO1Y87kV.js +105 -0
- package/dist/create-BBrtgUgS.js +969 -0
- package/dist/{create-CwnnNqv4.js → create-Cwc3SRWJ.js} +194 -168
- package/dist/create-Yvf2gStM.js +19 -0
- package/dist/doctor-C9ldpPFC.js +83 -0
- package/dist/{drivers-6RMOPIdn.js → drivers-DNrx4LWA.js} +185 -172
- package/dist/entry.d.ts +0 -5
- package/dist/entry.js +28083 -801
- package/dist/environment-DF1qKlny.js +58 -0
- package/dist/{existing-DHpPn1y6.js → existing-78LWSsqS.js} +12 -6
- package/dist/held-Cy8Wl4D1.js +1112 -0
- package/dist/held-Ddw1XSsr.js +16 -0
- package/dist/input-vi0bou04.js +42 -0
- package/dist/{integrate-BR2LR-EK.js → integrate-DcJhpXy8.js} +277 -253
- package/dist/kinds-GFXB3sYu.js +11 -0
- package/dist/log-NVhVe_oe.js +62 -0
- package/dist/login-B2TsCE2H.js +53 -0
- package/dist/login-BoBe8Psl.js +16 -0
- package/dist/{login-Bhxgqwtm.js → login-D0lh3_JI.js} +144 -66
- package/dist/lookup-D-nmmAbw.js +71 -0
- package/dist/migrate-Cfec564E.js +274 -0
- package/dist/notification-url-YDbq6FMA.js +100 -0
- package/dist/{open-studio-BnVD6tJ9.js → open-Ba2vBl1_.js} +34 -43
- package/dist/org-D0g_q3mv.js +35 -0
- package/dist/output-Ggzq5_-t.js +122 -0
- package/dist/paths-DxSLdpOI.js +29 -0
- package/dist/playbook-DIeb7hne.js +53 -0
- package/dist/{asc-products-Dvcyef3_.js → products-DH_fK9tY.js} +6 -39
- package/dist/promote-COD4fYdz.js +91 -0
- package/dist/push-CncywhkQ.js +482 -0
- package/dist/push-CtD4FZQV.js +22 -0
- package/dist/registry-DSrosOYs.js +10228 -0
- package/dist/{reports-DqMs9xNR.js → reports-DdPq4blM.js} +7 -6
- package/dist/{resources-Bf9O1JNM.js → resources-Dqr01Dep.js} +150 -55
- package/dist/{run-D-NbZLpj.js → run-C9qg_QlC.js} +16 -22
- package/dist/scan-Cv5uOwVY.js +4 -0
- package/dist/{scan-BmAW413l.js → scan-DLrsrFS9.js} +48 -37
- package/dist/scope-V336uz8j.js +198 -0
- package/dist/screenshot-file-0UETadF8.js +16 -0
- package/dist/{selection-BGi6GyxC.js → selection-Rdw-ZUoG.js} +94 -51
- package/dist/send-BxD9yf6F.js +150 -0
- package/dist/{dev-CgGAb5Al.js → server-D0tGG8C4.js} +82 -87
- package/dist/server-z1LH94R_.js +22 -0
- package/dist/session-1AV_Bs_d.js +6 -0
- package/dist/session-CFAmMhem.js +40 -0
- package/dist/session-D_nEWKXT.js +768 -0
- package/dist/skills/animate-onboarding/SKILL.md +467 -0
- package/dist/skills/animate-onboarding/references/engine.md +494 -0
- package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
- package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
- package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
- package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
- package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
- package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
- package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
- package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
- package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
- package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
- package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
- package/dist/skills/animate-onboarding/references/performance.md +41 -0
- package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
- package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
- package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
- package/dist/skills/index.json +37 -0
- package/dist/skills/mobile-design/SKILL.md +447 -0
- package/dist/skills/mobile-design/references/responsive.md +162 -0
- package/dist/skills/onboarding-questions/SKILL.md +231 -0
- package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
- package/dist/skills/onboarding-questions/references/craft.md +142 -0
- package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
- package/dist/skills/superwall/SKILL.md +82 -9
- package/dist/skills/superwall/references/api.md +153 -37
- package/dist/skills/superwall/references/apple-setup.md +316 -0
- package/dist/skills/superwall/references/asc.md +74 -38
- package/dist/skills/superwall/references/data-analytics.md +55 -21
- package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
- package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
- package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
- package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
- package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
- package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
- package/dist/skills/superwall/workflows/placements/android.md +2 -2
- package/dist/skills/superwall/workflows/placements/expo.md +2 -2
- package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
- package/dist/skills/superwall/workflows/placements/ios.md +2 -2
- package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
- package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
- package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
- package/dist/skills/superwall/workflows/review/playbook.md +1 -1
- package/dist/skills/superwall-editor/SKILL.md +61 -0
- package/dist/skills/superwall-editor/references/cli.md +135 -0
- package/dist/skills/superwall-editor/references/design.md +51 -0
- package/dist/skills/superwall-editor/references/native-elements.md +171 -0
- package/dist/skills/superwall-editor/references/workflow.md +65 -0
- package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
- package/dist/skills/superwall-framework/SKILL.md +78 -28
- package/dist/skills/superwall-framework/references/cli.md +58 -28
- package/dist/skills/superwall-framework/references/examples.md +4 -3
- package/dist/skills/superwall-framework/references/layout.md +30 -8
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
- package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
- package/dist/skills/wwdc/SKILL.md +22 -0
- package/dist/skills/wwdc/references/docs.md +52 -0
- package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
- package/dist/{skills-AxAf7bDB.js → skills-BvFOa4y6.js} +99 -122
- package/dist/skills-DMG4bpKk.js +14 -0
- package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
- package/dist/spinner-CneRK5rk.js +294 -0
- package/dist/storage-DYvmIOHa.d.ts +16 -0
- package/dist/storage-s2Dnz-yl.js +31 -0
- package/dist/storekit-DafAnGkM.js +16 -0
- package/dist/storekit-yY_kS2iR.js +47 -0
- package/dist/telemetry-DtG92m5O.js +56 -0
- package/dist/theme-DUsCh-Vd.js +25 -0
- package/dist/timing-BVxPrYq3.js +5 -0
- package/dist/{token-BGAVPSQc.js → token-DzRh7dI1.js} +6 -38
- package/dist/tools.d.ts +96 -0
- package/dist/tools.js +11178 -0
- package/dist/ui-D_qf3Gvw.js +53 -0
- package/dist/upgrade-Bt4Ouw1y.js +117 -0
- package/dist/upgrade-Cqy5orjb.js +7 -0
- package/package.json +10 -5
- package/dist/api-Dv3LyZ5m.js +0 -151
- package/dist/api-output-aJNw7Syy.js +0 -20
- package/dist/app-mJC5NDtW.js +0 -189
- package/dist/asa-D6H7Pjae.js +0 -1194
- package/dist/asc-xCin0akG.js +0 -539
- package/dist/auth-ZlLL-Gko.js +0 -139
- package/dist/billing-C8kBge_S.js +0 -80
- package/dist/command-3fGYyC8r.js +0 -301
- package/dist/dev-Dx99K183.js +0 -22
- package/dist/doctor-CyUvut31.js +0 -88
- package/dist/feedback-RKyGuQ8_.js +0 -152
- package/dist/hosted-BeGVAntr.js +0 -32
- package/dist/migrate-C-4ISELN.js +0 -284
- package/dist/org-CQduIOic.js +0 -40
- package/dist/output-C-4UKMot.js +0 -136
- package/dist/params-l3CrvRtR.js +0 -51
- package/dist/pipeline-CHX0Syre.js +0 -977
- package/dist/print-skill-BiZLdCKv.js +0 -74
- package/dist/promote-Pgpz-3xl.js +0 -88
- package/dist/publish-BPeuc3lq.js +0 -35
- package/dist/push-DcSQ4odB.js +0 -35
- package/dist/query-CWLaZkdm.js +0 -53
- package/dist/resource-jwASPCrw.js +0 -483
- package/dist/skills-FK5aDuNV.js +0 -64
- package/dist/spinner-DFctF_Jw.js +0 -18
- package/dist/storekit-CC4gnTI6.js +0 -29
- package/dist/telemetry-Ch9cCTI-.js +0 -169
- package/dist/ui-4gLyfrgl.js +0 -27737
- package/dist/update-DIXbL-H9.js +0 -59
- package/dist/upgrade-De7JMI1g.js +0 -72
- /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
|
|
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
|
|
49
|
-
|
|
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
|
|
77
|
-
superwall
|
|
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
|
|
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.
|
|
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
|
-
**
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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
|
|
52
|
-
superwall
|
|
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
|
|
61
|
-
|
|
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
|
|
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:
|
|
86
|
-
superwall campaigns
|
|
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
|
-
|
|
90
|
-
a project is created
|
|
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.
|
|
102
|
-
|
|
103
|
-
|
|
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
|
|
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
|
|
146
|
-
|
|
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
|
|
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
|
|
240
|
-
|
|
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
|