Generate a Human-Readable Drift Report with vg report

Scan output is useful, but most teams need a clean document they can attach to a PR, paste into a ticket, or email to a lead. vg report reads the artifacts that a scan produces and renders a human-readable drift report in Markdown, text, or JSON. This tutorial shows you how to scan, then generate and format that report.

Prerequisites

• Node.js 18+
• A project with a lockfile (npm, pnpm, yarn, or bun)
• The Vibgrate CLI installed

Steps

1. Install the Vibgrate CLI

npm i -g @vibgrate/cli

Prefer not to install? You can try a scan with npx @vibgrate/cli scan.

2. Run an initial scan

From your project root, run the default scan. Bare vg scans the current directory.

vg

The scan computes your DriftScore (0-100) and writes artifacts that vg report will consume.

3. Generate a Markdown report

vg report --format markdown

This renders a structured drift report: the overall DriftScore, risk levels, and the packages and signals driving your drift. Markdown is ideal for PR descriptions and wikis.

4. Switch the report format

Need plain text for a terminal or JSON for tooling? Set --format.

vg report --format json

JSON is the right choice when another script will read the report; Markdown and text are for humans.

5. Write the report to a file

Use --out to save the report instead of printing it.

vg report --format markdown --out drift-report.md

Commit this file or attach it to a release note so your DriftScore travels with the change.

6. Verify the report contents

Open the file and confirm the DriftScore and the top drift contributors are present.

vg report --format markdown --out drift-report.md

Verification

Confirm the report file exists and contains your DriftScore and risk breakdown. A successful vg report exits 0. If you piped the scan into a gate earlier, the report reflects the same numbers the gate evaluated.

Next Steps

• Push the same results to the dashboard: see "Push Scan Results to Vibgrate Cloud".
• Automate report generation on a schedule with "Schedule Recurring Drift Reporting".