One folder, every language, both stores
init finds the app, pulls every language it can reach from both stores and writes them as YAML. From then on the files are the listing, and a change to the listing is a change to a file.
$ npx @appeeky/spec coverage --country us
COVERAGE app-store · us indexed from en-US + es-MX
✓ white noise #8 +4 name
✓ sleep sounds #12 +29 name
✓ rain sounds #21 +17 subtitle
✓ brown noise #34 new keywords · es-MX
✗ fan sounds — — missing “fan”
Covered 4/5 targets
Spare es-MX keywords, 37 characters left
appeeky/store/app-store/en-US.yaml
only the fields in the file are managed
- nameSleep Sounds: White Noise compared · pushed…
- subtitleRain, Fan & Baby Sleep Aid compared · pushed…
- keywordsbrown,ambient,lullaby,nap,calm compared · pushed…
- promotionalText— left out of the file store keeps its own…
- description— left out of the file store keeps its own…
- whatsNew— left out of the file store keeps its own…
google-play/en-US.yaml holds title, short and full description and video.
Leave a field out to hand over one at a time. pull writes store-side edits back.
What the app should be found for
appeeky.spec.yaml names the app, how to reach each store and its targets: the searches it should be found for, per storefront. init suggests five from what the app already ranks for.
via picks the way in: your own App Store Connect key and Google Play service account on your machine (local), or your Appeeky connection (hosted), where the keys stay in Appeeky. Keys never go in the repo.
version: 1app:name: Sleep SoundsprimaryLocale: en-USstores:appStore:appId: "1234567890"via: auto # or local, hostedgooglePlay:packageName: com.example.sleepvia: autotargets: # per storefrontus: [sleep sounds, white noise, rain sounds, brown noise]de: [einschlafgeräusche, weißes rauschen]storefronts: # locales each readsus: [en-US, es-MX]
Coverage: which searches each store can find
coverage reads the targets against the fields each storefront indexes and marks each one covered, partial or missing, with the field that covers it. With an APPEEKY_API_KEY it is weighted by popularity, so the gaps worth fixing come first.
A storefront can read a second locale: the US App Store also reads Spanish (Mexico). Coverage counts it, and shows the spare characters in its keyword field.
$ npx @appeeky/spec coverage --country us✓ white noise #8 name✓ rain sounds #21 subtitle~ brown noise #34 keywords · es-MX✗ fan sounds — missing “fan”4/5 covered · es-MX: 37 characters free
Checked against the store rules
check runs on every pull request and before every push. Errors stop the change; warnings are for you to weigh, or fail too with --strict.
App Store
- LimitsName 30, subtitle 30, keywords 100, promotional text 170. Letters, not bytes.
- subtitle 26/30keywords 104/100
- Words onceName, subtitle and keyword words are indexed once.
- subtitle Rain, Fan & Baby · keywords fan,brown
- No wasted spaceSpaces around commas, duplicates, filler words, singular and plural pairs, 10+ unused characters.
- rain , sounds,sound,the,calm
- ScreenshotsSizes and counts per display type, from appeeky/screenshots/.
- de-DE iPhone 6.9″ 6 · iPad 13″ 0
fine flagged error, stops it
Google Play
- LimitsTitle 30, short description 80, full description 4,000.
- title 25/30short 40/80
- Title policy“best”, “#1”, “free” and all caps are flagged; emoji are an error.
- Best Sleep Sounds #1Sleep Sounds 🌙
- New languagesA new language needs the title, short and full description together.
- de-DE title ✓ short ✓ full —
fine flagged error, stops it
An error stops it, a warning asks
Over a limit is an error: the store would refuse it. A word repeated between the subtitle and the keyword field is a warning, because the store indexes it once and the space could hold another search.
In a pull request, the GitHub Action posts the same results as a comment with what changes and the coverage before and after, and fails the check on errors in the listing or the screenshots.
$ npx @appeeky/spec checkapp-store en-US✓ name 25/30 · subtitle 26/30! keywords: “fan” is in the subtitle· keywords: 68 characters unusedgoogle-play en-US✓ title 25/30 · short 40/800 errors · 1 warning · 1 note
The merge is the gate
Nothing reaches the stores until a person merges. Here is one change played through, from the edit to both stores.
- 01
Edit
Your agent changes the listing files on a branch and opens a pull request with its reason.
- 02
Check
Store limits and ASO rules on every pull request. An error fails it.
- 03
Diff
The files against the live store, field by field, and what has to wait for a new version.
- 04
Merge and push
The merge is the approval. What can go now goes, and the release file is written.
diff only reads──read──▶diff~ en-US subtitle
~ en-US promotionalText
writes to the store: never
Safe to run any time.
init --ci writes the workflows.github/workflows/
pull request
→ checkmerge that touches the listing
→ push --yesWithout CI, a person runs push and confirms.
Google Play is public in minutes- 0:00merge
- push
- +minspublic on Google Play
So it gets the same review as a release.
What goes live, and when
The App Store ties most fields to an app version; Google Play does not. The spec knows which is which, and diff tells you before you try.
App Store
- Promotional text 170✓ live now
next versionin the file - Name 30✓ live now
next versionin the file - Subtitle 30✓ live now
next versionin the file - Keywords 100✓ live now
next versionin the file - Description 4000✓ live now
next versionin the file - What's new 4000✓ live now
next versionin the file - Support and marketing URLs ✓ live now
next versionin the file
The rest goes with the next version: push --create-version 3.2.0
Google Play
- Title 30✓ live now
next versionin the file - Short description 80✓ live now
next versionin the file - Full description 4000✓ live now
next versionin the file - Promo video ✓ live now
next versionin the file
No app update needed. A new language needs all three text fields.
Every push leaves a record
push runs check and diff, asks you to confirm, saves the search rank of every target, sends what can go now and writes a release file: the values before and after, your --note and the ranks. Commit it; it is what day 7 and day 14 are measured against.
Fields blocked by a version stay in the files for the next push. push --create-version 3.2.0 opens the next App Store version first, so the name, subtitle and keywords can go with it. --store pushes one store only, --dry-run shows what would change.
id: 2026-11-14-fan-soundsnote: Lead with fan soundschanges:- app-store en-US promotionalText → New: a fan mix for hot nights.- google-play en-US shortDescription → Rain, fan and white noise to fall asleepbaseline:us: { fan sounds: null, rain sounds: 21, white noise: 8 }de: { einschlafgeräusche: 12 }
One command to undo
revert puts the values from before a release back into the files. It does not touch the store: review the files, then push them like any change. The revert is a release too, so it is measured like one.
log lists every release pushed from the spec, newest first, and log --markdown prints them for a changelog or a pull request.
$ npx @appeeky/spec revert 2026-11-14-fan-sounds✓ app-store en-US promotionalText✓ google-play en-US shortDescriptionrestored · next: diff, then push
New languages and screenshots
Localizing is keyword research per market, not translation. People in each country search with their own words.
A new market is a new file
Add the country's targets to the spec first, then a file for its locale. Start with name, subtitle and keywords; leave the description out until it is written properly. A new App Store locale ships with a version, and diff shows it as a new locale.
The appeeky-spec-localize skill teaches your agent this: targets before copy, the brand the same in every locale, no machine-translated keyword fields, and the cheapest win first, the spare keyword room in a locale a storefront already reads.
name: Sleep Sounds: Einschlafensubtitle: Regen, Ventilator & Rauschenkeywords: weißes,regengeräusche,baby,schlafhilfe,meer
Screenshots in the repo
screenshots pull downloads the live App Store screenshots of every locale into appeeky/screenshots/. screenshots check, also part of check, flags wrong sizes and counts per display type.
Screenshots are not searched; they change how many people install. A new set is best run as an experiment with its own metric, like conversion.
$ npx @appeeky/spec screenshots pullen-US iPhone 6.9″ 6 · iPad 13″ 5de-DE iPhone 6.9″ 6! de-DE has no iPad screenshotsSaved in appeeky/screenshots/app-store/
The commands
- init --pull
- Create the spec and write every live listing into appeeky/store/.
- pull
- Write the live listings into the files. Overwrites local edits.
- coverage
- Which targets each storefront finds, and the spare room in second locales.
- suggest --apply
- Add the missing target words to a keyword field.
- check --strict
- Store limits, ASO rules and screenshot sizes. Exits 1 on errors, or on warnings too.
- diff
- Field by field against the live store, and what waits for a new version.
- push --note "…"
- Check, diff, confirm, save the ranks, push, write the release file.
- push --create-version 3.2.0
- Open the next App Store version first.
- revert <release>
- Put the values from before a release back into the files.
- screenshots pull · check
- The live App Store screenshots, and their sizes.
- report --base main
- The Markdown a pull request needs: changes, checks, coverage.
Guides
- Getting started · 10 min readSet up Appeeky Spec in ten minutesConnect your stores, pull the live listing into your repo, pick the searches to win, and push your first checked change.
- The workflow · 7 min readHow a change goes liveFrom a file to the stores: what diff shows, which App Store fields wait for a version, how Google Play differs, and how to undo.
- 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.
- ASO · 7 min readLocalize without losing ranksA new language is keyword research, not translation. Targets first, the spare keyword space a storefront already reads, then one measured launch.

