CLI Reference

The CLI has git semantics on purpose: push saves, promote ships. Every push mints a sealed version; nothing users see changes until promote points production at it. This page is the command reference. Push, promote & publish explains the model.

superwall create                  # scaffold superwall/ inside your app
superwall dev                     # studio on http://localhost:6100
superwall push                    # build + version. Production untouched.
superwall promote                 # point production at the latest push
superwall publish                 # push + promote in one step
superwall publish -m "Q3 test"    # record why

The scaffolded package scripts mirror these (dev, push, promote, ship).

Channel

SUPERWALL_CHANNEL=next opts the CLI into experimental and beta features, and the framework is one of them: its commands exist only while the variable is set, and without it the CLI answers Unknown command: create. Export it in your shell profile (for example ~/.zshrc) so every terminal and agent sees it. superwall create doesn't save it into the project, so a shell without the variable loses the framework commands. To pin one project to the channel instead, add SUPERWALL_CHANNEL=next to its superwall/.env, which the CLI loads when you run it from the app root or the superwall/ directory. The same variable gives superwall login and superwall skills the channel's agent skills, including superwall-framework:

export SUPERWALL_CHANNEL=next
superwall create

Auth

Run superwall login once interactively. In CI, set SUPERWALL_API_KEY (an sk_… key). The project's .env is the usual home for it. dev needs no login.

superwall create

Scaffolds a complete project: the directory skeleton, a starter paywall, dependencies installed, your Superwall app connected, and a git init if needed. Run inside an app that already has a superwall/ project (or inside the project itself), it adds a paywall to it instead: a starter named as you answer, or, with --from, the rebuilt dashboard paywall. Examples and --app apply to new projects only.

superwall migrate <paywall-id>

Rebuilds a dashboard paywall as code with your coding agent. If the paywall isn't in the project yet it scaffolds it exactly as create --from does, then asks whether to run the rebuild headless with the agent it finds (Claude Code or Codex), copy the prompt for an agent you drive yourself, or stop there. --skill prints that prompt to stdout for a paywall that is already in the project. Without a paywall id, migrate is the provider migration (RevenueCat, Adapty, Qonversion). See Migrating from the editor.

superwall migrate --screen <path>

Rebuilds a native screen (a SwiftUI, UIKit, Kotlin Compose or Views, React Native or Flutter file) as a Superwall surface. It reads the file's strings, assets, links, product identifiers and actions into paywalls/<slug>/config.ts and a MIGRATION.md brief, records the source in superwall.lock, and offers the same agent / copy-the-prompt choice as migrate <paywall-id>. Without a path it scans the app for likely screens and asks which one. --screenshot <file> saves a capture of the original for Compare › Original; with a booted iOS simulator and no --screenshot, the CLI offers to capture it. --skill prints the prompt for a screen already in the project. See Migrating native screens.

superwall dev

Hosts the studio for the project, or several at once with a glob (superwall dev examples/*). Regenerates superwall.d.ts first, so route and product types are always current.

It prints a Device URL and a QR beside the studio one: scan it to open the paywalls on a phone. If your app's App Transport Security would block a plain-http dev server, it offers to add the two Info.plist keys that allow local networking — say yes for development builds, and keep them out of release ones.

Project problems (stray files in app/, duplicate routes) print as warnings here, the same ones that block a push, so fix them as they appear.

superwall push

Builds every paywall, versions the changed ones, and leaves production alone. Re-running with nothing changed is a no-op.

A push refuses, before anything is written, when:

• a selected paywall has diagnostics (publishing is immutable; fix first), but a directory missing app/index.tsx or config.ts isn't a paywall yet, so it's skipped silently rather than blocking; superwall dev is where you see it,
• a product in config.ts doesn't exist on the dashboard (every variable on it would be undefined on device),
• a directory rename is unresolved (below),
• the project pushes to several platforms and a selected paywall's config.ts has no platforms field, see Several platforms.

The first push binds each paywall, creating it on Superwall if needed, and records the binding in superwall.lock, per platform; commit that file. After that, push always updates the same paywalls; no IDs ever appear in your code. If the app already has a headless paywall with the same id that superwall.lock doesn't bind, push never takes it over on its own: an interactive push asks, and any other run stops and names it. Add the printed line to superwall.lock if it's yours, or rename the directory to create a new paywall.

Every push also snapshots your superwall/ source, so the code each version was built from is recoverable. It merges your changes onto what teammates have published since your last push, from the commit superwall.lock records, and stops naming the files rather than overwriting their work; --overwrite-source replaces the saved source when you mean to. A version whose source didn't land is never promoted: the next push finishes it. .env, node_modules/, .git/, key and credential files, and anything superwall/.gitignore lists never leave the machine. See Source snapshots.

Renames

Renaming a paywall directory is detected, never guessed. Interactively, push asks whether the unfamiliar directory is a rename (keeping the live paywall attached) or a new paywall. In CI, declare it, anything unresolved stops the push rather than creating a duplicate:

superwall push --rename plus-upgrade=pro-upgrade

Deleting a paywall directory never blocks a push. The dashboard paywall keeps serving, and restoring the directory re-binds it.

superwall promote

Points production at a pushed version. Promote never rebuilds, it only moves the live pointer.

superwall promote --id plus-upgrade --version 5
# → Rolled back version 7 → 5

superwall publish

Push + promote in one step. Takes -m <note>, --id, --platform, and --rename. Also warns about other paywalls that are pushed-but-not-live, so nothing ships half-forgotten.

Before pushing: create the products

A push refuses if a config.ts names a product the dashboard doesn't have. The fix is a command away. The same CLI writes products directly:

superwall entitlements list --json                 # grab the NUMERIC entitlement id
superwall products create --identifier pro_3999_year \
  --project <id> --app <id> \
  --name "Annual" --price 39.99 --period year \
  --trial-days 7 --entitlement <numeric-id> --json

• --entitlement takes the numeric id (55688), not the identifier (pro), the identifier fails with a decode error.
• Pass --app <id|dashboard link> or --project <id> when your account has several projects, or the command stops with "You can open N projects" and lists them.
• --price is major units (39.99); --period is day|week|month|year; --trial-days sets the intro offer.
• --dry-run confirms the target before writing anything.

Before you push

• One broken surface blocks the whole push. A leftover scaffold aimed at a nonexistent product stops everything, push what you built with repeated --id flags instead of touching unrelated directories.

For the full error-message-to-fix table, see Troubleshooting.