hristo2612/aso-cli

# 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:

```bash
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.

# ASO Audit

Produce a data-backed report card, not an opinion. Every grade must trace back to a number from the CLI, and every dimension you can't measure gets marked unknown instead of guessed at. Preflight: see the `aso` router skill.

## Iron law

**Grade on data, not impressions.** "Your keywords look fine" is not an audit finding. A grade needs a metric behind it: a lint score, a rank, a rating count, a character count. If you don't have the metric, the dimension is "unknown," not a guessed grade.

## Intake

1. App ID (required), primary storefront (default US)
2. Additional storefronts to check? (locale coverage dimension needs this)
3. 1-3 competitor app IDs for the ratings/rank comparison (ask, or derive via `aso-competitors`'s Step 1)

# ASO Competitor Analysis

Find keyword gaps and ranking opportunities by looking at who already ranks: not to copy them, but to find what they've validated that you haven't targeted yet.

Preflight: see the `aso` router skill.

## Iron law

**This is gap analysis, not copying.** The #1 app for a term already owns it: chasing it head-on is expensive. The value is in terms *they* rank for that you don't, and terms where you can realistically outrank a specific competitor, not the whole field.

## Step 1: Identify competitors

If the user already named competitor apps, get their app IDs. If not, find them from your own keyword data or a live search:

# ASO Conversion Optimization

Getting found is `aso-keyword-research`/`aso-metadata`'s job. This skill is what happens after someone sees the listing: does it convert a view into an install. `aso` has no visual or analytics data, this is qualitative guidance plus what the CLI can show you about the current listing and competitors.

Preflight: see the `aso` router skill.

## Iron law

**Conversion assets carry no searchable text.** Icon, screenshots, preview video, and Custom Product Page content don't get indexed, so never claim screenshot captions or icon text rank for keywords; treat every recommendation here as a conversion lever only. Conversion rate and ratings are widely believed to feed back into ranking indirectly over time (see `aso`), which is why this work still matters for ASO, just not through indexing.

## What the CLI can tell you

```bash
aso app <appId> --lang en-US        # your own listing: screenshot count context via description, ratings, version

# ASO Keyword Research

Find keywords the app can realistically win, backed by `aso` data: never gut feel.

Preflight: see the `aso` router skill (CLI installed, session status). Popularity needs a session; difficulty/rank/opportunity work without one.

## Iron law

**Never shortlist a keyword without running it through `aso keywords`.** Popularity and difficulty come from the CLI, not intuition.

## Step 1: Seed keywords

Brainstorm 10-20 seeds across categories, not just the obvious core term:

# ASO Localization

Fill more of a storefront's indexing capacity than the primary locale alone gives you: the single most under-used ASO lever for most apps.

Preflight: see the `aso` router skill.

## Iron law

**Research each locale natively: never translate.** A translated keyword is a guess about what a market searches; a keyword pulled from `aso suggest`/`aso keywords` with `-c <that country>` is measured. "Überwachungskamera" outperforms a literal translation of "security camera" in DE because it's what Germans actually type, not what English maps to.

## Step 1: Pick markets

```bash
aso storefronts

# ASO Metadata Optimizer

Craft title, subtitle, and keywords field for one locale so they both rank and convert.

Preflight: see the `aso` router skill.

## Iron law

**Never repeat a word across title, subtitle, and keywords.** Apple indexes all three independently and combines their tokens into phrases: repetition burns character budget for zero extra ranking benefit. Validate every draft with `aso lint` before presenting it.

## Step 1: Gather inputs

- Current metadata for the locale (ask the user, or read their fastlane `metadata/<locale>/{name.txt,subtitle.txt,keywords.txt}` if the project has one).
- A scored keyword shortlist. If you don't have one, run `aso-keyword-research` first: don't invent keywords here.

# ASO Rank Tracking

Rank tracking exists to answer one question: **did the change help?** Set it up once, then use it to evaluate every metadata change against a real before/after.

Preflight: see the `aso` router skill. Tracking data lives locally in SQLite at `~/.aso/aso.db`.

## Step 1: Add keywords to track

```bash
aso track add <appId> <term1> <term2> <term3> ...
```

Track: everything currently in the keywords field, the title/subtitle phrases, plus the shortlist from `aso-keyword-research` you intend to chase. Don't track everything you've ever considered, that just adds noise and cron runtime.