ASO CLI 📈

Free App Store Optimization for you and your AI agent. Real Apple Search Ads popularity, keyword difficulty, live App Store ranks, and a local history of all of it. Your agent signs in to Apple on its own (Keychain plus automatic 2FA), so it can research keywords, write metadata and track rankings while you build your app.

No account, no server, no telemetry, no subscription. One install and aso setup.

Install

Needs Node.js 22.13+.

npm i -g hristo2612/aso-cli && aso setup

Try it without installing:

npx hristo2612/aso-cli search "habit tracker"

Give your agent the ASO skills:

npx skills add hristo2612/aso-cli

New to all this? The guided installer checks Node.js (and offers to install it), installs the CLI, adds the skills to your agents and walks you through setup:

curl -fsSL https://raw.githubusercontent.com/hristo2612/aso-cli/main/install.sh | bash

From the npm registry (same package, published as aso-kit):

npm i -g aso-kit

Unattended install (CI, scripts): curl -fsSL https://raw.githubusercontent.com/hristo2612/aso-cli/main/install.sh | bash -s -- --yes --no-setup

Quick start

aso keywords "white noise,sleep sounds,rain sounds"   # popularity, difficulty, rank
aso suggest meditation                                 # keyword ideas
aso search "habit tracker"                             # who ranks right now
aso app 1083248251                                     # any app's public listing
aso lint --title "Lumen: Sleep Sounds" --subtitle "White noise & rain" --keywords "fan,ocean,storm"

Track rankings over time:

aso track add 1234567890 "white noise,sleep sounds"
aso track run                  # add to cron: 0 9 * * * aso track run --json >> ~/.aso/track.log 2>&1
aso ranks 1234567890           # rank, change since last check, popularity, difficulty
aso history "white noise" --app 1234567890
aso track add 1234567890 "white noise" -p mac   # Mac App Store ranks too

With the skills installed, just ask your agent: "Do a full ASO audit of my app 1234567890 and propose a new subtitle and keyword field."

Apple Ads (for popularity)

Popularity scores come from Apple Search Ads. You need an Apple ID that can open app-ads.apple.com:

1. Sign up at searchads.apple.com (free, no campaign or billing required).
2. Link your App Store Connect account: Apple Ads → account menu → Settings → Link Accounts.
3. Run aso setup.

That's all. aso login finds the Apple Ads org that can read popularity and the apps linked to it by itself, even if your account has several orgs.

Everything except popularity (search, ranks, difficulty, lint, history) works without Apple Ads.

How sign-in works: aso login opens your installed Chrome with a dedicated profile (~/.aso/browser). It fills your Apple ID from the Keychain and, on macOS, reads the verification code from the system "Apple Account Verification" prompt. That needs Accessibility permission for your terminal; otherwise you type the code yourself. Only the Apple Ads session cookies are saved, to ~/.aso/session.json (mode 600). Apple Ads sessions last about an hour; when one expires, aso signs in again on its own, invisibly in the background, and only opens Chrome if Apple needs you (aso config autoLogin false turns this off). On Linux, set ASO_APPLE_PASSWORD instead of using the Keychain.

If setup gets stuck

| You see | Do this | | --- | --- | | NO_APPLE_ADS_ACCOUNT | Create a free Apple Ads account at searchads.apple.com with the same Apple ID (pick United States if your country is missing), then aso login. | | NO_LINKED_APPS | In Apple Ads: account menu > Settings > Link Accounts, link App Store Connect, then aso login. | | BAD_CREDENTIALS | aso setup to save the right password, or aso login --manual. | | 2FA code isn't filled in | Allow your terminal in System Settings > Privacy & Security > Accessibility, or type the code in the browser (or the terminal). | | Popularity is 5 for many terms | Normal: Apple reports low-volume terms as 5. | | Anything else | aso status says what's missing and what to run next. Full error list in docs/COMMANDS.md. |

What the numbers mean

| Field | Meaning | | --- | --- | | popularity | Apple Search Ads popularity, 5–100. Apple reports low-volume terms as 5; aso re-checks those through recommendations, which often return the real value. | | difficulty | 0–100, higher is harder. Our ASOManiac model, calibrated against third-party difficulty scores (Pearson r 0.87): competition from the top 10 apps' ratings (55%), demand (10%), their average rating (35%). | | brand | true when the term is another app's brand name, like "spotify". Skip those. | | opportunity | popularity × (100 − difficulty) / 100: a sort key, not a forecast. | | rank | Your position in App Store search, in Apple's own result order (the same list the App Store app shows, about 250 deep). null means not in the top 250. Unpersonalized iPhone results; add -p mac for the Mac App Store. |

All commands print JSON when piped (for agents) and tables in a terminal. See docs/COMMANDS.md for the full reference.

Skills

| Skill | Use it for | | --- | --- | | aso | Entry point: preflight, Apple search rules, routing | | aso-keyword-research | Seed → ideas → scored shortlist | | aso-metadata | Title, subtitle, keyword field drafts, linted and logged | | aso-competitors | Who you're up against, keyword gaps | | aso-audit | A–F health check of a listing | | aso-tracking | Rank tracking and before/after measurement | | aso-localization | New markets, native keywords, cross-locale indexing, seasonal keywords | | aso-conversion | Icon, screenshots, preview video, custom product pages, in-app events |

aso never uploads metadata. Ship changes with fastlane deliver or App Store Connect.

Notes

• The Apple Ads popularity endpoints are the private API behind the Apple Ads dashboard. They're unofficial and can change. aso limits itself to about one request per second.
• Thanks to semihcihan/App-Store-Optimization-CLI (MIT) for the App Store search parsing approach and brand-keyword detection.

Development

git clone https://github.com/hristo2612/aso-cli && cd aso-cli && npm install
npm test
node bin/aso.js --help
ASO_HOME=/tmp/aso-dev node bin/aso.js status   # isolated config/db

Releasing: bump version in package.json (npm version patch) and push to main. GitHub Actions publishes to npm via trusted publishing and creates the GitHub release.

No build step: plain Node ESM, SQLite via the built-in node:sqlite, and one dependency (playwright-core, used only for sign-in).