CLI reference

Seven commands, one binary. Every command is the CLI face of an MCP tool — same engine, same provenance rules, same exit codes.

Commands

Command	What it does
`lumen audit <url>`	crawl a site (bounded, robots-safe) and print the audit report; use --max-pages to bound, --out to save
`lumen report <url>`	single-page report: PSI + CrUX when BYOK keys are configured, plus a local meta fetch
`lumen keywords <seed>`	keyword ideas for a seed term, with source labels; no fake volumes
`lumen rank <keyword> --domain <domain>`	best-effort SERP position check; appends to local history in .lumen/
`lumen authority <domain>`	domain authority signals (Open PageRank, Tranco) as labeled signals
`lumen mcp`	run the MCP server over stdio (for agents and IDEs)
`lumen config show`	print the resolved config — budgets, providers, thresholds, defaults included

Flags

Flag	Meaning
`--max-pages N`	page budget for a crawl (default 100, hard ceiling 10,000)
`--out <file>`	write the full report JSON to a file
`--json`	machine-readable output on stdout (every command)
`--domain <domain>`	target domain for lumen rank

Exit codes

Stable across commands — designed to be wired straight into CI:

Code	Meaning
`0`	ok — no issues at or above failThreshold
`1`	issues at or above failThreshold
`2`	config or provider error

Which severities count as “failure” is failThreshold in lumen.config.json (error by default; can be warning, info, or off).

Examples


      $ lumen audit https://example.com --max-pages 200 --out report.json

    
      $ lumen keywords "broadfork" --json | jq '.[0:5]'

    
      $ lumen rank "garden tools" --domain example.com

    
      position 14 (ddg-serp · gray, best-effort) — appended to .lumen/history.jsonl