CLI reference

Thirteen commands, one binary. The data commands are the CLI face of the same MCP tools — same engine, same provenance rules, same exit codes; init and doctor are CLI-only setup helpers.

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); --print <target> prints an onboarding snippet — json, claude, cursor, vscode, mcpb, registry, claude-plugin
`lumen config show`	print the resolved config — budgets, providers, thresholds, defaults included
`lumen init`	write a defaults lumen.config.json (BYOK env-var names, never values) and print next steps; --force overwrites
`lumen doctor`	setup report: node vs engines, config validity, per-provider BYOK status; --online probes ready providers once each
`lumen diff <a.json> <b.json>`	compare two saved audit reports — new/existing/fixed findings plus the score delta; exit 1 when the newer report has new findings
`lumen performance <site>`	Google Search Console clicks/impressions/position rows (first-party) — set LUMEN_GSC_CREDENTIALS to a service-account JSON path; --days N, --by query\|page
`lumen indexnow submit <urls…>`	submit URLs to IndexNow — dry run by default, --yes to send; the key file is verified at /<key>.txt on every host first; --from-sitemap to submit a sitemap's URLs
`lumen history audit\|rank`	local history trends: --domain, --since ISO, --limit (applied after --since), --format json\|csv; lumen history prune trims rotated generations (history.maxGenerations)

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
`--allow-private`	audit/report on a LOCAL target: loopback only (localhost, 127.0.0.0/8, ::1), scoped to the seed origin — redirects or links to any other private host are still refused; non-loopback ranges must be listed in crawl.allowPrivateHosts
`--canonical-origin <url>`	with --allow-private: the production origin a preview represents — scheme-context rules (insecure-http) evaluate against it instead of flooding on the preview
`--baseline <file>`	gate the audit only on findings NOT in the baseline (fingerprint = rule + normalized URL + selector; message tweaks never un-baseline); pages not audited this run are unknown, never "fixed"
`--update-baseline <file>`	write this run's fingerprints to a sorted, versioned baseline file and exit 0 — the adopt flow for a site with existing findings
`--verbose`	list every affected URL per rule group instead of 3 samples
`--format F`	audit output renderer: human (default) \| json \| sarif 2.1.0 \| md job summary (--json is an alias for json); with --out, sarif/md write the rendered artifact and stdout stays silent
`--source-map <glob>`	with --format sarif: best-effort page-URL → source-file mapping for annotations; an ambiguous match stays URL-only, never guessed
`--only <list>`	run only the comma-separated categories or rule ids (e.g. ai-search); an unknown token is a config error listing every valid one
`--with-gsc`	annotate audit rule groups with GSC clicks/impressions (28 days) when LUMEN_GSC_CREDENTIALS is set; findings never depend on it
`--days N`	lumen performance lookback window (default 28 days)

Exit codes

Stable across commands — designed to be wired straight into 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

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 audit http://localhost:4321 --allow-private --canonical-origin https://example.com

    
      $ 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