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.

Quick start with AI assistants

Paste this prompt into your AI coding tool (GitHub Copilot, Cursor, Claude, etc.) to get started:

Set up Vibgrate for upgrade drift tracking:
1. Install: npm install -g @vibgrate/cli@latest
2. Create DSN: npx vibgrate dsn create --workspace new
3. Save DSN: echo 'export VIBGRATE_DSN="<dsn>"' >> ~/.zshrc && source ~/.zshrc
4. Scan: npx vibgrate scan . --push
Then explain my drift score and top 3 upgrade priorities.

See docs/QUICKSTART-PROMPT.md for the full onboarding prompt.

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, .vbproj)
• 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
• 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).
• Additional commercial scanner families are available and independently toggleable in vibgrate.config.*: runtimeConfiguration, dataStores, apiSurface, operationalResilience, assetBranding, and ossGovernance (see docs/commercial-grade-scanners.md).
• --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|md] [--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|new> [--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

Use the maintained templates in this package for copy-paste setup:

• examples/github-actions/driftscore-ci.yml (JSON artifact + drift gate)
• examples/github-actions/driftscore-sarif.yml (SARIF upload to code scanning)
• docs/ci/github-actions.md (integration notes)

- 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 CLI reference.

Copyright © 2026 Vibgrate. All rights reserved. See Vibgrate CLI License for terms.