Quickstart

lumen is one npm package and a config file you mostly don’t need. Ten minutes from zero to a CI gate that fails when your site regresses.

Install

Install globally, or skip installation entirely with npx — @lumen-seo/cli is the only package you need:


      $ npm install -g @lumen-seo/cli

    
      # or, no install:

    
      $ npx -y @lumen-seo/cli audit https://example.com

First run

Optional but handy: lumen init writes a starter lumen.config.json (defaults plus your key env-var names — values stay in your environment) and prints the next steps, including the MCP install line. Then lumen doctor checks node, the config file, and which providers are ready — --online sends one probe per ready provider. Both are covered in the CLI reference.

First audit

Point lumen audit at a site you control. The crawler is bounded (100 pages by default) and polite (robots.txt respected, rate-limited per host, identifying User-Agent):


      $ lumen audit https://example.com --max-pages 50

    
      crawling · robots ok · 3 sitemap hints

    
      42 pages · 6 issues (2 error, 4 warning) · score 84/100

    
      exit code 1 — issues at or above failThreshold (error)

Add --out report.json to keep the full report — every issue carries a rule id, evidence, and a fix hint. The 36 rules are documented in the rules reference.

Adopting on a noisy site

Got 400 existing warnings? Record them once and gate only on regressions: lumen audit $SITE --update-baseline baseline.json (exits 0), then in CI lumen audit $SITE --baseline baseline.json. A finding is "new" only if its fingerprint (rule + normalized URL + selector — message tweaks never count) is absent from the baseline. Note the threshold still applies to new findings: a new warning does not fail a run whose failThreshold is error. Pages not audited in a run are unknown, never counted as fixed. Compare two saved reports any time with lumen diff a.json b.json.

Exit codes

Exit codes are a contract, made for CI:

Code	Meaning
`0`	ok — no issues at or above failThreshold
`1`	audit gate failed (issues at/above failThreshold, or new findings with --baseline) or diff found new findings
`2`	config or provider error

The threshold is failThreshold in lumen.config.json (error by default; see configuration).

JSON output

Every command takes --json. In CI, that plus the exit code is usually all you need:


      $ lumen audit "$SITE_URL" --json --out report.json

    
      exit 0 ok · exit 1 threshold breached · exit 2 config error

Local history

lumen rank appends each check to a JSONL history file under .lumen/ in the current directory — rank movement over time without any server. It stays on your machine unless a provider needs the query (each provider’s what-leaves-your-machine line says exactly when that is).