vg init

Overview

vg init is your first step when adopting Vibgrate. It creates the project structure and configuration file needed for drift tracking.

Usage

vg init [path] [options]

Options

What It Creates

Running vg init sets up the following structure:

your-project/
├── .vibgrate/
└── vibgrate.config.ts

--baseline also writes .vibgrate/baseline.json. The first scan writes .vibgrate/scan_result.json; init does not.

Examples

Basic initialization

vg init

Creates .vibgrate/ and, when the file is missing, vibgrate.config.ts. It then prints the next two commands: scan, then baseline. The live replay is this run.

Pass a path to initialize somewhere else: vg init ./my-project.

Initialize with a baseline

vg init --baseline

After the directory and config, this runs the same baseline scan as vg baseline and writes .vibgrate/baseline.json. That scan talks to package registries, so it is not part of the offline replay.

Scan every pull request

vg init --ci github

Also writes .github/workflows/vibgrate.yml. It scans every pull request and push to main with the vibgrate/cli Action and uploads SARIF to GitHub Security. No Vibgrate account is needed. An existing workflow is never overwritten, and the workflow does not fail the build until you opt in: the fail-on and max-score lines are in the file, commented out.

Add --baseline and the workflow also points at .vibgrate/baseline.json, so each run reports the change since that baseline. Commit the baseline so CI can read it. Failing on worsening stays a commented-out max-worsening line. Unknown providers exit with a usage error before anything is written.

Non-interactive (CI)

vg init --yes
vg init --yes --baseline

--yes is the non-interactive form. The replay uses it without --baseline. Add --baseline when the job should also write the first baseline.

Generated configuration

vg init writes this vibgrate.config.ts when the file is not already there:

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

const config: VibgrateConfig = {
  // exclude: ['legacy/**'],
  // maxFileSizeToScan: 5_242_880, // 5 MB (default)
  // projectScanTimeout: 180, // 3 min per project (default, in seconds)
  thresholds: {
    failOnError: {
      eolDays: 180,
      frameworkMajorLag: 3,
      dependencyTwoPlusPercent: 50,
    },
    warn: {
      frameworkMajorLag: 2,
      dependencyTwoPlusPercent: 30,
    },
  },
};

export default config;

Alternative Config Formats

A project has one config file. Vibgrate reads the first one it finds, in this order, and never merges two:

YAML and JSON take exactly the same settings. vg doctor names any config file that is present but ignored.

Drift Budget and Review Settings

Two settings judge changes before they merge: driftBudget and review. Put them in .vibgrate/config.yml or vibgrate.config.json. The Vibgrate GitHub App and vg review --base read them from the base branch, so a pull request cannot loosen the rules it is checked against. They read those files as data and never run a .ts or .js config.

# .vibgrate/config.yml
exclude:
  - legacy/**

driftBudget:
  mode: warn              # warn (default), enforce, or shadow
  maxScore: 40            # DriftScore ceiling, 0-100
  maxWorseningPercent: 5  # how much one change may worsen drift
  agents:
    maxWorseningPercent: 0  # stricter limit for bot and coding-agent pull requests

review:
  enforcement: advisory   # advisory reports only; enforced gates at failOn
  failOn: fail            # none, fail, or needs_review
  targetPattern: layered  # the architecture you want: clean, layered, hexagonal, ...

--drift-budget and --drift-worsening still work. When you pass either flag, vg scan uses the flags and ignores driftBudget.

The instructions Review reads, such as .vibgrate/review/policy.md and .vibgrate/review/checks/*.md, stay as Markdown files. The older .vibgrate/review.toml is still read when the config has no review block.

Best Practices

Recommended .gitignore Addition

# Vibgrate artifacts
.vibgrate/scan_result.json
.vibgrate/*.sarif

Related Commands

• vg scan — Run drift analysis
• vg baseline — Create/refresh baselines
• Getting Started — Full adoption workflow