A listing change in the spec is an edit to a file. Nothing reaches the store until you push, and every push leaves a record you can measure and undo. Here is what happens between the two.
The files are the listing
Each language on each store is one YAML file under appeeky/store/. A field in the file is managed: the spec compares it and pushes it. A field you leave out is not, so the store keeps whatever it has.
name: Sleep Sounds: White Noisesubtitle: Rain, Fan & Baby Sleep Aidkeywords: rain,fan,baby,brown noise,sleep aid
diff: what will change
diff reads the live store and compares it with the files, field by field. It is safe to run any time; it never writes.
$ npx @appeeky/spec diffen-US subtitle− White Noise & Sleep Aid+ Rain, Fan & Baby Sleep Aiden-US promotionalText+ New: a fan mix for hot nights.blocked until a new version: subtitle
The last line is the one people miss: some changes cannot go out yet, and diff says which and why before you try.
When each store changes
App Store
- Promotional text 170any time
- Name 30next version
- Subtitle 30next version
- Keywords 100next version
- Description 4000next version
- What's new 4000next version
- Support and marketing URLs next version
Google Play
- Title 30any time
- Short description 80any time
- Full description 4000any time
- Promo video any time
On the App Store, everything but promotional text belongs to an app version, and only a version still being prepared can be edited. Open one in App Store Connect, or let push --create-version 3.1.0 open it. On Google Play, changes are public within minutes, so they deserve the same review as a release.
push: what it does, in order
- 1
Runs check
The same rules as before. With errors it stops, unless you pass --force.
- 2
Runs diff
Against the live store, so it only sends what is still different.
- 3
Asks you
Lists the changes and asks. --yes skips the question, for CI or an agent you allowed.
- 4
Saves the baseline
The rank of every target in every storefront, right before anything changes. verify compares with it.
- 5
Pushes
What can go now goes. Blocked fields stay for the next push.
- 6
Writes the release
appeeky/releases/<date>.yaml: before and after values, your note, the baseline. Commit it.
$ npx @appeeky/spec push --note "Lead with fan sounds"✓ 1 field pushed · 1 waiting for a version✓ appeeky/releases/2026-11-03.yamlbaseline: fan sounds unranked · rain sounds #21
Undo with revert
revert <release> puts the values from before that release back into the files. It does not touch the store; review the files, then push them like any change.
$ npx @appeeky/spec revert 2026-11-03✓ en-US subtitle restored: White Noise & Sleep Aidnext: appeeky-spec diff, then push
When the store changed first
Someone edits the subtitle in App Store Connect. The next diff shows the store and the file disagreeing. You have two ways out:
- Keep their change:
pullwrites the live listing into the files. Commit it so the history knows. - Keep the files:
pushputs the files' version back in the store.