superwall · DreamingInBinary · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,7 +2,7 @@
 
 Instructions for AI coding agents working in this repository (Superwall docs site).
 
-For documentation-writing guidelines (tone, content conventions, etc.), see `content/README/AGENTS.md`.
+For documentation-writing tone and conventions, match the existing pages under `content/docs/**`; there is no separate writing-guidelines file.
 
 ## Project overview
 - **Stack**: Next.js + Fumadocs (MDX) + TailwindCSS
@@ -23,21 +23,18 @@ For documentation-writing guidelines (tone, content conventions, etc.), see `con
 
 ## Common commands (run from repo root)
 ```bash
-# Dev (http://localhost:8293)
+# Dev (http://localhost:3000; override with `bun run dev:port <port>`)
 bun run dev
 
-# Build (runs all generators, then MDX + Next build)
+# Build (runs generators, then Vite build + static cache + search index)
 bun run build
 
 # Clear caches (when build/dev gets weird)
-rm -rf .next
-bun run clear:cache
+rm -rf node_modules/.vite
 
-# Content generation / assets
-bun run generate:llm
-bun run generate:md
-bun run copy:docs-images
-bun run watch:images
+# Content generation / assets (images auto-copy via predev/prebuild)
+bun run scripts/copy-docs-images.cjs
+bun run generate:changelog
 
 # Cloudflare builds / preview
 bun run build:cf
@@ -57,7 +54,7 @@ bun run deploy
   - Create the `.mdx` file under the correct `content/docs/**` folder.
   - Update the folder’s `meta.json` to include it in navigation.
   - Run `bun run build` to verify generation + routing.
-- **Images**: assets in docs content are copied into `public/` during build (use `bun run copy:docs-images`; in dev use `bun run watch:images`).
+- **Images**: assets in docs content are copied into `public/` automatically before dev and build (`predev`/`prebuild` run `scripts/copy-docs-images.cjs`).
 
 ## Routing, redirects, and base path
 - The site is served under **`/docs`** (`basePath` + `assetPrefix` in `next.config.ts`).
@@ -128,7 +125,8 @@ This clones/pulls SDK repos into `reference/` (gitignored). Use the source to co
 
 ## Troubleshooting
 - **Build failures**: check MDX syntax; validate `meta.json`; ensure listed pages exist; run `bun run build` for full errors.
-- **Dev server issues**: `rm -rf .next`, `bun run clear:cache`, verify port 8293 is free, reinstall dependencies if needed.
+- **Dev server issues**: `rm -rf node_modules/.vite`, verify port 3000 is free, reinstall dependencies if needed.
+- **Preview shows stale content after a rebuild**: restart `bun run preview` - its Cloudflare cache emulation keeps serving the previous build (`cf-cache-status: HIT`).
 
 ## Skill mirrors
 - Keep `.agents/skills/` and `.claude/skills/` in sync for shared skills.
diff --git a/content/docs/dashboard/guides/query-clickhouse.mdx b/content/docs/dashboard/guides/query-clickhouse.mdx
@@ -5,6 +5,8 @@ description: "Use the Superwall API to query your organization's ClickHouse-back
 
 The ClickHouse query API gives you direct SQL access to the same analytics data Superwall uses for charts and campaign results. Use it when you need flexible reporting, internal dashboards, or ad hoc analysis without maintaining a separate data warehouse.
 
+Querying from the terminal or a coding agent? The [Superwall CLI](/dashboard/guides/superwall-cli#query-your-analytics-data) wraps this API: `superwall query "SELECT count() FROM sw.events_rep"` runs against your logged-in session, with no key handling needed.
+
 Requests are scoped to your organization and require an organization API key with the `data:read` scope. Superwall provisions a read-only ClickHouse user for your organization on first use, then applies row-level policies so queries only return data for your organization's applications.
 
 <Warning>

diff --git a/content/docs/dashboard/guides/superwall-cli.mdx b/content/docs/dashboard/guides/superwall-cli.mdx
@@ -0,0 +1,216 @@
+---
+title: "Superwall CLI"
+description: "Set up the SDK, manage products, campaigns, and paywalls, query your analytics data, and call the API from your terminal or coding agent using the Superwall CLI."
+---
+
+The [Superwall CLI](https://github.com/superwall/cli) brings your whole Superwall account to the terminal: set up the SDK in your app, manage products, campaigns, and paywalls, run SQL against your analytics data, and call the Superwall and App Store Connect APIs. It's built for humans and coding agents alike, so everything it can do, your agent can do too.
+
+<Note>
+The CLI is also what powers the [Superwall Skill](/dashboard/guides/superwall-skill). Installing the skill teaches your coding agent to use these commands on your behalf, so you rarely need to memorize them. This page is the full reference for when you're driving the terminal yourself, or want to know exactly what your agent can do.
+</Note>
+
+## Installation
+
+Install the CLI globally with npm, then log in:
+
+```bash
+npm install --global superwall
+superwall login
+```
+
+You can also run it without installing via `npx superwall`. The package installs two commands that behave identically: `superwall` and the shorter `sw`.
+
+The CLI tells you when a new version is available. Update any time with:
+
+```bash
+superwall upgrade
+```
+
+## Authentication
+
+`superwall login` opens your browser once, and every command shares that session. The session is stored in `~/.superwall`.
+
+```bash
+superwall login     # opens the browser
+superwall whoami    # shows the logged-in account
+superwall logout    # ends the session
+```
+
+<Frame>![Running superwall login in the terminal. The CLI shows a device code, waits for browser approval, then confirms the logged-in account and checks the agent skills.](/images/cli_prompt_for_auth.png)</Frame>
+
+Approve the login on the page that opens, and you're done. The terminal picks it up automatically:
+
+<Frame>![The auth.superwall.com confirmation page after approving the login, telling you the device is connected and the page can be closed.](/images/cli_confirmation.jpg)</Frame>
+
+In CI or other headless environments, log in with an API key instead of a browser:
+
+```bash
+superwall login --api-key <key>
+```
+
+If your account belongs to more than one organization, pick one with `superwall orgs use`. Otherwise, the CLI asks the first time it matters.
+
+<Note>
+Logging in also installs the [Superwall agent skills](/dashboard/guides/superwall-skill) into your coding agents and keeps them updated. See [Install agent skills](#install-agent-skills) below.
+</Note>
+
+## Set up your app
+
+The CLI's workflow commands handle SDK setup end to end:
+
+```bash
+npx superwall integrate   # set up Superwall in your app from scratch
+superwall migrate         # switch from RevenueCat, Adapty, or Qonversion
+superwall review          # audit an existing setup; add --fix to repair issues
+superwall doctor          # quick health check
+```
+
+`integrate` is the fastest way to get started, and it works even before you have a Superwall account: run it in your project directory and it walks you through signing up right from the terminal. It works out what kind of app it's looking at, connects it to your Superwall account, and then runs the coding agent already on your machine (Claude Code or Codex, headless) to install and configure the SDK. From there it walks you through the rest: products, campaigns, placements, paywalls, and verifying everything on a real device.
+
+`migrate` does the same for apps moving off RevenueCat, Adapty, or Qonversion, and `review` audits an existing integration, with `--fix` applying verified, safe fixes. Here's the end of a `review` run against a real iOS app: findings ranked by severity, proposed fixes written to a plan file, and nothing modified without your say-so:
+
+<Frame>![The end of a superwall review report on an iOS app, summarizing verified strengths, genuine findings, and a plan file with proposed fixes. No files were modified.](/images/cli_improvements_report_iOS_example.jpg)</Frame>
+
+### Drive the agent yourself
+
+The CLI normally runs its workflows through a headless Claude Code or Codex on your machine. Add `--skill` to `integrate`, `migrate`, or `review` and instead of running anything, the CLI prints the exact instructions it would have given that agent: the bundled playbook for the task, composed for your project's framework, so an Expo project gets Expo instructions and never sees Swift ones.
+
+```bash
+superwall integrate --skill   # prints the playbook, runs nothing
+```
+
+Reach for this when:
+
+- **You use a different agent.** The CLI only drives Claude Code and Codex headlessly. Paste the playbook into Cursor, Gemini CLI, or any other agent and it can follow the same guided workflow there.
+- **You want to stay in the loop.** A headless run works autonomously and reports back. Running the playbook in your own agent session lets you watch every step, approve each change, and steer as it goes.
+- **You want to read it first.** Review exactly what the agent will be told to do before anything touches your codebase.
+
+## Manage your account
+
+Everything in the dashboard, from the terminal:
+
+```bash
+superwall apps list
+superwall products create pro_monthly --price 9.99 --period month
+superwall products storekit               # generate a local .storekit file
+superwall entitlements create pro
+superwall campaigns create "Onboarding upsell" onboarding_complete
+superwall paywalls list
+superwall bootstrap                       # the whole account tree at a glance
+```
+
+| Command | Actions | Notes |
+|---------|---------|-------|
+| `bootstrap` | | Prints the complete account tree: orgs, projects, apps, campaigns, placements, and products |
+| `apps` | `list`, `create`, `use` | Projects and platform apps; `create` takes `--platform` and `--bundle` |
+| `products` | `list`, `create`, `storekit` | `create` takes `--price`, `--currency`, `--period`, `--period-count`, `--trial-days`, `--entitlement`; `storekit` writes a local `.storekit` file (`--out`) |
+| `entitlements` | `list`, `create` | |
+| `campaigns` | `list`, `create`, `placement` | `create` takes a name and a placement name |
+| `paywalls` | `list` | |
+| `orgs` | `list`, `use` | Only needed if you belong to multiple organizations |
+
+`list` is the default action, so `superwall products` means `superwall products list`. Add `--json` for machine-readable output, and `--project <id>` or `--app <id>` to scope when you have more than one. Run `superwall <command> --help` for every action and flag.
+
+## Query your analytics data
+
+Run SQL directly against your organization's ClickHouse analytics data:
+
+```bash
+superwall query "SHOW TABLES FROM sw"
+superwall query "SELECT count() FROM sw.events_rep"
+superwall query --file mrr.sql       # runs a saved .sql file
+cat query.sql | superwall query      # or pipe SQL on stdin
+```
+
+Use it for anything you'd build on raw data: ad hoc analysis, custom dashboards, scheduled reports, agent workflows. `--json` returns ClickHouse's native JSON envelope (leave any `FORMAT` clause out of the SQL; the CLI requests JSON for you). Your session needs data read access.
+
+See [Query with ClickHouse](/dashboard/guides/query-clickhouse) for the available tables and schema.
+
+## Call the API
+
+Make raw, authenticated requests to any Superwall API endpoint:
+
+```bash
+superwall get /v2/products
+superwall post /v2/products -d name="Pro Monthly" -d price:=9.99
+superwall delete /v2/products/prod_123
+```
+
+Params follow an httpie-style convention: `-d key=value` sends a string, `key:=value` sends typed JSON (numbers, booleans, objects), and `key[sub]=value` nests. On `get` and `delete`, `-d` params become query parameters.
+
+## App Store Connect
+
+The entire App Store Connect API, proxied and signed by Superwall, with no `.p8` file or JWT to manage locally. Connect your credentials once:
+
+```bash
+superwall asc keys set --key-id <id> --issuer <id> --key-file AuthKey.p8
+```
+
+From there, you can call any endpoint in the ASC API. The CLI is schema-aware: it keeps a copy of Apple's own OpenAPI spec (fetched on first use, refreshed in the background) and knows every endpoint, field, and enum.
+
+Look up the exact schema for anything, without hunting through Apple's docs:
+
+```bash
+superwall asc docs                          # browse every resource
+superwall asc docs "introductory offer"     # search by keyword
+superwall asc docs /v1/subscriptions post   # required fields, enums, relationships
+```
+
+Write with flat params. The CLI assembles the JSON:API body for you and validates it locally, so a mistake comes back as a precise fix instead of one of Apple's opaque `409` errors:
+
+```bash
+superwall asc post /v1/subscriptions \
+  -d name="Premium Monthly" -d productId=com.acme.pro \
+  -d subscriptionPeriod=MONTHLY -d group=<groupId>
+```
+
+```
+✗ Invalid POST /v1/subscriptions body:
+  • subscriptionPeriod "MONTHLY" not allowed — use ONE_WEEK|ONE_MONTH|…|ONE_YEAR
+```
+
+Fix the value and it goes through. Shortcuts cover the common reads (`asc apps`, `asc products <bundle-id>`, `asc subscriptions <bundle-id>`, `asc iaps <bundle-id>`); everything else is `asc get|post|patch|delete /v1/...`. If your organization has more than one ASC team connected, scope with `--team <id>`.
+
+## Install agent skills
+
+Logging in installs the [Superwall agent skills](/dashboard/guides/superwall-skill) into your coding agents automatically and keeps them updated. To reinstall them (or a subset) manually:
+
+```bash
+npx superwall skills
+```
+
+The CLI shows a picker with every skill pre-selected, so pressing **Enter** installs them all, globally, for every coding agent detected on your machine (Claude Code, Cursor, Codex, Gemini CLI, Copilot, Windsurf, and more). To skip the picker or force a refresh:
+
+```bash
+superwall skills --skill superwall        # install specific skills by name
+superwall skills --force                  # reinstall even if already up to date
+```
+
+## For agents and scripts
+
+Pass `--json` to any command: stable output shape, structured errors, and it never prompts. `--no-interactive` keeps the human-readable output but drops the prompts.
+
+```bash
+superwall products list --json
+superwall query "SELECT count() FROM sw.events_rep" --json
+```
+
+## Feedback
+
+Something broken, confusing, or missing? Send feedback straight to the team:
+
+```bash
+superwall feedback "migrate crashed on Expo"
+```
+
+## Telemetry
+
+The CLI sends fully anonymous usage events (which workflow ran and whether it succeeded, never emails, IDs, file paths, SQL, prompts, or error messages). Opt out with `SUPERWALL_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`.
+
+## Related
+
+- [Superwall Skill](/dashboard/guides/superwall-skill): Give your coding agent live Superwall docs and this CLI.
+- [Superwall MCP](/dashboard/guides/superwall-mcp): Manage your account from MCP-compatible AI tools.
+- [Query with ClickHouse](/dashboard/guides/query-clickhouse): The analytics tables behind `superwall query`.
+- [Editor MCP](/dashboard/dashboard-creating-paywalls/paywall-editor-mcp): Connect an agent to the paywall open in your editor.
+- [Vibe Coding](/sdk/guides/vibe-coding): All the AI tools available for working with Superwall in one place.
diff --git a/content/docs/dashboard/guides/superwall-mcp.mdx b/content/docs/dashboard/guides/superwall-mcp.mdx
@@ -79,6 +79,7 @@ When the agent creates an application, it returns a `public_api_key`. That's wha
 
 - [Superwall Agents](/agents): AI workspace for Superwall analysis with connected tooling, automations, webhooks, and hosted machines.
 - [Superwall Skill](/dashboard/guides/superwall-skill): Recommended if you want docs access, guided SDK integration, and account management in one tool.
+- [Superwall CLI](/dashboard/guides/superwall-cli): Manage your account, query analytics, and integrate the SDK from the terminal.
 - [Editor MCP](/dashboard/dashboard-creating-paywalls/paywall-editor-mcp): Connect an external agent to the paywall currently open in the editor.
 - [AI Chat Builder](/dashboard/dashboard-creating-paywalls/paywall-editor-ai-chat): Build and refine paywalls with Superwall's built-in editor chat.
 - [Vibe Coding](/sdk/guides/vibe-coding): Overview of the AI tools available for working with Superwall.