CLI reference

Use command-line options to choose what to scan, where to save reports, and when a run should fail a score threshold. Start with the basic command below. Look up an option only when you need it.

@forkpoint/agent-lighthouse scans a website, prints a summary and writes HTML, JSON or Markdown reports.

Read what your score means before comparing results. Saved settings and SDK options are in the configuration guide.

Install

npx @forkpoint/agent-lighthouse https://example.com    # one-off scan, no install
npm i -g @forkpoint/agent-lighthouse                    # global
pnpm add -D @forkpoint/agent-lighthouse                 # project dev dependency, for CI

The installed binary is agent-lighthouse. Node.js 22.22.2+, 24.15.0+ or 26+ is required.

Invocation

agent-lighthouse <url> [options]
agent-lighthouse audit <url> [options]
agent-lighthouse --registry [--json]
agent-lighthouse --help

--registry prints what the installed version checks: the core version, the number of audits and categories, the count per tier, the registry mass, and the same per category. It runs no scan. Add --json for the getRegistrySummary() object.

• The first two forms are the same scan.
• Flags may come before or after the URL: agent-lighthouse --timeout 30 https://example.com works.
• The URL must be absolute, with its scheme (https://example.com, not example.com). Anything else exits 1.
• -h or --help anywhere prints usage and exits 0. So does running the command with no arguments.
• The URL may come from a config file instead. agent-lighthouse audit with no URL, or a command made only of flags such as agent-lighthouse --silent, reads it. If neither the command nor the file names a URL, the CLI prints usage and exits 1.
• agent-lighthouse serve — run the task server. See server.md. Flags: --port (default 8787), --host (default 127.0.0.1), --token (or AL_SERVER_TOKEN), --allow-origin (repeatable).

Flags that take a value accept --flag value and --flag=value. In the space form the value must not start with -, or it is read as the next flag.

Flags

Precedence is flag, then config file, then default.

-c, --config <path>

Without the flag the CLI uses the first of agent-lighthouse.config.json, .agent-lighthouserc.json and .agent-lighthouserc in the working directory. With the flag, a missing or invalid file is a fatal error. Keys are in config.md.

--categories <list>

agent-lighthouse https://example.com --categories structured-data,agentic-commerce

Only the named categories run and count. The ids are access-crawl-control, content-extraction, machine-discovery, structured-data, answer-readiness, agent-interfaces, agentic-commerce and operability-safety, described in config.md. An unknown id exits 1 and prints the valid list.

--page-type <type>

agent-lighthouse https://example.com/product/widget --page-type product

Types: homepage, category, product, article (editorial: posts, news, guides) and general (any other page: about, FAQ, help, contact, policy).

• A declared type lets type-specific checks count toward the score. A detected type keeps them advisory.
• The flag overrides the config pageType. Config pages declares more URLs.
• A bare flag or an unknown type exits 1. The pre-v7 names unknown and content are refused with a hint to use general.
• Mixed scans keep declared and detected findings apart. Each audit counts once. --debug-audit <id> shows each population’s selected, input and unread URLs.

Detection reads a path of / as homepage. A subpath such as /shop/ or /en-us/ is a homepage only when the page’s own links say so: its site header’s first same-origin link points back at that path, or every same-origin link stays under it across at least three paths. A detected or declared subpath homepage looks for sitemaps under that subpath first. Declare --page-type when detection is wrong.

--experimental

Experimental audits are excluded by default. They carry weight 0, so this flag never changes a score; it only adds results. The evidence policy says what puts an audit in that tier.

-o, --output and -d, --output-dir

markdown is accepted for md. terminal prints to stdout; the others write files into the output directory:

Repeat runs overwrite them. --view opens nothing when html is not in the list.

--timeout <seconds>

When the budget runs out, requests in flight abort and no new ones start. Every audit not finished is reported na with the tag skipped:scan-budget, and the report records it under conditions.budget. If the cut, together with what the evidence gate removed, leaves more than 35% of the registry’s evidence mass unassessed, the scan reports no score. The config key is timeout.

A site that answers HTTP 429, a 403 to the scanner, or two 503s in a row makes the scanner stop sending it requests. The report records that under conditions.requestStop: the reason, how many audit requests were not sent, and how many audits and how much scored mass they touched. Each affected audit lists the URLs under coverage.unsentUrls. The stop does not change the score.

--min-score <number> and --assert-category <id:min>

agent-lighthouse https://example.com --min-score 80 \
  --assert-category structured-data:90 --assert-category access-crawl-control:75

• Reports are written before assertions run, so they survive a failure.
• A scan with no score fails --min-score.
• A category id matches the id first, then the display name, case-insensitively.
• A threshold naming a category that did not run is ignored.
• A category that ran but reached no scored verdict fails as “not assessed”.
• A threshold of 0 never fails.
• Config assertCategories merges with the flags; a flag wins for the same category.

--debug-audit <id|fails>

agent-lighthouse https://example.com --debug-audit structured-data/faqpage-schema
agent-lighthouse https://example.com --debug-audit sitemap   # title contains "sitemap"
agent-lighthouse https://example.com --debug-audit fails     # every fail or warn

Prints page URL, found and expected values, explanation, impact, fix and a code sample. The value matches an exact id or a title substring. fails also selects audits whose advisory population fails or warns. Not-applicable checks are searched too, which shows why an audit reported nothing.

--trace [path]

Writes one NDJSON record per registered audit, including audits that never ran. The default path is ./agent-lighthouse-trace.ndjson. The file is truncated at the start and appended during the scan, so a crash keeps what ran.

# compare two runs
diff <(jq -c '{id,outcome,status,score}' before.ndjson) <(jq -c '{id,outcome,status,score}' after.ndjson)

# audits that did not run, and why
jq -r 'select(.outcome != "ran") | "\(.outcome)\t\(.id)\t\(.explanation)"' agent-lighthouse-trace.ndjson

--log-level <level>

Levels: silent, error, warn, info, debug, trace. The flag overrides LOG_LEVEL. Without either, the CLI shows warn and error. An unknown level exits 1. --progress-json forces silent.

A text line shows the time, level, site, the first 8 characters of the scan id, and the component:

07:12:03.456 WARN  [example.com a1b2c3d4] orchestrator: Some requests got no answer phase=audits failed=3 requests=212 failures={"UND_ERR_CONNECT_TIMEOUT":3} caller=orchestrator.ts:837

Set LOG_FORMAT=json for one JSON object per line. Every line carries these context fields when they apply:

Other fields follow OpenTelemetry names: http.request.method, url.full, http.response.status_code, user_agent.original. Durations are durationMs. Errors are err, with type, message, stack and code. The logger removes URL credentials and the values of secret-named keys (authorization, cookie, token and similar) before writing.

--log-file <path>

Appends every line, down to trace, as JSON, whatever the terminal level. It records each request’s start and finish, time per phase, bot walls, requests the scan chose not to send, and requests still open when audits finished.

agent-lighthouse https://example.com --silent --log-file ./scan-log.jsonl

# slowest requests
jq -r 'select(.msg == "Request finished") | [.durationMs, ."url.full"] | @tsv' scan-log.jsonl | sort -rn | head
# requests per audit
jq -r 'select(.msg == "Request finished") | .audit // "(scan)"' scan-log.jsonl | sort | uniq -c | sort -rn
# time per phase
jq -r 'select(.msg == "Phase done") | "\(.phase)\t\(.durationMs)ms"' scan-log.jsonl

To send logs to your own logger from code, see logger in programmatic options.

--progress-json

agent-lighthouse https://example.com --output json --progress-json 2> progress.ndjson

Writes one ScanEvent per line to stderr and turns off the interactive display. Scanner logs are silenced to keep the stream parseable; audit errors still appear in the report.

What a scan reads

The scan reads the target URL plus any pages declared in a config file. It probes a fixed set of root files (/robots.txt, /llms.txt, /sitemap.xml, /.well-known/… and others). Some audits also sample sitemap pages; those samples do not decide whether the scan is scored. None of this is configurable.

When the target has no readable text and a same-origin <meta http-equiv="refresh"> or <link rel="canonical"> names another page, the scan reads that page once, as a second page. The gateway keeps its own findings. Other origins are not followed, and never more than one hop.

Exit codes

An assertion failure and a crash both exit 1. To tell them apart, check for reports/agent-lighthouse-report.json: it exists after an assertion failure, not after a crash.

In CI

- name: Audit agent readiness
  run: |
    npx @forkpoint/agent-lighthouse https://staging.example.com \
      --output terminal,html,json,md --min-score 80 \
      --assert-category structured-data:90

- name: Upload report
  if: always() # keep the report when an assertion fails
  uses: actions/upload-artifact@v4
  with:
    name: agent-lighthouse-report
    path: ./reports/

The ready-made action is in github-action.md. badge.md turns a score into a README badge.