ASO CLI 📈

Install | Commands | Agent Skills

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

npm i -g aso-kit

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

What the numbers mean

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

Skills

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).