Overview
Getting started with Vibgrate takes less than 5 minutes. This guide walks you through installation, your first scan, and the recommended adoption path.
Quick Start: Run npx @vibgrate/cli scan in any project directory to see your drift score immediately.
Installation
Option 1: npx (Recommended for One-off Scans)
# No installation required - runs directly
npx @vibgrate/cli scan
Option 2: Global Installation
# Install globally for repeated use
npm install -g @vibgrate/cli@latest
# Now available as a command
vg scan
Option 3: Project Dependency
# Add to your project's devDependencies
npm install --save-dev @vibgrate/cli@latest
# Run via npm scripts or npx
npx @vibgrate/cli scan
Choosing a Rollout Model
Most teams adopt Vibgrate in two phases:
| Phase | Mode | Purpose | Command |
|---|---|---|---|
| 📊 Phase 1 | One-off scan | Establish baseline, identify priorities | npx @vibgrate/cli scan |
| 🔄 Phase 2 | CI integration | Continuous governance, prevent regression | npx @vibgrate/cli scan --fail-on error |
Tip: Start with one-off scans to understand your current state. Add CI integration once you've established a baseline and remediation plan.
End-to-End Workflow
Step 1: Run Initial Scan
# Scan your repository
npx @vibgrate/cli scan
# Example output:
# ✓ Discovered 4 projects
# ✓ Node.js: 3 projects | .NET: 1 project
# ✓ DriftScore: 67/100
Step 2: Initialize and Save Baseline
# Create .vibgrate directory and config
npx @vibgrate/cli@latest init
# Save current state as baseline
npx @vibgrate/cli@latest baseline
What's a baseline? A snapshot of your current drift state. Future scans compare against this baseline to detect regression.
Step 3: Review the Report
# Generate human-readable report
npx @vibgrate/cli@latest report --format md
# Or export for tooling
npx @vibgrate/cli@latest report --format json
npx @vibgrate/cli@latest report --format sarif
Step 4: Integrate with CI
# Add to your CI pipeline with enforcement thresholds
npx @vibgrate/cli scan \
--baseline .vibgrate/baseline.json \
--drift-budget 40 \
--drift-worsening 5 \
--fail-on error
| Flag | Purpose |
|---|---|
--baseline | Compare against saved baseline |
--drift-budget | Maximum allowed drift score (0-100) |
--drift-worsening | Maximum allowed increase from baseline |
--fail-on | Exit with error code when threshold exceeded |
Expected Results
After completing the workflow, your team will have:
| Outcome | Benefit |
|---|---|
| 📈 Stable score trend | Track improvement over time, not just point-in-time snapshots |
| 🚨 Early CI failures | Catch drift regression before it reaches production |
| 📄 Export-ready reports | Markdown, JSON, SARIF for engineering and governance |
| 🎯 Prioritized roadmap | Clear list of upgrade priorities by impact |
Exit Codes
Understanding exit codes is essential for CI integration:
| Code | Meaning | Action |
|---|---|---|
0 | Success, no threshold violations | Pipeline continues |
1 | CLI error (invalid args, scan failure) | Debug command |
2 | Drift threshold exceeded | Block merge, address findings |
Project Structure
After initialization, your project will contain:
your-project/
├── .vibgrate/
│ ├── baseline.json # Saved drift baseline
│ ├── scan_result.json # Latest scan output
│ └── config.ts # Vibgrate configuration
├── package.json
└── ... (your code)
Next Steps
- How It Works — Understand the scanning architecture
- DriftScore Explained — Learn what the score means
- CI Integration — Set up automated governance
- Baselines & Fitness Functions — Configure thresholds