Configuration

Save repeatable scan settings in a JSON file. Command-line options usually override the file. Some settings work only as command-line flags; the tables below call out those limits.

Use this reference to choose scan categories, report formats, and time limits. It separates settings for the command-line tool from options for your own application.

See the command-line options for individual commands and understand your score for the results.

The config file

A config file lets a repository keep its scan settings under version control instead of in a long command line. The CLI looks for these names in the working directory, in this order, and uses the first that exists:

1. agent-lighthouse.config.json
2. .agent-lighthouserc.json
3. .agent-lighthouserc

All three are parsed as JSON. An auto-discovered file that fails to parse is reported as a warning and ignored, and the scan continues with defaults.

--config <path> overrides the search with an explicit file. In that case the file must exist and must parse: a missing path or invalid JSON is a fatal error rather than a fall back to auto-discovery.

{
  "url": "https://staging.yourstore.com",
  "preset": "ecommerce",
  "minScore": 80,
  "assertCategories": {
    "structured-data": 90,
    "access-crawl-control": 75
  },
  "output": ["terminal", "html", "json", "md"],
  "outputDir": "./reports"
}

With that file in place, agent-lighthouse audit — the sub-command with no URL after it — scans the declared URL and enforces the declared budgets. Any invocation whose first argument is a flag reads the file too, so agent-lighthouse --silent and agent-lighthouse --config ./ci/staging.json also pick the URL up from it.

A bare agent-lighthouse with no arguments at all does not: it prints the usage block and exits 1 before the config file is opened. See cli.md.

Keys

The config file accepts the last two keys, but they do not change the scan. Use the --categories command-line option to limit categories. You cannot change the page limit with maxPages.

Precedence

For every setting that both surfaces expose, the order is:

command-line flag → config file → built-in default.

assertCategories is the one exception, and it merges rather than overrides: thresholds from the config file and thresholds from repeated --assert-category flags are combined, with a flag winning for a category named in both.

defineConfig

@forkpoint/agent-lighthouse-core exports a defineConfig identity helper for authoring a config object in TypeScript with full type checking:

import { defineConfig } from "@forkpoint/agent-lighthouse-core";

export default defineConfig({
  url: "https://staging.yourstore.com",
  minScore: 80,
});

Note that the CLI’s loader reads JSON only — it does not import a .ts or .js config. Use defineConfig when you build the object in your own script (and, if you want the CLI to read it, write the result out as JSON).

The eight categories

Every audit belongs to exactly one category. These ids are what --categories and assertCategories accept, and what the JSON report keys its category results by.

Narrow a scan with the flag:

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

Unlisted categories are not scanned at all, so their audits appear nowhere in the report and contribute nothing to the score. An unknown id is rejected before the scan starts, with the valid list printed and exit code 1.

Experimental audits

--categories and --experimental are two independent filters over the same registry, applied together.

• --categories decides which categories run.
• --experimental decides whether experimental-tier audits are part of the run. They are excluded by default.

An experimental audit carries weight 0 whether or not it runs, so this flag can never move a score — it only adds results to the report. See scoring.md for the tiers and the evidence policy for what puts an audit in each one.

Programmatic options

runScan(url, options) from @forkpoint/agent-lighthouse-core takes the same decisions as ScanOptions:

import { runScan } from "@forkpoint/agent-lighthouse-core";

const report = await runScan("https://yourstore.com", {
  categories: ["structured-data", "agentic-commerce"],
  includeExperimental: false,
  pages: [
    { url: "https://yourstore.com/products/blue-widget", pageType: "product" },
    { url: "https://yourstore.com/collections/widgets", pageType: "category" },
  ],
  onEvent: (event) => console.error(JSON.stringify(event)),
});

console.log(report.overallScore, report.scoreTier);

A PageOverride declares { url, pageType }, where pageType is homepage, category, product or content. The declared type is forced onto that page, so type-gated audits run against the page you meant rather than against whatever discovery guessed. Overrides are resolved, de-duplicated (ignoring a trailing slash) and any that collide with the homepage are dropped; the remaining page budget is filled by discovery.

Field-level product verification (report.productFields) is only produced when a page override with pageType: 'product' is supplied. Without one, the report marks it skipped rather than guessing from an auto-discovered page.

Environment variables

Fixed limits

These are compile-time constants in packages/core/src/constants.ts and packages/core/src/fetcher.ts. There is no flag, config key or environment variable for them. The scan budget is the one exception: its default is a constant, and --timeout, the timeout key and timeoutMs change it.

The user agent is deliberately identifiable so that site owners can recognise, rate-limit or allow a scan in their logs. Individual audits that probe crawler parity send other user agents on purpose, to compare how the site answers a named AI crawler versus an ordinary browser.