Skip to main content

​
1. Run init

In your app’s repo (or any folder), with Node 20 or later:
With no options, init is a guided setup. It asks for the app’s name, finds it on the App Store, checks the Google Play package, offers to save your store keys, pulls every store it can reach, suggests five targets from what the app already ranks for, offers the GitHub workflows and the agent skills, and ends on the first coverage table. It also adds .appeeky/ to .gitignore. For scripts, pass everything and nothing is asked:
This writes appeeky.spec.yaml and pulls every live locale into appeeky/store/:
Commit it. Keep .appeeky/ (cache and private data) out of git.

​
2. Connect the stores

Spec reads and writes listings through the Appeeky store CLIs. Pick one way per store:
Save your keys once with the store CLIs. They live in your user config (~/.config/appstore/, ~/.config/gps/), never in the repo. init offers to do this for you.
With several teams, pick the account per app with stores.appStore.account and stores.googlePlay.account. In CI, pass ASC_KEY_ID, ASC_ISSUER_ID, ASC_PRIVATE_KEY and GOOGLE_APPLICATION_CREDENTIALS instead. See App Store Connect CLI install and Google Play CLI install.
With via: auto (the default), Spec uses the local CLI when it is installed, the hosted gateway when APPEEKY_API_KEY is set, and npx otherwise. Run doctor to see what is set up and how to fix what is not:

​
3. Say what the app should be found for

init suggests targets. Edit them in appeeky.spec.yaml, per storefront:
Targets in a second storefront give verify a control group: it compares the storefronts a release changed with the ones it did not.

​
4. Check and look for gaps

coverage marks each target covered, partial or missing, weighted by popularity when APPEEKY_API_KEY is set. It also counts listing locales a storefront reads besides its own, for example Spanish (Mexico) on the US App Store, and shows how much keyword space they have left.

​
5. Edit, diff, push

Edit the listing files, then:
push runs check, shows the diff, asks for confirmation, records the current search ranks of your targets, pushes, and writes appeeky/releases/<id>.yaml. If the App Store changes need a new version:
With the workflows from init --ci, you do not run push yourself: open a pull request, read the report comment, merge, and the push workflow pushes. See GitHub Actions & CI.

​
6. Measure

A week later:
Each release gets a verdict (won, lost, mixed, flat) and a line in appeeky/playbook.md. status lists everything still being measured. If a release lost:
See Push, measure and revert for how the verdict is decided.

​
Next