Usage
vg scan [path] [options]
What It Does
vg scan is the core command. It recursively scans your repository for projects, analyzes dependency drift, and produces an DriftScore with detailed findings.
All Flags
| Flag | Default | Description |
|---|---|---|
--format | text | Output format: text, json, sarif, or md |
--out <file> | — | Write output to a file |
--fail-on <level> | — | Exit with code 2 if findings at this level exist |
--baseline <file> | — | Compare against a previous baseline |
--exclude <glob>, -e <glob> | — | Exclude paths from the scan as glob patterns. Repeatable and accepts comma/semicolon-separated values. Merged (and de-duplicated) with the config exclude list |
--changed-only | — | Only scan changed files |
--concurrency <n> | 8 | Max concurrent registry calls |
--drift-budget <score> | — | Fitness gate: fail if drift score is above this budget |
--drift-worsening <percent> | — | Fitness gate: fail if drift worsens by more than % vs baseline |
--push | — | Upload scan artifact to Vibgrate Cloud after a successful scan |
--dsn <dsn> | VIBGRATE_DSN env | DSN used for --push authentication |
--region <region> | — | Override data residency (us, eu) during push |
--strict | — | Fail scan command if push fails |
--ui-purpose | — | Enable optional UI-purpose evidence extraction |
--offline | — | Disable network calls and disable upload/push behavior |
--package-manifest <file> | — | JSON or ZIP manifest for offline/latest lookups |
--no-local-artifacts | — | Do not write .vibgrate/*.json scan artifacts to disk |
--max-privacy | — | Hardened privacy mode with minimal scanners and no local artifacts |
Output Formats
Text (default)
A colored, human-readable report showing the overall drift score, score component breakdown, per-project details, and findings with severity icons.
vg scan
JSON
The full scan artifact in JSON format with all raw data, scores, findings, and VCS metadata.
vg scan --format json --out scan.json
SARIF
Static Analysis Results Interchange Format — compatible with GitHub Code Scanning and Azure DevOps.
vg scan --format sarif --out vibgrate.sarif
Markdown
A clean Markdown report suitable for PRs, wikis, or documentation.
vg scan --format md --out report.md
Quality Gates
Use --fail-on to make the CLI exit with code 2 when findings at a certain severity exist:
# Fail on any error-level finding
vg scan --fail-on error
# Fail on warnings too
vg scan --fail-on warn
Drift Fitness Functions
Combine baselines with drift budgets for precise CI enforcement:
vg scan \
--baseline .vibgrate/baseline.json \
--drift-budget 40 \
--drift-worsening 5 \
--fail-on error
This fails the scan if:
- The drift score exceeds 40 (budget gate)
- Drift has worsened by more than 5% compared to the baseline (regression gate)
- Any error-level findings are present
Scan with Vibgrate Cloud Push
vg scan --push --dsn $VIBGRATE_DSN --strict
Excluding Paths
Use --exclude (alias -e) to skip paths from a scan as glob patterns — the command-line equivalent of the exclude array in vibgrate.config.*. It's ideal for ad-hoc scans without editing config.
The flag follows common CLI conventions for multiple values. It's repeatable, accepts comma/semicolon-separated values in a single flag, and you can mix both styles:
# Repeatable
vg scan --exclude "legacy/**" --exclude "vendor/**"
# Comma/semicolon-separated within a single flag
vg scan -e "legacy/**,vendor/**;dist/**"
CLI excludes are additive: they're merged (and de-duplicated) with the config file's exclude list rather than replacing it, so committed defaults always apply.
Offline Mode
For air-gapped environments, use --offline with a pre-downloaded manifest:
vg scan --offline --package-manifest ./latest-packages.zip
Privacy Mode
vg scan --max-privacy
This runs minimal scanners and writes no local artifacts.
Local Artifacts
By default, the scan writes .vibgrate/scan_result.json. Suppress this with --no-local-artifacts or --max-privacy.