KAppMaker CLI

Full documentation at [cli.kappmaker.com](https://cli.kappmaker.com)

CLI tool that automates the entire mobile app launch process — from project scaffolding to store-ready builds.

A single kappmaker create command can:

• Clone a template repository and set up a new project
• Create a Firebase project, register Android + iOS apps, enable authentication, and download SDK configs
• Generate an AI-powered app logo with automatic background removal
• Create an App Store Connect listing with metadata, categories, age rating, subscriptions, privacy declarations, and review contact info
• Configure an existing Google Play Console app — store listings, subscriptions, one-time in-app products, and the data safety declaration — via a built-in wrapper around the Play Publisher API (no external CLI, no extra dependencies)
• Set up Adapty subscription products, paywalls, and placements for both iOS and Android
• Refactor Gradle package names and application IDs
• Set up the build environment (Android SDK)
• Produce a signed Android release build (AAB) via Fastlane, ready to upload to Google Play

On top of that, standalone commands let you generate marketing screenshots from a text description, translate screenshots to 48+ locales in parallel, generate arbitrary images with AI, remove image backgrounds, enhance image quality, and split grid images — all powered by AI.

By default it uses the KAppMaker boilerplate (Kotlin Multiplatform), but you can bring your own template repository via --template-repo or kappmaker config set templateRepo <your-repo-url>. Boilerplate-specific steps (Gradle refactor, Fastlane build, CocoaPods) are automatically detected and skipped with a warning when using a custom template.

Installation

npm install -g kappmaker

Then use it anywhere:

kappmaker create <AppName>

<details> <summary>Development setup</summary>

npm install
npx tsx src/index.ts create <AppName>

</details>

Configuration

Run interactive setup to configure API keys and preferences:

kappmaker config init

Or set keys individually:

kappmaker config set falApiKey <your-key>       # For AI features (logo, screenshots) — or prompted on first use
kappmaker config set imgbbApiKey <your-key>      # For screenshot translation/generation — or prompted on first use
kappmaker config set openaiApiKey <your-key>     # For generate-screenshots — or prompted on first use
kappmaker config set templateRepo <your-repo>    # Use your own template (default: KAppMaker)

See all config keys and external services setup for details.

Claude Code Skill

If you use Claude Code, you can install the /kappmaker skill to run any CLI command through natural language — with automatic prerequisite checks, guided setup, and inline error recovery.

Install:

npx skills add KAppMaker/KAppMaker-CLI --skill kappmaker

Or via the Claude Code plugin system:

/plugin marketplace add KAppMaker/KAppMaker-CLI
/plugin install kappmaker@KAppMaker-CLI

Use:

/kappmaker create MyApp
/kappmaker generate screenshots for my fitness app
/kappmaker set up App Store Connect

Claude will check your config, verify API keys are set, and walk you through any missing prerequisites before running the command.

Context-aware: when a command needs inputs you didn't pass (app description, app name, brand color, tagline, keywords, etc.), the skill reads your project's AiGuidelines/ folder first (app-idea.md, prd.md, keywords.md, brand.md), then README.md, then existing ASO metadata, and fills in what it finds — you're only prompted for things that aren't already written down somewhere in the project.

Table of Contents

• Claude Code Skill
• Configuration
• Commands Overview
• Features
• Prerequisites
• External Services & API Keys
• Commands
• create <app-name>
• clone <app-name>
• git setup-upstream
• firebase — Firebase setup steps (login, project, apps, auth, configs)
• create-logo
• generate-image
• create-appstore-app
• appstore-monetization-push — Push subs + IAPs from config to ASC (standalone)
• gpc — Google Play Console management
• gpc monetization push — Push subs + IAPs from config to Play (standalone)
• subscription add — Quick-add a subscription to Play + ASC
• iap add — Quick-add a credit-pack IAP to Play + ASC + Adapty
• adapty setup
• Image Tools
• convert-webp
• translate-screenshots
• generate-screenshots
• generate-feature-image
• generate-ios-icons
• generate-android-icons
• ASO Keyword Research (skill-driven)
• ASO Metadata Localization (skill-driven)
• fastlane configure
• publish
• generate-keystore
• android-release-build
• refactor
• update-version
• Config Reference
• Project Structure

Commands Overview

Features

Works with any project

These commands are standalone and don't depend on any specific boilerplate:

• AI logo generation — Generate logo variations with fal.ai, pick your favorite, auto-remove background
• AI screenshot generation — Generate marketing screenshots from a text description (8 style presets)
• Screenshot translation — Translate app screenshots to 48+ locales in parallel
• ASO keyword research — Skill-driven workflow that discovers high-value sub-niche keywords for a base topic via the Astro MCP tools (real-time App Store popularity + difficulty scores from competitor analysis and AI suggestions), filters them by configurable thresholds, clusters them by sub-niche, and writes AiGuidelines/keywords.md. Falls back to a manual brainstorm when Astro MCP isn't connected. Output feeds directly into the metadata localization workflow below.
• ASO metadata localization — Skill-driven workflow that writes per-locale name/subtitle/keywords/description (iOS) and title/short_description/full_description (Android) text files with two strategies: US-indexed keyword expansion (English copy with different keywords per locale to multiply indexed surface) or native per-market localization. Char-limits, keyword-field rules, and no-duplicate-word-across-fields are enforced automatically.
• App Store Connect setup — Register bundle ID (with Sign in with Apple, In-App Purchases, and Push Notifications capabilities enabled automatically), create app, set metadata, categories, age rating, subscriptions, privacy, and review info — fully automated, no manual App Store Connect steps needed
• Google Play Console setup — Push store listings, subscriptions (new monetization API), one-time in-app products, and the data safety declaration via a built-in wrapper around the Play Publisher API — no external CLI, no extra dependencies
• Adapty subscription setup — Create products, paywalls, and placements for iOS and Android
• Version bumping — Increment Android and iOS version codes and names in one command
• Image tools — Split grids, remove backgrounds, enhance quality, convert to WebP

KAppMaker boilerplate-specific

The create command runs the full end-to-end setup. Some steps assume the KAppMaker project structure and will be skipped with a warning if you use a custom template:

• Package refactor — Renames package name, app ID, and display name using the TypeScript refactor service (also available standalone via kappmaker refactor)
• Firebase SDK config placement — Downloads google-services.json and GoogleService-Info.plist to KAppMaker-specific paths (falls back to Assets/ for custom templates)
• Build environment — Creates local.properties; iOS dependencies resolve via Swift Package Manager at build time (CocoaPods runs only if a custom template still has a Podfile)
• Android release build — Generates keystore and builds signed AAB (also available standalone via kappmaker android-release-build)
• Git remotes — Renames origin to upstream (designed for the "fork from template" workflow)
• Screenshot translation default path — Defaults to MobileApp/distribution/ios/appstore_metadata/screenshots/en-US (falls back to parent of source directory)

Prerequisites

• Node.js >= 20
• Git
• Firebase CLI — npm install -g firebase-tools
• Fastlane — via Bundler in the template repo
• Android SDK — installed at ~/Library/Android/sdk (configurable)
• asc CLI (optional, for App Store Connect) — brew install asc (requires ≥ 1.4.0 as of KAppMaker 1.7.0 for the bulk CSV subscription-pricing path)
• Adapty CLI (optional, for Adapty setup) — npm install -g adapty
• No extra CLI for Google Play Console — kappmaker gpc talks to the Play Publisher API directly via Node's built-in fetch and crypto; all it needs is the service-account JSON path set in googleServiceAccountPath

External Services & API Keys

The CLI integrates with several external services for AI image generation, app store management, and subscription setup. All keys are stored locally at ~/.config/kappmaker/config.json.

fal.ai — AI Image Generation

Used for: Logo generation, background removal, image enhancement, screenshot translation, and screenshot generation.

How to get your key:

1. Sign up at fal.ai
2. Go to Dashboard > Keys and create an API key
3. kappmaker config set falApiKey <your-key> — or skip this and the CLI will prompt you the first time you run a command that needs it

ImgBB — Image Hosting

Used for: Temporarily hosting reference images when generating or translating screenshots (fal.ai needs a public URL to process images).

How to get your key:

1. Sign up at imgbb.com
2. Go to api.imgbb.com and get your free API key
3. kappmaker config set imgbbApiKey <your-key> — or prompted on first use

OpenAI — Prompt Generation

Used for: Generating detailed screenshot specifications from a short app description (uses GPT-4.1). Only needed for the generate-screenshots command.

How to get your key:

1. Sign up at platform.openai.com
2. Go to API Keys and create a new key
3. kappmaker config set openaiApiKey <your-key> — or prompted on first use

App Store Connect CLI (asc) — iOS App Management & Publishing

Used for: Creating apps, setting metadata, categories, subscriptions, privacy declarations, and review info on App Store Connect (create-appstore-app). The same API key credentials are also used by publish --platform ios to build and upload IPAs via Fastlane.

How to set up:

1. Install: brew install asc
2. Generate an API key at App Store Connect > Users and Access > Integrations > API (Admin role, download the .p8 file immediately)
3. Configure:

   kappmaker config set ascKeyId <your-key-id>
   kappmaker config set ascIssuerId <your-issuer-id>
   kappmaker config set ascPrivateKeyPath /path/to/AuthKey.p8
   kappmaker config set appleId [email protected]

Or run kappmaker config appstore-defaults --init for interactive setup.

Note: kappmaker publish --platform ios uses ascKeyId, ascIssuerId, and ascPrivateKeyPath to automatically generate the Fastlane-format publisher JSON — no separate credentials needed.

Adapty CLI — Subscription Management

Used for: Setting up in-app subscription products, paywalls, and placements across iOS and Android via Adapty's backend.

How to set up:

1. Install: npm install -g adapty
2. Log in: adapty auth login (opens browser for authentication)
3. Run: kappmaker adapty setup

Firebase CLI — Backend Setup

Used for: Creating Firebase projects, registering Android/iOS apps, downloading SDK config files (google-services.json, GoogleService-Info.plist), and enabling anonymous authentication.

How to set up:

1. Install: npm install -g firebase-tools
2. The create command handles login and project creation interactively.

Google Play Publisher — Android Store Uploads + Play Console Management

Used for:

• Building and uploading Android AABs to Google Play Store via kappmaker publish --platform android (Fastlane)
• Configuring store listings, subscriptions, in-app products, and the data safety declaration via kappmaker gpc ... (direct Publisher API call, no external CLI)

Both flows share the same service account JSON key — set it once, use it everywhere.

How to set up:

1. Go to Google Cloud Console and create a new project (or select existing)
2. Open APIs & Services > Library, search for Google Play Android Developer API, and enable it
3. Go to IAM & Admin > Service Accounts, create a new service account (skip role assignment)
4. Open the service account, go to Keys, click Add key > Create new key > JSON, and download it
5. Open Google Play Console, go to Settings > Users and permissions
6. Click Invite new user with the service account email ([email protected]) and grant permissions for your app(s)
7. Save the JSON key file and configure:

   kappmaker config set googleServiceAccountPath /path/to/google-service-app-publisher.json

Note: Google Play does not allow creating new apps via any public API — you must create the app manually once in Play Console before kappmaker gpc can configure it.

App Store Publisher — iOS Store Uploads

Used for: Building and uploading iOS IPAs to App Store Connect, managing App Store metadata and screenshots via kappmaker publish --platform ios.

The publish command reuses the same App Store Connect API key credentials used by create-appstore-app (ascKeyId, ascIssuerId, ascPrivateKeyPath) and automatically generates the Fastlane-format publisher JSON.

How to set up (if not already configured for create-appstore-app):

1. Open App Store Connect > Users and Access > Integrations
2. Create an API key with App Manager access and download the .p8 file
3. Note the Key ID and Issuer ID
4. Configure:

   kappmaker config set ascKeyId <your-key-id>
   kappmaker config set ascIssuerId <your-issuer-id>
   kappmaker config set ascPrivateKeyPath /path/to/AuthKey.p8

create <app-name>

Full end-to-end app bootstrapping. Creates a new KAppMaker app from the template and optionally sets up everything needed to publish.

kappmaker create Remimi

What it does (13 steps):

Options:

clone <app-name>

Clones the template repository into <AppName>-All. This is step 1 of create exposed as a standalone command — useful when you only want to scaffold a project and apply your own changes (e.g. clone + refactor without Firebase, ASC, etc.).

kappmaker clone Remimi
kappmaker clone Remimi --template-repo [email protected]:my-org/my-template.git
kappmaker clone Remimi --target-dir ./projects/Remimi

What it does:

1. Validates the app name (PascalCase)
2. If no config exists at ~/.config/kappmaker/config.json, runs kappmaker config init first
3. If the target directory already exists, prompts to delete and start fresh
4. Runs git clone <templateRepo> <targetDir>

Minimal flow — clone + refactor without anything else:

kappmaker clone MyApp
cd MyApp-All/MobileApp
kappmaker refactor --app-id com.example.myapp --app-name MyApp

git setup-upstream

Renames the origin remote to upstream. Step 10 of create as a standalone command — designed for the "fork from template" workflow where the template repo becomes upstream and you add your own origin later.

kappmaker git setup-upstream                    # Run from inside the cloned repo
kappmaker git setup-upstream ./MyApp-All        # Or pass the path explicitly

Exits non-zero if the path is not a git repository.

firebase

Five standalone subcommands matching steps 2–6 of create. Run them individually for partial flows (e.g. set up Firebase for an existing project), or together to replicate what create does.

kappmaker firebase login
kappmaker firebase project --app-name MyApp                # derives project-id = myapp-app, display = MyApp
kappmaker firebase project --project-id myapp-prod --display-name MyApp  # explicit
kappmaker firebase apps --project myapp-app --app-name MyApp --package-name com.example.myapp
kappmaker firebase auth-anonymous --project myapp-app
kappmaker firebase configs --project myapp-app --app-name MyApp --package-name com.example.myapp

firebase login

Runs firebase login (interactive). No args.

firebase project

Creates the Firebase project. Idempotent — if the project already exists it skips creation. Returns success/failure to the orchestrator (controls whether create proceeds with steps 4–6).

firebase apps

Creates an Android + iOS app under the project. Idempotent — reuses existing apps that match the display name ${appName} (Android App) / ${appName} (iOS App).

firebase auth-anonymous

Enables anonymous authentication via the Identity Toolkit Admin API. If Firebase Auth has never been initialized for the project, the command pauses and asks you to click "Get started" in the Firebase Console, then retries automatically.

firebase configs

Downloads google-services.json and GoogleService-Info.plist for the Android + iOS apps and writes them to the right place. Apps are looked up via --app-name (display name match) unless you pass --android-app-id / --ios-app-id directly.

Output auto-detection (when --android-output / --ios-output aren't given): probes MobileApp/androidApp/google-services.json, then MobileApp/composeApp/google-services.json, then falls back to Assets/google-services.json. Same for iOS — MobileApp/iosApp/iosApp/GoogleService-Info.plist if it exists, otherwise Assets/GoogleService-Info.plist.

When --package-name is provided, the downloaded google-services.json is verified against the expected package name and patched in-place if it doesn't match (handles cases where the Firebase app was registered with an older bundleIdPrefix).

create-logo

Generates an app logo using fal.ai's nano-banana-2 model.

kappmaker create-logo
kappmaker create-logo --prompt "A minimalist fitness tracker for runners"
kappmaker create-logo --output ./custom/path/logo.png

Flow:

1. Reads app idea from --prompt (or prompts interactively if omitted)
2. Generates a 4x4 grid of 16 logo variations (2K, 1:1)
3. Opens grid in Preview.app for review
4. Pick a logo (1-16) or R to regenerate — optional: 5 --zoom 1.1 --gap 3
5. Extracts chosen logo at 512x512

Output: Assets/app_logo.png + Assets/logo_variations.png

Requires a fal.ai API key (prompted on first use if not set, or set manually: kappmaker config set falApiKey <your-key>)

generate-image

Generic AI image generator — a thin wrapper around fal.ai's nano-banana-2 (text-to-image) and nano-banana-2/edit (with reference images). Use this any time you need a one-off image without the logo-grid selection flow.

kappmaker generate-image --prompt "A minimalist mountain landscape at sunset"
kappmaker generate-image --prompt "Hero banner for a meditation app" --aspect-ratio 16:9 --resolution 4K
kappmaker generate-image --prompt "Product render" --num-images 4 --output Assets/hero
kappmaker generate-image --prompt "Put this logo on a black t-shirt" --reference Assets/app_logo.png
kappmaker generate-image --prompt "Blend these into a single composition" --reference Assets/moodboard
kappmaker generate-image --prompt "Match this product shot" --reference https://example.com/ref.jpg

Reference images (edit mode): Passing --reference switches the endpoint from nano-banana-2 (text-to-image) to nano-banana-2/edit (reference-guided). Each entry can be a file path, a directory (all png/jpg/jpeg/webp inside are picked up, sorted, non-recursive), or an HTTP(S) URL. Max 10 references total. If imgbbApiKey is configured, local files are uploaded to imgbb for reliable URLs; otherwise they are sent inline as data URIs (fine for small images, can fail on very large ones).

Output path behavior:

• No --output → Assets/generated.png (single) or Assets/generated_1.png, _2.png… (multi)
• --output <dir> (no extension) → saves into that directory
• --output <file.png> → single image uses path verbatim; multi-image appends _1, _2 before extension

Requires a fal.ai API key (prompted on first use if not set).

create-appstore-app

Creates and fully configures an app on App Store Connect using the asc CLI. Requires asc ≥ 1.4.0.

kappmaker create-appstore-app
kappmaker create-appstore-app --config ./my-config.json

First-time setup

1. Generate an API key at App Store Connect > Users and Access > Integrations > API — Admin access, download the .p8 file immediately
2. Run one-time setup:

   kappmaker config appstore-defaults --init

What it does (13 steps)

1. Validate asc CLI and authentication
2. Load config (from file or interactive prompts)
3. Register Bundle ID + enable capabilities (Sign in with Apple, In-App Purchases, Push Notifications). Name follows Apple convention: XC com measify myapp for com.measify.myapp
4. Find or create app (fully automated via asc web apps create — no manual App Store Connect step needed)
5. Set content rights
6. Create app version (1.0.0)
7. Set categories
8. Set age rating
9. Update localizations
10. Set pricing, availability, and subscriptions
11. Set privacy data usages
12. Set encryption declarations
13. Set review contact details

Config resolution

Layers are deep-merged (later overrides earlier):

1. Built-in template — age rating, privacy, encryption, subscriptions
2. Global defaults (~/.config/kappmaker/appstore-defaults.json) — review contact, copyright
3. Local config (./Assets/appstore-config.json or --config)
4. Interactive prompts — only for fields still empty

Default subscriptions

Auto-generated naming: group {appname}.premium.v1, ref name {AppName} Premium Weekly v1 (6.99).

Per-territory PPP pricing (1.7.0+ — bulk CSV import)

Subscriptions and IAPs are fanned out to every ASC territory (~175) with purchasing-power-parity-adjusted prices in a single API call per product. Requires asc CLI ≥ 1.4.0 (brew upgrade asc).

• Subscriptions (1.7.0+): asc subscriptions pricing prices import --input <csv>. KAppMaker writes a temp CSV with territory,price,price_point_id rows for all ~175 territories and pipes it in. Replaces the 155-call loop from 1.6.x which hit Apple's rate limits.
• IAPs: a single asc iap pricing schedules create --prices "PP_ID:DATE,…" call covers all territories (unchanged).

Set "ppp_enabled": false on any subscription or IAP to opt out and keep only your explicitly-listed prices. User-listed territory prices are always preserved (they win the merge).

Tier resolution: Apple's price-point catalog uses globally-stable tier numbers (1..800 — tier N = the same USD-equivalent across every territory). KAppMaker resolves each unique PPP USD target → tier ONCE via USA's catalog (where customerPrice is in USD), then synthesises per-territory price-point IDs locally using Apple's base64 {s, t, p} format. Critical fix vs 1.6.x: the old code compared a USD target against local-currency price-points (e.g. ¥, ₩, ₹) and ended up picking the FREE tier — products silently landed at $0 in JPN/IDR/INR/KRW/etc. The new tier-based resolution avoids that entirely.

Distinct catalogs: subscriptions use subscriptionPricePoints (CLI: asc subscriptions pricing price-points list) while IAPs use appPricePoints (CLI: asc pricing price-points). Their s (catalog identifier) fields differ — mixing IDs across catalogs returns 400 The provided entity is invalid.

Idempotent re-runs: when setup reports "already been used", KAppMaker now logs existing — refreshing pricing and continues into the PPP fan-out so re-runs actually update territory pricing (1.6.x silently skipped).

App Review screenshots (1.7.1+)

Apple requires a review screenshot on every subscription and IAP — without one, products remain in MISSING_METADATA state and per-territory pricing won't "resolve". KAppMaker uploads it automatically when you set review_screenshot in the config:

{
  "review_screenshot": "Assets/appstore/review-screenshot.png",
  "subscriptions": {
    "groups": [{
      "subscriptions": [{
        "ref_name": "Premium Weekly",
        "review_screenshot": "Assets/appstore/weekly-review.png"
      }]
    }]
  },
  "in_app_purchases": [{
    "product_id": "credit_pack_10_499_myapp",
    "review_screenshot": "Assets/appstore/iap-review.png"
  }]
}

• Global default: review_screenshot at the top level applies to every sub + IAP.
• Per-product override: each subscription / IAP can specify its own path.
• Idempotent: re-runs check view / images list first and skip if a screenshot is already attached. Delete via Apple's UI to force a re-upload.
• Silent skip on missing file: if the path doesn't resolve to an existing file, KAppMaker logs and moves on — no error.

Under the hood: asc subscriptions review screenshots create --file <path> for subs and asc iap images create --file <path> for IAPs.

#### Required size + auto-resize prompt

Apple's recommended size for App Review screenshots is 1290 × 2796 px (iPhone 6.7" Display, portrait — matches App Store listing screenshot dimensions). Minimum: 640 × 920 px. Format: PNG or JPG.

If the file's dimensions don't match 1290 × 2796, KAppMaker prompts:

WARN Review screenshot wrong-size.png is 1920×1080.
-- Apple's App Store recommended size for review screenshots: 1290×2796 (iPhone 6.7" Display, portrait).
  Resize to 1290×2796 keeping aspect ratio? (Y/n)

• Y (default) — sharp resizes the file with fit: 'inside' (preserves aspect ratio, may end up smaller than the target on the constraining dimension; e.g. a 1920 × 1080 input becomes 1290 × 726). Writes to a temp file. Uploads the resized copy.
• N — uploads the file as-is. Apple may still accept it (the rule is just min 640 × 920) but the aspect ratio won't match typical iPhone screenshots.

Files that are already 1290 × 2796 skip the prompt entirely.

#### Standalone replace commands

Two top-level appstore- prefixed commands replace existing screenshots without running the full create-appstore-app flow:

# Replace the review screenshot on EVERY subscription in the config
kappmaker appstore-update-subscription-review-screenshot --file ./Assets/appstore/new-review.png

# Replace the review image on EVERY IAP
kappmaker appstore-update-iap-review-screenshot --file ./Assets/appstore/iap-review.png

# Without --file, the commands use the per-product `review_screenshot` from the config
kappmaker appstore-update-subscription-review-screenshot
kappmaker appstore-update-iap-review-screenshot

# Target a single product
kappmaker appstore-update-iap-review-screenshot \
    --file ./Assets/appstore/credit-pack-30.png \
    --product-id credit_pack_30_999_myapp

These commands force-replace existing screenshots (delete + create under the hood — empirically asc … update doesn't actually swap the binary). The setup-flow upload in create-appstore-app remains idempotent (skips when one is already attached).

Default in-app purchases (credit packs)

The template also ships three CONSUMABLE in-app purchases shaped as credit packs. Auto-fill triggers on any in_app_purchases[] entry with a credits numeric field.

Format: credit_pack_{credits}_{priceDigits}_{appname}. The same ID is used on Google Play and Adapty so app code can reference one constant per platform pair.

Created via the same one-shot asc iap setup workflow that drives subscription setup. Reruns are idempotent — already-existing product IDs are skipped with an info log.

Default privacy

During interactive setup, the CLI asks if the app accesses user content (AI image/video wrapper). If yes, adds Photos or Videos + Other User Content (both App Functionality / Not Linked to You).

appstore-monetization-push

Standalone command that re-runs only the subscription + IAP push step from create-appstore-app. Useful when you want to sync pricing (including PPP fan-out) without repeating the full 13-step setup — e.g. after adding a new subscription period, adjusting prices, or upgrading to a newer KAppMaker version with PPP fixes.

# Push everything (subscriptions + IAPs)
kappmaker appstore-monetization-push

# Subscriptions only
kappmaker appstore-monetization-push --subscriptions-only

# IAPs only
kappmaker appstore-monetization-push --iap-only

# Custom config path
kappmaker appstore-monetization-push --config ./path/to/appstore-config.json

Reads Assets/appstore-config.json (or --config <path>). Resolves the ASC app ID from app.id or by looking up app.bundle_id via asc. Calls the same setupSubscriptions / setupInAppPurchases functions as create-appstore-app — fully idempotent: existing products get pricing refreshed with the full PPP regional fan-out.

gpc

Google Play Console management — a tight wrapper around the official Google Play Android Publisher API. All subcommands authenticate via the service account JSON at googleServiceAccountPath (same one used by publish --platform android). No external CLI and no extra npm dependencies — the JWT flow and HTTPS calls are implemented with Node's built-in crypto and fetch.

Note: Google Play does not allow creating new apps via any public API. Create the app manually once in Play Console, then use these commands to configure it.

gpc setup

Full end-to-end configuration (11 steps) — the Google Play parallel to create-appstore-app.

kappmaker gpc setup
kappmaker gpc setup --config ./my-config.json

What it does:

1. Validate service account + obtain access token
2. Load config (./Assets/googleplay-config.json or interactive prompts). Auto-detects Play's actual default language via a throwaway edit probe and rewrites config.app.default_language + the matching listing locale if your config drifted from reality. Also migrates legacy product IDs and legacy data-safety placeholders. Also reads tracks state to verify an APK/AAB is uploaded.
3. Review summary and confirm
4. Verify app exists on Play Console (fails fast with a deep link if not — Google does not allow app creation via the public API)
5. Start a Play Console edit (only if the default-language listing has a title — otherwise steps 5-7 are skipped cleanly)
6. Update app details (default language + contact website/email/phone)
7. Update store listings per locale (title, short/full description, video); commits the edit. Empty listing titles are auto-filled from the app name
8. Pre-flight build check, then create subscriptions via the new monetization API (POST /subscriptions with productId + regionsVersion.version as query params, base plans in body in DRAFT state, then basePlans:activate each one). Base plans are available to all ~175 Play regions — regions without explicit prices get auto-converted pricing from Google. Idempotent — existing product IDs are skipped. Subscription listings are auto-cloned into Play's default language if missing. Skipped with a clear message if no build is uploaded to any track (Google rejects monetization writes in that case).
9. Create one-time in-app products via the new monetization API (PATCH /onetimeproducts/{id}?allowMissing=true + purchaseOptions:batchUpdateStates to activate). Idempotent via GET /oneTimeProducts. Replaces the legacy /inappproducts endpoint that returns 403 on migrated apps.
10. Update the data safety declaration: converts data_safety JSON → Google's CSV format using a bundled canonical template + KAppMaker defaults (USER_ID for app functionality + account management; DEVICE_ID for app functionality + advertising + account management; crash/performance/diagnostics/interactions for analytics), then posts it via POST /dataSafety with { safetyLabels: "<csv>" }. Respects data_safety_csv_path as an escape hatch for pre-exported CSVs.
11. Print a checklist of policy declarations that the Publisher API does NOT expose (content rating / IARC, target audience, ads, health apps, financial features, government apps, news apps, gambling, COVID-19 tracing, app access, advertising ID, families compliance, app pricing tier) with a deep link to Play Console's App content page. All verified against Google's v3 discovery document — none have REST endpoints.

gpc listings push

Push just the store listings section from the config file (useful after editing copy).

kappmaker gpc listings push
kappmaker gpc listings push --config ./my-config.json

Runs a single edit transaction: updates app details → updates every listing locale → commits.

gpc subscriptions list

Read-only — lists existing subscription product IDs on Play Console.

kappmaker gpc subscriptions list --package com.example.myapp
kappmaker gpc subscriptions list   # uses app.package_name from the config file

gpc subscriptions push

Create or reuse subscriptions from the config file. Idempotent — already-existing product IDs are skipped, and base plans are activated even for reused subscriptions.

kappmaker gpc subscriptions push

Uses the new monetization API (applications/{pkg}/subscriptions + basePlans:activate). Auto-generated IDs:

These align 1-to-1 with what adapty setup writes to android_product_id and android_base_plan_id, so Adapty links the products automatically without any extra configuration.

gpc iap list

Read-only — lists existing one-time in-app product SKUs on Play Console.

kappmaker gpc iap list --package com.example.myapp
kappmaker gpc iap list

gpc iap push

Create or reuse one-time in-app products from the config file. Idempotent — existing products are PATCHed with fresh PPP regional pricing.

kappmaker gpc iap push
kappmaker gpc iap push --recreate-stuck   # DELETE + recreate products stuck at regionsVersion 2022/02

Uses the new monetization API: PATCH /applications/{pkg}/onetimeproducts/{id}?allowMissing=true to create/update the product, then purchaseOptions:batchUpdateStates with an activatePurchaseOptionRequest to activate the default purchase option so it's available to buyers. Replaces the legacy /inappproducts endpoint, which Google now rejects with "Please migrate to the new publishing API" on migrated apps.

Default credit packs ship in Assets/googleplay-config.json. Auto-fill triggers on any in_app_products[] entry with a credits numeric field — SKU is set to credit_pack_{credits}_{priceDigits}_{appname} (matches the ASC and Adapty IDs):

Global region availability with PPP pricing (1.6.0+): subscriptions and one-time products are both created with explicit per-region prices in every Play-supported region (~175), with purchasing-power-parity multipliers applied — IN gets ~0.35×, AR/PK/EG get 0.30×, US/CA/EU base at 1.00×, CH/NO at 1.10×. The multipliers come from a Steam/Spotify-inspired tier table (iosdevmax/ppp-pricing, MIT). Prices round to .99 endings.

Each region's price is in its native currency (AE → AED, JP → JPY, IN → INR, etc.) — Google Play rejects mismatched currencies. The CLI calls Google's convertRegionPrices endpoint with your USD base price to get fair FX-converted native prices for every billable region, then multiplies by the region's PPP multiplier and charm-rounds (.99 for decimal currencies, X99 / X9 for zero-decimal currencies like JPY / KRW). Sanctioned countries (AF, IR, KP, SY, etc.) are auto-excluded — they don't appear in convertRegionPrices output.

`regionsVersion=2022/02` drift override (1.6.11+): Google's monetization API requires regionsVersion.version and "2022/02" is the only documented value. Several regions have drifted since that snapshot was taken — Google's live API returns one currency but 2022/02 expects another. The CLI handles this with an explicit override table:

Net effect: typical products land with all ~173 billable regions AVAILABLE (only MN drops out). Google's storage layer auto-converts each region's submitted currency to the user-facing display currency (we send BG/BGN → end users see EUR; we send CI/USD → end users see XOF).

Existing products with regions stuck at `2022/02`: if Google's old catalog has stored MN (or another NEVER_BILLABLE region) on an existing product, that PATCH cannot be completed — Google won't accept MN's currency but also refuses to remove the region. The CLI surfaces these "stuck" products at the end of the run and offers three fix paths:

1. Recommended — bump the product_id in your config (e.g. credit_pack_10_499_myapp → credit_pack_10_499_myapp_v2). Fresh product, no legacy baggage, no waiting period.
2. --recreate-stuck flag — DELETEs the stuck product(s) and recreates them fresh. WARNING: Google soft-deletes for a few minutes to a few hours; CREATE during that window returns "Product ID already in use". Plan downtime.
3. Manually delete on Play Console UI, wait for the reservation window to clear, then re-run.

"New countries and regions" set to AVAILABLE (1.6.11+): both subscriptions (otherRegionsConfig) and one-time products (newRegionsConfig) are now always set to availability: AVAILABLE with USD + EUR anchors when a USD anchor is present. Means any region Google adds to its billable catalog in the future is auto-priced from those anchors — no future-proofing maintenance needed.

Want simpler pricing without PPP? Set "ppp_enabled": false on a base plan or one-time product to skip the PPP fan-out. The CLI then submits only your user-listed regions in regional_configs (typically just US) plus otherRegionsConfig (subscriptions) / newRegionsConfig (one-time products) with USD + EUR anchors. Google handles the fan-out via its own pricing-template FX algorithm — every billable region gets a price, but without PPP discounting in lower-income markets. Trade-off: smaller payload, less control.

gpc data-safety push

Push only the data safety declaration. Faster than running the full setup when you're iterating on the privacy answers.

kappmaker gpc data-safety push

How it works under the hood: Google's POST /applications/{pkg}/dataSafety does not take structured JSON — it takes a CSV file (the same one Play Console exports from Policy → App content → Data safety → Export to CSV), wrapped in { safetyLabels: "<csv>" }. KAppMaker lets you stay in JSON and converts internally.

Two ways to configure it in `Assets/googleplay-config.json`:

1. Structured JSON (recommended) — data_safety.answers overlay on top of KAppMaker defaults:

Account creation: "My app does not allow users to create an account" (PSL_ACM_NONE).

Data deletion: skipped entirely (the question is optional).

Data types collected:

Data handling (same for ALL data types above):

• Collected only, not shared with third parties
• Processed ephemerally (YES)
• Collection is required — users can't turn it off
• Purposes: Analytics (+ App functionality for Device ID)

Security: encrypted in transit = YES.

Example config (just use the default — override if you need to add data types or change handling):

   "data_safety": {
     "apply_defaults": true,
     "answers": {}
   }

To override a specific answer, add keys to answers. Keys are either QuestionID (for single-answer rows) or QuestionID/ResponseID (for multi-choice rows). Values are true / false / URL string / null:

   "data_safety": {
     "apply_defaults": true,
     "answers": {
       "PSL_DATA_TYPES_PERSONAL/PSL_USER_ACCOUNT": true,
       "PSL_DATA_TYPES_LOCATION/PSL_APPROX_LOCATION": true
     }
   }

Internally, KAppMaker loads a canonical 783-row template (extracted from the well-maintained fastlane-plugin-google_data_safety), applies defaults + your overrides, emits a filled CSV, and uploads it via POST /dataSafety.

1. Escape hatch: CSV file — if you already exported a real CSV from Play Console and filled it in:

   "data_safety_csv_path": "Assets/data-safety.csv"

When this field is set and the file exists, it takes priority over the JSON block and is uploaded verbatim.

Important: Review the summary Play Console shows after the push before publishing. Google's conditional question logic may reject some answers — paste the error and I'll adjust the defaults.

gpc app-check

Quick read-only probe to verify that an app exists on Play Console. Useful for CI scripts and before running destructive operations.

kappmaker gpc app-check --package com.example.myapp

Exits 0 if found, 2 if missing (prints the Play Console deep link).

Config

All gpc subcommands except app-check load ./Assets/googleplay-config.json by default. The first run of kappmaker gpc setup creates it interactively.

Alias: kappmaker create-play-app is kept as a shortcut for kappmaker gpc setup (the entire 11-step flow is also what the top-level kappmaker create calls under step 8 when you answer yes to the Google Play Console prompt).

gpc monetization push

Standalone command that re-runs only the subscription + IAP push steps from gpc setup. Useful when you want to sync pricing (including full PPP fan-out across ~175 regions) without repeating listings, data safety, or the manual-checklist prompt.

# Push everything (subscriptions + IAPs)
kappmaker gpc monetization push

# Subscriptions only
kappmaker gpc monetization push --subscriptions-only

# IAPs only
kappmaker gpc monetization push --iap-only

# Custom config path
kappmaker gpc monetization push --config ./path/to/googleplay-config.json

# Re-create products stuck due to regionsVersion 2022/02 drift
kappmaker gpc monetization push --recreate-stuck

Reads Assets/googleplay-config.json (or --config <path>). Validates the service account and probes the app state (requires at least one uploaded build — internal testing track is enough). Calls the same setupSubscriptions / setupInAppProducts functions as gpc setup — fully idempotent: existing products are PATCHed with refreshed PPP regional fan-out.

subscription add

Quick-add a single new subscription to Google Play and App Store Connect without editing config files. Auto-generates aligned product IDs across both stores, fans out PPP pricing across ~175 Play regions and ~155 ASC territories, and auto-creates the App Store Connect subscription group if it doesn't exist yet.

# Minimum invocation — defaults to --platform all (Play + ASC)
kappmaker subscription add --period weekly --price 9.99

# v2 product line alongside an existing v1
kappmaker subscription add --period weekly --price 9.99 --product-version 2

# Single store
kappmaker subscription add --period monthly --price 19.99 --platform android
kappmaker subscription add --period yearly --price 29.99 --platform ios

# Full control — fully spelled out
kappmaker subscription add \
  --period weekly --price 6.99 --product-version 2 \
  --name "Weekly Premium" \
  --description "Full access for one week." \
  --review-screenshot "Assets/appstore/review-screenshot_subscription.jpg" \
  --group "myapp.premium.v2" --group-name "Premium Access" \
  --app-name "MyApp"

What it creates (for --period weekly --price 9.99 --product-version 1):

Flags:

Idempotency: safe to re-run. Existing products are PATCHed with refreshed PPP regional fan-out (same code path as gpc subscriptions push and create-appstore-app). Existing ASC subscriptions log "already exists — refreshing pricing" and continue.

Adapty is intentionally NOT included — Adapty pulls live store prices at runtime via its store integrations, so creating an extra Adapty product entry adds noise without unlocking anything the SDK can't already fetch. Adapty product entries remain managed via kappmaker adapty setup for the canonical product set. (For credit packs iap add DOES include Adapty, see below.)

Notes:

• No --free-trial flag yet. For intro offers, edit Assets/{googleplay,appstore}-config.json and run gpc subscriptions push / create-appstore-app.
• Only en-US localization is created. For multi-locale, edit the config files.
• Only first regional price (US/USD) is set explicitly. Other regions come from PPP fan-out.

iap add

Quick-add a single credit-pack consumable IAP to Google Play, App Store Connect, AND Adapty (Adapty is included here because credit packs use the credit_pack_access access level to gate consumable entitlements that have no store-side equivalent). Auto-generates aligned product IDs across all three.

# Minimum invocation
kappmaker iap add --credits 50 --price 14.99

# v2 product line (appends "_v2" suffix to the ID)
kappmaker iap add --credits 50 --price 14.99 --product-version 2

# Single store
kappmaker iap add --credits 100 --price 24.99 --platform ios

# Full control
kappmaker iap add \
  --credits 10 --price 4.99 --product-version 2 \
  --name "Basic Credit Pack" \
  --description "10 credits to use in the app." \
  --review-screenshot "Assets/appstore/review-screenshot_credits.jpg"

What it creates (for --credits 10 --price 4.99 --product-version 1 --name "Basic Credit Pack"):