JSPM

@vibgrate/cli
Continuous Upgrade Drift Intelligence for engineering teams

Vibgrate gives you a clear answer to one question: How far behind is this repo, and what should we upgrade first?

In one command, you get:

• A deterministic Upgrade Drift Score (0–100)
• A clear risk level (Low / Moderate / High)
• Runtime + framework major-version lag
• Dependency age distribution + EOL proximity
• Priority actions for what to fix next

Supported ecosystems today: Node.js/TypeScript, .NET, Python, and Java.

Why teams adopt Vibgrate

Most systems do not fail all at once. They accumulate upgrade debt silently until migrations become expensive.

Vibgrate makes drift measurable and repeatable:

• Developers run a one-off scan to understand current debt.
• CI pipelines run every PR/build to stop regression.
• Engineering leaders track trends over time in the dashboard (optional push).

One-off scan vs CI-integrated drift tracking

Recommended rollout: start with a one-off scan now, then add Vibgrate to CI this week.

Quick start

Run instantly (no install):

npx @vibgrate/cli scan .

Or install locally:

npm install -D @vibgrate/cli
npx vibgrate scan .

Add an npm script:

{
  "scripts": {
    "drift": "vibgrate scan ."
  }
}

Local binaries are in node_modules/.bin, so use npx (or an npm script) unless you install globally.

What the report contains

Every scan includes:

• Overall score and risk level
• Score breakdown (runtime, frameworks, dependencies, EOL)
• Per-project details across Node, .NET, Python, and Java
• Actionable findings (warnings/errors/notes)
• Top Priority Actions ranked by likely impact

We keep output plain and operational: easy to convert into backlog items and CI policy.

New capabilities included in this release

1) Multi-language workspace scanning

Vibgrate recursively scans mixed repositories and supports:

• Node.js / TypeScript (package.json)
• .NET (.sln, .csproj)
• Python (requirements.txt, pyproject.toml style ecosystems)
• Java (pom.xml, Gradle-style manifest ecosystems)

2) Extended scanner suite

Beyond core drift scoring, Vibgrate can also detect:

• Platform matrix and native-module risk
• Dependency risk, graph duplication, and phantom dependencies
• Full tooling inventory and build/deploy surface
• TypeScript modernity and breaking-change exposure
• File hotspots and structural security posture
• Security scanner readiness and local policy coverage checks
• Service dependency mapping (cloud, db, auth, messaging, etc.)
• Architecture layer mapping
• Code-quality metrics (complexity, nesting, cycles, god files)
• OWASP category mapping from security findings

3) SBOM Export & Delta

Vibgrate now emits rich dependency inventory data in the JSON artifact, including lockfile-derived package graphs, duplicate-version hotspots, and phantom dependencies.

This gives teams practical SBOM-ready supply-chain visibility for governance workflows while keeping the scan fast and CI-friendly.

Use scan artifacts as operational SBOM intelligence in either CycloneDX or SPDX format:

npx vibgrate sbom export --format cyclonedx --out sbom.cdx.json
npx vibgrate sbom export --format spdx --out sbom.spdx.json

Compare two scan artifacts to see dependency additions/removals/version changes between releases:

npx vibgrate sbom delta --from .vibgrate/baseline.json --to .vibgrate/scan_result.json --out sbom-delta.txt

This keeps reports plain and actionable, so teams can go from scan output to backlog tasks quickly.

4) Baseline, Drift Budgets & Fitness Gates

Take a baseline snapshot, then enforce dependency drift fitness functions in CI:

npx vibgrate baseline .
npx vibgrate scan --baseline .vibgrate/baseline.json --drift-worsening 5 --drift-budget 40

• --drift-budget <score> fails the build if absolute drift score exceeds your budget.
• --drift-worsening <percent> fails the build if drift worsens by more than X% relative to baseline.

This turns drift scoring into a quality gate instead of passive reporting.

Privacy & offline-first workflows

Vibgrate now supports explicit privacy controls:

• --no-local-artifacts prevents writing .vibgrate/*.json files to disk.
• --max-privacy enables a hardened profile (suppresses local artifact writes and disables high-context scanners such as UI-purpose evidence and architecture/code-quality enrichment).
• --offline disables live registry/network lookups and never uploads scan results.
• --package-manifest <file> accepts a local JSON or ZIP package-version manifest so drift can still be calculated offline. Download the latest bundle at https://github.com/vibgrate/manifests/latest-packages.zip.

Example:

vibgrate scan . --offline --package-manifest ./package-versions.zip --max-privacy --format json --out scan.json

When offline mode runs without a package manifest, package freshness is marked as unknown and drift scoring is necessarily partial.

Core commands

vibgrate scan [path] [--format text|json|sarif] [--out <file>] [--fail-on warn|error] [--offline] [--package-manifest <file>] [--no-local-artifacts] [--max-privacy]
vibgrate baseline [path]
vibgrate report [--in <artifact.json>] [--format md|text|json]
vibgrate push [--dsn <dsn>] [--file <artifact.json>] [--strict]
vibgrate init [path] [--baseline] [--yes]
vibgrate dsn create --workspace <id> [--region us|eu] [--write <path>]

Command examples with expected results

# 1) Scan current repo (text output)
npx @vibgrate/cli scan .

Expected result:

• Prints overall score + risk level
• Shows detected projects (Node/.NET/Python/Java)
• Writes .vibgrate/scan_result.json unless disabled

# 2) Scan with CI gating
npx @vibgrate/cli scan . --fail-on error --drift-budget 40

Expected result:

• Exit code 0 when no error-level finding and score is within budget
• Exit code 2 when the configured gate is exceeded

# 3) Offline scan using local package-version bundle
npx @vibgrate/cli scan . --offline --package-manifest ./latest-packages.zip --format json --out scan.json

Expected result:

• No registry/network lookup
• JSON artifact in scan.json
• Package freshness may be marked unknown if manifest lacks entries

# 4) Export SBOM and compare two runs
npx @vibgrate/cli sbom export --format cyclonedx --out sbom.cdx.json
npx @vibgrate/cli sbom delta --from .vibgrate/baseline.json --to .vibgrate/scan_result.json --out sbom-delta.txt

Expected result:

• CycloneDX (or SPDX) JSON export file
• Human-readable delta report with added/removed/changed dependencies

Common usage:

# Standard scan
npx @vibgrate/cli scan .

# CI-ready SARIF output
npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error

# Baseline and compare drift deltas over time
npx @vibgrate/cli baseline .
npx @vibgrate/cli scan . --baseline .vibgrate/baseline.json

CI integration (recommended)

GitHub Actions

- name: Vibgrate scan
  env:
    VIBGRATE_DSN: ${{ secrets.VIBGRATE_DSN }}
  run: npx @vibgrate/cli scan . --push --format sarif --out vibgrate.sarif --fail-on error

- name: Upload SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: vibgrate.sarif

Azure DevOps

- script: npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
  displayName: Vibgrate scan

GitLab CI

vibgrate:
  image: node:20
  script:
    - npx @vibgrate/cli scan . --push --fail-on error

Dashboard upload (optional)

The CLI is fully useful offline. Upload is opt-in.

If you want trend analysis across runs/repos, push scan artifacts with a DSN:

VIBGRATE_DSN="vibgrate+https://<key_id>:<secret>@us.ingest.vibgrate.com/<workspace_id>" \
  npx @vibgrate/cli scan . --push

You can also upload an existing artifact:

VIBGRATE_DSN="..." npx @vibgrate/cli push --file .vibgrate/scan_result.json

Get your DSN from vibgrate.com. For CI, always store it as a secret (never commit it).

Privacy and safety

• No data leaves your machine unless you run --push / vibgrate push
• Core drift analysis is based on manifests/configs
• Works without login and without SaaS dependencies
• .vibgrate/ artifacts are local outputs and may be gitignored

Add this to .gitignore:

.vibgrate/

The CLI writes per-project score files to .vibgrate/ inside each detected project directory. These are regenerated on every scan and should not be copied between environments.

Commands

Requirements

• Node.js 20+
• macOS, Linux, Windows

Full docs

For full command reference, configuration, scanner details, and advanced examples, see DOCS.md.

Copyright © 2026 Vibgrate. All rights reserved. See LICENSE.md for terms.