> ## Documentation Index
> Fetch the complete documentation index at: https://docs.githits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scan command reference

> Find githits-scan commands, flags, output formats, dependency diffs, offline replay inputs, and exit codes.

Use `detect` to review your package files, then generate an SBOM, audit dependencies, or check licenses. This reference covers **Alpha** version 0.5.0.

For help with a command, run `githits-scan <command> --help`. For nested commands, use the full name, such as `githits-scan sbom generate --help` or `githits-scan license check --help`.

## Common options

All six commands accept these output options:

| Option | What it does |
| - | - |
| `-o, --output FILE` | Write the report to a file. Use `-` for stdout, which is the default. Existing report output files are overwritten. |
| `-q, --quiet` | Suppress routine progress and success messages. Reports, findings, warnings, and errors remain. |
| `--no-color` | Disable color. A nonempty `NO_COLOR` also disables it. Scan uses color when writing to a terminal. |

Diagnostics go to stderr. Reports go to stdout or the output file.

For discovery and online analysis, use these options to control [file selection](https://docs.githits.com/scan/configuration.md):

| Option | What it does |
| - | - |
| `PATH` | Scan this directory. Defaults to `.`. |
| `--config FILE` | Read this configuration instead of `githits-scan.toml` in the scan root. Paths inside the configuration stay relative to the scan root. |
| `--no-check` | Use the configured selection despite inventory drift. Does not widen the selection or disable audit findings or license policy. |
| `--lockfiles-only` | Skip unconfigured projects that have a manifest without a lockfile. Keep associated manifests and eligible Cargo, npm, and Bun workspace members. |
| `--exclude GLOB` | Omit matching package files, including associated manifests and workspace member manifests. Repeat to add patterns. |

Online analysis requires [`GITHITS_API_TOKEN`](https://docs.githits.com/scan/installation#set-up-authentication). Review [what Scan uploads](https://docs.githits.com/scan/overview.md#review-what-you-upload) before running it. The [HTTP API reference](https://docs.githits.com/api/lockfile-analysis.md) describes upload limits, quota, and how to interpret results.

## Detect

Preview the package files Scan would upload, without a token or network connection:

```bash theme={null}
githits-scan detect
githits-scan detect --json -o inventory.json
```

Scan reads the selected files locally and prepares the same selection as an upload, including eligible workspace members. The inventory distinguishes selected files from candidates that won't be uploaded. It lists skipped directory subtrees as patterns because their file counts are unknown.

After reviewing the selection, save it to your configuration:

```bash theme={null}
githits-scan detect --save
```

| Option | What it does |
| - | - |
| `--json` | Write inventory JSON (schema 2). `upload_paths` contains the exact selection prepared locally. |
| `--save` | Record the reviewed inventory in the selected configuration. Create a commented template if needed, preserving existing comments, license policy, and excludes. Conflicts with `--no-check`. |

If no package files are selected, Scan exits 1. If Scan cannot prepare an upload, JSON inventory is still available with null `upload_paths` and an `upload_error`. The command then exits 2 for usage errors or 3 for I/O errors.

## Generate an SBOM

Generate a dependency inventory in the format you need:

```bash theme={null}
githits-scan sbom generate -o bom.cdx.json
githits-scan sbom generate --format spdx -o bom.spdx
githits-scan sbom generate --format text -o bom.txt
```

Scan submits one analysis job and writes the complete document returned by GitHits. Use `--format` to choose the output:

| Value | Document |
| - | - |
| `cyclonedx` (default) | CycloneDX 1.7 JSON |
| `spdx` | SPDX 2.3 tag-value, not JSON |
| `text` | Human-readable inventory report |

## Audit dependencies

Check vulnerabilities, native lifecycle events such as deprecated or withdrawn releases, outdated and duplicate versions, and manifest/lockfile disagreements:

```bash theme={null}
githits-scan audit
githits-scan audit --details
githits-scan audit --json -o audit.json
githits-scan audit --save-analysis analysis.json
```

Audit requests native lifecycle report v3 automatically. Unignored findings, retained lifecycle warnings, and actionable incomplete checks return exit 1. Expected Git coverage limits appear as informational coverage notes and don't fail an audit on their own. Lifecycle collection limits and checks that don't apply also return exit 0 on their own; `--details` explains them. A clean audit covers the selected package files; it does not establish that an installed build is safe. Scan shows change suggestions when GitHits supplies them. It does not edit your dependencies.

| Option | What it does |
| - | - |
| `--json` | Write compact audit JSON (format 2), including native `lifecycle` evidence. `incomplete` reports coverage gaps separately from `actionable_incomplete`, and each `issues[]` entry has an `actionable` boolean. |
| `--details` | Show more detail in human-readable output, including lifecycle checks that were not collected or don't apply. |
| `--save-analysis FILE` | Save analysis data to a **new** file for offline inspection. Conflicts with `--output` and `--from-analysis`. Does not accept `-`. |
| `--from-analysis FILE` | Read a saved analysis offline. Conflicts with explicit `PATH`, `--config`, `--exclude`, `--lockfiles-only`, `--no-check`, and `--save-analysis`. Does not accept `-`. |
| `--explain PACKAGE` | With `--from-analysis`, explain an exact vulnerable `registry:name@version` in the saved analysis. |

JSON and saved analyses retain findings even when the human-readable output omits details. To inspect an analysis offline, save it with `--save-analysis`. Compact `audit --json` output cannot be used as a saved analysis.

Saved analyses use format 2, and saved explanations add `audit_actionable_incomplete`. `audit --from-analysis` reads only format 2. To replay an analysis saved by 0.4.0 (format 1), use Scan 0.4.0. Neither version migrates the other's saved analyses.

If GitHits returns an audit report version this Scan version doesn't support, Scan exits 3 without writing output or resubmitting the job.

To accept a reviewed advisory, add an [`[[audit.ignore]]` entry](https://docs.githits.com/scan/configuration#ignore-reviewed-advisories) to your configuration. Ignored findings stay visible with their reason and don't cause exit 1 on their own.

## Compare dependencies between revisions

> [!WARNING]
>
> **Experimental.** `diff` output is informational and can change between releases.

Compare direct and transitive dependencies between two Git revisions, or between a revision and the working tree:

```bash theme={null}
githits-scan diff --base "$(git merge-base origin/main HEAD)" --head HEAD
githits-scan diff --base HEAD --format json
githits-scan diff --base HEAD~1 --head HEAD --output-json diff.json --output-markdown diff.md
```

Scan reads package files from each revision without changing your checkout and submits both sides as one analysis job. The report shows dependency changes per source, ownership, advisory changes, and direct upgrade evidence. Human-readable and Markdown output include changelog items and links returned by GitHits. JSON preserves the exact report from GitHits.

`diff` requires Git and `GITHITS_API_TOKEN`, even when both sides are identical or empty. One comparison is charged at twice the quota weight of an audit. Both sides together share the upload limits of 256 files and 8,000,000 bytes including multipart framing.

`diff` ignores `githits-scan.toml`. Use `--exclude` and `--lockfiles-only` to control the selection.

| Option | What it does |
| - | - |
| `PATH` | Git repository root. Defaults to `.`. |
| `--base REV` | Base revision. For a pull request, use the merge base. Required. |
| `--head REV` | Head revision. Omit it to compare against the working tree. |
| `--format FORMAT` | `human` (default), `json`, or `markdown`. Markdown is suitable for a pull request comment. |
| `--output-json PATH` | Write the exact JSON report to `PATH`. |
| `--output-markdown PATH` | Write the Markdown report to `PATH`. |

Use `--output-json` and `--output-markdown` together to save both documents from the same analysis, or use either one alone. `-` writes to stdout for at most one of them. These options conflict with `--format` and `-o, --output`.

Exit 0 means Scan produced a report, including when evidence is partial or unknown. It is not a policy pass.

## Report licenses

Read license information without applying a policy:

```bash theme={null}
githits-scan license report
githits-scan license report --details
githits-scan license report --json -o licenses.json
```

You don't need a license policy for this command. Exit 0 means Scan produced a report, even if license information is unknown or incomplete. Use `license check` to enforce a policy.

| Option | What it does |
| - | - |
| `--json` | Write the complete experimental service report (schema 2). |
| `--details` | Show source attribution, observations, and coverage gaps in human-readable output. |
| `--from-report FILE` | Read saved report JSON offline. Accepts schemas 1 and 2; JSON output preserves the original bytes. Conflicts with explicit `PATH`, `--config`, `--no-check`, `--lockfiles-only`, and `--exclude`. Does not accept `-`. |

The report separates reported licenses, publisher context, source observations, and coverage gaps. It does not give a policy verdict.

## Check license policy

[Configure a license policy](https://docs.githits.com/scan/configuration.md#license-policy), then check dependencies against it:

```bash theme={null}
githits-scan license check
githits-scan license check --sbom bom.cdx.json
githits-scan license check --sbom bom.cdx.json --json
```

Without `--sbom`, Scan generates a CycloneDX JSON document online. With `--sbom`, it reads an existing document offline. Both forms require `[licenses]` in the selected configuration.

Violations, missing or unrecognized licenses, and unresolved projects return exit 1.

Scan warns on stderr when no components were evaluated or dependency resolution is incomplete. With `--sbom`, it also warns when the document has no `githits:completeness` property, because inventory completeness is unknown. Warnings appear even with `--quiet` and `--json`. They don't change the verdict or exit code.

| Option | What it does |
| - | - |
| `--sbom FILE` | Read an existing CycloneDX JSON SBOM. Conflicts with `--no-check`, `--lockfiles-only`, and `--exclude`. |
| `--json` | Write a policy verdict for automation. This output is not a license report or replay input. |
| `--details` | Include violation component references and package URLs in human-readable output. |

## Offline replay

Inspect a saved analysis, read a license report, or check an SBOM without contacting the API. These commands need no token:

```bash theme={null}
githits-scan audit --from-analysis analysis.json
githits-scan license report --from-report licenses.json
githits-scan license check --sbom bom.cdx.json
```

Use the matching saved document for each command:

| Saved document | Produce it with | Use it with |
| - | - | - |
| Audit analysis | `audit --save-analysis FILE` | `audit --from-analysis FILE` |
| License report JSON | `license report --json -o FILE` | `license report --from-report FILE` |
| CycloneDX JSON SBOM | `sbom generate -o FILE` | `license check --sbom FILE` (still needs policy) |

Replay uses the saved information. It does not refresh data from GitHits. Compact audit JSON and policy verdict JSON are for automation and cannot be used as replay inputs.

## Exit codes

| Exit | Meaning |
| - | - |
| 0 | Success. Checks have no unignored findings; a license report and `diff` are informational. |
| 1 | Findings, actionable audit gaps, inventory drift, policy violations, unresolved license projects, or nothing selected. |
| 2 | Invalid invocation, configuration, or input; upload limits; missing or rejected token; or account access requiring action. |
| 3 | Network, I/O, rate limit, service, or protocol failure. |

Use these distinctions to handle failures in [CI](https://docs.githits.com/scan/ci.md). Read the diagnostic before rerunning an online command: it submits a new job and can consume quota again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.