Every review, in the repo
Every review from the App Store and Google Play, in plain files next to the listing. Your agent reads them before it proposes a change, and you can grep them like code.
One file per store and month
reviews pull writes each review to appeeky/reviews/<store>/<YYYY-MM>.jsonl, one JSON object per line: id, rating, title, body, territory or language, app version, date and your reply if there is one.
Pull again and new reviews are added, edited or answered ones replaced. --since limits it to a date, --max caps each store (2,000 by default).
$ npx @appeeky/spec reviews pullApp Store 412 reviews · 38 new · 2 changedGoogle Play 198 reviews · 21 new · 0 changedWrote appeeky/reviews/summary.md
The summary is the brief
summary.md is rewritten on every pull: the last 30 days next to the 30 before, and ratings per app version, so an update that upset people shows.
Last, the words users use that your listing does not: phrases in three or more reviews and in no listing. Each is a candidate target, a line for the description, or a request for the product.
## App Store| | reviews | average | 1–2 stars | unanswered || last 30 days | 184 | 4.52 | 6% | 11 || 30 days before | 151 | 4.31 | 11% | 9 || version | reviews | average | 1–2 stars || 3.1 | 96 | 4.55 | 5% || 3.0 | 212 | 4.21 | 12% |Low ratings without a reply:- `1834` 2★ 2026-11-02 US: Wish it had fan sounds- `1821` 1★ 2026-10-30 GB: Crashes when I open settings## Words users use that your listing does not| words | reviews | of them 1–3 stars || fan sounds | 9 | 5 || sleep timer | 7 | 6 |
From a two-star review to a reply that went out
A reply is public copy with your name on it, so it goes through the same pull request as a listing change. Here is one, from the pull to the store.
- 01
Pull
New reviews from both stores land in a file per month.
- 02
Summarize
summary.md counts ratings, low ones waiting for a reply, and words your listing never says.
- 03
Draft
Your agent drafts a reply in replies/, for a person to read in the pull request.
- 04
Send
The merge runs reviews push. Nothing goes to a store before that.
A draft, reviewed like code
What the review said and what you answered stay together in git, so the next reply can build on the last.
One file per reply
reviews list filters the pulled files by store, stars and unanswered. It needs no network, so your agent runs it as often as it likes.
The Appeeky Spec skill keeps each reply specific to what the user said, with no promises the app does not keep. Someone reads the drafts in the pull request, edits a word or two, and merges. Then they go out.
id: "1834"store: app-storereview: "2★ 2026-11-02: Wish it had fan sounds for summer nights."text: Thanks! Fan sounds are in 3.2, out this week.status: draft
Competitors, in a file each
List the apps you compete with, or let Appeeky find them. Each one gets a file, and every pull says what it changed since the last.
Name them, or discover them
competitors discover lists apps like yours, on Google Play with --store google-play. --add 3 writes the first three into the spec. Or by hand:
competitors:- name: Calm NightappStore: "1234567891"googlePlay: com.calmnight.app- name: Pure NoiseappStore: "1234567892"
$ npx @appeeky/spec competitors discover --add 31234567891 Calm Night 4.6★ 182041234567892 Pure Noise 4.4★ 93101234567893 Dream Fan 4.7★ 2210Added 3 to appeeky.spec.yaml. Run appeeky-spec competitors pull.
What each file holds
competitors pull writes, per store: title, rating, version and release notes, the first part of the description, its 25 best searches in your first targets country, its ranks for your targets, and its recent low ratings. What users dislike there is often what your listing should lead with.
Every pull adds what moved to appeeky/competitors/changes.md: a new title, a new version and its notes, a rewritten description, a climb into the top 10 for one of your targets.
name: Calm NightpulledAt: 2026-11-12country: usstores:app-store:title: Calm Night - Fan & Rain Soundsrating: 4.6version: "5.2"releaseNotes: Fan and AC sounds, a new sleep timerranks:- keyword: white noiserank: 2yourTargets:- keyword: fan soundsrank: 4recentReviews:average: 3.9low:- rating: 2text: Too many ads before the sound starts
What the agent does with them
Two of the six specialists read these files. They only read; the co-founder review picks one change and opens a pull request, and the rest is for you.
What needs an Appeeky key
Reviews and competitors come from the store connections in Appeeky, so pulling and sending need an APPEEKY_API_KEY. Reading and drafting work on the files alone.

reviews pull
Reads both stores through your connections in Appeeky.
APPEEKY_API_KEY
reviews push
Sends the drafts through the same connections.
APPEEKY_API_KEY
competitors discover · pull
Listings, ranks and reviews of other apps, from Appeeky.
APPEEKY_API_KEY
reviews list · reply
Read and write the files already in the repo.
no key, works offline
Fresh every morning
No CI is needed: your agent runs these when it wants fresh files, on your machine with your key. To keep them current on their own, schedule reviews pull and competitors pull once a day and commit what changed.
verify then reads the pulled reviews around every listing push: the average rating and the share of one- and two-star reviews, before and after.
on:schedule: [{ cron: "0 6 * * *" }]jobs:refresh:runs-on: ubuntu-latestpermissions: { contents: write }steps:- uses: actions/checkout@v4- run: npx @appeeky/spec reviews pullenv: { APPEEKY_API_KEY: "${{ secrets.APPEEKY_API_KEY }}" }- run: npx @appeeky/spec competitors pullenv: { APPEEKY_API_KEY: "${{ secrets.APPEEKY_API_KEY }}" }- run: git add appeeky && git commit -m "Daily pull" && git push || true
The commands
- reviews pull
- Both stores' reviews into appeeky/reviews/, and summary.md rewritten.
- reviews list
- Reviews from the repo, newest first: --store, --rating 1-2, --unanswered, --limit.
- reviews reply <id> --text
- Draft a reply in appeeky/reviews/replies/ for the pull request.
- reviews push
- Send the drafts to the stores and mark them sent. --yes skips the question.
- competitors discover
- Apps like yours; --add <n> puts the first n in the spec.
- competitors pull
- Each competitor's listing, ranks and low ratings, and what changed, in appeeky/competitors/.
- status
- Every change being measured, with a warning when a competitor moved inside its window.
Guides
- Users · 6 min readReviews, answered in a pull requestPull every review into the repo, read the summary, draft replies with your agent and send them after a review.
- ASO · 8 min readPick the searches to winChoosing targets per country, reading coverage, using the second language a storefront reads, and where the words should go.