---
name: appstore-reviews
description: "Scrape and analyze Apple App Store and Google Play reviews. Use when analyzing competitor apps, finding user complaints, identifying feature gaps, or hunting bugs from reviews."
---

# appstore-review-cli - App Store & Google Play Review Scraper

<!-- Generated by: appstore-reviews setup copilot -->
<!-- Install to .github/skills/appstore-reviews/ or ~/.copilot/skills/appstore-reviews/ -->

You have access to a CLI tool called `appstore-reviews` that scrapes Apple App Store and Google Play reviews. Use it when the user asks about competitor analysis, app reviews, user complaints, feature gaps, or bug reports from app stores.

**You ARE the analyzer.** Fetch reviews with the CLI commands below, then analyze them directly in your response. Do NOT suggest the user install Ollama or run the `analyze` command - you have the intelligence to do the analysis yourself.

## CLI Bootstrap (run this FIRST - ONE command)

Before running any review commands, run this **single** preflight script. It checks everything in one shot:
```bash
if command -v appstore-reviews &>/dev/null; then
  echo "OK: appstore-reviews"
elif python3 -m appinsight --help &>/dev/null; then
  echo "OK: python3 -m appinsight"
else
  for d in .venv venv env; do
    if [ -f "$d/bin/activate" ]; then
      echo "Activating $d"
      source "$d/bin/activate"
      break
    fi
  done
  if command -v appstore-reviews &>/dev/null; then
    echo "OK: appstore-reviews"
  elif python3 -m appinsight --help &>/dev/null; then
    echo "OK: python3 -m appinsight"
  else
    echo "NOT INSTALLED"
  fi
fi
```

**Read the output:**
- `OK: appstore-reviews` - Use `appstore-reviews` as the command for all subsequent calls.
- `OK: python3 -m appinsight` - Use `python3 -m appinsight` as the command for all subsequent calls.
- `NOT INSTALLED` - Stop and tell the user:
  > `appstore-review-cli` is not installed in your current Python environment. Install it with:
  > ```bash
  > pip install appstore-review-cli
  > ```
  > Or create an isolated environment first:
  > ```bash
  > python3 -m venv .venv && source .venv/bin/activate && pip install appstore-review-cli
  > ```

  Do NOT run `pip install` yourself without asking the user first.

**Important**: Use the working command from the bootstrap for ALL subsequent calls in the session. Do not re-check or switch commands mid-session.

For Google Play support: `pip install "appstore-review-cli[google]"`

## Common Mistakes (NEVER do these)

- **NEVER use `python`** - always use `python3`. Many systems do not have `python` in PATH.
- **NEVER run `pip install` without asking the user** - they may want a specific environment.
- **NEVER run `pip list | grep` to check installation** - the bootstrap script above already handles detection.
- **NEVER run the bootstrap steps as separate commands** - run the single script above, read the output, done.
- **NEVER try `appstore-reviews`, then `python -m appinsight`, then `python3 -m appinsight` as separate commands** - the bootstrap handles all of this in one call.

**Always use the CLI in the terminal. Do NOT use the Python API or import statements - use the bash commands shown below.**

## Important Behavior

- **Output streams**: Data goes to stdout, progress/status messages go to stderr. Use `2>/dev/null` to suppress status messages when piping.
- **Review limit**: Apple's RSS feed returns a maximum of ~500 reviews per country (10 pages × 50 reviews). Don't expect more.
- **Deduplication**: Reviews are automatically deduplicated across pages.
- **Input validation**: `--stars` accepts 1-5, `--pages` accepts 1-10. Invalid values produce an error.
- **Filters stack**: `--stars`, `--min-stars`, `--keywords`, `--days`, and `--version` combine with AND logic. Each filter narrows the previous result.
- **Rating range**: `--stars 2` means 1-2 stars. `--min-stars 3 --stars 4` means 3-4 stars. `--min-stars 3 --stars 3` means only 3-star reviews.
- **Sorting**: Default is newest first. Use `--sort votes` to surface the most impactful reviews, `--sort rating` for lowest-rated first.
- **"No reviews match"**: If filters return zero results, the output will say "No reviews match the given filters." This is normal - try relaxing filters (fewer keywords, more days, higher star rating).
- **No reviews at all**: If an app has zero reviews in the store, the CLI will say so clearly and suggest trying a different country. Small or new apps often have no reviews.
- **Network errors**: If Apple's API is unreachable, the CLI prints a friendly error to stderr instead of a traceback.
- **Google Play**: Use `--store google` with package names (e.g. `com.Slack`). Requires `pip install appstore-review-cli[google]`.
- **Google Play search**: The first search result sometimes lacks a package name (library limitation). Use the package name directly if needed (find it in the Google Play URL).

## Output Rules

**NEVER redirect CLI output to files** (no `> file.txt`, `> reviews.csv`, etc.). Always read the output directly from stdout. The CLI is designed to print results to the terminal for you to analyze inline. Do not create `.txt`, `.csv`, `.json`, or any other files with review data unless the user explicitly asks for a file export.

## Available Commands

### 1. Search for an app
```bash
appstore-reviews search "app name"
```
Returns app IDs, names, ratings. Use this first to find the numeric app ID.

**Options:**
- `--limit 10` - Max results to return (default: 5)
- `--format json` - Output as JSON instead of table (useful for structured processing)

`--country` also works with search (e.g., `--country germany` to search the German App Store).

### 2. Fetch and filter reviews
```bash
appstore-reviews reviews <APP_ID> [options]
```

**Options (all optional, filters stack with AND logic):**
- `--stars 2` - Max star rating to include (1-2 stars). Valid range: 1-5.
- `--min-stars 3` - Min star rating to include (3+ stars). Use with `--stars` for exact range (e.g. `--min-stars 3 --stars 3` for only 3-star reviews).
- `--days 30` - Only reviews from the last 30 days
- `--keywords crash,freeze,bug` - Only reviews mentioning these words (case-insensitive, matches title or content)
- `--version 5.0.1` - Only reviews for a specific version
- `--pages 5` - Fetch more pages, 1-10 (default: 3, max useful: 10 = ~500 reviews)
- `--format json|text|csv|markdown` - Output format (default: text). Use `csv` for pandas/spreadsheet analysis.
- `--sort date|rating|votes` - Sort order: `date` (newest first, default), `rating` (lowest first), `votes` (most helpful first)
- `--stats` - Show rating distribution (printed to stderr, won't pollute data output)
- `--country us` - App Store region. Accepts codes (`us`, `gb`, `de`) or names (`germany`, `japan`, `united kingdom`)

### 3. Compare multiple apps
```bash
appstore-reviews compare <APP_ID_1> <APP_ID_2> [options]
```
Takes two or more app IDs. Supports `--stars`, `--min-stars`, `--days`, `--keywords`, `--pages`, `--sort`, `--country`.
Produces: overview table, per-app rating distribution, top complaint categories, top keywords, shared vs unique complaints.

### 4. Compare sentiment between versions
```bash
appstore-reviews version-diff <APP_ID> --pages 5
appstore-reviews version-diff <APP_ID> --old 4.23.0 --new 4.29.149
```
Supports `--stars`, `--min-stars`, `--days`, `--keywords`, `--pages`.
Shows: version comparison table, category changes with arrows, new/resolved issues, top keywords per version. Auto-detects the two most reviewed versions if `--old`/`--new` are omitted.

### 5. Show rating trend over time
```bash
appstore-reviews trend <APP_ID> --pages 5
appstore-reviews trend <APP_ID> --period month --stars 2
```
Supports `--stars`, `--min-stars`, `--days`, `--keywords`, `--pages`, `--period week|month`.
Shows: per-period average rating, review count, trend arrows (▲/▼), sparkline bars, star distributions, and overall trend direction.

All three commands (`compare`, `version-diff`, `trend`) support `--format json` and `--format csv` for machine-readable export.

## Analysis Modes

When the user asks for analysis, fetch the relevant reviews with the CLI, then **analyze them yourself** in your response. Do not run `analyze` or pipe to another LLM - you are the LLM.

### Gap Finder
Fetch 1-2 star reviews and analyze for unmet needs:
```bash
appstore-reviews reviews <APP_ID> --stars 2 --days 90 --pages 5 --format text
```
Look for patterns: "I wish it had...", "competitors do X better", "missing feature", "switched to Y".
**In your response**, group complaints by feature category, rank by frequency, and cite specific reviews as evidence.

### Bug Hunter
Fetch 1-2 star reviews filtered to technical issues:
```bash
appstore-reviews reviews <APP_ID> --stars 2 --keywords crash,bug,freeze,error,broken,slow,stuck --format text
```
**In your response**, group by symptom (crashes, performance, data loss), identify affected versions, and rank by severity.

### Sentiment Snapshot
Get the big picture before diving in:
```bash
appstore-reviews reviews <APP_ID> --stats --pages 5
```
Check the rating distribution first, then drill into the problem areas with targeted filters.

## Example Workflows

**"What are users complaining about in Slack?"**
```bash
appstore-reviews search "Slack"
# Find the app ID from results (e.g., 803453959)
appstore-reviews reviews 803453959 --stars 2 --days 60 --format text --stats
```
Then categorize the complaints: UX issues, missing features, bugs, performance. Rank by how often each category appears.

**"Find payment bugs in Spotify"**
```bash
appstore-reviews reviews 324684580 --stars 2 --keywords payment,subscribe,charge,billing --format text
```
Group results by symptom: failed payments, unwanted charges, subscription cancellation issues.

**"Compare negative reviews for two competing apps"**
```bash
appstore-reviews compare <APP_A_ID> <APP_B_ID> --stars 2 --pages 5
```
The compare command produces a structured report with per-app breakdowns, shared complaints, and unique weaknesses. You can supplement with additional analysis.

**"Check reviews for a specific country"**
```bash
appstore-reviews reviews 803453959 --stars 2 --country de --format text
```

**"Find complaints about Spotify on Android"**
```bash
appstore-reviews --store google reviews com.spotify.music --stars 2 --days 60 --format text
```
Group complaints by category: performance, features, bugs.

**"How has Slack's rating been trending?"**
```bash
appstore-reviews trend 803453959 --pages 5
```
The trend command shows weekly averages with sparklines. Use `--period month` for broader view.

## Python API (for scripts/notebooks only)

Only use this if the user is explicitly writing Python code or a notebook - otherwise always use the CLI commands above.
```python
from appinsight import get_reviews, get_reviews_df

# As list of dicts (no pandas needed)
reviews = get_reviews(618783545, stars=2, days=30)

# Google Play
reviews = get_reviews("com.Slack", stars=2, days=30, store="google")

# As pandas DataFrame (requires: pip install appstore-review-cli[pandas])
df = get_reviews_df(618783545, stars=2, pages=5)
df.groupby("version")["rating"].mean()
df[df["content"].str.contains("crash", case=False)]
```

Or export CSV from the CLI:
```bash
appstore-reviews reviews 618783545 --stars 2 --format csv
```
