@superwall/cli 2.1.1 → 2.2.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 (107) hide show
  1. package/README.md +12 -1
  2. package/dist/{apple-BHbX0jbn.js → apple-DaqaI4vD.js} +13 -13
  3. package/dist/auth.d.ts +1 -1
  4. package/dist/auth.js +3 -3
  5. package/dist/{billing-4zhIBFRQ.js → billing-DyKr2kmd.js} +3 -3
  6. package/dist/{bind-CHLHmxgA.js → bind-BpxebZf4.js} +4 -4
  7. package/dist/{build-5PQeSnNN.js → build-DzbdRThf.js} +6 -6
  8. package/dist/{client-BIvOmWPC.js → client-BF9rCULI.js} +3 -3
  9. package/dist/{create-VK-pNfN7.js → create-B55V99TD.js} +22 -22
  10. package/dist/create-BYAPuhhf.js +19 -0
  11. package/dist/{create-BSNIFsnN.js → create-D7AZHYGH.js} +6 -6
  12. package/dist/{doctor-9JS96QkX.js → doctor-B2mPKiaJ.js} +6 -6
  13. package/dist/{drivers-BamBJ10Y.js → drivers-DOMky8Ug.js} +3 -3
  14. package/dist/entry.js +19 -19
  15. package/dist/{environment-eV7LEnSN.js → environment-DBwo79dy.js} +1 -1
  16. package/dist/{existing-C8dSYHGk.js → existing-B4VK4BCL.js} +2 -2
  17. package/dist/held-C9FqvNbn.js +16 -0
  18. package/dist/{held-BMisHn8F.js → held-DjcZPCwn.js} +6 -6
  19. package/dist/{integrate-VWtTNPCr.js → integrate-B8oHbvwz.js} +21 -21
  20. package/dist/{login-BmwG14LC.js → login-B8hgMLhS.js} +1 -1
  21. package/dist/login-D-a7oS_8.js +16 -0
  22. package/dist/{login-BimbukE5.js → login-DfhqWY9C.js} +256 -33
  23. package/dist/{lookup-k9EeOiZr.js → lookup-r8p6H2ZC.js} +2 -2
  24. package/dist/{migrate-C86h6jeF.js → migrate-DQf2Fosc.js} +21 -21
  25. package/dist/{notification-url-BVaTgWZ5.js → notification-url-BxPTEmkv.js} +2 -2
  26. package/dist/{open-0tDCQOXC.js → open-CrEnSL4v.js} +21 -17
  27. package/dist/{org-DUwdrKPV.js → org-Cc2WGvl1.js} +2 -2
  28. package/dist/{paths-BCbjCLP5.js → paths-BcNbJfpw.js} +1 -1
  29. package/dist/{playbook-oov9yV0q.js → playbook-D9J8frkE.js} +10 -10
  30. package/dist/{promote-DPGPamkE.js → promote-C8T7DCFF.js} +16 -16
  31. package/dist/{push-Cz4lJ8Qd.js → push-Bzs1l_5C.js} +4 -4
  32. package/dist/push-snV3SrnH.js +22 -0
  33. package/dist/{registry-CTczUigi.js → registry-CpxZbmxp.js} +83 -63
  34. package/dist/{resources-B1qKDVXd.js → resources-Bo6i7wBi.js} +1 -1
  35. package/dist/{run-DTPsVmFw.js → run-BUp4r8Kk.js} +2 -2
  36. package/dist/{scan-Bb48xZqB.js → scan-8cxu2fx0.js} +1 -1
  37. package/dist/scan-nUeXs9a1.js +4 -0
  38. package/dist/{scope-B6UYGuwn.js → scope-CPG_wWXL.js} +4 -4
  39. package/dist/{selection-BbNk9r1q.js → selection-CMA4aG4V.js} +3 -3
  40. package/dist/server-Boqa8jh_.js +22 -0
  41. package/dist/{server-EYBMKAG1.js → server-Xb3wp-mx.js} +66 -16
  42. package/dist/{session-xG9E8J2N.js → session-DOZV1TP6.js} +1 -1
  43. package/dist/session-DtBpdlF-.js +6 -0
  44. package/dist/{session-Crg9X-FI.js → session-eZeXR9xU.js} +9 -8
  45. package/dist/skills/animate-onboarding/SKILL.md +1 -1
  46. package/dist/skills/index.json +18 -18
  47. package/dist/skills/mobile-design/SKILL.md +1 -1
  48. package/dist/skills/onboarding-questions/SKILL.md +1 -1
  49. package/dist/skills/superwall/SKILL.md +102 -17
  50. package/dist/skills/superwall/references/api.md +13 -2
  51. package/dist/skills/superwall/references/data-analytics.md +7 -8
  52. package/dist/skills/superwall/workflows/dashboard/playbook.md +2 -1
  53. package/dist/skills/superwall/workflows/dashboard/setup.md +3 -1
  54. package/dist/skills/superwall/workflows/integrate/playbook.md +4 -2
  55. package/dist/skills/superwall/workflows/migrate/adapty.md +3 -3
  56. package/dist/skills/superwall/workflows/migrate/playbook.md +2 -1
  57. package/dist/skills/superwall/workflows/migrate/qonversion.md +3 -3
  58. package/dist/skills/superwall/workflows/migrate/revenuecat.md +4 -4
  59. package/dist/skills/superwall-editor/SKILL.md +53 -1
  60. package/dist/skills/superwall-framework/SKILL.md +10 -5
  61. package/dist/skills/superwall-framework/references/migrate-from-editor.md +3 -2
  62. package/dist/skills/superwall-framework/references/mobile-design.md +1 -1
  63. package/dist/{skills-Dg3k6TRC.js → skills-BI19OGlS.js} +8 -8
  64. package/dist/{skills-BdMKE2uO.js → skills-DDf10ufO.js} +4 -4
  65. package/dist/{spinner-Ba3XhlMb.js → spinner-BClMQGGN.js} +3 -3
  66. package/dist/{storage-CerJ5KLP.d.ts → storage-BbJF7z3l.d.ts} +1 -0
  67. package/dist/{storage-DIkYajce.js → storage-Po9E-CHL.js} +12 -2
  68. package/dist/storekit-BU6Eq_UO.js +16 -0
  69. package/dist/{storekit-C2UzIIMs.js → storekit-Cbn9DBLA.js} +3 -3
  70. package/dist/{telemetry-CVP8O6Y3.js → telemetry-s6dag6tb.js} +1 -1
  71. package/dist/{token-IWv2httm.js → token-CPplNMVa.js} +1 -1
  72. package/dist/tools-skills/animate-onboarding/SKILL.md +1 -1
  73. package/dist/tools-skills/mobile-design/SKILL.md +1 -1
  74. package/dist/tools-skills/onboarding-questions/SKILL.md +1 -1
  75. package/dist/tools-skills/superwall/SKILL.md +80 -8
  76. package/dist/tools-skills/superwall/references/api.md +116 -24
  77. package/dist/tools-skills/superwall/references/apple-setup.md +316 -0
  78. package/dist/tools-skills/superwall/references/asc.md +74 -38
  79. package/dist/tools-skills/superwall/references/data-analytics.md +62 -29
  80. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +3 -3
  81. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +8 -8
  82. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +6 -6
  83. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +4 -4
  84. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +5 -5
  85. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +6 -6
  86. package/dist/tools-skills/superwall/workflows/placements/android.md +2 -2
  87. package/dist/tools-skills/superwall/workflows/placements/expo.md +2 -2
  88. package/dist/tools-skills/superwall/workflows/placements/flutter.md +2 -2
  89. package/dist/tools-skills/superwall/workflows/placements/ios.md +2 -2
  90. package/dist/tools-skills/superwall/workflows/placements/playbook.md +2 -2
  91. package/dist/tools-skills/superwall/workflows/placements/react-native.md +2 -2
  92. package/dist/tools-skills/superwall/workflows/placements/strategy.md +2 -2
  93. package/dist/tools-skills/superwall/workflows/review/playbook.md +1 -1
  94. package/dist/tools-skills/superwall-editor/SKILL.md +2 -2
  95. package/dist/tools.d.ts +8 -8
  96. package/dist/tools.js +21 -24
  97. package/dist/{upgrade-DLf0LJDh.js → upgrade-1OYm5NQU.js} +2 -2
  98. package/dist/{upgrade-1t3aQUxh.js → upgrade-ahapZeex.js} +1 -1
  99. package/package.json +2 -2
  100. package/dist/create-oj3zXvHZ.js +0 -19
  101. package/dist/held-DeJW2gUk.js +0 -16
  102. package/dist/login-2JHCG6c1.js +0 -16
  103. package/dist/push-Chp21y3a.js +0 -22
  104. package/dist/scan-B1SkkUi7.js +0 -4
  105. package/dist/server-CwrZ-I1r.js +0 -22
  106. package/dist/session-DItGa4z0.js +0 -6
  107. package/dist/storekit-DHNxDDpA.js +0 -16
@@ -1,10 +1,10 @@
1
- import { a as CHANNEL, o as CHANNELS, v as VERSION } from "./environment-eV7LEnSN.js";
1
+ import { a as CHANNEL, o as CHANNELS, v as VERSION } from "./environment-DBwo79dy.js";
2
2
  import { m as writeSkillsSync, s as readSkillsSync } from "./config-BO1Y87kV.js";
3
- import { r as track } from "./telemetry-CVP8O6Y3.js";
3
+ import { r as track } from "./telemetry-s6dag6tb.js";
4
4
  import { r as spawnStream } from "./spawn-DmmmHIP-.js";
5
- import { n as withSpinner } from "./spinner-Ba3XhlMb.js";
5
+ import { n as withSpinner } from "./spinner-BClMQGGN.js";
6
6
  import { n as ui } from "./ui-D_qf3Gvw.js";
7
- import { i as packagedDir, t as AGENT_SKILLS_DIR } from "./paths-BCbjCLP5.js";
7
+ import { i as packagedDir, t as AGENT_SKILLS_DIR } from "./paths-BcNbJfpw.js";
8
8
  import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
9
9
  import { join } from "node:path";
10
10
  import { tmpdir } from "node:os";
@@ -1,7 +1,7 @@
1
- import { r as NotLoggedInError } from "./token-IWv2httm.js";
1
+ import { r as NotLoggedInError } from "./token-CPplNMVa.js";
2
2
  import { i as writeJson, n as createCommandOutput } from "./output-Ggzq5_-t.js";
3
- import { a as CHANNEL } from "./environment-eV7LEnSN.js";
4
- import { t as ApiError } from "./client-BIvOmWPC.js";
3
+ import { a as CHANNEL } from "./environment-DBwo79dy.js";
4
+ import { t as ApiError } from "./client-BF9rCULI.js";
5
5
  import { n as ui, r as useRenderer } from "./ui-D_qf3Gvw.js";
6
6
  import pc from "picocolors";
7
7
 
@@ -1,4 +1,5 @@
1
1
  //#region src/core/account/storage.d.ts
2
+
2
3
  interface Session {
3
4
  authMethod?: "oauth" | "api_key";
4
5
  apiKey?: string;
@@ -1,11 +1,21 @@
1
1
  import { l as readJson, r as formatJson, u as state } from "./output-Ggzq5_-t.js";
2
- import { n as API_HOST_OVERRIDE, t as API_HOST } from "./environment-eV7LEnSN.js";
2
+ import { n as API_HOST_OVERRIDE, t as API_HOST } from "./environment-DBwo79dy.js";
3
3
 
4
4
  //#region src/core/account/storage.ts
5
5
  const sessionOrgName = (session) => {
6
6
  return session?.authMethod === "api_key" ? session.orgName : void 0;
7
7
  };
8
8
  const FILE = "auth.json";
9
+ const PENDING_FILE = "pending-login.json";
10
+ function writePendingLogin(pending) {
11
+ state().write(PENDING_FILE, `${formatJson(pending)}\n`);
12
+ }
13
+ function readPendingLogin() {
14
+ return readJson(state(), PENDING_FILE) ?? null;
15
+ }
16
+ function removePendingLogin() {
17
+ state().remove(PENDING_FILE);
18
+ }
9
19
  function writeSession(session) {
10
20
  state().write(FILE, `${formatJson(session)}\n`);
11
21
  }
@@ -28,4 +38,4 @@ function serializeSession(session) {
28
38
  }
29
39
 
30
40
  //#endregion
31
- export { sessionOrgName as a, serializeSession as i, removeSession as n, writeSession as o, resolveApiHost as r, readSession as t };
41
+ export { resolveApiHost as a, writePendingLogin as c, removeSession as i, writeSession as l, readSession as n, serializeSession as o, removePendingLogin as r, sessionOrgName as s, readPendingLogin as t };
@@ -0,0 +1,16 @@
1
+ import "./token-CPplNMVa.js";
2
+ import "./output-Ggzq5_-t.js";
3
+ import "./environment-DBwo79dy.js";
4
+ import "./storage-Po9E-CHL.js";
5
+ import "./client-BF9rCULI.js";
6
+ import "./config-BO1Y87kV.js";
7
+ import "./spinner-BClMQGGN.js";
8
+ import "./ui-D_qf3Gvw.js";
9
+ import "./resources-Bo6i7wBi.js";
10
+ import "./org-Cc2WGvl1.js";
11
+ import "./lookup-r8p6H2ZC.js";
12
+ import "./scope-CPG_wWXL.js";
13
+ import "./input-vi0bou04.js";
14
+ import { n as writeStoreKit, t as generateStoreKit } from "./storekit-Cbn9DBLA.js";
15
+
16
+ export { generateStoreKit, writeStoreKit };
@@ -1,7 +1,7 @@
1
1
  import { r as formatJson } from "./output-Ggzq5_-t.js";
2
- import { t as apiCall } from "./spinner-Ba3XhlMb.js";
3
- import { m as listResource } from "./resources-B1qKDVXd.js";
4
- import { a as pickScope } from "./scope-B6UYGuwn.js";
2
+ import { t as apiCall } from "./spinner-BClMQGGN.js";
3
+ import { m as listResource } from "./resources-Bo6i7wBi.js";
4
+ import { a as pickScope } from "./scope-CPG_wWXL.js";
5
5
  import { r as textOf } from "./input-vi0bou04.js";
6
6
  import { writeFileSync } from "node:fs";
7
7
 
@@ -1,4 +1,4 @@
1
- import { S as isNonInteractive, g as TELEMETRY_KEY, h as TELEMETRY_HOST, v as VERSION } from "./environment-eV7LEnSN.js";
1
+ import { S as isNonInteractive, g as TELEMETRY_KEY, h as TELEMETRY_HOST, v as VERSION } from "./environment-DBwo79dy.js";
2
2
  import { h as writeTelemetryNoticeShown, l as telemetryNoticeShown, t as readAnonymousId } from "./config-BO1Y87kV.js";
3
3
 
4
4
  //#region src/core/support/telemetry.ts
@@ -1,4 +1,4 @@
1
- import { o as writeSession, t as readSession } from "./storage-DIkYajce.js";
1
+ import { l as writeSession, n as readSession } from "./storage-Po9E-CHL.js";
2
2
 
3
3
  //#region src/core/account/errors.ts
4
4
  var NotLoggedInError = class extends Error {
@@ -38,7 +38,7 @@ skill assumes that shape, and the engine below is mapped onto its router:
38
38
  ().paywall !== undefined`), never mount: the SDK preloads surfaces hidden.
39
39
 
40
40
  Read the `superwall-framework` skill before touching the flow (install it if
41
- it isn't there: `npx skills add https://github.com/superwall/skills/tree/next
41
+ it isn't there: `npx skills add https://github.com/superwall/skills
42
42
  --skill superwall-framework --global --yes --agent claude-code universal
43
43
  --full-depth`); its `references/mobile-design.md` carries the touch, motion
44
44
  and type rules this skill builds on. A flow that is not a surface yet (a
@@ -440,7 +440,7 @@ screen that already exists — and read the `superwall-framework` skill for
440
440
  the mechanics; the user decides. Install it if it isn't there:
441
441
 
442
442
  ```bash
443
- npx skills add https://github.com/superwall/skills/tree/next --skill superwall-framework --global --yes --agent claude-code universal --full-depth
443
+ npx skills add https://github.com/superwall/skills --skill superwall-framework --global --yes --agent claude-code universal --full-depth
444
444
  ```
445
445
 
446
446
  This skill is complete without it: everything above applies to any web
@@ -36,7 +36,7 @@ version, and a campaign switches it live.
36
36
 
37
37
  So when the spec is approved, the next step is to build it there: the
38
38
  `superwall-framework` skill carries the how (install it if missing: `npx
39
- skills add https://github.com/superwall/skills/tree/next --skill
39
+ skills add https://github.com/superwall/skills --skill
40
40
  superwall-framework --global --yes --agent claude-code universal
41
41
  --full-depth`), its `onboarding-quiz` and `web-funnel` examples are the two
42
42
  shapes this spec takes (in-app before the paywall; on the web before
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: superwall
3
- description: Use the `superwall` CLI to manage apps, products, entitlements, campaigns, paywalls, App Store Connect, Apple Search Ads, and ClickHouse analytics. Also covers documentation lookup, dashboard links, SDK source inspection, and integration, migration, review, and dashboard workflows. Use for Superwall API or CLI tasks, data analysis, SDK setup, provider migration, webhook events, and SDK debugging — and whenever an app has a screen it should be able to change without a release (paywall, onboarding, update-required, lifecycle prompt, announcement), which belongs in Superwall as a surface behind a placement. When the Superwall MCP connector is available, use its tools directly for account tasks (apps, products, entitlements, campaigns, paywalls, webhooks, analytics) and keep the CLI for everything else.
3
+ description: Use the `superwall` CLI to manage apps, products, entitlements, campaigns, paywalls, App Store Connect (including connecting its keys, server notifications and revenue provider), Apple Search Ads, and ClickHouse analytics. Also covers documentation lookup, dashboard links, SDK source inspection, and integration, migration, review, and dashboard workflows. Use for Superwall API or CLI tasks, data analysis, SDK setup, provider migration, webhook events, and SDK debugging — and whenever an app has a screen it should be able to change without a release (paywall, onboarding, update-required, lifecycle prompt, announcement), which belongs in Superwall as a surface behind a placement. When the Superwall MCP connector is available, use its tools directly for account tasks (apps, products, entitlements, campaigns, paywalls, webhooks, analytics) and keep the CLI for everything else.
4
4
  ---
5
5
 
6
6
  # Superwall
@@ -11,6 +11,26 @@ and current documentation; account commands need the `superwall` CLI. When the
11
11
  Superwall MCP connector is available, use its tools directly for account data
12
12
  and configuration. Use the CLI for capabilities the connector does not expose.
13
13
 
14
+ ## MCP tools - the same commands, without a terminal
15
+
16
+ Every MCP tool is a CLI command: its name is the command's words joined by
17
+ `_` (`apps_get`, `campaigns_placements_create`, `asc_subscriptions_create`,
18
+ `query`, `api_docs`), its input is the command's arguments and flags in
19
+ `snake_case` (`--event-name` is `event_name`), and it returns the command's
20
+ `--json` output. Everything this skill says about a command applies to its tool.
21
+ There is no `whoami` tool; `apps_list` shows what the user can reach. Each call
22
+ acts as the signed-in user, with their dashboard role. Destructive tools run
23
+ without the CLI's own confirmation, so the same approval rules apply before
24
+ calling them.
25
+
26
+ Work that needs the user's machine has no tool. Ask the user to run it in a
27
+ terminal (`npx superwall <command>`, after `npx superwall login`): `integrate`,
28
+ `review`, `migrate`, `setup apple`, `asc keys create`, `asc keys update`,
29
+ `asc screenshots upload`, `products storekit`, `apps use`, `login`, `logout`,
30
+ `whoami`, `doctor`, `skills`, `upgrade`, `feedback`, and on the `next`
31
+ channel the paywall-as-code commands (`create`, `dev`, `build`, `push`,
32
+ `promote`, `publish`).
33
+
14
34
  ## CLI prerequisite — use the installed version
15
35
 
16
36
  CLI tasks require a one-time user installation:
@@ -20,7 +40,8 @@ npm install --global superwall
20
40
  ```
21
41
 
22
42
  Use `superwall ...` directly once it is installed. Do not automatically install
23
- or upgrade the CLI, or use a download-and-run fallback. Ask the user to install
43
+ or upgrade the CLI, or use a download-and-run fallback, with one exception:
44
+ before reporting a bug, upgrade and retry (see Feedback below). Ask the user to install
24
45
  it if a requested CLI task cannot proceed. Bundled playbooks, references, local
25
46
  SDK review, and documentation tasks remain available without the CLI.
26
47
 
@@ -39,6 +60,11 @@ 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.
@@ -51,7 +77,9 @@ 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.
@@ -76,12 +104,23 @@ endpoint and its exact body. The API covers far more than the resource commands
76
104
  (campaign audiences, variants and traffic weights, users, webhooks, charts,
77
105
  retention): search it, never guess a path or a body.
78
106
 
107
+ Commands follow the API, Stripe-style: `superwall <resource> [nested]
108
+ <operation> [ids] [--field value]`, with `list · get · create · update · delete`
109
+ everywhere the API has them. **Run `superwall <resource> --help` for its
110
+ operations and `superwall <resource> <operation> --help` for the exact flags**
111
+ (read from the live API reference) - never guess a flag. For an endpoint no
112
+ resource covers, find it with `superwall api docs` and call it with the raw
113
+ `get|post|patch|delete /v2/...` verbs.
114
+
79
115
  ```bash
80
116
  superwall apps list --json
117
+ superwall apps get <app> --json # everything about one app
118
+ superwall apps update <app> --bundle-id com.acme.app --json
81
119
  superwall paywalls list --app <id|dashboard link> --search onboarding --json
120
+ superwall campaigns create --description "New user paywall" --placement onboarding_complete --app <id> --json
121
+ superwall campaigns audiences --help # what a nested resource can do
82
122
  superwall api docs variant # find endpoints by keyword
83
123
  superwall api docs /v2/campaigns/{id}/audiences/{audience_id}/variants post # exact body
84
- superwall campaigns create "New user paywall" onboarding_complete --project <id> --app <id> --json
85
124
  ```
86
125
 
87
126
  ## App Store Connect - App Store Connect API
@@ -103,6 +142,25 @@ superwall asc post /v1/subscriptions -d name="Pro Monthly" \
103
142
  -d productId=com.acme.pro -d subscriptionPeriod=ONE_MONTH -d group=<id> --json
104
143
  ```
105
144
 
145
+ ## Apple setup - bundle ID, keys, server notifications, revenue provider
146
+
147
+ Use when: setting an app's bundle ID or package name, connecting an iOS app to
148
+ App Store Connect, getting Apple's server notifications to Superwall (directly,
149
+ through RevenueCat, or from the user's server), or reading or changing the
150
+ revenue provider. Each step is one command;
151
+ the reference is the order to run them in. Look before you change anything,
152
+ import a key before creating one, never create a second key, and never change
153
+ the revenue provider without the user's decision.
154
+
155
+ [Read the Apple setup reference](references/apple-setup.md).
156
+
157
+ ```bash
158
+ superwall apps get <app> --json # bundle ID, SDK reports, keys, URL, revenue provider
159
+ superwall asc keys import --app <app> --json # reuse a key the organization has
160
+ superwall asc notification-url check --app <app> --json # what Apple has, and whose it is
161
+ superwall apps update <app> --revenue-provider <p> # only after the user decides
162
+ ```
163
+
106
164
  ## Apple Search Ads - Apple Ads API
107
165
 
108
166
  Use when: reading or managing Apple Search Ads - campaigns, ad groups,
@@ -136,9 +194,14 @@ the connector does not expose the needed capability.
136
194
 
137
195
  ```bash
138
196
  superwall query "SELECT ..." --json
139
- superwall query --file report.sql --json
197
+ superwall query --file report.sql --app <id> --json
140
198
  ```
141
199
 
200
+ For anything about revenue, pass `--app` and filter by the app's revenue
201
+ provider with the `{revenue_integrations:Array(String)}` parameter it fills, or
202
+ the numbers double-count apps that send revenue from both the store and
203
+ RevenueCat (see the reference).
204
+
142
205
  ## Screens as code - the Superwall framework
143
206
 
144
207
  Use when: building or editing anything that ships through Superwall as a
@@ -172,11 +235,11 @@ That work has its own skill carrying the framework's full documentation.
172
235
  Prefer it if installed (`superwall-framework`); otherwise install it:
173
236
 
174
237
  ```bash
175
- npx skills add https://github.com/superwall/skills/tree/next --skill superwall-framework --global --yes --agent claude-code universal --full-depth
238
+ npx skills add https://github.com/superwall/skills --skill superwall-framework --global --yes --agent claude-code universal --full-depth
176
239
  ```
177
240
 
178
- The framework is a private beta on the `next` channel: the CLI has these
179
- commands only while `SUPERWALL_CHANNEL=next` is set in the environment. If
241
+ The framework is in public beta. Until the CLI turns these commands on by
242
+ default, it has them only while `SUPERWALL_CHANNEL=next` is set in the environment. If
180
243
  `superwall create` answers `Unknown command`, the variable is missing from
181
244
  your environment: ask the user to set it globally (shell rc) and relaunch.
182
245
 
@@ -246,6 +309,15 @@ missing features count too (`--kind idea`).
246
309
  end-user emails or IDs. Org and email of the logged-in account go along
247
310
  automatically for follow-up.
248
311
 
312
+ Before reporting a bug, make sure it still happens on the latest CLI: it may
313
+ already be fixed.
314
+
315
+ 1. Compare `superwall --version` with `npm view superwall version`.
316
+ 2. If the installed version is older, run `superwall upgrade`, then repeat
317
+ the exact command that failed.
318
+ 3. Fixed by the upgrade → tell the user which version fixed it and send
319
+ nothing. Still broken → report it, with the version you reproduced it on.
320
+
249
321
  ```bash
250
322
  superwall feedback "Ran X; expected Y; got Z. Steps: 1… 2… 3…" \
251
323
  --title "push 413s on assets over 2MB" --kind bug \
@@ -7,12 +7,17 @@ lives in `~/.superwall`.
7
7
 
8
8
  ```bash
9
9
  superwall login # device-flow OAuth (opens browser); acts as you
10
- superwall whoami --json # show the logged-in account / org
10
+ superwall whoami --json # show the logged-in account
11
11
  superwall logout --json
12
12
  ```
13
13
 
14
14
  Add `--help` / `-h` to any command for its flags.
15
15
 
16
+ `SUPERWALL_API_KEY` is only ever the organization's secret key (`sk_…`), which
17
+ CI uses to push and promote without a login. It is never the app's public key:
18
+ `superwall integrate` takes that (`pk_…`) from `--api-key`, or finds it in the
19
+ project. Never read, print or move either key.
20
+
16
21
  ## Data hierarchy
17
22
 
18
23
  Organization → Projects → Applications. Each application has a `platform` (ios,
@@ -54,16 +59,59 @@ uses two-space indentation, never prompts, and returns errors as `{ "error": {
54
59
 
55
60
  ## Resources
56
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
+
57
71
  ```bash
58
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
59
74
  superwall products list --project <id> --json
60
75
  superwall entitlements list --project <id> --json
61
76
  superwall campaigns list --project <id> --app <id> --json
77
+ superwall campaigns get <campaignId> --json
62
78
  superwall paywalls list --project <id> --app <id> --json
79
+ superwall users subscriptions <appUserId> --app <id> --json
80
+ superwall webhooks list --app <id> --json
63
81
  ```
64
82
 
65
- `apps list` nests apps under their projects - there is no separate projects
66
- command; `--project <id>` is how you scope when it matters.
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
101
+ ```
102
+
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.
67
115
 
68
116
  **Large accounts.** Every `list` takes `--search <text>` (matches id, name,
69
117
  identifier or bundle id, case-insensitively) and `--limit <n>`. With `--json` a
@@ -80,13 +128,13 @@ tree instead of the whole account.
80
128
  ```bash
81
129
  # Apps: an app is a platform of a project. Without --project a new project is spun
82
130
  # up for it; each project allows one app per platform.
83
- superwall apps create "My App" --platform ios [--bundle com.acme.app] [--project <projectId>] --json
131
+ superwall apps create --name "My App" --platform ios [--bundle-id com.acme.app] [--project <projectId>] --json
84
132
 
85
133
  # Entitlements
86
- superwall entitlements create pro --project <id> --json
134
+ superwall entitlements create --identifier pro --project <id> --json
87
135
 
88
136
  # Products (identifier is required; the rest is a full definition, mainly for agents)
89
- superwall products create com.acme.pro.monthly \
137
+ superwall products create --identifier com.acme.pro.monthly \
90
138
  --name "Pro Monthly" \
91
139
  --price 9.99 --currency USD \
92
140
  --period month --period-count 1 \
@@ -94,15 +142,16 @@ superwall products create com.acme.pro.monthly \
94
142
  --entitlement pro \
95
143
  --project <id> --json # repeatable: grant multiple entitlements
96
144
 
97
- # Campaigns (the create arg is a description)
98
- superwall campaigns create "Onboarding paywall" onboarding_complete --project <id> --app <id> --json
145
+ # Campaigns: a description and the placement that triggers it
146
+ superwall campaigns create --description "Onboarding paywall" --placement onboarding_complete --project <id> --app <id> --json
99
147
 
100
- # Placements: attach a placement (event name) to a campaign
101
- superwall campaigns placement <campaignId> onboarding_complete --project <id> --app <id> --json
148
+ # Placements: trigger an existing campaign on another event
149
+ superwall campaigns placements create <campaignId> --event-name onboarding_complete --project <id> --app <id> --json
102
150
  ```
103
151
 
104
- Projects aren't created directly - add the first platform with `apps create` and
105
- a project is created for you.
152
+ `create` always takes flags, never positionals. Projects aren't created
153
+ directly - add the first platform with `apps create` and a project is created
154
+ for you.
106
155
 
107
156
  ### StoreKit config
108
157
 
@@ -113,10 +162,30 @@ superwall products storekit --project <id> [--out Superwall.storekit] --json
113
162
  ## App Store Connect
114
163
 
115
164
  Superwall proxies the App Store Connect API with a signed request - no `.p8`
116
- file or JWT to manage locally. Use credentials the user has already connected
117
- privately. If missing, have the user consult `superwall asc keys set --help`
118
- at their own terminal and complete setup themselves. Do not request, inspect,
119
- or upload private key files or secrets as an agent.
165
+ file or JWT to manage locally. It uses the key the organization has for the
166
+ Apple team. Connecting keys, Apple's server notifications and the revenue
167
+ provider are in the [Apple setup reference](apple-setup.md). Do not request,
168
+ inspect, or upload private key files or secrets as an agent.
169
+
170
+ ```bash
171
+ superwall apps get <app> --json # bundle ID, Apple keys, notification URL, SDK reports, revenue provider
172
+ superwall asc keys import --app <app> --json # reuse a key the organization already has
173
+ superwall asc notification-url check --app <app> --json # what Apple has, and whose it is
174
+ ```
175
+
176
+ An app's own keys are managed with `asc keys`; `superwall apps get <app>` shows
177
+ which it has:
178
+
179
+ ```bash
180
+ superwall asc keys list --app <id> --json # the app's keys
181
+ superwall asc keys import --app <id> --json # reuse a key the organization already has
182
+ superwall asc keys import api_key --app <id> --from <app> --json # ...from that app
183
+ superwall asc keys sources --app <id> --json # keys import could use
184
+ superwall asc keys create api_key --app <id> # signs in to Apple: a person runs this
185
+ superwall asc keys delete purchase_key --app <id> --json
186
+ superwall asc notification-url check --app <id> --json # whose URL Apple sends purchase events to
187
+ superwall asc notification-url set --app <id> --json # set it where Apple has none
188
+ ```
120
189
 
121
190
  Then call ASC through the proxy:
122
191
 
@@ -124,11 +193,10 @@ Then call ASC through the proxy:
124
193
  # Shortcuts
125
194
  superwall asc apps --json
126
195
  superwall asc products <bundle-id | asc-app-id> --json
127
- superwall asc subscriptions com.acme.app --json
196
+ superwall asc subscriptions list com.acme.app --json
128
197
 
129
- # Raw API - a verb + path, or just a path (defaults to GET)
198
+ # Raw API - a verb + path
130
199
  superwall asc get /v1/apps --json
131
- superwall asc /v1/apps --json
132
200
  superwall asc post /v1/... -d key=value -d count:=3 --json
133
201
 
134
202
  # Multiple connected teams
@@ -157,8 +225,10 @@ A malformed body is rejected locally with the exact fix (missing required field,
157
225
  invalid enum value) before it ever reaches Apple's opaque errors. Fix the payload
158
226
  using the reported schema; keep validation enabled.
159
227
 
160
- For end-to-end recipes (creating a subscription with prices and offers) and the
161
- full workflow, see the [App Store Connect reference](asc.md).
228
+ For the resource commands (subscription groups, subscriptions, in-app purchases,
229
+ localizations, prices, offers, availability, review screenshots, submissions)
230
+ and releases (versions, builds, metadata, release), see the
231
+ [App Store Connect reference](asc.md).
162
232
 
163
233
  ## Apple Search Ads
164
234
 
@@ -168,7 +238,7 @@ Nothing is stored locally; the CLI picks the connected iOS app itself, or takes
168
238
  `--app <id>`:
169
239
 
170
240
  ```bash
171
- superwall asa keys list --json # which apps are connected
241
+ superwall asa keys --json # which apps are connected
172
242
 
173
243
  # Resources: asa <resource> <action> [id], scoped with --campaign / --adgroup / --adam-id
174
244
  superwall asa campaigns list --json
@@ -270,8 +340,30 @@ or on stdin. With `--json`, omit the SQL `FORMAT` clause because the CLI request
270
340
  ClickHouse JSON. Without `--json`, any explicit ClickHouse `FORMAT` clause is
271
341
  preserved.
272
342
 
273
- The CLI supplies the current organization ID and authenticated session. The
274
- credential must have `data:read` access. See `data-analytics.md` for exposed
343
+ The CLI supplies the organization ID and authenticated session. The credential
344
+ must have `data:read` access.
345
+
346
+ ### Revenue: always use the app's revenue provider
347
+
348
+ Many apps receive revenue from both the store and RevenueCat, so the same
349
+ purchase can arrive twice. Each app's **revenue provider** decides which one its
350
+ dashboard figures count, and every revenue query must count the same rows or
351
+ its numbers won't match the dashboard. Pass `--app <id>`: the query then gets
352
+ the provider as ClickHouse parameters, `{app:UInt64}`,
353
+ `{revenue_provider:String}` (`open_revenue`, `revenue_cat`, or empty) and
354
+ `{revenue_integrations:Array(String)}`. Filter revenue exactly like this:
355
+
356
+ ```sql
357
+ -- superwall query --file revenue.sql --app <id> --json
358
+ SELECT sum(price) AS revenue
359
+ FROM open_revenue.attributed_events_by_ts_rep FINAL
360
+ WHERE applicationId = {app:UInt64}
361
+ AND (integration IN {revenue_integrations:Array(String)} OR source = 'sdk')
362
+ AND NOT (coalesce(integration, '') = 'revenue_cat' AND store = 'STRIPE')
363
+ ```
364
+
365
+ `--param name=value` adds any other parameter (`{from:Date}`). One query covers
366
+ one app's provider; query apps with different providers separately. See `data-analytics.md` for exposed
275
367
  tables, query patterns, and performance guardrails.
276
368
 
277
369
  ## Utilities