> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Write and check your listing

> Edit your listing as files, check it against store limits and ASO rules, see which target searches each storefront covers, and find words worth adding.

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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.appeeky.com/docs/spec-files.md#listing-files).

## Target searches per storefront

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

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec check
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.appeeky.com/docs/spec-screenshots.md)) |
| `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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec coverage
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec suggest --locale en-US --country us
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
+ 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`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec diff
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.appeeky.com/docs/spec-stores.md#what-can-change-when). When the diff looks right, [push it](https://docs.appeeky.com/docs/spec-releases.md).

Next: [Push, measure and revert](https://docs.appeeky.com/docs/spec-releases.md) · [Screenshots](https://docs.appeeky.com/docs/spec-screenshots.md) · [Commands](https://docs.appeeky.com/docs/spec-commands.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.