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:
Diagnostics go to stderr. Reports go to stdout or the output file.
For discovery and online analysis, use these options to control file selection:
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:
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:--format to choose the output:
Audit dependencies
Check vulnerabilities, native lifecycle events such as deprecated or withdrawn releases, outdated and duplicate versions, and manifest/lockfile disagreements:--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.
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 to your configuration. Ignored findings stay visible with their reason and don’t cause exit 1 on their own.
Compare dependencies between revisions
Compare direct and transitive dependencies between two Git revisions, or between a revision and the working tree: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.
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:license check to enforce a policy.
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:--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.
Offline replay
Inspect a saved analysis, read a license report, or check an SBOM without contacting the API. These commands need no token:
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
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.