> ## Documentation Index > Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt > Use this file to discover all available pages before exploring further. # Reviews > Pull App Store and Google Play reviews into the repo, see what users ask for in a summary, and answer them through a pull request. Reviews tell you what users want in their own words. Appeeky Spec writes them next to your listing, so you and your coding agent can read them before the next change, and answer them through a pull request like any other change. Reviews come from the store connections in Appeeky, so every `reviews` command that talks to a store needs `APPEEKY_API_KEY` and your apps connected in Appeeky. `reviews list` and `reviews reply` only read the repo. ## Pull reviews ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec reviews pull # App Store 412 reviews · 12 new · 3 changed # Google Play 168 reviews · 4 new · 0 changed # # Wrote appeeky/reviews/summary.md ``` | Option | What it does | | - | - | | `--since ` | Only reviews from this date on (default: everything the connection has) | | `--max ` | At most this many reviews per store (default 2000) | Pulling again adds new reviews and replaces ones the user edited or you answered. Nothing is lost between pulls. The daily workflow from `init --ci` and the Docker `daily` routine run `reviews pull` for you. ## Where they are stored ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} appeeky/reviews/app-store/2026-11.jsonl one review per line, newest first appeeky/reviews/google-play/2026-11.jsonl appeeky/reviews/summary.md what users say, in numbers appeeky/reviews/replies/-.yaml replies waiting to be sent ``` Each line of a monthly file is one review: `id`, `store`, `rating`, `title` (App Store only), `body`, `author`, `where` (the App Store territory, or the Google Play language), `version`, `date` and `reply` when there is one. `summary.md` is rewritten on every pull. For each store it has: * reviews, average rating, share of 1–2 stars and unanswered reviews for the last 30 days, the 30 days before, and everything pulled * star counts, and ratings for the last five versions * up to five low ratings still waiting for a reply, with their ids * **Words users use that your listing does not**: words and two-word phrases that come up in three or more reviews and appear in none of your listings, with how many came from 1–3 star reviews That last table is often the most useful part. A phrase like "fan sounds" in nine reviews is a keyword to check with `suggest`, or a feature to build. It filters English filler words only, so reviews in other languages show more noise. ## Read them ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec reviews list --rating 1-2 --unanswered # 2★ 2026-11-02 app-store US 3.1 1834 # Timer stops early The sleep timer cuts off after 20 minutes even when set to 8 hours. ``` | Option | What it does | | - | - | | `--store ` | `app-store` or `google-play` | | `--rating ` | Only this many stars, or a range like `1-2` | | `--unanswered` | Only reviews without a reply | | `-n, --limit ` | How many (default 20) | Add `--json` to any command for output an agent can read. ## Reply from the repo A reply is a small YAML file. Draft it, review it in a pull request, then send it. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec reviews reply 1834 --text "Sorry about that. 3.2 fixes the sleep timer, so it now runs the full 8 hours." # Drafted appeeky/reviews/replies/app-store-1834.yaml ``` ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} # appeeky/reviews/replies/app-store-1834.yaml id: "1834" store: app-store review: "2★ 2026-11-02: Timer stops early. The sleep timer cuts off after 20 minutes even when set to 8 hours." text: Sorry about that. 3.2 fixes the sleep timer, so it now runs the full 8 hours. status: draft ``` The review has to be in the repo already, so run `reviews pull` first. The `review` line is there for whoever reviews the pull request. You can edit `text` by hand. The stores limit reply length, and `reply` warns right away when a draft is over: | Store | Limit | | - | - | | App Store | 5,970 characters | | Google Play | 350 characters | Then commit the replies on a branch and open a pull request: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} git checkout -b reviews/replies git add appeeky/reviews && git commit -m "Reply to sleep timer reports" ``` ## Send replies Merging the pull request sends them: the push workflow from `init --ci` and the Docker `push` routine run `reviews push --yes`, and the pull request report lists every reply that goes out, with any that are too long. You can also send them yourself at any time, with or without a pull request: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec reviews push # 1834 app-store # Sorry about that. 3.2 fixes the sleep timer, so it now runs the full 8 hours. # Send 1 reply? [y/N] y # Sent 1. ``` `push` sends every reply still marked `status: draft`, then marks each one `status: sent` with `sentAt`, so it never goes out twice. Commit that change. If any draft is over the store's limit, nothing is sent until you shorten it. `--yes` sends without asking. Without a terminal (in CI or a script), pass `--yes`; otherwise nothing is sent. ## Ratings in verify `verify` reads the pulled review files to compare the average rating (`rating`) and the share of 1–2 star reviews (`low_ratings`, lower is better) before and after each push. A window with fewer than five reviews is skipped, because a handful of reviews says nothing about a change. You can also use either one as an [experiment](https://docs.appeeky.com/docs/spec-experiments.md) metric. ## How agents use them Your coding agent reads `summary.md` and the monthly files like any other file. Ask it things like *"what are people complaining about since 3.1?"* or *"draft replies to the unanswered 1-star reviews"*. In the [weekly review](https://docs.appeeky.com/docs/spec-growth-team.md), the `appeeky-reviews` specialist reads the reviews, their summary and competitors' low ratings. It returns what users ask for, a listing change that answers it, replies to draft and product requests the app cannot answer yet. Replies to draft go into the brief as work for a person. The weekly agent is never allowed to run `reviews push`. Related: [Competitors and market data](https://docs.appeeky.com/docs/spec-competitors.md) · [Specialists and the weekly review](https://docs.appeeky.com/docs/spec-growth-team.md) · [Commands](https://docs.appeeky.com/docs/spec-commands.md#reviews-pull) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.