App Store Growth Agent

Manage Apple Ads, discover App Store keywords, and connect acquisition to subscription outcomes. Agents use the asga CLI; people follow the results in the local Growth Pulse MCP App.

asga wraps Apple's official Ads SDK with structured JSON, persistent keyword research, campaign diagnostics, guarded deployment workflows, and optional RevenueCat outcome data. Mock mode needs no credentials. Live mutations require an explicit preview and --yes approval.

Install

Requires Node.js 22.5 or newer.

From npm:

npm install --global app-store-growth-agent
asga --help

From source:

git clone https://github.com/zvadaadam/app-store-growth-agent.git
cd app-store-growth-agent
npm ci
npm run build
npm link
asga --help

The legacy aso-agent command remains available. The focused aso command exposes only organic keyword research.

To give Codex the bundled Apple Ads skills and local Growth Pulse MCP App, preview and install the plugin first—credentials and app scope are not required:

asga --dry-run setup codex
asga --yes setup codex

Start a new Codex task and ask the agent to open Growth Pulse. Its Connections tab guides setup and opens a protected local browser page for credentials. As an optional shortcut, append --app-id YOUR_APP_STORE_ADAM_ID --country US --target-cpi 3; or use --plan /ABSOLUTE/PATH/TO/apple-ads-plan.json when a plan already contains that non-secret observer scope.

Try it without credentials

asga --mock apps search "meditation"
asga --mock keywords discover \
  --app-id 1234567890 --country US \
  --seed "ai therapist" --seed "mental health coach" --related-only
asga --mock campaigns audit \
  --app-id 1234567890 --country US --target-cpi 3

Authenticate

Start with Apple Ads. You need an Apple Ads account and an administrator who can grant API access. An App Store Connect login alone is not enough. RevenueCat is optional; add it when you want trials and revenue alongside campaign data.

asga auth setup --provider apple-ads

# Optional, after Apple Ads is working
asga auth setup --provider revenuecat

The CLI and MCP App open the same local setup page. It walks through the provider's account and key steps, saves new credentials on this computer, and preserves existing credentials. Enter secrets only on that local page, never in chat. Then verify access and configure the account and app you want to review.

Apple's API-user/key setup is supported today. A one-click ASGA OAuth sign-in is not yet implemented. App Store Connect access for product-page publishing is also not implemented and is not required for ads reporting.

See the step-by-step connection guide for Apple roles, asking an administrator for access, optional RevenueCat attribution, manual setup, and troubleshooting.

Use it

export APP_ID="YOUR_APP_STORE_ADAM_ID"
export COUNTRY="US"

# Source-backed organic and paid keyword research
asga --live aso research \
  --app-id "$APP_ID" --country "$COUNTRY" \
  --seed "primary category term" --seed "important user outcome"

# Campaign and delivery diagnosis
asga --live campaigns audit \
  --app-id "$APP_ID" --country "$COUNTRY" --target-cpi 3
asga --live campaigns delivery-doctor \
  --app-id "$APP_ID" --country "$COUNTRY" \
  --target-cpi 3 --tap-install-rate 0.40

# Objective-aware, read-only bid guidance
asga --live campaigns bid-advisor \
  --app-id "$APP_ID" --country "$COUNTRY" \
  --objective volume --target-cpi 3 --hard-stop-cpi 6 \
  --tap-install-rate 0.40 --top 25

# Apple-attributed subscription outcomes
asga revenuecat asa-outcomes \
  --start <YYYY-MM-DD> --end <YYYY-MM-DD> \
  --level keyword --country "$COUNTRY" \
  --app-id "YOUR_REVENUECAT_APP_ID"

Output is JSON by default. Use --compact for one line or --select data.result for bounded fields. Run asga --help for the full command surface.

TypeScript consumers can import focused surfaces from app-store-growth-agent/apple-ads, /aso, /revenuecat, /cloud, and /testing.

Optional hosted history

The local SQLite database remains the source of truth; no cloud account is required. If you configure a Cloudflare tenant, sharing defaults to contribute: supported workflows send public keyword observations and bounded bid evidence to that tenant. Credentials, customer records, and full private search-term exports are never included. Use asga cloud settings --sharing never or ASGA_CLOUD_NEVER_SEND=1 to block cloud writes. See Cloud intelligence for the data model, settings, and commands.

Observe it as an MCP App

Growth Pulse shows campaign delivery, keywords, revenue aggregates, benchmarks, freshness, and recorded bid activity. Ask your agent to refresh your app's data and open the dashboard. One date selector covers Overview, Benchmarks, Keywords, and Activity: today, yesterday, 7/30/90 days, or custom dates, with an optional previous-period comparison. It defaults to 30 days; current bids, budgets, connections, and latest organic ranks remain explicitly current state. The MCP server runs locally over STDIO and exposes no Apple Ads mutation tools. The Connections tab is available before any credentials exist. See the MCP App guide for setup and behavior.

Use with Codex scheduled tasks

The installed Codex plugin includes focused skills under skills/. Invoke $schedule-apple-ads-monitor to create or update a recurring read-only task. Each run delegates account diagnosis to $monitor-apple-ads-delivery; live Apple Ads changes remain separate interactive dry-runs with explicit approval. See the official Scheduled tasks guide.

Safety

Apple Ads mutations are blocked by default and exit 3 with a structured preview. Review exact IDs and before/after values, dry-run the frozen change, then approve only that invocation with global --yes.

Approved writes use a 120-second default API timeout. If Apple still does not confirm a mutation before that deadline, ASGA reports MUTATION_OUTCOME_UNKNOWN with retrySafe: false. Read every frozen target and reconcile its current value against the approved before/after values; never repeat the write merely because the transport timed out.

Never commit Apple private keys, RevenueCat secrets, tokens, customer data, or private campaign exports. Existing data under ~/.config/aso-agent or ~/.config/mind-apple-ads is detected automatically; no migration is required.

Documentation

• Authentication and troubleshooting
• Cloud intelligence and private bid history
• Growth Pulse MCP App
• Agent protocol
• Architecture
• Apple Ads campaign playbook
• RevenueCat verification
• Apple Ads Platform API

Development

npm ci
npm run verify
npm run test:package

CI runs the complete verification suite on Node.js 22 and 24 and exercises the installed tarball. Stable vMAJOR.MINOR.PATCH tags publish through npm trusted publishing after the one-time npm setup. See CONTRIBUTING.md and the release guide.

Independent open-source software. Not affiliated with or endorsed by Apple Inc.