appstore-review-cli 0.1.0__tar.gz

appstore_review_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[google]"
+          pip install pytest
+
+      - name: Run tests
+        run: pytest -q

appstore_review_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

appstore_review_cli-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+uv.lock
+.env
+.DS_Store
+*.egg
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.swp
+*.swo
+.idea/
+.vscode/

appstore_review_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,179 @@
+# appstore-review-cli — App Store & Google Play Review Scraper
+
+<!-- This file was generated by: appstore-reviews setup claude -->
+<!-- It teaches Claude Code about the appstore-reviews CLI. -->
+
+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.
+
+## Quick Reference
+
+Search for an app:
+```bash
+appstore-reviews search "app name"
+```
+Fallback: `python3 cli.py 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 > reviews.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 > diff.csv
+appstore-reviews trend <APP_ID> --format csv > trend.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.
+- **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`. Common alternatives: `gb`, `de`, `fr`, `jp`, `au`, `ca`, `nl`, `br`, `kr`.
+- **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).
+
+## 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 de --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 programmatic use (e.g., in a script or notebook the user is building):
+```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]`

appstore_review_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vasilis Kayatas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

appstore_review_cli-0.1.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: appstore-review-cli
+Version: 0.1.0
+Summary: Scrape App Store and Google Play reviews. Filter the noise. Feed the signal to your coding agent.
+Project-URL: Homepage, https://github.com/vkayatas/appstore-review-cli
+Project-URL: Repository, https://github.com/vkayatas/appstore-review-cli
+Project-URL: Issues, https://github.com/vkayatas/appstore-review-cli/issues
+Author: Vasilis Kayatas
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,app-reviews,app-store,cli,coding-agent,copilot,google-play,play-store,product-analytics,ratings,reviews,scraper,sentiment
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28
+Provides-Extra: google
+Requires-Dist: google-play-scraper>=1.2; extra == 'google'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# appstore-review-cli
+
+[![CI](https://github.com/vkayatas/appstore-review-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/vkayatas/appstore-review-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/appstore-review-cli)](https://pypi.org/project/appstore-review-cli/)
+
+**Turn App Store and Google Play reviews into product intelligence - from the terminal or through your AI coding agent.**
+
+App store reviews are the largest public dataset of unfiltered user feedback. But reading them on the store websites is painful: no filtering, no export, no way to search across versions or countries. This tool fixes that.
+
+## Why Use This?
+
+- **Two stores**: Apple App Store and Google Play - same filters, same output, one tool.
+- **Competitor research**: Pull 1-star reviews for any app and find the feature gaps your product can fill.
+- **Bug triage**: Filter reviews by keywords like "crash", "freeze", "login" and group by app version.
+- **Version monitoring**: Compare sentiment between releases - see what got better, what got worse, and what's new.
+- **Multi-country insights**: Same app, different markets - compare complaints across `us`, `de`, `jp`, etc.
+- **AI-native**: Your coding agent (Copilot, Claude Code, Cursor) can fetch and analyze reviews in natural language. No Ollama needed - the agent IS the LLM.
+
+No API keys. No accounts. No servers. Just `pip install` and go.
+
+## Install
+
+```bash
+pip install appstore-review-cli
+```
+
+For Google Play support:
+```bash
+pip install "appstore-review-cli[google]"
+```
+
+## Quick Start
+
+```bash
+# Find an app
+appstore-reviews search "Slack"
+
+# Get negative reviews from the last 30 days
+appstore-reviews reviews 803453959 --stars 2 --days 30
+
+# Filter by keywords
+appstore-reviews reviews 803453959 --keywords crash,freeze --stars 2
+
+# Sort by most helpful
+appstore-reviews reviews 803453959 --stars 2 --sort votes
+
+# Get only 3-star reviews (the nuanced ones)
+appstore-reviews reviews 803453959 --min-stars 3 --stars 3
+
+# Export to CSV or JSON
+appstore-reviews reviews 803453959 --stars 2 --format csv > reviews.csv
+appstore-reviews reviews 803453959 --stars 2 --format json > reviews.json
+
+# Compare two apps side by side
+appstore-reviews compare 803453959 310633997 --stars 2 --pages 3
+
+# Google Play - use --store google with package names
+appstore-reviews --store google search "Slack"
+appstore-reviews --store google reviews com.Slack --stars 2 --days 30
+appstore-reviews --store google compare com.Slack com.microsoft.teams --stars 2
+
+# Compare sentiment between app versions
+appstore-reviews version-diff 803453959 --pages 5
+appstore-reviews version-diff 803453959 --old 4.23.0 --new 4.29.149
+
+# Show rating trend over time (weekly or monthly)
+appstore-reviews trend 803453959 --pages 5
+appstore-reviews trend 803453959 --period month --stars 2
+
+# Export compare/version-diff/trend to JSON or CSV
+appstore-reviews compare 803453959 310633997 --format json > compare.json
+appstore-reviews version-diff 803453959 --format csv > diff.csv
+appstore-reviews trend 803453959 --format csv > trend.csv
+```
+
+## Agent Integration
+
+One command to teach your AI coding agent every command, filter, and workflow:
+
+```bash
+appstore-reviews setup copilot      # GitHub Copilot → creates SKILL.md
+appstore-reviews setup claude       # Claude Code    → creates CLAUDE.md
+appstore-reviews setup cursor       # Cursor         → creates .cursor/rules/appstore-reviews.md
+appstore-reviews setup windsurf     # Windsurf       → creates .windsurfrules
+```
+
+Then just ask in natural language:
+
+- *"What are the top complaints about Slack this month?"*
+- *"Find crash reports for WhatsApp in the last 30 days"*
+- *"Compare Notion vs Obsidian - what do users hate about each?"*
+- *"What features are German Duolingo users requesting?"*
+
+The agent runs the CLI, fetches reviews, and analyzes them directly. No Ollama, no extra setup.
+
+Use `--force` to overwrite an existing file, `--append` to add to one.
+
+### Without an agent
+
+Use the built-in Ollama analysis, or pipe to any LLM:
+
+```bash
+# Ollama (local, private)
+ollama pull qwen3.5:4b
+appstore-reviews analyze 803453959 --stars 2 --mode summary
+appstore-reviews analyze 803453959 --stars 2 --mode gaps
+appstore-reviews analyze 803453959 --stars 2 --mode bugs --keywords crash,freeze
+
+# Or pipe raw output to any tool
+appstore-reviews reviews 803453959 --stars 2 --format text | your-llm "Summarize:"
+```
+
+## All Options
+
+### Global flags (apply to all commands)
+
+| Flag | Description |
+|------|-------------|
+| `--store google` | Use Google Play instead of Apple App Store (default: `apple`) |
+| `--country de` | Store region (default: `us`) |
+
+### `search` - Find an app by name
+
+| Flag | Description |
+|------|-------------|
+| `--limit 10` | Max results (default: 5) |
+| `--format json` | Output as JSON instead of table |
+| `--country de` | App Store region (default: `us`) |
+
+For Google Play, app IDs are package names (e.g. `com.Slack`). For Apple, they're numeric (e.g. `803453959`).
+
+### `reviews <APP_ID>` - Fetch and filter reviews
+
+| Flag | Description |
+|------|-------------|
+| `--stars 2` | Max star rating to include (1-5). `2` = 1-2 stars |
+| `--min-stars 3` | Min star rating (1-5). `--min-stars 3 --stars 3` = only 3★ |
+| `--days 30` | Only reviews from the last N days |
+| `--keywords crash,bug` | Only reviews containing these words (case-insensitive) |
+| `--version 5.0.1` | Only reviews for a specific app version |
+| `--pages 5` | Pages to fetch (1-10, default 3; 10 ≈ 500 reviews) |
+| `--format text` | Output as `text` \| `json` \| `csv` \| `markdown` |
+| `--sort votes` | Sort by: `date` (newest) \| `rating` (lowest) \| `votes` (most helpful) |
+| `--stats` | Show rating distribution |
+| `--country de` | App Store region (default: `us`) |
+
+All filters stack with AND logic.
+
+### `analyze <APP_ID>` - LLM analysis via Ollama
+
+| Flag | Description |
+|------|-------------|
+| `--mode summary` | Analysis type: `summary` \| `gaps` \| `bugs` |
+| `--model qwen3.5:4b` | Ollama model to use |
+| `--list-models` | Show available Ollama models |
+
+Plus all the same filters as `reviews` (`--stars`, `--min-stars`, `--days`, `--keywords`, `--version`, `--pages`, `--sort`, `--stats`, `--country`).
+
+### `compare <APP_ID> <APP_ID> [...]` - Compare multiple apps
+
+| Flag | Description |
+|------|-------------|
+| `--stars 2` | Max star rating to include (1-5) |
+| `--min-stars 3` | Min star rating (1-5) |
+| `--days 30` | Only reviews from the last N days |
+| `--keywords crash,bug` | Only reviews containing these words |
+| `--pages 5` | Pages to fetch per app (1-10, default 3) |
+| `--sort votes` | Sort by: `date` \| `rating` \| `votes` |
+| `--country de` | App Store region (default: `us`) |
+| `--format json` | Output format: `text` (default) \| `json` \| `csv` |
+
+Outputs: overview table, per-app rating distribution, top complaint categories, top keywords, shared vs unique complaints.
+
+### `version-diff <APP_ID>` - Compare sentiment between versions
+
+| Flag | Description |
+|------|-------------|
+| `--old 4.23.0` | Old version to compare (auto-detected if omitted) |
+| `--new 4.29.149` | New version to compare (auto-detected if omitted) |
+| `--stars 2` | Max star rating to include (1-5) |
+| `--min-stars 3` | Min star rating (1-5) |
+| `--days 90` | Only reviews from the last N days |
+| `--keywords crash,bug` | Only reviews containing these words |
+| `--pages 5` | Pages to fetch (1-10, default 5) |
+| `--format json` | Output format: `text` (default) \| `json` \| `csv` |
+
+Outputs: version comparison table, rating distributions, complaint category changes (with arrows), new/resolved issues, top keywords per version. Versions are auto-detected from the two most reviewed if not specified.
+
+### `trend <APP_ID>` - Show rating trend over time
+
+| Flag | Description |
+|------|-------------|
+| `--period week` | Group by `week` (default) or `month` |
+| `--stars 2` | Max star rating to include (1-5) |
+| `--min-stars 3` | Min star rating (1-5) |
+| `--days 90` | Only reviews from the last N days |
+| `--keywords crash,bug` | Only reviews containing these words |
+| `--pages 5` | Pages to fetch (1-10, default 5) |
+| `--format json` | Output format: `text` (default) \| `json` \| `csv` |
+
+Outputs: per-period table with average rating, review count, trend arrows (▲/▼), ASCII sparkline bars, mini star distributions, and overall trend summary.
+
+### `setup <agent>` - Install agent instructions
+
+| Argument / Flag | Description |
+|-----------------|-------------|
+| `copilot` | Creates `SKILL.md` for GitHub Copilot |
+| `claude` | Creates `CLAUDE.md` for Claude Code |
+| `cursor` | Creates `.cursor/rules/appstore-reviews.md` |
+| `windsurf` | Creates `.windsurfrules` |
+| `--force` | Overwrite existing file |
+| `--append` | Append to existing file |
+
+**Country codes:** `us` (default), `gb`, `de`, `fr`, `jp`, `au`, `ca`, `nl`, `br`, `kr`
+
+## Python API
+
+```python
+from appinsight import get_reviews, get_reviews_df, search
+
+# Search
+apps = search("Slack", limit=3)
+
+# As dicts (no pandas needed)
+reviews = get_reviews(618783545, stars=2, days=30)
+
+# As pandas DataFrame
+df = get_reviews_df(618783545, stars=2, pages=5)
+df.groupby("version")["rating"].mean()
+df[df["content"].str.contains("crash", case=False)]
+# Google Play
+reviews = get_reviews("com.Slack", stars=2, days=30, store="google")
+df = get_reviews_df("com.Slack", stars=2, pages=5, store="google")
+```
+
+Install with pandas: `pip install appstore-review-cli[pandas]`
+Install with Google Play: `pip install appstore-review-cli[google]`
+
+## Good to Know
+
+- **Pipe-safe**: Data goes to stdout, progress to stderr.
+- **Review limit**: Apple returns max ~500 reviews per country (10 pages × 50). This is Apple's limit.
+- **Deduplication**: Reviews are automatically deduplicated across pages.
+- **Validation**: `--stars`/`--min-stars` accept 1-5, `--pages` accepts 1-10. Invalid values are rejected.
+- **Google Play search**: The first search result sometimes lacks a package name (library limitation). Use the package name directly if your app doesn't appear (find it in the Google Play URL).
+- **No results?** Filters are too narrow - try fewer keywords, more days, or a higher star ceiling.
+
+## Development
+
+```bash
+git clone https://github.com/vkayatas/appstore-review-cli.git
+cd appstore-review-cli
+uv sync
+uv run pytest
+```
+
+## Roadmap
+
+- [x] Google Play Store support
+- [x] Multi-app comparison command
+- [x] Version diff (sentiment changes between releases)
+- [x] Rating trend over time (weekly/monthly)
+- [x] Export compare/version-diff/trend to JSON/CSV
+- [x] PyPI publish with GitHub Actions CI