CLI Commands
CLI command reference
FAQs
What does the vg init command do?
The vg init command sets up Vibgrate in your project by creating a .vibgrate/ directory for scan artifacts and baselines, plus a vibgrate.config.ts file with sensible defaults. Use --baseline to also create an initial drift baseline. Use --yes to skip confirmation prompts. This is typically the first command when adopting Vibgrate.
What flags does the scan command support?
Key flags: --format (text/json/sarif/md), --out (output file), --fail-on (error/warn - exit code 2 if findings exist), --baseline (compare against baseline), --drift-budget (fail if score exceeds value), --drift-worsening (fail if drift worsens by %), --push (upload to dashboard), --dsn (DSN for push), --offline (no network calls), --max-privacy (minimal data collection).
How do I upload scan results to the dashboard?
Use vibgrate push after running a scan, or combine them with vg scan --push. The DSN is read from VIBGRATE_DSN environment variable or pass with --dsn. Use --strict to fail if upload fails (for CI). Use --region eu for EU data residency. Uploading to Vibgrate Cloud is always optional — the CLI provides full value locally.
How do I generate reports from existing scans?
Use vg report to render existing scan artifacts into different formats without re-scanning. By default, it reads .vibgrate/scan_result.json. Use --in path/to/artifact.json for a specific file. Use --format md for Markdown (great for PRs), --format text, or --format json. The report command never runs a new scan.
How do I export SBOMs from Vibgrate scans?
Use vg sbom export to emit CycloneDX or SPDX SBOMs from scan artifacts. Example: vg sbom export --format cyclonedx --out sbom.cdx.json. Use vg sbom delta --from old.json --to new.json to compare dependencies between two scans, showing packages added, removed, or changed. Use vg sbom vex --product <ref> --statement '{...}' --out openvex.json to generate a spec-compliant OpenVEX document of exploitability statements you can attach as a signed attestation.
What do the CLI exit codes mean?
Exit code 0: Success (scan completed, all gates passed). Exit code 1: Runtime error (invalid flags, missing files, crash). Exit code 2: Threshold exceeded (--fail-on severity gate or drift budget/worsening gate triggered). Use these codes to control CI pipeline flow.
What's the difference between --fail-on error and --fail-on warn?
--fail-on error exits with code 2 only if error-level findings exist (e.g., runtime near EOL, framework 3+ majors behind). --fail-on warn exits with code 2 if warning-level OR error-level findings exist. Use --fail-on error in CI to catch critical issues; add --fail-on warn when you want stricter enforcement.
How do I generate a DSN token?
Run vibgrate dsn create --workspace ws-abc123 to generate an HMAC-signed DSN token. Use --region eu for EU data residency. Use --write .vibgrate/.dsn to save to a file (add to .gitignore). The DSN format is: vibgrate+https://<key_id>:<secret>@<ingest_host>/<workspace_id>. Never commit DSN tokens to source control.
What does the --changed-only flag do?
The --changed-only flag scans only files that have changed (typically detected via git diff). This speeds up scans in CI by skipping unchanged projects in monorepos. Useful for pull request checks where you only care about drift in modified code. Still compares against full baseline for accurate regression detection.
What does --strict do on the push command?
When --strict is set, the push command exits with error code if the dashboard upload fails (network error, authentication problem, etc.). Without --strict, push failures are logged but don't affect the exit code. Use --strict in CI when you want builds to fail if metrics can't be uploaded to the dashboard.