DocumentationSearch docs
  1. 01Getting started
  2. 02Scanning
  3. 03Checks
  4. 04Services
  5. 05Configuration
  6. 06Ignoring checks
  7. 07CI
  8. 08Agent skill
  9. 09Dashboard
  10. 10Supported stacks

Configuration

Copy Markdown

Configuration

preflight init writes preflight.yml to your project’s root. Commit it, so every machine and every CI run scans the same way.

An example

projectName: my-app
stack: rails  # rails, next, react, vite, laravel and so on

urls:
  staging: "https://staging.example.com"
  production: "https://example.com"

services:
  stripe:
    declared: true
  sentry:
    declared: true

checks:
  envParity:
    enabled: true
    envFile: ".env"
    exampleFile: ".env.example"

  healthEndpoint:
    enabled: true
    path: "/health"  # optional: with enabled: true, only this path is checked

  stripeWebhook:
    enabled: true
    url: "https://api.example.com/webhooks/stripe"  # optional: probed with a GET

  seoMeta:
    enabled: true
    mainLayout: "app/views/layouts/application.html.erb"

  security:
    enabled: true

  secrets:
    enabled: true
    allowlist:
      - path: web/js/golden-hour.js
        fingerprint: "sha256:<hex>"
        reason: "HTTP-referrer-restricted Google Timezone key"

  indexNow:
    enabled: true
    key: "0123456789abcdef0123456789abcdef"  # 32 hex characters

  emailAuth:
    enabled: true   # opt-in: SPF and DMARC
    domain: mail.example.com  # optional: the domain you send mail from

  humansTxt:
    enabled: false  # opt-in: credits the team

  license:
    enabled: false  # opt-in: for open source projects

ignore:
  - sitemap
  - llms_txt
  - google_analytics

The project

projectName names the project in the report and on the dashboard. stack tells the checks where to look: which layout holds the meta tags, where the public files live, which package manager to audit. preflight init detects it; supported stacks lists the values.

URLs

urls.production and urls.staging are where the network checks go: ssl, security_headers, www_redirect, health_endpoint, and the checks that read the rendered page. preflight init asks for both, and both are optional. Without a URL, the network checks never pass: ssl, www_redirect, and health_endpoint stay out of the scan, security_headers is reported as skipped, and the page checks read your templates instead.

Network checks connect directly and do not use HTTP_PROXY or HTTPS_PROXY. Preflight looks at each address before it connects and refuses private ones, and a proxy would make that connection out of its sight. On a network that only reaches the internet through a proxy, the network checks report the site as unreachable; run them from a machine with direct access.

Services

Each entry under services: says whether the project uses that service. A declared service that never gets initialized is reported. See services for the IDs.

preflight init lists every service it knows, most with declared: false. A service ID this version doesn’t know is dropped with a note when it has declared: false, since a newer Preflight may have written it, and is an error when it has declared: true, since that is most likely a typo. The old groq ID is read as grok, with a note to rename it.

Checks

Keys under checks: turn checks on or off and give them settings. They are camelCase (seoMeta, envParity), a separate schema from the snake_case check IDs.

An opt-in check runs only when its block is here. preflight init writes envParity and secrets turned on, and security turned on when it is given a production URL, so most projects have them; a hand-written file without those blocks leaves the three checks out.

A block without an enabled: key turns its check on (since 1.1): writing secrets.allowlist or envParity.envFile is asking for that check. Before 1.1 such a block left an opt-in check off without saying so. Only enabled: false turns a check off, and a key with nothing under it (secrets: on its own) changes nothing. healthEndpoint runs by default whenever a URL is set, and seoMeta whenever a layout or URL is found, so a block that only sets path or mainLayout leaves them on as well. One block is the exception: healthEndpoint: {enabled: false, path: /health}, exactly, is what preflight init used to write for CMS and static sites, so it keeps its old meaning (the check still runs when a URL is set) and prints a note saying how to turn it off. init no longer writes it.

Key Settings
envParity envFile and exampleFile, compared for missing variables. Both must be paths inside the project. Opt-in
healthEndpoint path, when it isn’t one of the usual ones. Without enabled, it is tried first, then the usual ones; with enabled: true, only it is
stripeWebhook Turns on the Stripe check (result ID stripe), which looks for the API keys, the webhook secret, and the SDK’s initialization. url is optional and is probed with a GET; a 404 or no answer is reported. Opt-in: declaring stripe under services: is not enough on its own
seoMeta mainLayout, the template that holds your <head>. It must be a path inside the project
security Turns on the security_headers check. Opt-in
secrets allowlist, for findings you have checked (see ignoring checks). Opt-in
indexNow key, your IndexNow key. Opt-in
emailAuth Turns on the SPF and DMARC check. Opt-in. domain is the domain you send mail from. Without it, the check uses the production URL’s host, then its organizational domain (www.example.com, then example.com), and says so in its message; with no production URL either, it is skipped
adsTxt, humansTxt, license Turn on these file checks. Opt-in

Ignore

ignore: lists the check and service IDs to leave out of every scan. preflight ignore <id> and preflight unignore <id> edit it for you. An entry with a /, *, or . is a path glob instead, and leaves matching files out of the source checks (vendor/**). A bare word that is neither an ID nor a glob, like vendor, loads with a note: it matches only a file of that name at the project root.

Strict loading

Preflight reads preflight.yml strictly, so a typo can’t silently turn a check off. A file path that leaves the project (a leading /, or any ..) in envFile, exampleFile, or mainLayout stops the scan with exit 64 too. An unknown key stops the scan with exit 64 and says where it is:

Error: failed to parse preflight.yml: unknown key "bogus" under checks: at line 5. Check the spelling; if this file was written by a newer Preflight, upgrade the CLI

Strictness cuts both ways: a newer Preflight may write keys an older one rejects. When a teammate’s preflight init adds a key your CLI doesn’t know, upgrade the CLI rather than deleting the key.