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

Scanning

Copy Markdown

Scanning

preflight scan runs every enabled check against the project in the current directory, or in the directory you name.

preflight scan                    # the current directory
preflight scan /path/to/project   # another one

Flags

Flag What it does
-v, --verbose Show detail for each check, including which files matched
--only <ids> Run only these checks or services, comma-separated
--skip <ids> Skip these checks or services for this run
--ci Run without prompts, for CI
--format json Print JSON instead of the human report
--publish Send the results to your dashboard

--only and --skip take the IDs that preflight checks lists. They are for a single run, and they leave preflight.yml as it is. To silence a check for good, use preflight ignore.

# Rerun only what you are fixing.
preflight scan --only seo_meta,og_twitter

# Leave out the slow or risky ones.
preflight scan --skip vulnerability,secrets

JSON output

--format json prints one JSON document with a schema_version, the CLI version, the project name, a summary, and one entry per check:

{
  "schema_version": 2,
  "cli_version": "1.1.0",
  "project": "acme-store",
  "summary": { "ok": 5, "warn": 12, "fail": 1, "skipped": 1, "inconclusive": 1 },
  "checks": [
    {
      "id": "canonical",
      "title": "Canonical URL",
      "passed": false,
      "severity": "warn",
      "message": "No canonical URL tag found",
      "suggestions": ["Set metadataBase in root layout.tsx"]
    },
    {
      "id": "email_auth",
      "title": "Email authentication (SPF/DMARC)",
      "passed": false,
      "skipped": true,
      "severity": "info",
      "message": "Skipped: set checks.emailAuth.domain to the email sending domain (there is no production URL to take it from)"
    }
  ]
}

Each check has one of four outcomes:

  • Passed: passed is true. The check verified what it looks for.
  • Failed: passed is false, and severity is warn or error.
  • Skipped: skipped is true, passed is false, and severity is info. The check had nothing to verify against, such as a network check with no URL. A skipped check is not a pass.
  • Inconclusive: inconclusive is true. The check ran but could not decide, such as an audit tool that is not installed or a DNS lookup that failed. It counts as a warning (or an error, for an error severity).

skipped and inconclusive are left out when they are false. In the summary, ok, warn, and fail count the checks that ran; skipped counts the skipped ones, which are in none of the other three; and inconclusive counts the inconclusive ones, which are also in warn or fail. skipped and inconclusive are left out when they are zero.

schema_version 2 (since 0.24) added the skipped and inconclusive outcomes. In schema 1, a check that had nothing to check passed. preflight history --format json and published runs carry the same version. Output with no schema_version came from a CLI older than 0.22, which used camelCase IDs.

Exit codes

Code Meaning
0 Every check passed
1 Warnings only, or no check ran
2 At least one check found an error
64 Preflight could not run: a bad path, a missing, unreadable, or invalid preflight.yml, an unknown or pre-0.22 check ID, an --only that matches no enabled check, or a bad flag
130 The scan was cancelled (Ctrl-C or SIGTERM)

A scan whose checks were all skipped exits 1: nothing failed, but nothing was verified either. So does a scan where no check ran at all, because everything was ignored or skipped with --skip (since 1.1). Inconclusive checks also exit 1, unless another check found an error.

Codes 1 and 2 mean the scan ran and reported something. Code 64 means it never got that far, so CI can tell "this project has problems" apart from "this command was wrong".

Two cases of 64 are easy to meet. A directory with no preflight.yml stops with preflight.yml not found (run preflight init first). And --only naming a check that is not enabled for this project, such as an opt-in check with no block under checks:, stops with no enabled checks match --only.

The other commands use the same numbers differently. preflight auth and preflight history exit 0 on success, 2 when they fail (not logged in, or a network error), and 64 on a usage error. They never exit 1.

Color

Output is colored in a terminal and plain when piped. It also respects the NO_COLOR environment variable.

Environment variables

Variable What it does
NO_COLOR Turns off colored output
PREFLIGHT_TOKEN A token for preflight auth login to store instead of opening a browser (see dashboard)
PREFLIGHT_NO_UPDATE_CHECK Any value turns off the daily check for a newer version. It is already off with --ci and --format json
PREFLIGHT_INSTALL_DIR Where the install script puts the binary, instead of /usr/local/bin
PREFLIGHT_VERSION The release the install script installs, such as v1.1.0, instead of the latest
PREFLIGHT_API_URL The dashboard’s address. Internal, for testing against a local dashboard only

Help

preflight help <command>, or preflight <command> --help, shows a command’s flags and examples.

preflight version, or preflight --version, prints the installed version.

Shell completions

Tab completion for commands, flags, and check IDs, including the values of --only and --skip:

# bash (add to ~/.bashrc)
source <(preflight completion bash)

# zsh (add to ~/.zshrc)
source <(preflight completion zsh)

# fish
preflight completion fish | source

# PowerShell (add to your profile)
preflight completion powershell | Out-String | Invoke-Expression