# Scanning

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

```bash
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](https://preflight.sh/docs/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`](https://preflight.sh/docs/ignoring/).

```bash
# 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:

```json
{
  "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`](https://no-color.org) 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](https://preflight.sh/docs/dashboard/#connect-the-cli)) |
| `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
# 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
```
