# Citelens SEO

> Run a technical + on-page SEO audit on a website from the terminal — crawl the site and report broken pages, missing or oversized titles and meta descriptions, missing H1s, thin content, missing canonicals, and images without alt text, plus a 0–100 health score. Use when the user says "run an SEO audit", "crawl my site", "check <domain> for SEO issues", "what's wrong with my site's SEO", or "citelens seo".

- Skill: `manavarya09/citelens-seo` (Agent Skill)
- Install (CLI): `npx skillmds@latest add manavarya09/citelens-seo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/manavarya09/citelens-seo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: manavarya09 (https://skillmd.com/u/manavarya09)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/manavarya09/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):

```bash
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.