CLI Usage
Command-line interface usage guides
FAQs
How do I run my first scan?
Run vg scan in your project directory. The scan recursively discovers projects (package.json, .csproj, pom.xml, requirements.txt), detects runtime versions and dependencies, queries registries for latest versions, computes drift, and generates findings. The default output is a colored, human-readable report in your terminal.
What does the scan command analyze?
The scan analyzes: runtime versions (Node.js, .NET, Python, Java, Go, Rust, PHP, Ruby, and more), framework versions (React, Next.js, Angular, Vue, NestJS, etc.), all dependencies from manifests like package.json, .csproj, requirements.txt, pom.xml, go.mod, Cargo.toml, composer.json, or Gemfile, lockfile data (duplicates, phantom deps), TypeScript configuration (strict mode, module system), and end-of-life risk for runtimes. Core analysis (the DriftScore) reads only manifest/config files. A few extended scanners also read parts of your source files locally for specific structural signals — code-quality metrics, database schema structure, UI text — see Extended Scanners Overview for exactly which ones. Nothing is ever executed, and nothing leaves your machine unless you push.
How do I create a drift baseline?
Run vg baseline to perform a full scan and save the result to .vibgrate/baseline.json. This snapshot becomes your reference point for measuring whether drift is improving or worsening. Commit the baseline to version control so all branches compare against the same reference. Use vg init --baseline to create both config and baseline in one step.
What output formats does the scan support?
Four formats: Text (default, colored human-readable), JSON (full artifact for automation), SARIF (for GitHub Code Scanning, Azure DevOps), and Markdown (for PRs, wikis, docs). Use --format json, --format sarif, or --format md. Use --out filename to write to a file instead of stdout.
How do I scan a specific directory instead of the whole project?
Pass the path as an argument: vg scan packages/api or vg scan /absolute/path/to/project. The scan will discover projects recursively from that path. To exclude subdirectories, use the exclude array in vibgrate.config.ts, or pass --exclude (alias -e) on the command line for a one-off scan — for example vg scan --exclude "legacy/**" --exclude "vendor/**". The flag is repeatable, accepts comma/semicolon-separated values, and is merged with (not a replacement for) the config exclude list.
How do I compare two scan results?
Use vg sbom delta --from old-scan.json --to new-scan.json to see dependencies added, removed, and changed between scans. For drift score comparison, use baselines: create a baseline, run a new scan with --baseline .vibgrate/baseline.json, and the output shows the delta. Vibgrate Cloud also shows historical trends.
How do I scan a Node.js or TypeScript project?
Run vg scan in your project directory. Vibgrate detects package.json files, lockfiles (npm, pnpm, yarn), .nvmrc/.node-version, and tsconfig.json. It analyzes runtime version, framework versions (React, Next.js, etc.), all dependencies from package.json, lockfile duplicates, and TypeScript modernity. Works with monorepos automatically.
How do I scan a .NET project?
Run vg scan /path/to/dotnet-solution. Vibgrate discovers .sln and .csproj files, evaluates target framework version (net6.0, net7.0, net8.0), .NET SDK version from global.json, NuGet packages from PackageReference elements, and EOL risk for .NET versions. Each project gets its own drift score, with aggregate scores for solutions.
How do I scan a Python project?
Run vg scan /path/to/python-project. Vibgrate detects requirements.txt, pyproject.toml, setup.py, and Pipfile. It analyzes Python version from .python-version or pyproject.toml, all dependencies, package version lag against PyPI, and EOL risk for Python versions. Supports Poetry, PEP 621, and Pipenv formats.
How do I scan a Java project?
Run vg scan /path/to/java-project. Vibgrate discovers pom.xml (Maven) and build.gradle/build.gradle.kts (Gradle) files. It analyzes Java version, all dependencies, package version lag against Maven Central, framework versions (Spring Boot, Quarkus, etc.), and EOL risk. Multi-module projects are fully supported.
How do I scan for known vulnerabilities?
Run `vg scan --vulns`. It matches every installed dependency against the public OSV database and reports known vulnerabilities with advisory id and CVE, severity, CVSS score, and the version that fixes each one — in the terminal, in the scan artifact, and as SARIF for CI code scanning. Use `vg scan --full` to run drift, vulnerabilities, and a banned-dependency report in one pass.
Can I scan for vulnerabilities offline or air-gapped?
Yes. `vg scan --vulns` queries the OSV database over the network by default, but you can supply advisories in a package-version manifest and run fully offline: `vg scan --vulns --offline --package-manifest ./package-versions.zip`. Nothing leaves your machine.
What does the vg why command do?
`vg why <package>` traces a dependency through your git history: who added it, every version change since, and who made each one. If your latest `vg scan --vulns` found open vulnerabilities for that package, `vg why` lists them with the commit that introduced the affected version and how long you have been exposed.
What does the vg bisect command do?
`vg bisect <package> <constraint>` pinpoints the commit where a dependency crossed a version line. Where `vg why` narrates every version change, `vg bisect` answers one question: when did we cross this line? A bare version means "reached or surpassed" (`vg bisect lodash 4.17.21` equals `vg bisect lodash '>=4.17.21'`), or you can pass an explicit semver range. It reads the same offline lockfile history and reports the crossing commit — or tells you the line was never crossed and shows the latest version in history, so an unadopted fix is obvious.
Can vg bisect fail my build until a dependency is patched?
Yes. Add `--assert`: `vg bisect lodash 4.17.21 --assert` exits non-zero when the current version does not satisfy the constraint, so a CI step blocks the merge until the fix is adopted. Exit codes are 0 when the query resolves, 2 when `--assert` finds the constraint unsatisfied, 3 when the package has no version history, and 5 for an invalid version or range.
What does vg scan --full do?
`vg scan --full` runs a comprehensive scan in one command: the normal DriftScore, known-vulnerability detection (the same as `--vulns`), and, when a standards policy is committed, a banned-dependency report. It is the quickest way to get the complete picture without remembering individual flags.
See a real scan run
A replay of the actual CLI running against our test repositories — live progress, real findings, a genuine DriftScore. Nothing executes in your browser.