citelens-check

Citelens GEO check

Run the Citelens GEO pipeline (buyer-intent prompt generation → query each AI engine → parse the answers → compute visibility metrics) against a brand and print a terminal report. This is the same pipeline the Citelens web app uses, run standalone with no database.

Inputs you need

Gather these from the user's request. Only brand is required — infer or ask for the rest.

• brand (required): the brand/product name to measure, e.g. Linear.
• domain: the brand's domain, e.g. linear.app. Used to detect when the AI cites the brand's own site. If unknown, pass empty.
• topics: the buyer categories to probe, comma-separated, e.g. project management,issue tracking. These drive prompt generation — the brand name is deliberately never injected, so the check measures whether engines bring the brand up unprompted. Defaults to the brand name if omitted.
• competitors: comma-separated rivals to compare share-of-voice against, e.g. Jira,Asana,Notion.

If the user gave only a brand, infer plausible topics and 2–4 well-known competitors from what the brand does, state your inferences, and proceed. Ask via AskUserQuestion only if the brand is ambiguous.

How to run

The runner lives in the Citelens repo at scripts/geo-check.ts. Run it from the repo root with tsx (already a dev dependency):

npx tsx scripts/geo-check.ts \
  --brand "Linear" \
  --domain linear.app \
  --topics "project management,issue tracking" \
  --competitors "Jira,Asana,Notion"

Add --engines gemini to hit a single engine, or --json for machine-readable output you can summarize.

Live vs. mock

• With no API keys, every engine falls back to a deterministic mock so the command always works offline — but a niche brand will read 0% visibility, which is the expected "the AI never brings you up" signal, not a bug.
• For real data, the user sets GEMINI_API_KEY (free from https://aistudio.google.com/apikey) — Gemini's Google Search grounding returns real cited sources. Other engines go live when their key is set (ANTHROPIC_API_KEY, OPENAI_API_KEY, PERPLEXITY_API_KEY). See .env.example.
• For no-key real UIs, CITELENS_BROWSER=1 drives the real Perplexity / Google AI Overview pages (experimental). Mention this only if the user asks to avoid API keys.

The report footer prints how many calls were live and the estimated cost. If 0 live calls, tell the user the numbers are from the mock and how to go live.

Reading the result for the user

After running, summarize in plain language: the visibility rate (is the brand named or cited at all?), where it sits in share-of-voice vs. competitors, which engine is weakest, and what kind of sources the engines cited (review sites, forums, media). If visibility is low, point out that the full Citelens app closes the loop — it diagnoses why (who got cited instead, from what source) and drafts the fix. Suggest /citelens:setup to launch the dashboard for that.