appeeky spec
← Learn

The workflow · 7 min read

How a change goes live

From a file to the stores: what diff shows, which App Store fields wait for a version, how Google Play differs, and how to undo.

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.

appeeky/store/app-store/en-US.yaml
name: Sleep Sounds: White Noise
subtitle: Rain, Fan & Baby Sleep Aid
keywords: 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.

zsh
$ npx @appeeky/spec diff
en-US subtitle
− White Noise & Sleep Aid
+ Rain, Fan & Baby Sleep Aid
en-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. 1

    Runs check

    The same rules as before. With errors it stops, unless you pass --force.

  2. 2

    Runs diff

    Against the live store, so it only sends what is still different.

  3. 3

    Asks you

    Lists the changes and asks. --yes skips the question, for CI or an agent you allowed.

  4. 4

    Saves the baseline

    The rank of every target in every storefront, right before anything changes. verify compares with it.

  5. 5

    Pushes

    What can go now goes. Blocked fields stay for the next push.

  6. 6

    Writes the release

    appeeky/releases/<date>.yaml: before and after values, your note, the baseline. Commit it.

zsh
$ npx @appeeky/spec push --note "Lead with fan sounds"
✓ 1 field pushed · 1 waiting for a version
✓ appeeky/releases/2026-11-03.yaml
baseline: 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.

zsh
$ npx @appeeky/spec revert 2026-11-03
✓ en-US subtitle restored: White Noise & Sleep Aid
next: 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: pull writes the live listing into the files. Commit it so the history knows.
  • Keep the files: push puts the files' version back in the store.