Usage
vibgrate scan [path] [options]
What It Does
vibgrate scan is the core command. It recursively scans your repository for projects, analyzes dependency drift, and produces an Upgrade Drift Score 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 |
--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 dashboard 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 |
--install-tools | — | Auto-install missing local security tools via Homebrew |
--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.
vibgrate scan .
JSON
The full scan artifact in JSON format with all raw data, scores, findings, and VCS metadata.
vibgrate scan . --format json --out scan.json
SARIF
Static Analysis Results Interchange Format — compatible with GitHub Code Scanning and Azure DevOps.
vibgrate scan . --format sarif --out vibgrate.sarif
Markdown
A clean Markdown report suitable for PRs, wikis, or documentation.
vibgrate 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
vibgrate scan . --fail-on error
# Fail on warnings too
vibgrate scan . --fail-on warn
Drift Fitness Functions
Combine baselines with drift budgets for precise CI enforcement:
vibgrate 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 Dashboard Push
vibgrate scan . --push --dsn $VIBGRATE_DSN --strict
Offline Mode
For air-gapped environments, use --offline with a pre-downloaded manifest:
vibgrate scan . --offline --package-manifest ./latest-packages.zip
Privacy Mode
vibgrate 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.