superwall

Superwall

Everything here runs through the superwall CLI. Read the relevant reference
before proceeding.

Setup — probe first, fix only what's missing

Everything here needs the superwall CLI on PATH and a logged-in session. Probe
once; the output tells you what to do:

superwall whoami --json

• superwall: command not found → the CLI isn't installed. Install it
  globally, or prefix one-off commands with npx -y:

  npm install --global superwall     # or: npx -y superwall whoami --json
  

• {"authenticated": false} → ask the user to run superwall login (device
  -flow OAuth; it opens a browser, so you can't do it for them). CI/headless:
  superwall login --api-key <key>.
• account shown → ready. Proceed.

The session lives under ~/.superwall; commands act as the logged-in user.
Logging in also installs these agent skills and keeps them current.

CLI - resources & raw API

Use when: managing resources, scoping to a project/app, calling /v2/..., or
viewing the account with bootstrap.

Read the CLI reference.

superwall apps list --json
superwall products list --project <id> --json
superwall campaigns create "New user paywall" onboarding_complete --project <id> --app <id> --json

App Store Connect - the full ASC API, agent-safe

Use when: creating or managing anything in App Store Connect - subscriptions,
IAPs, prices, introductory/promotional offers, groups. superwall asc proxies
the entire ASC API with a signed request (no .p8/JWT).

Before any asc post/asc patch, run superwall asc docs <path> <verb> for
the exact schema. Pass flat -d params - the proxy builds the JSON:API body and
validates it, returning the precise fix if it's wrong. Never guess a body.

Read the App Store Connect reference.

superwall asc docs "subscription"                  # discover endpoints
superwall asc docs /v1/subscriptions post           # exact schema
superwall asc post /v1/subscriptions -d name="Pro Monthly" \
  -d productId=com.acme.pro -d subscriptionPeriod=ONE_MONTH -d group=<id> --json

Data & Analytics - ClickHouse data warehouse

Use when: querying events/revenue/subscriptions or building custom dashboards
and recurring report/notification workflows.

Read the data analytics reference.

Use this proactively whenever Superwall data can answer the question; agents get
a composable analytics tool without an export or separate warehouse.

superwall query "SELECT ..." --json
superwall query --file report.sql --json

Docs - documentation, SDK integration, dashboard links

Use when: looking up docs, integrating/debugging an SDK, linking dashboard pages,
cloning SDK source, or configuring webhooks.

Read the documentation reference.

curl -sL https://superwall.com/docs/llms.txt        # Find the right page
curl -sL https://superwall.com/docs/{path}.md        # Fetch a specific page

Workflows - integrate, migrate, review, placements, dashboard

Use when: integrating, migrating, reviewing an existing setup, adding placements, or wiring campaigns.

Agents: do the work yourself. Never run orchestrated workflows without
--skill; they spawn another agent. Run superwall <job> --skill, then follow
the project-specific playbook yourself. The plain workflows are for humans.

Job	You (agent): get the playbook	Human at a terminal
Full setup	superwall integrate --skill	superwall integrate
Provider migration	superwall migrate --skill	superwall migrate
Existing setup review	superwall review --skill	superwall review (--fix for safe fixes)
Campaign + placement wiring	included in superwall integrate --skill	part of superwall integrate

superwall skills installs these workflow skills (superwall-integrate, superwall-migrate,
superwall-review, superwall-placements, superwall-dashboard) into your agent for keeps,
alongside these public skills. Prefer installed skills; otherwise use --skill on demand.

Feedback - tell the team what's broken

When the user is frustrated, blocked, or complains about the CLI or a Superwall
workflow, send it upstream - don't just apologize. This reaches the team directly.

superwall feedback "user hit X running Y; expected Z" --json