Overview
vg fix reads your drift — the gap between the versions you run and the latest stable releases — and returns three ranked upgrade plans, scored on real-world exploitability. It answers the question a plain outdated-dependency list can't: which upgrade should you do first?
Printing plans, previewing one plan, and applying are separate steps. --no-apply prints the plans and never touches the project. --dry-run previews the plan from --plan, or the recommended plan when --plan is omitted, and never prompts. With several plans and no --plan, --dry-run previews the recommended one. --yes applies the recommended plan. --plan <tier> applies that tier. A single plan in text output is applied directly. Several plans on a terminal are listed for you to choose. Several plans with no terminal are left unapplied until you pass --yes or --plan.
Hosted capability. Drift scoring and the code map are free and local. The ranked planner runs on Vibgrate's servers, so vg fix needs a DSN: --dsn, then VIBGRATE_DSN, then the DSN saved by vg login. It sends dependency names and versions, and aggregate usage signals (how widely each package is imported, and which symbols those imports use when the CLI can read them). When available, the request also includes the repository name and commit. Your source stays on your machine. --no-apply and --dry-run still call the planner. They do not run the package manager. Applying does, and that install reaches the registries the package manager is configured to use. In CI, set VIBGRATE_DSN from the secret store. Do not paste a token into the workflow or a committed env file.
Usage
vg fix
Analyze the current directory. Pass a path to analyze elsewhere: vg fix packages/api.
The three plans
Each plan is an ordered set of upgrades. The text report names:
- how many drifted dependencies were analyzed, and whether the pass was preflight-only or included deep analysis of major upgrades
- a line when any package is on the CISA KEV list, including the peak EPSS when the planner has one
- one block per plan that actually contains upgrades: Low-risk, Balanced, or Full, marked when it is the recommendation, with a risk score out of 100, the upgrade count, the advisories that plan closes, and the DriftScore that plan would land on
- a recommendation line with the planner's rationale
There is no sample transcript on this page. Those numbers come from the hosted planner for your repository, and the CLI cannot replay a plan without a login.
The report labels the tiers Low-risk, Balanced, and Full. --plan takes the tier id, not that label: safe is Low-risk, balanced is Balanced, and aggressive is Full. Any other value is an error that names those three ids. When two tiers list the same upgrades, the command keeps the lower-risk plan and accepts the other id as a name for that plan.
Scored on exploitability, not just severity
The ranking layers two public signals on top of advisory data, so the queue reflects what is actually happening in the wild:
- CISA KEV — the Known Exploited Vulnerabilities catalog. A flaw on this list is being exploited now.
- FIRST EPSS — the Exploit Prediction Scoring System, a probability of near-term exploitation.
A known-exploited, high-EPSS package outranks a higher-CVSS flaw that no one has ever weaponized.
It re-scans so the plan is current
If a manifest or lockfile changed since your last scan, vg fix re-runs the drift scan first, so recommendations describe the code you have now — not a stale snapshot. That scan contacts package registries for current versions.
Preview, then apply
vg fix --no-apply
vg fix --dry-run
vg fix --plan balanced --dry-run
vg fix --yes
vg fix --plan safe --yes
vg fix --no-apply prints the plans and never touches the project. vg fix --dry-run previews the tier you name with --plan and never prompts. With several plans and no --plan, it previews the recommended one. With only one plan that has upgrades, it previews that plan. It does not run the package manager. vg fix --yes applies the recommended plan. vg fix --plan safe applies the Low-risk tier (safe).
In CI, set VIBGRATE_DSN from the secret store:
- name: Apply the low-risk plan
env:
VIBGRATE_DSN: ${{ secrets.VIBGRATE_DSN }}
run: vg fix --plan safe --yes
Do not paste a token into the workflow, onto the command line, or into a committed env file.
Applying a plan runs your project's own package manager, which reaches the registries that manager is configured to use. An advisory stays open when its upgrade does not land: blocked by policy, blocked by a peer conflict, no fixed version is published, or the install fails. A failed install restores the manifest and lockfile. --format json and --format md print a report and do not apply. The command exits non-zero if an upgrade fails.
Gate CI on exploitability
--fail-on-vulns exits non-zero when the recommended plan would still leave an advisory at or above the given severity unresolved:
vg fix --no-apply --fail-on-vulns high
Options
| Flag | Description |
|---|---|
--plan <tier> | Apply safe, balanced, or aggressive with no prompt (report labels Low-risk, Balanced, and Full). With --dry-run, preview that tier instead |
--no-apply | Print the plans and stop. Never modifies the project |
--dry-run | Preview the --plan tier. Never prompts. With several plans and no --plan, previews the recommended one. With only one plan that has upgrades, previews that plan |
--yes | Apply the recommended plan with no prompt |
--fail-on-vulns <severity> | Exit non-zero if an advisory at/above low|moderate|high|critical is left unresolved |
--format <format> | Output format: text (default), json, or md |
--in <file> | Scan artifact to read (default .vibgrate/scan_result.json) |
--dsn <dsn> | DSN. Checked before VIBGRATE_DSN, which is checked before the DSN saved by vg login |
--region <region> | Data-residency region (us, eu) |
Related
- vg scan — the drift scan that feeds the planner
- vg scan --vulns — the vulnerability data behind the ranking
- DriftScore — the 0–100 metric each plan moves