Overview
vg scan is the core command of the Vibgrate CLI. It recursively analyzes your repository, calculates the DriftScore, and outputs actionable findings.
Quick Start: Run npx @vibgrate/cli scan in any project directory for an instant drift assessment.
Usage
vg scan [path] [options]
Options Reference
Output Options
| Flag | Default | Description |
|---|---|---|
--format <type> | text | Output format: text, json, sarif, md |
--out <file> | stdout | Write output to a file |
Quality Gate Options
| Flag | Default | Description |
|---|---|---|
--fail-on <level> | — | Exit code 2 if findings at level: error, warn, info |
--baseline <file> | — | Compare against a previous baseline |
--drift-budget <score> | — | Fail if drift score exceeds this value (0-100) |
--drift-worsening <percent> | — | Fail if drift increased by this % vs baseline |
Scope Options
| Flag | Default | Description |
|---|---|---|
--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 file's exclude list. |
Performance Options
| Flag | Default | Description |
|---|---|---|
--concurrency <n> | 8 | Maximum concurrent registry API calls |
--changed-only | — | Only scan files changed since baseline |
--project-scan-timeout <seconds> | 180 | Per-project scan timeout in seconds |
--ui-purpose | — | Enable optional UI purpose evidence extraction (slower) |
--offline | — | Disable network calls (requires package manifest) |
--package-manifest <file> | — | Offline package version data |
Vibgrate Cloud Upload Options
| Flag | Default | Description |
|---|---|---|
--push | — | Upload scan artifact to dashboard |
--dsn <dsn> | VIBGRATE_DSN env | DSN token for authentication |
--region <region> | — | Data residency override: us, eu |
--repository-name <name> | dir / package name | Override the repository name recorded for this scan |
--strict | — | Fail pipeline if upload fails |
Privacy & Security Options
| Flag | Default | Description |
|---|---|---|
--max-privacy | — | Hardened privacy mode, minimal data collection |
--no-local-artifacts | — | Don't write .vibgrate/*.json files |
Output Formats
Text (Default)
vg scan
Example Output:
╭─────────────────────────────────────────────╮
│ VIBGRATE DRIFT REPORT │
├─────────────────────────────────────────────┤
│ DriftScore: 67/100 │
│ Projects: 4 (Node.js: 3, .NET: 1) │
│ Findings: 12 (3 errors, 7 warnings, 2 info)│
╰─────────────────────────────────────────────╯
🔴 ERROR: Node.js 16.x is EOL
→ Upgrade to Node.js 20.x or 22.x
🟡 WARNING: 45% of dependencies are 2+ majors behind
→ Review dependency-risk findings
🔵 INFO: TypeScript 4.9 → 5.x available
→ Consider upgrade for improved type inference
JSON
vg scan --format json --out scan.json
Example Output:
{
"meta": {
"version": "1.0.0",
"timestamp": "2025-01-15T10:30:00Z",
"duration": 4520
},
"driftScore": 67,
"projects": [
{
"path": "./",
"ecosystem": "nodejs",
"drift": 45,
"runtimeVersion": "16.20.0"
}
],
"findings": [
{
"severity": "error",
"scanner": "platform-matrix",
"message": "Node.js 16.x is EOL",
"recommendation": "Upgrade to Node.js 20.x or 22.x"
}
]
}
SARIF (GitHub/Azure DevOps)
vg scan --format sarif --out vibgrate.sarif
Tip: SARIF integrates with GitHub Code Scanning and Azure DevOps for native PR annotations.
Markdown
vg scan --format md --out report.md
Use Case: Generate markdown for PR comments, wikis, or release documentation.
Quality Gates
Fail on Severity Level
# Fail on any error-level finding
vg scan --fail-on error
# Fail on warnings or worse
vg scan --fail-on warn
# Fail on any finding
vg scan --fail-on info
| Level | Exit Code | Use Case |
|---|---|---|
error | 2 | Block on critical issues only |
warn | 2 | Stricter governance |
info | 2 | Zero-tolerance policy |
Drift Fitness Functions
Fitness functions enforce drift budgets over time:
vg scan \
--baseline .vibgrate/baseline.json \
--drift-budget 40 \
--drift-worsening 5 \
--fail-on error
| Gate | Trigger | Purpose |
|---|---|---|
--drift-budget 40 | Score > 40 | Absolute drift ceiling |
--drift-worsening 5 | Increase > 5% vs baseline | Prevent regression |
--fail-on error | Any error finding | Catch critical issues |
Warning: Fitness functions require a baseline. Create one with vg baseline first.
Special Modes
Offline Mode
For air-gapped environments or CI runners without internet:
vg scan --offline --package-manifest ./packages.zip
Privacy Mode
For maximum data minimization:
vg scan --max-privacy --no-local-artifacts
CI Pipeline Mode
Recommended CI configuration with all quality gates:
vg scan \
--baseline .vibgrate/baseline.json \
--drift-budget 40 \
--drift-worsening 5 \
--fail-on error \
--format sarif \
--out vibgrate.sarif \
--push \
--strict
Excluding Paths
Use --exclude (alias -e) to skip paths from a scan as glob patterns. This is the command-line equivalent of the exclude array in vibgrate.config.*, useful for ad-hoc, one-off scans without editing config.
The flag follows common CLI conventions for "multiple values":
| Style | Example |
|---|---|
| Repeatable | --exclude "legacy/**" --exclude "vendor/**" |
| Comma/semicolon-separated | --exclude "legacy/**,vendor/**;dist/**" |
| Mixed | -e "legacy/**" -e "vendor/**,dist/**" |
# Exclude a couple of directories for this run only
vg scan --exclude "legacy/**" --exclude "vendor/**"
# Same thing, comma/semicolon-separated in a single flag
vg scan -e "legacy/**,vendor/**;dist/**"
Additive, not a replacement: CLI excludes are merged (and de-duplicated) with the config file's exclude list rather than replacing it, so your committed defaults always apply. Patterns use glob syntax matched against the workspace root.
Exit Codes
| Code | Meaning | Action |
|---|---|---|
0 | Success, no threshold violations | Pipeline continues |
1 | CLI error (invalid args, scan failure) | Debug command |
2 | Drift threshold exceeded | Block merge, address findings |
Related Commands
- vg init — Initialize project
- vg baseline — Create baseline snapshot
- vg report — Generate reports from artifacts
- CI Integration — Full pipeline setup