Your store listing, as files in your repo

Every language on the App Store and Google Play in one folder, checked against the store rules, diffed before it goes live, and pushed only after a merge.

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

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.

sleep-sounds — ASO
ASO >app-storeus>covered4/5
1# ASO · App Store · United States
2Indexed from en-US and es-MX. Ranks from the last 7 days.
3
4| target | rank | 7d | pop | covered by |
5|------------------|------|------|-----|--------------------|
6| white noise | 8 | +4 | 71 | name |
7| sleep sounds | 12 | +29 | 62 | name |
8| rain sounds | 21 | +17 | 48 | subtitle |
9| brown noise | 34 | new | 39 | keywords · es-MX |
10| fan sounds | — | — | 33 | missing “fan” |
11
12## Worth adding
13- fan pop 33 · fits in es-MX keywords (37 left)
14- baby sleep pop 44 · persona new-parents
15
16## Competitor moves
17- Calm Sleep dropped “rain” from its subtitle on Oct 28
claude - agentsleep-sounds - zsh

$ 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

main · localaso · us · 4/5 targets covered · 2 worth adding

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.

appeeky.spec.yaml
version: 1
app:
name: Sleep Sounds
primaryLocale: en-US
stores:
appStore:
appId: "1234567890"
via: auto # or local, hosted
googlePlay:
packageName: com.example.sleep
via: auto
targets: # per storefront
us: [sleep sounds, white noise, rain sounds, brown noise]
de: [einschlafgeräusche, weißes rauschen]
storefronts: # locales each reads
us: [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.

zsh
$ 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.

zsh
$ npx @appeeky/spec check
app-store en-US
✓ name 25/30 · subtitle 26/30
! keywords: “fan” is in the subtitle
· keywords: 68 characters unused
google-play en-US
✓ title 25/30 · short 40/80
0 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.

  1. 01

    Edit

    Your agent changes the listing files on a branch and opens a pull request with its reason.

  2. 02

    Check

    Store limits and ASO rules on every pull request. An error fails it.

  3. 03

    Diff

    The files against the live store, field by field, and what has to wait for a new version.

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

    merge that touches the listing
    → push --yes

    Without CI, a person runs push and confirms.

  • Google Play is public in minutes

    1. 0:00merge
    2. push
    3. +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.

appeeky/releases/2026-11-14.yaml
id: 2026-11-14-fan-sounds
note: Lead with fan sounds
changes:
- app-store en-US promotionalText → New: a fan mix for hot nights.
- google-play en-US shortDescription → Rain, fan and white noise to fall asleep
baseline:
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.

zsh
$ npx @appeeky/spec revert 2026-11-14-fan-sounds
✓ app-store en-US promotionalText
✓ google-play en-US shortDescription
restored · 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.

appeeky/store/app-store/de-DE.yaml
name: Sleep Sounds: Einschlafen
subtitle: Regen, Ventilator & Rauschen
keywords: 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.

zsh
$ npx @appeeky/spec screenshots pull
en-US iPhone 6.9″ 6 · iPad 13″ 5
de-DE iPhone 6.9″ 6
! de-DE has no iPad screenshots
Saved 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.
Every command in the docs

Guides

More in Appeeky Spec