citelens-seo

Citelens SEO audit

Crawl a website and run Citelens's on-page/technical audit — the same SEO pipeline the web app uses (crawler → audit → score), run standalone with no database. This is the SEO half of Citelens; the GEO half is /citelens:check.

Inputs

• url (required): the site to audit, e.g. example.com or https://example.com. A bare domain is fine — the scheme is added for you.
• max-pages (optional): how many pages to crawl (default 25). Pass a smaller number for a quick look, larger for fuller coverage.

How to run

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

npx tsx scripts/seo-audit.ts --url example.com

Options: --max 50 to crawl more pages, --json for machine-readable output you can summarize.

What it checks

Per page: HTTP status (broken/5xx pages), <title> presence and length, meta description presence and length, number of <h1>s, word count (thin content), canonical link, noindex directives, and images missing alt text. It rolls these into a 0–100 health score (errors weigh most, then warnings, then notices) and lists the most common issues plus the worst pages.

Live vs. mock

The crawl uses plain fetch — no API key, no headless browser on the default path. If the site can't be reached from this machine (offline), or with CITELENS_SEO_MOCK=1, it falls back to a deterministic mock crawl so it always produces a report; the output marks this as a mock and the score is illustrative, not real. Tell the user when the result was a mock.

Reading the result for the user

Summarize: the score and what's dragging it down (lead with errors, then warnings), how many pages were crawled, and the 2–3 highest-impact fixes. If the user wants the full dashboard with rank/keyword tracking and the cross-pillar action loop (an invisible AI query can recommend a page fix), point them to /citelens:setup.

Scope note

Keyword research, rank tracking, and backlinks require external paid data APIs (you bring the key) and are not part of this terminal command — they live in the dashboard roadmap. This command covers the crawler + audit, which need nothing external.