# adapty-cli

Sets up and manages Adapty subscriptions, paywalls, placements and migrations from the command line, and reads Attribution analytics.

Skill by Adapty. Category: Agent craft.

## Install

Project (for this project only):

```sh
npx skills add adaptyteam/adapty-cli --skill adapty-cli
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add adaptyteam/adapty-cli --skill adapty-cli -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass
- Runlayer: Warn
- ZeroLeaks: Pass

Installs: 231. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/adaptyteam/adapty-cli/adapty-cli)

## Source

[Open the source](https://github.com/adaptyteam/adapty-cli/tree/HEAD/skills/adapty-cli). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: adapty-cli
description: Use when setting up or managing Adapty in-app subscriptions, paywalls, placements, or migrations via CLI, or when reading Attribution analytics (spend, installs, ROAS, cohort revenue, predictions) with `adapty attribution`.
---

# Adapty CLI Skill

## Installation

```sh
npm install -g adapty
```

Or run without installing:

```sh
npx adapty@latest
```

---

Two modes: **Setup** (new users, quiz-driven) and **Manage** (existing users, direct commands).

## Mode: Setup (New to Adapty)

The setup flow has 3 phases: **Quiz → Create → Guide**. Collect ALL information first, then create everything, then tell the user what to do next.

### Phase 1: Quiz

Before creating anything, detect the platform and then run an interactive quiz to collect all data.

**CRITICAL: You MUST use the AskUserQuestion tool for EVERY quiz question.** Do NOT print questions as regular text output. Each question must be a separate AskUserQuestion tool call so the user gets an interactive input prompt. After each answer, proceed to the next AskUserQuestion. This is non-negotiable.

**Step 1: Detect platform** — silently glob the codebase:

| Platform       | Glob pattern                                            |
| -------------- | ------------------------------------------------------- |
| iOS/Swift      | `**/*.swift`, `**/Package.swift`, `*.xcodeproj`         |
| Android/Kotlin | `**/*.kt`, `**/build.gradle.kts`                        |
| Flutter        | `**/pubspec.yaml` (look for `flutter:` key)             |
| React Native   | `**/react-native.config.js`, `**/app.json` with RN deps |
| Unity          | `**/ProjectSettings/ProjectSettings.asset`              |
| Capacitor      | `**/capacitor.config.ts`, `**/capacitor.config.json`    |
| KMP            | `**/build.gradle.kts` with `kotlin("multiplatform")`    |

**Step 2: Ask questions** — use AskUserQuestion tool calls. Bundle related sub-questions into a single AskUserQuestion to minimize round-trips (e.g. app name + platforms + bundle ID = one question). Suggest defaults so the user can just confirm or pick a number. Aim for 2-3 total AskUserQuestion calls, not one per field.

Bundle into 2-3 AskUserQuestion calls:

**AskUserQuestion 1: App + Products** — bundle app info and product selection:
> App name: [suggest from package.json, Info.plist, or AndroidManifest]
> Bundle ID: [suggest from detected config files]
> Platforms: 1. iOS only / 2. Android only / 3. Both
>
> Products: 1. Monthly (`monthly`) / 2. Annual (`annual`) / 3. Monthly + Annual / 4. Weekly (`weekly`) / 5. Lifetime (`lifetime`) / 6. Custom
>
> Valid `--period` values: `weekly`, `monthly`, `two_months`, `trimonthly`, `semiannual`, `annual`, `lifetime`. Do NOT use `month`, `year`, `yearly`, or any other aliases — use these exact API values.
> Product name prefix: [suggest based on app name, e.g. "Premium"]

After this answer, you have enough to generate store product IDs. Pre-fill them using the convention `<bundle_id>.<prefix>.<period>` and include in the next question.

**AskUserQuestion 2: Store IDs + Placements + Paywall approach** — confirm generated IDs and collect remaining info:
> **Store product IDs** — these MUST match the IDs you create (or will create) in App Store Connect / Google Play Console.
> Confirm or edit the suggested IDs:
> - iOS: `com.example.app.premium.monthly` / `com.example.app.premium.annual`
> - Android product ID: `premium_monthly` / base plan: `monthly-base` (if Android)
>
> If your iOS and Android IDs differ, enter them separately (e.g. "iOS: com.app.monthly, Android: monthly_sub / base plan: monthly-bp").
> If you haven't created store products yet, these suggestions work — just use the same IDs when you set them up in App Store Connect / Google Play Console later.
>
> Placements: 1. Onboarding (`onboarding`) / 2. Settings (`settings`) / 3. Feature gate (`feature_gate`) / 4. All of the above / 5. Custom
>
> Paywall UI: 1. Paywall Builder (visual editor, no UI code) / 2. Custom (your own UI)

### Phase 2: Create

After collecting all answers, confirm the plan with the user in a summary table, then create everything sequentially. Do NOT ask questions during creation — use collected data.

**IMPORTANT: Products and paywalls cannot be fully edited after creation** (period, store product IDs, base plan IDs are permanent). This is why Phase 1 confirmation is critical.

Execution order (each step uses output from previous):
1. `adapty auth login` (if not already authenticated, check with `adapty auth whoami`)
2. `adapty apps create --title "..." --platform ... --apple-bundle-id/--google-bundle-id ...` → save output: `id` (use as `--app`), `sdk_key` (use in SDK), plus the default access level `id` and `sdk_id` printed after creation
3. For each product: `adapty products create --app <APP_ID> --title "..." --period ... --access-level-id <DEFAULT_AL_ID> --ios-product-id/--android-product-id ... [--android-base-plan-id ...]` → save product IDs. Android subscriptions (non-lifetime) require `--android-base-plan-id`. Web products bind Stripe/Paddle instead: `--stripe-product-id`+`--stripe-price-id` or `--paddle-product-id`+`--paddle-price-id` (each pair required together).
4. `adapty paywalls create --app <APP_ID> --title "..." --product-id <ID1> --product-id <ID2> ...` → save paywall ID
5. For each placement: `adapty placements create --app <APP_ID> --title "..." --developer-id ... --audiences '[{"segment_ids":[],"paywall_id":"<PAYWALL_ID>","priority":0}]'`
   - `--paywall-id <PAYWALL_ID>` is still accepted as legacy shorthand but emits a stderr deprecation warning. Prefer `--audiences` for the canonical default-audience shape.

Print progress as you go (e.g. "Created app ✓", "Created product 'Monthly' ✓").
If a step fails, stop and ask the user how to proceed — don't retry blindly.

### Phase 3: Guide (Interactive Loop)

After all entities are created, print a brief summary with key values:

```
Dashboard:              https://app.adapty.io
Your SDK key:           <sdk_key from apps create>
Placement developer IDs: <list of developer_ids>
Access level SDK ID:    <sdk_id from access level, e.g. "premium">
```

Then use AskUserQuestion to ask what they want to do next. **Repeat this after each sub-guide until the user says they're done.** Build the options dynamically based on their setup answers:

> What do you want to do next?
> 1. Integrate SDK into the codebase
> 2. Configure app/products on Apple side *(only if iOS)*
> 3. Configure app/products on Google side *(only if Android)*
> 4. Design paywall in Paywall Builder *(only if they chose Paywall Builder)*
> 5. I'm done for now

**Option 1: SDK Integration** — print the quickstart link for their platform + paywall approach, plus the key values above. Use Context7 MCP for latest SDK code examples:
```
resolve-library-id: "adaptyteam/adapty-docs"
query-docs: topic="<platform> <feature>"
```

Paywall Builder quickstarts:
- iOS: `https://adapty.io/docs/ios-quickstart-paywalls.md`
- Android: `https://adapty.io/docs/android-quickstart-paywalls.md`
- Flutter: `https://adapty.io/docs/flutter-quickstart-paywalls.md`
- React Native: `https://adapty.io/docs/react-native-quickstart-paywalls.md`

Custom paywall quickstarts:
- iOS: `https://adapty.io/docs/ios-quickstart-manual.md`
- Android: `https://adapty.io/docs/android-quickstart-manual.md`
- Flutter: `https://adapty.io/docs/flutter-quickstart-manual.md`
- React Native: `https://adapty.io/docs/react-native-quickstart-manual.md`

**Option 2: Apple side** — print checklist:
- Create subscription products in App Store Connect with IDs: `<list ios_product_ids>`
- Adapty Dashboard → App Store Connect: upload In-App Purchase Key (.p8), enter Key ID, Issuer ID, Bundle ID, App Apple ID → `https://adapty.io/docs/app-store-connection-configuration.md`
- App Store Connect → Server Notifications V2: set URL from Adapty Dashboard → `https://adapty.io/docs/enable-app-store-server-notifications.md`

**Option 3: Google side** — print checklist:
- Create subscription products in Google Play Console with IDs: `<list android_product_ids>`, base plans: `<list base_plan_ids>`
- Adapty Dashboard → Google Play: upload service account JSON key, enter Package Name → `https://adapty.io/docs/google-play-store-connection-configuration.md`
- Google Play Console → RTDN: configure Pub/Sub topic from Adapty Dashboard → `https://adapty.io/docs/enable-real-time-developer-notifications-rtdn.md`

**Option 4: Paywall Builder** — link to dashboard paywalls section and guide: `https://adapty.io/docs/adapty-paywall-builder.md`

After showing any option's guide, **loop back** — ask "What's next?" again with the same AskUserQuestion (minus completed items if user indicates they're done with a step). Stop only when user picks "I'm done."

---

## Mode: Manage (Existing Adapty Users)

For users who already have an Adapty app and want to manage entities, see `references/cli-commands.md` for the full command reference.

Key notes:

- Product, paywall, placement, access-level and segment commands require `--app <APP_ID>` (UUID)
- `apps get <app_id>` and `apps update <app_id>` use a positional arg (no `--app` flag)
- For products, paywalls, placements and access levels, `get`/`update` use a positional resource ID **plus** `--app`
- Lists of these entities and apps support `--page` and `--page-size`; `migrations list` does not
- All commands support `--json`
- Use `--title` for apps, products, paywalls, placements and access levels; `migrations create` uses `--name`
- Use `--apple-bundle-id` / `--google-bundle-id` (not ios/android)

### Migrations

For migrations into Adapty, read [Migrations in the command reference](references/cli-commands.md#migrations).
The server supplies the available flows, action IDs and input schemas.

- Create with `--name` for a new app, or `--flow` and `--app` together for an existing app, as offered by `migrations list`
- Pass `-m` explicitly in scripts; otherwise the CLI uses `ADAPTY_MIGRATION`, then the selection saved by `use` or `create`
- Use `create --no-select` to preserve the shared default; `current` shows selection and `unuse` clears saved selection
- Use `status --json` to read the current action's `reads`, `input_schema` and `confirm` before running it
- Review `confirm` before passing `--yes`; migration commands do not show interactive confirmation prompts
- Check `migration.state` after each action or wait; exit 0 does not mean the migration completed

---

## Apple Ads

The `adapty asa` commands ship in this CLI and are listed in the `asa` section of `references/cli-commands.md`;
`asa metrics` is the Apple-reported side of the attribution crosswalk. The agent guidance for managing Apple Ads
campaigns (write rules, playbooks, and vertical guides) lives in the `apple-ads` skill at
[adaptyteam/apple-ads-cli](https://github.com/adaptyteam/apple-ads-cli). Reads (`asa whoami`, any `list`,
`asa metrics`) are safe to run directly; open `apple-ads` before any `asa` write, because writes spend real money
and cannot be undone.

---

## Attribution Analytics

Cross-network attribution analytics (spend, installs, revenue, ROAS, cohort values, and predictions, as the
Attribution dashboard shows them) live in the read-only `adapty attribution` topic. See the `attribution` section of
`references/cli-commands.md`. Discover before querying: `adapty attribution metrics`, then `dimensions`, then
`values`, then `report`. A `null` value means not computable, never zero.

---

## Adapty Concepts

- **Product** — subscription or one-time purchase mapped to store product IDs. Has a period, grants an access level.
- **Paywall** — screen showing products. Can use Paywall Builder (visual editor) or remote config (custom JSON).
- **Placement** — location in app where paywall appears. Identified by `developer_id`. Holds one or more audiences; each audience routes a segment to a paywall by priority. Default audience (`segment_ids: []`) is the fallback and must have max priority.
- **Access Level** — permission gate (e.g. "premium"). Products grant access levels on purchase. Identified by `sdk_id`.
- **Segment** — filter rule (e.g. "VIP users"). Read-only via CLI: `adapty segments list --app <APP_ID>`. Compose into placement audiences to give different segments different paywalls at the same placement.
- **Audience** — `(segments, paywall, priority)` tuple inside a placement. Auto-materialized from segment composition. CLI exposes audiences as the `--audiences` JSON shape on `placements create`/`update`.

---

## Documentation

- Full docs index: `https://adapty.io/docs/llms.txt`
- Individual pages: `https://adapty.io/docs/<slug>.md`
- SDK code examples: Context7 MCP with `adaptyteam/adapty-docs`
````

- Previous: [forge-cost-optimizer](https://syn4pse.dev/terminal/forge-cost-optimizer.md)
- Next: [apply-conventions](https://syn4pse.dev/terminal/playcanvas-apply-conventions.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
