ASO Router

Entry point for all ASO work with the aso CLI (hristo2612/aso-cli on GitHub, aso-kit on npm). Do preflight, know the core facts, then route.

Preflight

Run once per session before any other aso command:

aso status

• If aso: command not found: install it with npm i -g hristo2612/aso-cli (needs Node.js 22.13+, also published as aso-kit on npm), or curl -fsSL https://raw.githubusercontent.com/hristo2612/aso-cli/main/install.sh | bash.
• If aso status shows no active session: run aso setup (interactive first-run, Apple ID, app, default country, then triggers login) or aso login if already configured. Both open Chrome and handle 2FA/Keychain in the user's own terminal.
• Never ask the user for their Apple ID password in chat. Credentials go in macOS Keychain via aso setup/aso login, run directly by the user in their terminal. If a command needs interactive auth, tell the user to run it themselves and report back.
• Everything except popularity works without a session (search, ranks, difficulty, app lookup, lint). If there's no session and the user only needs those, proceed: popularity will just come back null.
• aso login finds the right Apple Ads org and a linked app on its own; you no longer need to look up or set aso config orgId as a normal step. aso status prints a next field naming the exact step to take when something's missing, read it before guessing.
• If a session exists but looks stale, aso auto-retries login once when credentials are in the Keychain; don't loop on it manually.

If setup gets stuck

Core Apple search facts (know these before touching metadata)

• Three indexed fields per locale: title (30 chars), subtitle (30 chars), keywords field (100 BYTES, not characters). Apple tokenizes all three and combines tokens into searchable phrases, a word in the title and a word in the subtitle can match together as a compound query.
• The keywords field's 100-byte limit bites non-Latin locales hardest: CJK and Arabic characters cost 2-3 bytes each in UTF-8, so a locale like ja, zh, or ar effectively gets far fewer keyword slots than an ASCII locale for the same 100 bytes. Budget by bytes, not by how many characters look like they'd fit. See aso-localization.
• Never repeat a word across fields. A word already indexed via the title gains nothing by also appearing in the subtitle or keywords field: it only burns a character budget that could hold a new term.
• Plurals are mostly redundant: Apple stems automatically, so "camera" already covers most "cameras" searches. Prefer the singular unless the plural has genuinely different search intent (e.g. "glass" vs "glasses").
• The keywords field is comma-separated with no spaces after commas: every space is a wasted character.
• The description is NOT indexed for search on iOS. Apple's algorithm ignores it for ranking; treat it purely as a conversion/readability lever, not a keyword-placement opportunity (see aso-conversion).
• Developer name and in-app purchase display names are also indexed text, on top of the three per-locale fields above.
• Category placement affects relevance and category-chart ranking, not just discovery structure: pick the category your target keywords actually belong to, don't chase a bigger but less relevant one.
• Cross-locale indexing: a storefront indexes more than its "native" locale. The US store, for example, also indexes locales like es-MX, fr-CA, pt-BR, zh-Hans/Hant, ja and the other English variants. Filling extra locales you're entitled to multiplies your effective keyword budget for that storefront. See aso-localization.
• Ratings, reviews, and conversion rate aren't indexed text either, but they're widely believed to feed back into ranking indirectly (an app that converts and retains better tends to rank better over time), separate from the direct textual indexing above. See aso-audit and aso-conversion.

Data caveats

• Popularity floor: Apple's Search Ads popularity score (5-100) floors low/unknown-volume keywords at 5. aso keywords flags this as popularityFloor: true. Treat a floored 5 as "no reliable signal", not "dead keyword", it can still be a real long-tail term.
• Difficulty is the ASOManiac model, not an Apple number: calibrated against third-party difficulty scores, it weighs competition from the top-10 ranking apps' ratings counts (55%), demand from popularity plus autocomplete signal (10%), and market quality from the top-10 apps' average rating (35%). Scored 0-100, higher is harder. Use it to compare keywords relative to each other and to the app's own authority, not as an absolute probability of ranking.
• opportunity = popularity × (100 − difficulty) / 100. It's a sort key for prioritizing candidates, not a traffic forecast.
• rank comes from Apple's own store search order (about 250 deep, unpersonalized iPhone results). null means not in the top 250 today, not "unranked forever". Users' own devices can show slightly different, personalized orders.
• Each aso keywords item also carries brand (true when the term is essentially the #1 ranking app's own publisher/brand name, someone else's brand: don't shortlist it) and confidence (high/medium/low, how much to trust that term's popularity/difficulty numbers). --min-popularity <n> and --max-difficulty <n> pre-filter a batch; filtered terms come back under filteredOut with a reason, worth a glance before assuming they're all noise.
• Popularity needs an Apple Ads session; everything else works logged out.

The CLI does not upload metadata

aso reads and measures; it never writes to App Store Connect. To ship a title/subtitle/keywords change, use fastlane deliver (a fastlane/metadata/<locale>/{name.txt,subtitle.txt,keywords.txt} tree) or paste manually into App Store Connect. Never push or upload metadata without the user's explicit approval of the exact new text. See aso-metadata for detail.

Routing

Most requests map to exactly one skill. For a full "optimize everything" request, run in this order: aso-audit (find the gaps) → aso-keyword-research (fill them) → aso-metadata (draft and validate) → aso-conversion (fix conversion assets) → aso-tracking (measure). Confirm the app ID and country (-c, default from aso config) before running anything if either is ambiguous.

Google Play

aso is Apple-only: it has no Google Play data or commands. If asked about a Play listing, say so and give the mental model only; see the Google Play appendix in aso-audit.