App Store Optimization CLI

Research ASO keywords, inspect competition, and manage results from one local-first CLI.

What Is It?

• Fast, free keyword research and visibility tracking
• Keyword scoring with popularity + difficulty + brand classification in one command
• Local ASO dashboard for reviewing keyword/app data
• MCP tool (aso_evaluate_keywords) for agent workflows and automated keyword research

ASO Dashboard

MCP

The dashboard keywords shown above were discovered and added automatically by an agent using the MCP tool.

Install

npm install -g aso-cli

Note: requires Node.js >=18.14.1.

Apple Search Ads Setup

ASO commands require Apple Search Ads setup.

Prerequisites

• App Store Connect account
• App ID of a published app you can access
• No campaign creation required
• No billing information required

Setup

1. Create/sign in: https://searchads.apple.com

1. Open Apple Search Ads Advanced: https://searchads.apple.com/advanced
2. Click your account name in the top-left corner.
3. Under Campaign Groups, click Settings.
4. Click Link Accounts.
5. Select your App Store Connect account and save.

1. Copy an App ID from your App Store URL (number after id)

https://apps.apple.com/us/app/example-app/id123456789

1. Run aso auth and complete Apple ID + password + 2FA in terminal

• You may see a missing billing information warning; this can be safely ignored.
• Ensure all campaign groups are linked to a valid App Store Connect account.
• Troubleshoot App Store Connect account linking

Quick Start

# Authenticate once
aso auth
Fetch keyword metrics
aso keywords "meditation,sleep sounds,white noise"
Open dashboard
aso

Command Reference

| Command | What it does | | ------------------------------- | ------------------------------------------------------- | | aso | Starts the local dashboard (default command) | | aso keywords "k1,k2,k3" | Fetches keyword popularity/difficulty and prints JSON | | aso keywords "k1,k2" --stdout | Machine-readable mode for automation/agents | | aso auth | Reauthenticates Apple Search Ads session | | aso reset-credentials | Clears saved credentials/cookies | | aso --primary-app-id | Sets primary App ID used for popularity requests |

Supported flags

• --country : currently US only
• --primary-app-id : saved locally for future runs
• --min-popularity : filters out low-popularity keywords before enrichment
• --max-difficulty : filters out high-difficulty keywords after enrichment
• --app-id : associates keywords to this local app id (default: research)
• --exclude-existing: skips keywords already associated with the target app/country before evaluation
• --no-associate: skips app-keyword association writes for the current aso keywords run

{
  "items": [
    {
      "keyword": "meditation",
      "popularity": 45,
      "difficultyScore": 62,
      "minDifficultyScore": 38,
      "isBrandKeyword": false
    }
  ],
  "failedKeywords": [],
  "filteredOut": []
}

{
  "error": {
    "code": "CLI_RUNTIME_ERROR",
    "message": "Primary App ID is missing. Run 'aso --primary-app-id <id>' or run 'aso' in a terminal to set it, then retry this command with --stdout."
  }
}

{
  "mcpServers": {
    "aso": {
      "command": "aso-mcp"
    }
  }
}