What users ask for, and what competitors change

Reviews from both stores with their themes and drafts for replies, and every competitor's listing, ranks and ratings, as files your agent reads.

Then ask your agent: “Set up Appeeky Spec for this app.”

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

zsh
$ npx @appeeky/spec reviews pull
App Store 412 reviews · 38 new · 2 changed
Google Play 198 reviews · 21 new · 0 changed
Wrote 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.

appeeky/reviews/summary.md
## 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.

  1. 01

    Pull

    New reviews from both stores land in a file per month.

  2. 02

    Summarize

    summary.md counts ratings, low ones waiting for a reply, and words your listing never says.

  3. 03

    Draft

    Your agent drafts a reply in replies/, for a person to read in the pull request.

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

appeeky/reviews/replies/app-store-1834.yaml
id: "1834"
store: app-store
review: "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:

appeeky.spec.yaml
competitors:
- name: Calm Night
appStore: "1234567891"
googlePlay: com.calmnight.app
- name: Pure Noise
appStore: "1234567892"
zsh
$ npx @appeeky/spec competitors discover --add 3
1234567891 Calm Night 4.6★ 18204
1234567892 Pure Noise 4.4★ 9310
1234567893 Dream Fan 4.7★ 2210
Added 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.

appeeky/competitors/calm-night.yaml
name: Calm Night
pulledAt: 2026-11-12
country: us
stores:
app-store:
title: Calm Night - Fan & Rain Sounds
rating: 4.6
version: "5.2"
releaseNotes: Fan and AC sounds, a new sleep timer
ranks:
- keyword: white noise
rank: 2
yourTargets:
- keyword: fan sounds
rank: 4
recentReviews:
average: 3.9
low:
- rating: 2
text: 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.

.github/workflows/appeeky-spec-daily.yml
on:
schedule: [{ cron: "0 6 * * *" }]
jobs:
refresh:
runs-on: ubuntu-latest
permissions: { contents: write }
steps:
- uses: actions/checkout@v4
- run: npx @appeeky/spec reviews pull
env: { APPEEKY_API_KEY: "${{ secrets.APPEEKY_API_KEY }}" }
- run: npx @appeeky/spec competitors pull
env: { 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.
Every command in the docs

Guides

More in Appeeky Spec