appeeky spec
← Learn

Getting started · 10 min read

Set up Appeeky Spec in ten minutes

Connect your stores, pull the live listing into your repo, pick the searches to win, and push your first checked change.

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: local

App Store: an App Store Connect API key (Users and Access → Integrations, role App Manager), saved once on your machine.

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

zsh
$ 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: hosted

Connect App Store Connect and Google Play once in Appeeky. The keys stay there, and every machine and CI job uses one API key instead.

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

zsh
$ npx @appeeky/spec init
1/6 Your app
What is it called on the App Store? Sleep Sounds
1 Sleep Sounds: Rain & Ocean Calm Apps · 4.7★ · 1234567890
Google Play package, or - for none: (com.example.sleep)
✓ found on Google Play
3/6 Store access and your live listing
✓ App Store hosted through your Appeeky connection
✓ Google Play local gps CLI · its saved account
App Store: 4 locales · Google Play: 2 locales
4/6 The searches to win in US
white noise #8
rain sounds #21
ocean sounds not in the top 200
5/6 Automation: GitHub Actions, agent skills
6/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:

▾ sleep-sounds
appeeky.spec.yaml# app ids and the searches to win
▾ appeeky
▾ store
▾ app-store
en-US.yaml# name, subtitle, keywords, descriptions
es-MX.yaml
…
▾ google-play
en-US.yaml# title, short and full description
…
playbook.md# what worked, filled in by verify
.appeeky# local cache and data, kept out of git

Any time something does not work, or before you hand the repo to a teammate, ask what is set up:

zsh
$ npx @appeeky/spec doctor
✓ App Store hosted through your Appeeky connection
✓ targets 5 in us
! control group Targets in one storefront only
Add 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 spec
Optional: npx @appeeky/spec init --ci
Ready · 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.

appeeky.spec.yaml
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.

zsh
$ npx @appeeky/spec check
✓ en-US subtitle 27/30 · keywords 49/100
! en-US “sleep” in name and subtitle: index it once
0 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:

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

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

zsh
$ 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.yaml
baseline: 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:

zsh
$ 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.yml
# .github/workflows/appeeky-spec.yml
on: pull_request
permissions:
contents: read
pull-requests: write
jobs:
spec:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
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.