> ## 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.

# Appeeky Spec quickstart

> Pull your live listings into files, check them, find keyword gaps and push your first measured change.

## 1. Run init

In your app's repo (or any folder), with Node 20 or later:

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

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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec init \
  --name "Sleep Sounds" \
  --app-store 1234567890 \
  --google-play com.example.sleep \
  --pull --ci
```

This writes `appeeky.spec.yaml` and pulls every live locale into `appeeky/store/`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
appeeky.spec.yaml
appeeky/
  store/
    app-store/en-US.yaml
    app-store/de-DE.yaml
    google-play/en-US.yaml
```

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:

> [tab] Your own keys (local)
>
> 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.
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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
> npx -p @appeeky/google-play-store-cli gps accounts add my-co \
>   --credentials ~/play-service-account.json --default-package com.example.sleep --default
> ```
>
> 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](https://docs.appeeky.com/docs/store-cli-app-store-connect-install.md) and [Google Play CLI install](https://docs.appeeky.com/docs/store-cli-google-play-install.md).

> [tab] Your Appeeky connection (hosted)
>
> Connect the store in **Settings → Data sources** on appeeky.com, then set your [API key](https://docs.appeeky.com/docs/authentication.md):
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> export APPEEKY_API_KEY=ak_...
> ```
>
> Store keys stay in Appeeky. Each store call counts as one Appeeky API call.

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:

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

## 3. Say what the app should be found for

`init` suggests targets. Edit them in `appeeky.spec.yaml`, per storefront:

```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]
```

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec check      # limits, ASO rules, screenshot sizes
npx @appeeky/spec coverage   # which targets each storefront indexes
npx @appeeky/spec suggest    # words worth adding to the keyword field
```

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec diff
npx @appeeky/spec push --note "Add brown noise to the US keyword field"
```

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec push --create-version 2.5.0 --note "..."
```

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](https://docs.appeeky.com/docs/spec-ci.md).

## 6. Measure

A week later:

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

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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @appeeky/spec revert <release-id>
npx @appeeky/spec push --note "Revert: lost 'white noise'"
```

See [Push, measure and revert](https://docs.appeeky.com/docs/spec-releases.md) for how the verdict is decided.

## Next

* [Put it in pull requests](https://docs.appeeky.com/docs/spec-ci.md) so every listing change gets a coverage report.
* [Let a coding agent drive it](https://docs.appeeky.com/docs/spec-agents.md), or run the [weekly co-founder review](https://docs.appeeky.com/docs/spec-growth-team.md).
* [Use your own keys](https://docs.appeeky.com/docs/spec-own-keys.md) for AI visibility, Search Console, Search Ads and UGC.


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