---
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 claude -->
<!-- Install to .claude/skills/appstore-reviews/ or ~/.claude/skills/appstore-reviews/ -->

The user has `appstore-review-cli` installed - a CLI tool for scraping Apple App Store and Google Play reviews. Use it to analyze competitor apps, find user complaints, and identify feature gaps.

**You ARE the analyzer.** Fetch reviews with the CLI, then reason over them directly. Do NOT suggest the user install Ollama or use the `analyze` command - you can do the analysis yourself.

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

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

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

## Quick Reference

Search for an app:
```bash
appstore-reviews search "app name"
```

Search with more results or JSON output:
```bash
appstore-reviews search "app name" --limit 10 --format json
```

Fetch negative reviews:
```bash
appstore-reviews reviews <APP_ID> --stars 2 --days 30 --format text
```

Fetch only 3-star reviews (the nuanced ones):
```bash
appstore-reviews reviews <APP_ID> --min-stars 3 --stars 3 --format text
```

Sort by most helpful (votes) instead of date:
```bash
appstore-reviews reviews <APP_ID> --stars 2 --sort votes --format text
```

Export to CSV for data analysis:
```bash
appstore-reviews reviews <APP_ID> --stars 2 --format csv
```

Fetch reviews with keyword filter:
```bash
appstore-reviews reviews <APP_ID> --keywords crash,bug,slow --format text
```

Combine filters (AND logic - all filters stack):
```bash
appstore-reviews reviews <APP_ID> --stars 2 --days 30 --keywords crash,freeze --version 5.0.1
```

Google Play - use `--store google` with package names:
```bash
appstore-reviews --store google search "Slack"
appstore-reviews --store google reviews com.Slack --stars 2 --days 30 --format text
appstore-reviews --store google compare com.Slack com.microsoft.teams --stars 2 --pages 3
```

Compare multiple apps side by side:
```bash
appstore-reviews compare <APP_ID_1> <APP_ID_2> --stars 2 --pages 3
```
Shows: overview table, rating distributions, top complaint categories, top keywords, shared vs unique complaints.

Compare sentiment between app versions:
```bash
appstore-reviews version-diff <APP_ID> --pages 5
appstore-reviews version-diff <APP_ID> --old 4.23.0 --new 4.29.149
```
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.

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

Export compare/version-diff/trend to JSON or CSV:
```bash
appstore-reviews compare <APP_ID_1> <APP_ID_2> --format json
appstore-reviews version-diff <APP_ID> --format csv
appstore-reviews trend <APP_ID> --format csv
```

All options: `appstore-reviews reviews --help`

## Important Behavior

- **Output streams**: Data goes to stdout, progress/status goes to stderr. Pipe-safe by default.
- **Review limit**: Apple's RSS feed returns max ~500 reviews per country (10 pages × 50). Use `--pages 10` for maximum coverage.
- **Deduplication**: Reviews are automatically deduplicated across pages.
- **Input validation**: `--stars` and `--min-stars` accept 1-5, `--pages` accepts 1-10. Invalid values are rejected.
- **Rating range**: `--stars 2` means 1-2 stars. Use `--min-stars 3 --stars 3` for only 3-star reviews.
- **Sorting**: `--sort date` (newest first, default), `--sort rating` (lowest first), `--sort votes` (most helpful first).
- **No results?**: "No reviews match the given filters" means filters are too narrow. Try fewer keywords, more days, or higher star ceiling.
- **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 the App Store is unreachable, the CLI prints a clear error to stderr instead of a traceback.
- **Country codes**: Default is `us`. Accepts 2-letter ISO codes (`de`, `gb`, `fr`) or full country names (`germany`, `united kingdom`, `japan`). Common aliases also work: `uk`, `usa`, `holland`. Example: `--country germany`.
- **Google Play**: Use `--store google` with package names (e.g. `com.Slack`). Requires `pip install appstore-review-cli[google]`.
- **Google Play search**: The first result sometimes lacks a package name. Use the package name directly if needed (find it in the Google Play URL).

**NEVER redirect CLI output to files** (no `> file.txt`, `> reviews.csv`, etc.). Always read the output directly from stdout. Do not create files with review data unless the user explicitly asks for a file export.

## How to Analyze (You Do This Yourself)

When asked to analyze reviews, use the CLI to fetch them, then reason over the output directly:

1. **Gap Finder**: Use `--stars 2` and look for "wish it had", "missing", "competitor does X". Group by feature category and rank by frequency.
2. **Bug Hunter**: Use `--stars 2 --keywords crash,bug,freeze,error,broken,slow`. Group by symptom, identify affected versions, rank by severity.
3. **Sentiment Snapshot**: Run with `--stats --pages 5` first to see the rating distribution before drilling into details.

Do NOT pipe output to Ollama or another external LLM. Analyze the review text yourself and present structured findings to the user.

## Example Workflows

**User asks: "What are Slack users complaining about?"**
```bash
appstore-reviews search "Slack"
# Get the app ID from results
appstore-reviews reviews 618783545 --stars 2 --days 60 --format text --stats
```
Then categorize the complaints in your response: UX issues, missing features, bugs, performance. Rank by frequency.

**User asks: "Find crash reports for WhatsApp"**
```bash
appstore-reviews search "WhatsApp"
appstore-reviews reviews <APP_ID> --stars 2 --keywords crash,freeze,error,broken,stuck --format text
```
Group by symptom in your response, note affected versions, rank by severity.

**User asks: "Compare Spotify vs Apple Music reviews"**
```bash
appstore-reviews compare 324684580 1108187390 --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.

**User asks: "What do German users think of Duolingo?"**
```bash
appstore-reviews search "Duolingo"
appstore-reviews reviews <APP_ID> --stars 2 --country germany --days 90 --format text
```
Analyze with awareness that reviews may be in German.

**User asks: "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.

**User asks: "What changed in the latest version of Notion?"**
```bash
appstore-reviews search "Notion"
appstore-reviews version-diff <APP_ID> --pages 5
```
The version-diff command shows exactly how sentiment shifted: rating changes, new/resolved complaint categories, and top keywords per version.

**User asks: "How has Slack's rating been trending?"**
```bash
appstore-reviews search "Slack"
appstore-reviews trend <APP_ID> --pages 5
```
The trend command shows weekly or monthly rating averages with sparkline visualizations. Use `--period month` for a broader view or `--stars 2` to track negative sentiment trends.

## 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 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
df = get_reviews_df(618783545, stars=2, pages=5)
df.groupby("version")["rating"].mean()
```
Requires: `pip install appstore-review-cli[pandas]`
