> ## 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, 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.3.0. For help with a command, run `githits-scan --help`. For nested commands, use the full name, such as `githits-scan sbom generate --help` or `githits-scan license check --help`. ## Common options All five 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 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, deprecated 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 ``` Any finding or incomplete check returns exit 1. 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 findings and incomplete checks as JSON. | | `--details` | Include deprecated, outdated, and duplicate lists in human-readable output. | | `--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. ## 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. | 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 findings; a license report is informational. | | 1 | Findings, incomplete audit, 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.