> ## 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. # Push, measure and revert > How a push is recorded, how verify decides whether a listing change won or lost, and how to roll it back. Every listing push is an experiment. Appeeky Spec records what changed and the search ranks from right before it, checks again on day 7 and day 14, and writes the verdict next to the change. ## What push does 1. Runs `check`. Errors stop the push unless you pass `--force`. 2. Diffs the spec with the live store and shows the changes. Blocked changes (App Store fields that need a new version) are listed with the reason. 3. Asks for confirmation (skip with `--yes`). 4. Records the current rank of every target in `appeeky.spec.yaml` for each storefront (skip with `--no-baseline`). 5. Pushes the changes. 6. Writes `appeeky/releases/.yaml` with the before and after values, your `--note` and the rank baseline. Write the hypothesis in `--note`. It ends up in the release file, in `log --markdown` and in the playbook. ## Where ranks come from | Source | Stores | When | | - | - | - | | Appeeky API | App Store, Google Play | `APPEEKY_API_KEY` is set | | Apple's public search | App Store | Fallback without a key; top 200 results | A target the app does not rank for is recorded as unranked. ## How verify decides `verify` compares each storefront's ranks with the baseline. A move counts when it is at least 3 places. | Verdict | When | | - | - | | `lost` | One target that was in the top 10, or two targets that were in the top 20, fell out of the top 20 by 10 or more places (or stopped ranking) | | `won` | More targets rose than fell | | `mixed` | Some rose, as many or more fell | | `flat` | Nothing moved 3 or more places | `lost` uses the same rule the Appeeky co-founder uses to propose reverting a metadata change. ### Control group Storefronts whose listing the release did not change are measured over the same days. A push to en-US changes the US store; the German store reads de-DE and did not change, but its ranks still move with the store's algorithm, the season and competitors. When the changed storefronts gained less than 2 places per target beyond the unchanged ones, a `won` becomes `mixed`: the store moved, not the listing. The check records both moves and the net under `control`. Add targets in a second storefront so there is a control group. ### Normal moves Before comparing conversion, installs or revenue, `verify` reads the four windows before the push and learns how much each metric moves on its own. A change inside that range is `flat`, and the output says so: `downloads/day 100 → 120 (+20%) (moves ±41% on its own)`. ### When no target moved When no target moved, or the release has no targets, the outcomes decide: organic installs and their revenue with `attribution:`, otherwise store conversion, otherwise downloads, otherwise the category rank from `appeeky/category.csv`. Better is `won`, worse is `lost`, and the check records what decided it as `decidedBy`. Run it on a schedule. It only measures releases that reached day 7 or day 14 and have not been measured for that day yet: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec verify --playbook ``` `--now` measures every release right away, whatever its age. ### Conversion, downloads and revenue Ranks say whether more people find the app. `verify` also checks whether more of them install and pay. It compares the same number of days before and after the push (up to 14, leaving out the day of the push) for every source you have: | Metric | From | | - | - | | Conversion (downloads ÷ product page views), page views, downloads, proceeds, trials | App Store Connect or Google Play (`APPEEKY_API_KEY`) | | Revenue, trials, trial conversion | RevenueCat (`APPEEKY_API_KEY`) | | Ad installs, cost per install | Apple Search Ads (Appeeky, or `appeeky/search-ads/` on your own key) | | Spend, installs and cost per result | Meta and TikTok campaigns under `ads:` (`APPEEKY_API_KEY`) | | Organic installs, their revenue, the share that paid | `attribution:` (Appeeky Analytics) | | Average rating, share of 1–2 star reviews | `appeeky/reviews/` | | `ai_visibility` | `appeeky/visibility/` | | `search_clicks`, `search_impressions`, `web_rank`, `ai_overview_citations` | `appeeky/seo/` ([Website and Google search](https://docs.appeeky.com/docs/spec-website.md)) | | `category_rank` | `appeeky/category.csv` | Each metric is marked `better`, `worse` or `flat` (within 5%, or within the metric's normal moves); for cost per install, lower is better. Conversion is left out when a window has fewer than 50 page views. RevenueCat numbers are used only when the RevenueCat project holds just this app. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} 2026-11-02T09-14-00Z-app-store day 7: won 3 up · 0 down · 0 top-20 lost up US "rain sounds" 38 → 21 better conversion 3.1% → 3.6% (+16%) better revenue/day $41.20 → $47.90 (+16%) flat cost per ad install $0.79 → $0.81 (+3%) ``` The numbers go into the release file under `checks[].metrics` and, with `--playbook`, into the playbook line. ## Revert ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec revert 2026-11-02T09-14-00Z-app-store npx @appeeky/spec diff npx @appeeky/spec push --note "Revert: lost 'white noise' (12 → 38)" ``` `revert` only edits the spec files; nothing goes live until you push. A field that was empty before the release is cleared. ## The playbook `verify --playbook` adds one line per result to `appeeky/playbook.md`: ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}} - 2026-11-02, app-store, en-US keywords: Add brown noise → day 7 won ("brown noise" 48→21) - 2026-10-12, app-store, en-US subtitle: Lead with white noise → day 14 lost (lost "sleep sounds" 6→31) ``` Over time this is the record of what works for your app. Read it before planning the next change; agents using the [Appeeky Spec skill](https://docs.appeeky.com/docs/spec-agents.md) read it first. ## Sharing results ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec log --markdown -n 1 ``` prints the last release as a Markdown table with its note and latest verdict, ready for a PR description, changelog or team update. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.