appeeky spec
← Learn

Growth · 8 min read

AI answers and Google search, on your own keys

Find out whether ChatGPT, Claude, Gemini and Perplexity name your app, where your site ranks on Google, and fix the website crawlers read. On your own keys.

People ask ChatGPT for an app, and they search Google and land on its website. The spec records both next to the listing. It runs on your own model keys and your own Search Console, and nothing needs an Appeeky account.

Two more ways to be found

A store search is one way in. An assistant answering “what app helps me sleep” is another, and it names three or four apps, not a page of results. The website is the third: it ranks in Google, and it is one of the pages the assistants read and cite.

The spec keeps all three as files. That way your agent reads them before it proposes a change, and verify measures them after each release.

Your keys, your bill

  • ChatGPTOPENAI_API_KEYgpt-4.1 with web search
  • ClaudeANTHROPIC_API_KEYClaude Haiku with web search
  • GeminiGEMINI_API_KEYGemini 2.5 Flash with Google Search
  • PerplexityPERPLEXITY_API_KEYSonar, which always searches
  • Search ConsoleGSC_CREDENTIALSa service account key, or your gcloud login
  • Google ranksDATAFORSEO_LOGINwith DATAFORSEO_PASSWORD, your DataForSEO account

Any of them. Each model key adds that assistant to the scan, and that provider bills you directly. With an Appeeky plan, Appeeky AI Visibility can run the scans for you instead and write the same file. Pick one per repo.

What people ask

An intent is what someone wants. Its prompts are how they would ask an assistant. Both live in the spec. To start, have your model write them from the listing:

zsh
$ npx @appeeky/spec visibility init --local
✓ US: wrote 6 intents to aiVisibility.intents in appeeky.spec.yaml
gpt-4.1-mini on your key, about $0.004. Edit them, then: appeeky-spec visibility scan --local --dry-run
appeeky.spec.yaml
# appeeky.spec.yaml
web:
url: https://sleepsounds.app/
aiVisibility:
countries: [us]
models: [chatgpt, claude, gemini, perplexity] # optional: the ones with a key
aliases: [Sleep Sounds] # other names the assistants use
intents:
us:
- label: Fall asleep to rain sounds
prompts:
- what app plays rain sounds to help me fall asleep
- best free rain sounds app for iphone

Edit them like any other part of the spec. A prompt sounds like a person typing. It never contains the app's own name, and it uses the storefront's language.

Ask the assistants

zsh
$ npx @appeeky/spec visibility scan --local --dry-run
US 6 intents · 24 prompts × chatgpt, claude, gemini, perplexity · about $2.45
About $2.45 on your own keys in all. Nothing was asked.

Without --dry-run, it asks after you confirm. Each prompt goes to each assistant with web search on, the way the apps answer people. A second, cheap call then lists the apps each answer names, in order. A provider that fails is reported, and the rest of the scan goes on.

Read the answers

appeeky/visibility/us.yaml
# appeeky/visibility/us.yaml
source: local
summary: { winning: 2, weak: 1, missing: 3, noData: 0 }
intents:
- label: Fall asleep to rain sounds
status: missing
you: 0
byModel: { chatgpt: 0, claude: 0, gemini: 0, perplexity: 0 }
namedInstead: [Calm (75%), BetterSleep (50%), Rain Rain (25%)]
sources:
- { domain: reddit.com, count: 6, url: https://www.reddit.com/r/sleep/… }
- { domain: sleepsounds.app, count: 2, yours: true, url: https://sleepsounds.app/rain }
▾ appeeky/visibility
us.yaml# each intent: named or not, per assistant, who instead, cited pages
changes.md# intents that started or stopped naming the app
history.csv# one row per scan, intent and assistant
▾ answers# every answer, to read why someone else was named
us.jsonl

missing means no assistant names the app for that intent. namedInstead is who they name. sources lists the pages they read, and yours: true marks your own site. Assistants repeat what the web says. If they cite review sites and Reddit threads that name your competitors, those pages and your own website are what to work on, along with the listing's first lines.

The site, as a crawler sees it

zsh
$ npx @appeeky/spec seo check
Search
✓ Title: “Sleep Sounds: rain and white noise” (34 characters)
! No canonical link
The app
! No Smart App Banner
AI assistants
✗ robots.txt blocks GPTBot, ClaudeBot
! No llms.txt
! 86 words readable without JavaScript
12 of 18 fine.

It needs no key. It reads the page, robots.txt, the sitemap and llms.txt, and every finding comes with its fix. The AI part matters most: most AI crawlers do not run JavaScript. A blocked crawler, or a page that only renders in the browser, leaves the assistants with nothing to cite.

zsh
$ npx @appeeky/spec seo llms --out public/llms.txt
✓ public/llms.txt

llms.txt is written from the listing: what the app is, where to get it, the searches it is for, and its description. Run it in your website's repo, or have your agent propose it there.

Google ranks on DataForSEO

Search Console shows the searches you already appear for. To see the searches you want to win, use your own DataForSEO account. It checks Google for each keyword in web.keywords (or your store targets), the way a phone sees the results.

zsh
$ npx @appeeky/spec seo ranks
6 keywords in US · about $0.12 on DataForSEO
✓ appeeky/seo/ranks.md 3 of 6 in the top 10 · AI Overview cites you 2×
US rain sounds site 6 store page 2 AI cites you
US white noise app site 14 store page — AI cites calm.com, reddit.com

Each keyword gets three answers. Where your site ranks. Where your App Store or Google Play page ranks on Google, which is often higher than the site. Whether Google's AI Overview shows, and if it cites you. A keyword that enters or leaves the top 10 goes to changes.md.

seo keywords adds search volume, difficulty and related ideas. seo domain shows everything the site ranks for and which sites compete for the same searches. Every command quotes first with --dry-run. The daily routine checks ranks once a week when the account is set.

Measured with every release

zsh
$ npx @appeeky/spec verify
2026-11-03 day 14: won 3 up · 0 down
better AI answers that name the app 0.18 → 0.31
better Google search clicks/day 38 → 46
better average Google position of the site 18.4 → 11.2

verify reads ai_visibility from history.csv, and search_clicks and search_impressions from daily.csv, and web_rank and ai_overview_citations from ranks.csv. Assistants change their answers slowly and Search Console lags two days, so read both on day 14. The verdict goes into the playbook with the ranks, and the next proposal starts from it.