By the end you will have your App Store and Google Play listing in your repo as files, the searches you want to rank for written down, and one change checked, pushed and waiting to be measured. Nothing goes to the stores until you say so.
What you need
- node
Node.js
Version 20 or newer. The spec runs with
npx, so there is nothing to install. Your App Store app id
The app's numeric id, from App Store Connect (App Information → Apple ID) or the URL of its store page.
Your Google Play package name
The package name, like
com.example.sleep.- API
An Appeeky API keyoptional
Search popularity, ranks on both stores, analytics, reviews and ads. Everything in this guide works without it.
One store is enough. If you only ship on iOS, leave Google Play out everywhere below.
Connect your stores
The spec reads and writes the listing through the store APIs. Pick one of two ways per store. Either way, keys never go into the repo.
Your own keys
via: localApp Store: an App Store Connect API key (Users and Access → Integrations, role App Manager), saved once on your machine.
$ npx -p @appeeky/app-store-connect-cli appstore accounts add my-team \--key-id ABC123DEFG --issuer-id <issuer-id> \--private-key-path ~/AuthKey_ABC123DEFG.p8 --default
Google Play: a service account with access to the app in Play Console.
$ npx -p @appeeky/google-play-store-cli gps accounts add my-co \--credentials ~/play-service-account.json --default
Both are open source: the App Store Connect CLI and the Google Play CLI. The keys are saved in your user config, never in the repo, and init offers to save them for you.
Through Appeeky
via: hostedConnect App Store Connect and Google Play once in Appeeky. The keys stay there, and every machine and CI job uses one API key instead.
$ export APPEEKY_API_KEY=apk_…
The default, via: auto, uses your own keys when the store CLI is set up and Appeeky when the key is set.
Pull your live listing
In the repo where your app lives, run init with no options. It asks a few questions and does the rest:
$ npx @appeeky/spec init1/6 Your appWhat is it called on the App Store? Sleep Sounds1 Sleep Sounds: Rain & Ocean Calm Apps · 4.7★ · 1234567890Google Play package, or - for none: (com.example.sleep)✓ found on Google Play3/6 Store access and your live listing✓ App Store hosted through your Appeeky connection✓ Google Play local gps CLI · its saved accountApp Store: 4 locales · Google Play: 2 locales4/6 The searches to win in USwhite noise #8rain sounds #21ocean sounds not in the top 2005/6 Automation: GitHub Actions, agent skills6/6 Where you stand: the first coverage table
It finds the app on the App Store, checks the Google Play package, pulls every store it can reach, suggests targets from what the app already ranks for, offers the GitHub workflows and the agent skills, and ends on coverage. In a script, pass everything instead: init --name "Sleep Sounds" --app-store 1234567890 --google-play com.example.sleep --pull --ci.
You now have a folder you can read, search and diff, with one file per language on each store:
Any time something does not work, or before you hand the repo to a teammate, ask what is set up:
$ npx @appeeky/spec doctor✓ App Store hosted through your Appeeky connection✓ targets 5 in us! control group Targets in one storefront onlyAdd a few targets for a second country: verify compares the storefronts a release changed with the ones it did not.! GitHub Actions No workflow runs the specOptional: npx @appeeky/spec init --ciReady · 2 optional
Pick the searches to win
Targets are the searches you want to be found for, per country. Everything the spec measures is about them: coverage, ranks, and whether a change worked. Start with five to ten per country.
targets:us: [sleep sounds, white noise, rain sounds, brown noise, fan sounds]tr: [uyku sesleri, beyaz gürültü]
Not sure which? With an Appeeky key, npx @appeeky/spec suggest lists searches people use that your listing does not cover yet, by popularity. Your agent can also pick them for you; see step 7.
Check and measure
Two commands tell you where you stand before you change a word.
$ npx @appeeky/spec check✓ en-US subtitle 27/30 · keywords 49/100! en-US “sleep” in name and subtitle: index it once0 errors · 1 warning
check catches store limits, words repeated across the name, subtitle and keyword field, wasted keyword space and Google Play title policy. coverage shows which targets each storefront can match, and where the words come from:
$ npx @appeeky/spec coverage --country us✓ white noise #8 name✓ rain sounds #21 subtitle✗ fan sounds — missing “fan”4/5 covered · es-MX has 37 characters free
Push your first change
Edit a file the way you would edit code. Here, “fan” goes into the subtitle. Then diff shows exactly what will go live:
$ npx @appeeky/spec diffen-US subtitle− White Noise & Sleep Aid+ Rain, Fan & Baby Sleep Aidblocked until a new version: subtitle
On the App Store, only the promotional text changes on the live version. The rest ships with the next version, so push can open it for you. It checks again, asks you to confirm, saves today's ranks and writes a release file:
$ npx @appeeky/spec push --create-version 3.1.0 --note "Lead with fan sounds"✓ created 3.1.0 · 1 field pushed✓ appeeky/releases/2026-11-03.yamlbaseline: fan sounds unranked · rain sounds #21
Commit the release file with the change. On day 7 and day 14, npx @appeeky/spec verify --playbook compares the ranks with that baseline, marks the release won, lost, mixed or flat, and adds a line to the playbook. If it lost, revert puts the old values back.
Hand it to your agent
The spec is plain files and every command takes --json, so Claude Code, Codex, Cursor or Gemini can do all of the above. Install the skills once in the repo:
$ npx skills add appeeky/skills
Then ask in plain words. The agent reads the playbook first, edits the files, runs the checks and leaves the push to you:
you Get us ranking for “fan sounds” in the US.
agent Reading playbook.md and the last two releases first.
$ appeeky-spec coverage --country us --json
“fan” fits in the es-MX keywords (37 characters free). Edited, check passes.
Run it on pull requests
Optional, and worth it once more than one person or agent touches the listing. The GitHub Action comments what a pull request will change and fails it on check errors:
# .github/workflows/appeeky-spec.ymlon: pull_requestpermissions:contents: readpull-requests: writejobs:spec:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4with:fetch-depth: 0- uses: appeeky/spec@v0
That is the whole setup. From here, every listing change is a file, a pull request and a measured release. The commands are all in the command reference.