CLI Reference
Every superwall command (create, dev, push, promote, publish) with flags, auth, and the checks that run before anything ships.
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 whyThe scaffolded package scripts mirror these (dev, push, promote, ship).
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, when the app is not already in a git repository, a new one with the scaffold and everything else in the folder committed. 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.
After installing, create checks that the framework resolves from superwall/. In a pnpm monorepo whose workspace doesn't include superwall/, it retries with pnpm install --ignore-workspace; if the framework still isn't there, it names the command to run instead of reporting success. See Project structure.
The default starter and --from include a design system: DESIGN.md, design/tokens.css, design/base.css and a shared components/Button.tsx. The starter paywall's app/theme.css imports the two stylesheets. Examples from --example don't include one. When create adds a paywall to an existing project, it writes any of these files that are missing and leaves the rest alone. See The design system.
| Flag | What it does |
|---|---|
--example <name> | Start from an example instead of the default starter. |
--from <paywall-id> | Rebuild a dashboard paywall as code: scaffolds paywalls/<slug>/config.ts from the paywall's products, presentation, settings, background and locales, writes a MIGRATION.md brief with an inventory of its pages, actions and variables, records the source in superwall.lock so the studio can show it under Compare › Original, and connects the paywall's app. Needs a login and a paywall your account can open; cannot be combined with --example or --no-connect. See Migrating from the editor. |
--app <id> | Connect this Superwall app by id instead of detecting it from the SDK key or asking, so an agent binds the right app without a picker. Fails if the id isn't in your account. |
--yes, -y | Accept the defaults and skip the optional prompts. |
--no-install | Skip installing dependencies. |
--no-connect | Skip connecting a Superwall app; the first push connects you. Incompatible with --app. |
--no-git | Skip the git step: outside a git repository, create otherwise runs git init and commits the scaffold together with everything else in the folder. Use it when the repository's own rules decide what gets committed. Needs superwall 2.6.0 or later. |
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. --dry-run reads the paywall and its served document, then prints what it would create under paywalls/<slug> and the app id it would save in superwall.lock; it writes nothing, offers no rebuild and opens no studio. It still needs a login to read the paywall, still refuses what a real run refuses (a slug that already exists, a package.json in superwall/ that isn't a superwall project, a headless paywall or one this account can't see, a paywall with no served document), and ends with Dry run - no changes made. 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. --dry-run reads the file and prints its inventory and the paywalls/<slug> it would create; it writes nothing, asks for no screenshot, offers no rebuild and opens no studio. It still refuses what a real run refuses (a slug that already exists, a package.json in superwall/ that isn't a superwall project, a --screenshot file that isn't there), and ends with Dry run - no changes made. 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.
| Flag | What it does |
|---|---|
--port, -p | Port, default 6100, moves to the next free port if taken. |
--host | Bind address, default 0.0.0.0, so a phone on the same wifi can reach it. |
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.
When a newer superwall release is out, it prints the command to update right after it starts, and the studio shows it in a banner. See Update prompts.
superwall push
Builds every paywall, versions the changed ones, and leaves production alone. Re-running with nothing changed is a no-op.
| Flag | What it does |
|---|---|
--id <id> | Limit to these paywalls or funnels; repeatable or comma-separated. |
--platform <p> | Limit to these platforms (ios, android, web); repeatable or comma-separated. |
--rename <old>=<new> | Declare a directory rename so CI can resolve it. |
-m <note> | Recorded on the source commit, it only lands when the source actually changed. |
--overwrite-source | Replace this paywall's source in the app's source repo with yours, with its shared files and superwall.lock entries. Other paywalls in the repo stay as they are. |
--existing | Only push paywalls already on Superwall, meaning bound in superwall.lock. Any other paywall or platform is skipped with a note instead of being created. Apps come from superwall.lock, so it never asks for one. Combines with --id and --platform. |
--source | Also push the project source to every app in this run whose paywalls didn't change, so shared files such as the design system reach every app's source repo. Apps with a changed paywall already get the source with that push. Needs at least one paywall already on Superwall in the run to carry it. -m and --overwrite-source apply to it too. |
To ship a design-system change, such as a new value in design/tokens.css, to every paywall already on Superwall without creating new ones:
superwall publish --existing --source -m "Rounder corners"publish makes every rebuilt paywall live, including any that were pushed but never promoted. To version them without going live, run superwall push --existing --source instead.
A push refuses, before anything is written, when:
- a selected paywall has diagnostics (publishing is immutable; fix first), but a directory missing
app/index.tsxorconfig.tsisn't a paywall yet, so it's skipped silently rather than blocking;superwall devis where you see it, - a product in
config.tsdoesn'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.tshas noplatformsfield, 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 writes only the pushed paywall's folder, the shared files and that paywall's superwall.lock entries; other paywalls stay as the app's source repo has them. It merges 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: run superwall pull, then push again, or push with --overwrite-source to replace only this paywall's source. 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.
A paywall with teleport: { route } also has that route pre-rendered, so the web page paints before its JavaScript runs. A page that can't be pre-rendered prints a warning and is left out; it never fails the push, and that page renders in the browser instead. See How the web page loads.
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-upgradeDeleting 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.
| Flag | What it does |
|---|---|
--id <id> | Limit to one paywall or funnel. |
--platform <p> | Limit to one platform. |
--version, -v <n> | Pick a specific version (with a single --id, and --platform when that paywall is on several platforms), which is also the rollback. |
superwall promote --id plus-upgrade --version 5
# → Rolled back version 7 → 5superwall publish
Push + promote in one step. Takes -m <note>, --id, --platform, --rename, --overwrite-source, --existing, and --source, which work as they do for push. Also warns about other paywalls that are pushed-but-not-live, so nothing ships half-forgotten.
superwall pull
Merges each bound app's source repo into superwall/: teammates' paywalls and funnels, their bindings in superwall.lock, and the sync point the next push merges from. Your own edits stay. No GitHub repo needed.
pull needs superwall 2.3.0 or later. Inside a project, the project's own superwall dependency is the CLI that runs, so if it's older you get Unknown command: pull whatever version you installed globally. See Which CLI runs.
superwall pull # merge what teammates published
superwall pull --theirs # take the repo's copy of conflicting files
superwall pull --app 20749 # new project from the app's source| Flag | What it does |
|---|---|
--theirs | For each file that conflicts, take the repo's whole copy of it. |
--platform <p> | Limit the pull to the apps of these platforms. |
--app <app> | With no project, create [dir]/superwall/ from this app's source. Refuses a folder that's already a project or a superwall/ that has files. |
Edits to different lines of one file merge cleanly; a conflict changes nothing and names the files. See superwall pull.
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 create --identifier pro --app <id>
superwall products create --identifier pro_3999_year \
--app <id> \
--name "Annual" --price 39.99 --period year \
--trial-days 7 --entitlement pro --json--entitlementtakes an entitlement's identifier (pro) or its id, and repeats for more than one. The CLI resolves each to the entitlement on the product's app.- In a project with several apps, name the same app on both commands. An entitlement on another app than the product's is refused before anything is written, with a message naming both apps.
- 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. --priceis major units (39.99). In superwall 2.6.0 and later, it's converted with the currency's own decimals:--price 1200 --currency JPYis ¥1200, and a price with more decimals than the currency allows is refused.--periodisday|week|month|year;--trial-dayssets the intro offer.- For a custom store, pass the store's id or name as
--app.--store customwithout--appuses the project's default custom store, and--storealso takesapp_storeandplay_store. These need superwall 2.6.0 or later. --dry-runconfirms 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
--idflags instead of touching unrelated directories.
For the full error-message-to-fix table, see Troubleshooting.
How is this guide?