Connect the stores

Appeeky Spec reads your live listing from App Store Connect and Google Play and pushes your changes back. This page shows how to give it access, how to handle several apps or teams, and which changes go live right away and which wait for a new App Store version.

Two ways in

Each store is reached one of two ways. You pick per store with via in appeeky.spec.yaml, or for one run with --via.

`via`	How	Needs
`local`	The App Store Connect CLI (`appstore`) and Google Play CLI (`gps`) run on your machine with your own keys. Without them installed, Spec runs them through `npx`	An App Store Connect API key and a Google Play service account, saved with the CLIs
`hosted`	Appeeky’s store gateways make the calls. Your store keys stay in Appeeky	`APPEEKY_API_KEY` and the store connected in Settings → Data sources on appeeky.com
`auto` (default)	The local CLI when it is installed, the hosted gateway when `APPEEKY_API_KEY` is set, `npx` otherwise

With your own keys, no Appeeky account is needed for pulling, diffing and pushing.

Create an App Store Connect key

In App Store Connect, open Users and Access → Integrations → App Store Connect API.
Create a key with the App Manager role. That role can push listing changes.
Note the Key ID and the Issuer ID, and download the AuthKey_<KEYID>.p8 file.

A key made under your own user profile (an individual key) has no Issuer ID; leave it out. More detail: App Store Connect CLI install.

Create a Google Play service account

In Google Cloud, create a service account and enable the Google Play Android Developer API on its project.
Download a JSON key for it. Keep it outside your repo.
In Play Console → Users and permissions, invite the service account’s email and give it access to the app’s store listing.

More detail: Google Play CLI install.

Save the keys

The guided init checks each store. When one cannot be reached, it asks:

3/6 Store access and your live listing
  ✗ App Store            No store key saved, no appstore CLI and no APPEEKY_API_KEY
    Save your App Store Connect API key once with the App Store Connect CLI: ...
Save your own App Store key on this machine now? [Y/n]
  App Store Connect → Users and Access → Integrations → App Store Connect API. Role App Manager to push.
  Key ID: ABC123DEFG
  Issuer ID (Enter for an individual key):
  Path to the AuthKey_….p8 file: ~/Downloads/AuthKey_ABC123DEFG.p8
  ✓ saved as "sleep-sounds" in the appstore CLI's config (not in this repo)

For Google Play it asks for the path to the JSON key. The account is named after the app (sleep-sounds), linked to this app and made the default. To save keys by hand:

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

The keys live in the CLIs’ config on your machine (~/.config/appstore/, ~/.config/gps/), never in the repo.

Several apps or teams

Keep one appeeky.spec.yaml per app, each in its own repo or folder. Run a command for another folder with --cwd <dir>. When your apps belong to different teams or clients, save one named account per team and pick it in each app’s spec:

stores:
  appStore:
    appId: "1234567890"
    account: my-team        # appstore accounts add my-team ...
  googlePlay:
    packageName: com.example.sleep
    account: my-co          # gps accounts add my-co ...

Without account, the CLI’s default account is used. Each accounts add ... --default makes that account the new default, so set account once you have more than one. For a Mac, Apple TV or Vision Pro app, set stores.appStore.platform to MAC_OS, TV_OS or VISION_OS (default IOS).

In CI and on a server

There are no saved accounts on a CI runner. Pass the keys as environment variables instead:

Variable	Store
`ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_PRIVATE_KEY` (the PEM text) or `ASC_PRIVATE_KEY_PATH`	App Store
`GOOGLE_APPLICATION_CREDENTIALS` (path to the JSON key), or `GPS_CREDENTIALS` (the JSON itself)	Google Play

Or set only APPEEKY_API_KEY and use your Appeeky connection. See GitHub Actions & CI and Self-hosting.

What can change when

Store	Changes on the live listing	Needs a new app version
App Store	Promotional text	Name, subtitle, keywords, description, what’s new, marketing and support URLs
Google Play	Title, short description, full description, video	Nothing

App Store. Spec edits the version you are preparing (prepare for submission, or rejected) when there is one. Otherwise it edits the live version, where only promotional text can change. diff and pull show which version they read:

App Store: version 2.5.0 (prepare for submission) via local appstore CLI

Changes pushed to a version you are preparing go live when that version is approved and released. While one is in preparation, promotional text goes to it too, not to the live version. To open the next version, create it in App Store Connect, or let push do it:

npx @appeeky/spec push --create-version 2.5.0 --note "Lead with white noise in the US"

Google Play. Listing changes go live without an app update, one language at a time. New languages. A new App Store locale needs a name in its file. A new Google Play language needs title, shortDescription and fullDescription. Locales that exist only in the store are never touched. diff and push mark changes that cannot go live yet as blocked, with the reason. push sends the rest. See Troubleshooting for each reason.

Check the setup

npx @appeeky/spec doctor

  ✓ node                 Node 20.11.1
  ✓ spec                 appeeky.spec.yaml · Sleep Sounds
  ✓ App Store            your own key: appstore CLI, saved account sleep-sounds
  ✓ App Store listing    2 locales in appeeky/store/app-store/
  ✗ Google Play          No store key saved, no gps CLI and no APPEEKY_API_KEY
    Save your Google Play service account once with the Google Play CLI: ...
  ! Google Play listing  Not pulled yet
    Run `npx @appeeky/spec pull --store google-play`.
  ...

1 to fix · 6 optional

For each store, doctor says how it will be reached: your own key (from saved accounts or environment variables, through the installed CLI or npx) or your Appeeky connection. It also shows whether each store’s listing has been pulled. A ✗ must be fixed; ! is optional. It exits 1 while anything is ✗. Next: Write and check your listing · On your own keys · Troubleshooting

Get started

Your listing

Know your market

Grow

Automate

Reference

Two ways in

Create an App Store Connect key

Create a Google Play service account

Save the keys

Several apps or teams

In CI and on a server

What can change when

Check the setup

​Two ways in

​Create an App Store Connect key

​Create a Google Play service account

​Save the keys

​Several apps or teams

​In CI and on a server

​What can change when

​Check the setup

Two ways in

Create an App Store Connect key

Create a Google Play service account

Save the keys

Several apps or teams

In CI and on a server

What can change when

Check the setup