JSPM

@vibgrate/cli
Continuous Upgrade Drift Intelligence for Node & .NET

Modern codebases don't break all at once — they decay silently. Node runtimes fall behind LTS. .NET frameworks approach end-of-life. Core dependencies lag multiple major versions. Upgrade cost compounds until it becomes a project in itself.

Vibgrate turns that invisible decay into a measurable signal. One CLI command gives you an Upgrade Drift Score (0–100), actionable findings, and a clear picture of where your upgrade debt lives.

Quick Start

Run instantly with npx — no install required:

npx @vibgrate/cli scan

Or install as a dev dependency:

npm install -D @vibgrate/cli

Then scan your project:

npx vibgrate scan

Why npx? Installing with -D places the binary in node_modules/.bin/, which isn't on your system PATH. Use npx to run it, or add a script to your package.json:

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

Then run npm run drift. Alternatively, install globally with npm install -g @vibgrate/cli to use vibgrate directly.

That's it. You'll see a full drift report in seconds.

What You Get

    ╭───╮➜
   ╭┤◉ ◉├╮  V I B G R A T E
   ╰┤───├╯  Drift Intelligence Engine v1.x.x
    ╰───╯

╔══════════════════════════════════════════╗
║        Vibgrate Drift Report             ║
╚══════════════════════════════════════════╝

  Drift Score:  72/100
  Risk Level:   LOW
  Projects:     3
  VCS:          git main a1b2c3d

  Score Breakdown
    Runtime:      ████████████████████ 100
    Frameworks:   ████████████████░░░░  78
    Dependencies: ██████████████░░░░░░  64
    EOL Risk:     ████████████████████ 100

  ── my-api (node) src/api
     Runtime: 20.11.0 (current)
     Frameworks:
       NestJS: 10.3.0 → 11.0.0 (1 behind)
     Dependencies:
       42 current  8 1-behind  3 2+ behind

  ── web-app (node) src/web
     Runtime: 20.11.0 (current)
     Frameworks:
       React: 18.2.0 → 19.0.0 (1 behind)
     Dependencies:
       31 current  5 1-behind  2 2+ behind

  Tech Stack
    Frontend: React, Tailwind CSS
    Bundlers: Vite
    Testing: Vitest, Playwright
    Lint & Format: ESLint, Prettier

  Services & Integrations
    Cloud: AWS SDK v3
    Databases: PostgreSQL

  TypeScript
    v5.4.2 · strict ✔ · ESM · target: ES2022

  Build & Deploy
    CI: GitHub Actions
    Docker: 2 Dockerfiles (node:20-alpine)
    Package Managers: pnpm

  Security Posture
    Lockfile ✔ · .env ✔ · node_modules ✔

  Dependency Graph
    pnpm-lock.yaml: 312 unique, 487 installed
    5 duplicated packages

  Findings (2 warnings, 1 note)
    ⚠ Framework "NestJS" is 1 major version(s) behind
      framework/outdated in src/api/package.json
    ⚠ 12% of dependencies are 2+ major versions behind
      dependency/outdated in src/api/package.json
    ℹ TypeScript target is ES2022
      ts/target in tsconfig.json

╔══════════════════════════════════════════╗
║        Top Priority Actions              ║
╚══════════════════════════════════════════╝

  1. Upgrade NestJS 10.3.0 → 11.0.0 in my-api
     1 major version behind. Major framework drift increases
     breaking change risk and blocks access to security fixes.
     ./src/api
       NestJS: 10.3.0 → 11.0.0 (1 behind)
     Impact: +5–15 points (framework score)

  2. Reduce dependency rot in my-api (42% severely outdated)
     3 of 53 dependencies are 2+ majors behind. Run `npm outdated`
     and prioritise packages with known CVEs.
     ./src/api
       express: 3.4.0 → 5.0.0 (2 majors behind)
       lodash: 3.10.1 → 4.17.21 (1 major behind)
       ... and 1 more
     Impact: +5–10 points (dependency score)

  Scanned at 2026-02-16T00:00:00.000Z · 1.2s · 48 files scanned

Key Features

Upgrade Drift Score

A single 0–100 number that tells you how upgrade-ready your codebase is. Computed from runtime lag, framework versions, dependency age distribution, and EOL proximity. Deterministic and comparable across repos.

Multi-Platform Scanning

Works across Node.js/TypeScript and .NET projects in the same scan. Detects package.json, .sln, and .csproj files recursively.

CI-Native

Designed to live in your build pipeline. Returns meaningful exit codes, produces SARIF output for GitHub Code Scanning and Azure DevOps, and requires zero configuration to get started.

Ten Extended Scanners

Beyond the core drift score, Vibgrate runs a suite of extended scanners — all optional, all privacy-safe:

Baseline & Delta Tracking

Take a baseline snapshot, then measure drift over time:

npx vibgrate baseline .
npx vibgrate scan --baseline .vibgrate/baseline.json

Multiple Output Formats

Dashboard Upload (Optional)

Push scan results to the Vibgrate Dashboard for trend analysis, cross-repo comparison, and team-wide visibility. Upload is always opt-in — the CLI provides full value offline.

The easiest way is to combine scan and push in a single command:

VIBGRATE_DSN="..." npx @vibgrate/cli scan --push

Or pass the DSN directly:

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

You can also push a previously generated artifact separately:

VIBGRATE_DSN="..." vibgrate push

Get your DSN: Sign up at vibgrate.com and your workspace will be created automatically with a ready-to-paste code snippet containing your DSN.

CI Integration

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

Setup: Add your DSN as a repository secret named VIBGRATE_DSN under Settings → Secrets and variables → Actions. Get your DSN from vibgrate.com — it's generated automatically when you create a workspace.

Azure DevOps

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

Works in any CI environment. No login required. No configuration needed.

Configuration

Optionally create a vibgrate.config.ts to customise thresholds and scanner toggles:

vibgrate init

import type { VibgrateConfig } from '@vibgrate/cli';

const config: VibgrateConfig = {
  exclude: ['legacy/**'],
  thresholds: {
    failOnError: {
      eolDays: 180,
      frameworkMajorLag: 3,
      dependencyTwoPlusPercent: 50,
    },
  },
};

export default config;

Privacy First

Vibgrate is designed to be safe to run on any codebase:

• No source code is read — only package.json, tsconfig.json, lockfiles, and project manifests
• No secrets are scanned — ever
• No git history, authors, or commit messages — only HEAD SHA and branch name for traceability
• No data leaves your machine unless you explicitly run vibgrate push or vibgrate scan --push
• No login required — works fully offline

.gitignore

The .vibgrate/ directory contains ephemeral scan results and should not be committed to version control. Add it to your .gitignore:

# Vibgrate scan results (do not commit)
.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.0.0
• Works on macOS, Linux, and Windows

Full Documentation

See DOCS.md for the complete reference — all commands, all flags, configuration options, extended scanner details, CI examples, and more.

Links

• Website
• Documentation

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