Scan command reference

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 <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 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:

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. Review what Scan uploads before running it. The HTTP API reference describes upload limits, quota, and how to interpret results.

Detect

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

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:

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:

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:

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:

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, then check dependencies against it:

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:

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. Read the diagnostic before rerunning an online command: it submits a new job and can consume quota again.

Get Started

Agent tools

CLI

Scan

Guides

Scan command reference

Common options

Detect

Generate an SBOM

Audit dependencies

Report licenses

Check license policy

Offline replay

Exit codes

​Common options

​Detect

​Generate an SBOM

​Audit dependencies

​Report licenses

​Check license policy

​Offline replay

​Exit codes

Common options

Detect

Generate an SBOM

Audit dependencies

Report licenses

Check license policy

Offline replay

Exit codes