doctor. It lists what is set up, what is missing and the command that fixes it. The sections below cover the messages you are most likely to see, then common questions.
Start with doctor
APPEEKY_API_KEY, attribution, the GitHub workflows, the agent skills, the specialist agents and .gitignore. ✗ must be fixed, ! is optional, and it exits 1 while anything is ✗. Add --json to give the result to an agent or a script. See Connect the stores for sample output.
Setup
No appeeky.spec.yaml found here or in a parent folder. Run appeeky-spec init first.
You are outside the app’s folder. cd into it, pass --cwd <dir>, or run npx @appeeky/spec init.
appeeky.spec.yaml already exists in … Run appeeky-spec doctor to see what is set up.
init never overwrites a spec. To add only the GitHub workflows to an existing spec, run init --ci.
Give an App Store id or a Google Play package to set up the spec.
The guided setup did not find the app. Run it again and type the numeric App Store id or the Google Play package name when asked.
A file path, then a field and a reason, for example …/appeeky/store/app-store/en-US.yaml: (root): Unrecognized key(s) in object: 'subtitel'
A spec or listing file has a typo or a wrong value. Fix the field the message names. Common ones:
Store access
Could not start npx: … Save your App Store Connect API key once … (or appstore, gps)
The store CLI could not start. Check that Node 20+ and npx work, or install the CLI. Then save your key as the message shows. See Connect the stores.
appstore … failed: … or gps … failed: …
The store said no. The end of the message is the store’s own reason. Most often:
- The key is wrong, revoked, or the
.p8path moved. Save the account again. - The App Store key’s role cannot write. Pushing needs App Manager.
- The Google Play service account is not invited in Play Console → Users and permissions, or has no access to this app.
- With several accounts, the wrong one is the default. Set
stores.appStore.accountorstores.googlePlay.account.
Set APPEEKY_API_KEY to use the hosted app-store gateway.
The spec or --via says hosted, but no key is set. Set APPEEKY_API_KEY, or switch via to local or auto and use your own keys.
… failed on asc-api.appeeky.com: … or Could not reach …
The hosted store connection failed. Check that the store is still connected in Settings → Data sources on appeeky.com and that your network is up. Or use your own keys.
The spec has no stores.appStore section.
A command needs a store the spec does not list. screenshots pull needs the App Store. Add the store under stores:.
Pushing
Fix these first, or pass --force.
check found listing errors, usually a field over its limit. Fix them; --force pushes anyway and the store will likely reject the field.
Not a terminal: pass --yes to push.
push asks before it changes anything. In CI or a script, pass --yes.
Nothing to push.
The spec matches the store, or every change is blocked. Run diff to see which.
App Store Connect did not return the new version 2.5.0.
--create-version did not get a version back. Check in App Store Connect whether it exists. If it does, run push again without --create-version.
A change is blocked
diff and push show blocked: under a change that cannot go live yet. push sends everything else.
Listing tools
No App Store listing for en-GB. Run appeeky-spec pull first.
suggest works on an App Store locale file. Pull it, or pass a --locale that exists.
Popularity missing for 4 keywords: …, or Appeeky API …: … (retry after 30s)
The Appeeky API allows 10 popularity lookups a minute. Spec stops when it hits the limit and keeps what it got for 7 days. Run coverage again in a minute to fill in the rest.
Set APPEEKY_API_KEY: …
Reviews, competitors, social, UGC from Appeeky and similar commands read data you connected in Appeeky. See On your own keys for what runs without it.
No release 2026-11-02. See appeeky-spec log.
revert needs a release id, or the start of one. List them with log.
FAQ
Do I need an Appeeky account? No. With your own store keys you can pull, check, run coverage and suggest, diff, push, revert and verify on App Store ranks. An Appeeky API key adds keyword popularity, Google Play ranks, conversion and revenue inverify, and more. See On your own keys.
Where are my keys kept?
Saved accounts are in the store CLIs’ config on your machine (~/.config/appstore/, ~/.config/gps/). In CI they are repository secrets. With via: hosted, the store keys stay in Appeeky. Spec never writes keys into the repo. .appeeky/ holds the cache and private data; keep it out of git.
Can I undo a push?
Yes. revert <release-id> puts the values from before the release back into the spec, then push sends them. A field that was empty before is cleared. Reverting App Store fields other than promotional text needs a new version, like any other change.
Can I see what a push would do first?
diff shows every change. push --dry-run shows the same and stops before it changes anything.
Will push delete a locale or a field I did not list?
No. Only the fields in your files are compared and pushed. Locales that exist only in the store are left alone. To clear a field, set it to "".
Someone edited the listing in App Store Connect. What now?
diff shows their edit as a change, and push would put your file’s value back. To keep their edit, run pull (it overwrites your local files) and commit.
Does push upload screenshots?
No. See Screenshots.
Next: Connect the stores · Commands · On your own keys