Write and check your listing

Your listing lives in appeeky/store/ as one YAML file per locale. You edit those files, Spec checks them, shows which of your target searches each storefront is found for, and shows exactly what would change on the store before you push.

The listing files

pull writes every live locale into its own file. It overwrites the local files, so commit or stash your edits first.

npx @appeeky/spec pull                       # both stores
npx @appeeky/spec pull --store app-store --locale en-US de-DE

appeeky/store/app-store/en-US.yaml:

name: "Sleep Sounds: Rain & Ocean"
subtitle: White noise, fan, lullaby
keywords: insomnia,relax,meditation,storm,thunder,baby,nap,calm
promotionalText: New: brown noise mixes.
description: |
  Fall asleep faster with ...
whatsNew: Bug fixes.

appeeky/store/google-play/en-US.yaml has title, shortDescription, fullDescription and video.

Store	Field	Limit	Searched
App Store	`name`	30	Yes
App Store	`subtitle`	30	Yes
App Store	`keywords`	100	Yes
App Store	`promotionalText`	170	No
App Store	`description`, `whatsNew`	4000	No
App Store	`marketingUrl`, `supportUrl`		No
Google Play	`title`	30	Yes
Google Play	`shortDescription`	80	Yes
Google Play	`fullDescription`	4000	Yes
Google Play	`video`		No

Limits are in characters, counted the way the stores count them: a Cyrillic or Japanese letter is one. A field you leave out of a file is not managed, and "" clears it. See Spec files.

Target searches per storefront

Targets are the searches the app should be found for, per two-letter storefront code, in appeeky.spec.yaml:

targets:
  us: [sleep sounds, white noise, rain sounds, brown noise]
  de: [einschlafgeräusche, weißes rauschen]

An App Store storefront can read more than one listing locale. The US store also reads Spanish (Mexico), Canada reads French (Canada), Switzerland reads German, French and Italian. Spec knows the common ones; to set your own:

storefronts:
  us: [en-US, es-MX]

On Google Play, a storefront’s coverage is read from the one language that store most likely shows.

check

npx @appeeky/spec check

warn   App Store de-DE subtitle  Subtitle repeats "regen" from the name. Each word is indexed once, so use the space for a new word. (subtitle/repeats-name)
warn   App Store de-DE keywords  Spaces around commas waste characters in the keyword field. Write `a,b,c`. (keywords/spaces)
info   App Store en-US keywords  47 characters of the keyword field are unused. (keywords/unused-space)
error  Google Play en-US title  Google Play does not allow emoji in the title. (play/title-emoji)

Rule	Level	What it catches
`limit`	error	A field over the store’s limit; the store would reject it
`required`	error	An empty App Store name
`play/title-emoji`	error	Emoji in a Google Play title
`screenshots`	error	A screenshot with the wrong size, or more than 10 in a set (Screenshots)
`subtitle/repeats-name`	warning	Subtitle words already in the name
`keywords/spaces`	warning	Spaces around commas in the keyword field
`keywords/no-commas`	warning	A keyword field written as one long phrase
`keywords/duplicate`	warning	The same entry twice in the keyword field
`keywords/duplicate-of-name`	warning	Keyword words already in the name or subtitle
`play/title-policy`	warning	”best”, “top”, “free”, “#1”, “sale” or “discount” in a Google Play title
`play/title-caps`	warning	An all-caps Google Play title
`keywords/repeated-word`	info	One word written in several keyword entries
`keywords/filler`	info	”app”, “the”, “and”, “iphone” and similar (English locales)
`keywords/plural-pair`	info	Singular and plural of one word (English locales)
`keywords/unused-space`	info	10 or more characters of the keyword field unused
`listings/empty`	info	A store in the spec with no listing files yet

check exits 1 on errors. --strict exits 1 on warnings too. push stops on listing errors unless you pass --force.

coverage

npx @appeeky/spec coverage

App Store US (en-US, es-MX)  3/4 covered (75%, 83% by popularity)
  ✓ sleep sounds                 in title       pop  62 diff  48
  ✓ white noise                  name+subtitle  pop  58 diff  55
  ✓ rain sounds                  name+subtitle  pop  41 diff  37
  ~ brown noise                  partial        pop  33 diff  29  missing: brown

tip  US also indexes es-MX: add "brown" to its keyword field → dormir,relajarse,lluvia,ruido,brown

Mark	Level	Meaning
✓	`in title`	The exact phrase is in the App Store name or Google Play title
✓	`name+subtitle`	Every word is in the App Store name or subtitle
✓	`short desc`	Every word is in the Google Play title or short description
✓	`indexed`	Every word is in a searched field of one locale
~	`split locales`	Every word is indexed, but across locales; they may not combine
~	`partial`	Some words are indexed
✗	`missing`	No word is indexed

The tip lines use the spare keyword space in a second locale a storefront reads. --country us de limits the report.

Keyword popularity

pop and diff are search popularity and difficulty (0–100) from the Appeeky API. They need APPEEKY_API_KEY. Results are cached for 7 days in .appeeky/cache/; --no-metrics skips them.

Works without a key	Needs `APPEEKY_API_KEY`
`check`, `diff`, coverage levels, `suggest` from your targets	Popularity and difficulty in `coverage`, weighted coverage
App Store ranks for `push` and `verify` (Apple’s public search, top 200)	Keyword opportunities in `suggest`, Google Play ranks

suggest

Words to add to an App Store keyword field: the missing words of your targets first, then, with a key, popular searches the app does not rank for yet. Brand terms and words the locale already indexes are left out.

npx @appeeky/spec suggest --locale en-US --country us

+ brown               helps: brown noise
+ pink               pop 38  helps: pink noise
+ womb               pop 24  helps: womb sounds

Add with: appeeky-spec suggest --locale en-US --apply <words...>

+ means the word still fits in the 100 characters; · means it does not. Add words with --apply:

npx @appeeky/spec suggest --locale en-US --apply brown pink
# Updated en-US keywords → insomnia,relax,meditation,storm,thunder,baby,nap,calm,brown,pink

diff

npx @appeeky/spec diff

App Store: version 2.5.0 (prepare for submission) via local appstore CLI
App Store en-US
  keywords
    - insomnia,relax,meditation,storm,thunder,baby,nap,calm
    + insomnia,relax,meditation,storm,thunder,baby,nap,calm,brown,pink
Google Play: com.example.sleep (live listing) via local gps CLI
In sync with the store.

diff compares only the fields your files list. Trailing spaces and line endings do not count. A change that cannot go live yet shows blocked: and the reason; see Connect the stores. When the diff looks right, push it. Next: Push, measure and revert · Screenshots · Commands

Get started

Your listing

Know your market

Grow

Automate

Reference

The listing files

Target searches per storefront

check

coverage

Keyword popularity

suggest

diff

​The listing files

​Target searches per storefront

​check

​coverage

​Keyword popularity

​suggest

​diff

The listing files

Target searches per storefront

check

coverage

Keyword popularity

suggest

diff