lumen

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 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 18 rules are documented in the rules reference.

Exit codes

Exit codes are a contract, made for CI:

CodeMeaning
0ok — no issues at or above failThreshold
1issues at or above failThreshold
2config 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).

Next