{ "markdown": "

\n \"Vibgrate\"\n

\n\n

\n @vibgrate/cli\n
\n Local codebase intelligence for AI coding agents — graph, drift, and version-correct docs on your machine\n

\n\n

\n \"npm\n \"npm\n \"Vibgrate\n \"live\n \"VG\n \"Vibgrate\n \"Apache\n \"node\n

\n\n`vg` answers three questions for any repo:\n\n1. **What is this codebase?** — A deterministic [code graph](https://vibgrate.com/graph): call trees, import paths, impact surfaces, dependency facts.\n2. **How far behind is it?** — A ranked **[DriftScore](https://vibgrate.com/driftscore)** (0–100) with runtime/framework lag, dependency age and EOL proximity, and a prioritized fix list. Exposure is scored separately as a **[RiskScore](https://vibgrate.com/riskscore)**; the two together are the **[DriftRisk Index](https://vibgrate.com/driftrisk)**. The full methodology — formulas, sources, and limitations — is published as a [whitepaper](https://vibgrate.com/whitepapers/software-risk-and-drift-scoring-methodology) under CC BY 4.0 (DOI [10.5281/zenodo.21336304](https://doi.org/10.5281/zenodo.21336304)).\n3. **Can we fix it here?** — [**VG Code**](#vg-code--write-the-change-not-just-the-report), a coding agent whose search tool is the code graph, not a grep — in your terminal as `vg code` and as the VG Code panel in [Vibgrate for VS Code](https://vibgrate.com/vscode) — plus `vg fix`, ranked upgrade plans it can apply.\n\nEverything runs **on your machine**. No API key, no network call, no data leaving your repo unless you explicitly push. The `vibgrate` command is an alias for `vg` — they are interchangeable.\n\n---\n\n## See it run\n\n

\n \n \"Animated\n \n

\n\n

\n A real vg scan replay — drift score, breakdown, and ranked priorities in one command. Animation plays right here on GitHub; nothing runs in your browser.\n

\n\n

\n ▶ Try the live, interactive CLI simulator →
\n Step through every command (scan, build, ask, why, …) against real sample repos.\n

\n\n---\n\n## Try it in 10 seconds\n\nNo install, no signup:\n\n```bash\nnpx @vibgrate/cli scan # drift score + upgrade priorities\nnpx @vibgrate/cli build # build the code graph\nnpx @vibgrate/cli ask \"what does AuthService do?\"\nnpx @vibgrate/cli code # a coding agent — it asks before every edit\n```\n\nInstall for repeat runs:\n\n```bash\nnpm install -D @vibgrate/cli\nnpx vg scan # vg is the primary command; vibgrate is an alias\n```\n\n> Local binaries live in `node_modules/.bin` — use `npx vg` (or an npm script) unless you install globally.\n\n---\n\n## Use it with your AI assistant\n\n`vg serve` starts **[Vibgrate AI Context](https://vibgrate.com/library)** — a local-first [MCP](https://vibgrate.com/glossary/model-context-protocol) server that\ngives any MCP-compatible assistant (Claude, Cursor, Windsurf, Copilot, Gemini\nCLI, …) your code map, **offline drift**, local models, and **version-correct\nlibrary docs**, all from your machine (no account, nothing uploaded; thin\nlocal docs fall through to the hosted catalog unless you pass `--local`). No\ncontext-window stuffing, no hallucinated APIs. The map **keeps itself fresh**:\nwhen files change — including edits the assistant itself just made — the next\ntool call rebuilds it incrementally before answering, with no watcher or\ndaemon involved.\n\nWire it up in one command:\n\n```bash\nvg install # interactive: pick your assistant(s) and done\nvg install --all # install for every detected assistant at once\n```\n\nThis writes the MCP config for your chosen tool(s) and installs a skill that teaches the assistant how to query the graph. After reloading your assistant you get graph-aware answers: call trees, impact analysis, drift findings, version-correct library docs — all from local data. The token savings are measured and published, methodology included, at [vibgrate.com/cli/benchmarks/token-savings](https://vibgrate.com/cli/benchmarks/token-savings).\n\nBrowse all 21+ supported assistants and their skill descriptions at **[vibgrate.com/skills](https://vibgrate.com/skills)**.\n\n## Tools\n\n`vg serve` exposes 19 MCP tools:\n\n- **orient** — start here: project overview, entry points, where to look first.\n- **search_symbols** — find a symbol by name or literal string.\n- **query_graph** — find code by meaning: symptoms, relationships, what-breaks-if.\n- **get_node** — inspect one symbol: signature, callers, callees, area.\n- **find_path** — shortest connection between two symbols.\n- **impact_of** — blast radius of a change: dependents, files, covering tests, risk.\n- **tests_for** — which tests cover a symbol.\n- **get_graph_summary** — code map overview: counts, languages, top areas and hubs.\n- **list_areas** — code areas (communities) by size.\n- **list_hubs** — most-depended-on symbols.\n- **get_facts** — deterministic facts for a node (contract / invariant / characterization).\n- **guide_node** — cited standards and practices for a node (OWASP/CWE).\n- **check_drift** — offline dependency inventory with optional git who-added attribution.\n- **vuln_attribution** — who introduced each open vulnerability, exposure windows, CRA remediation metrics.\n- **list_vulnerabilities** — known vulnerabilities from the last `vg scan --vulns`: CVE, severity, CVSS, fixed version.\n- **upgrade_impact** — what breaks if you upgrade a package: major distance, import blast radius, vulns fixed.\n- **list_models** — local models on disk (Ollama / LM Studio / gguf).\n- **resolve_library** — resolve a library to its canonical id and the version your project uses.\n- **library_docs** — version-correct usage docs for a library, sliced to a token budget.\n\nPrefer the hosted server over your team's scan data? **[Vibgrate Cloud MCP](https://vibgrate.com/mcp)** connects your assistant to Vibgrate Cloud (OAuth 2.1, 51 tools).\n\n---\n\n## Understand any codebase\n\nBuild the graph once, query it continuously:\n\n```bash\nvg build # index the repo (incremental; re-run after changes)\nvg show src/auth/service.ts # what this file does, calls, and is called by\nvg ask \"where is rate limiting enforced?\"\nvg impact src/db/connection.ts # what breaks if this changes + tests to run\nvg path src/api/handler.ts src/db/query.ts # shortest call path between two files\nvg tree src/server.ts # call tree rooted at a node\nvg insights # overview: hubs, hotspots, untested paths\n```\n\nThe graph is byte-deterministic and reproducible — the same repo always produces the same graph on every machine.\n\n```bash\nvg share # make the graph committable + auto-updating for the team\nvg serve # start Vibgrate AI Context (local-first MCP: code map + drift + version-correct docs)\n```\n\n---\n\n## VG Code — write the change, not just the report\n\n**VG Code** is the coding agent inside Vibgrate CLI. Its search tool is the deterministic code graph — **not a grep, not embeddings over chunks** — and it runs on a local model or a hosted one, your choice.\n\n```bash\nvg code # guided: pick a model, then describe tasks\nvg code \"add a --timeout flag to the scan command\"\n```\n\n**Does it write to your disk?** Yes — through steps you approve, and only those. Read-only steps (search, read, list, impact) run without prompting; every edit and every command asks first. `--auto` runs the same loop with no prompts for CI. Without a terminal and without `--auto`, `vg code` refuses to start rather than writing unattended.\n\n**Two surfaces, one agent.** `vg code` is the terminal surface. The **VG Code panel** in [Vibgrate for VS Code](https://vibgrate.com/vscode) is the graphical one, and for most people it will be the one they live in: warm sessions between tasks, chat history, inline Approve / Reject cards with diffs, checkpoints, and @-mentions. The extension does not re-implement the agent — it runs the one shipped with this CLI over `--stream-json` and relays your decisions to it, so terminal, editor, and CI behave the same way.\n\n### Why an agent here, and not another chat window?\n\n- **Search is the graph.** `search_code` resolves symbols, callers, and callees from the map `vg build` produced — so the model gets the three functions that matter, not forty files that mention the word.\n- **Blast radius before the edit.** `graph_impact` tells the model what depends on a symbol *before* it changes it, and `vg tests` knows which tests to run after.\n- **Version-correct library docs.** `library_docs` pins to the version in your lockfile, so the model writes against the API you actually have.\n- **Invented identifiers are blocked, not flagged.** Before an edit is written, its replacement body is scanned against the graph's identifier trie. A symbol the graph does not know — and that is not already local to the target file — stops the write.\n- **Local models are first-class, hosted models are one flag away.** With a pulled model there is no account and no key, and Code Modes fit the model to the machine. When a task needs more, [Vibgrate Relay](https://vibgrate.com/relay) supplies hosted models on your Vibgrate account — no per-provider API keys — and falls back to your local model if it is unreachable.\n- **It adopts the MCP servers you already have.** `.mcp.json` (Claude Code), `.cursor/mcp.json`, and `.vscode/mcp.json` are read and merged with `.vibgrate/code.json`, which wins on a name clash.\n- **Cost is visible.** A token/$ meter after each task and on `/cost`; `vg savings` reports graph-backed calls per model.\n\n**Trade-off:** no model ships with the CLI, and VG Code is only as good as the model you point it at. A 7B local model is not a frontier model — it buys you privacy, offline inference, and no per-token cost. Relay buys you capacity at a per-token price. Pick the tier that matches the task; the graph grounding is the same either way.\n\n### A session, end to end\n\n```text\n VG Code · graph-grounded coding · v2026.x\n\n ✔ Code map built\n ✔ Model catalog loaded\n ◆ Ready — ollama/qwen2.5-coder:7b · graph 48213. Describe a task, or /help.\n\n code › add a --timeout flag to the scan command and use it\n\n → search_code(query: --timeout flag scan command)\n scanCommand (function) src/commands/scan.ts:12\n → graph_impact(symbol: runScan)\n 3 symbol(s) depend on runScan: …\n → edit_file(path: src/commands/scan.ts, …)\n ? Apply edit to src/commands/scan.ts? [Y/n] y\n ✔ edited src/commands/scan.ts\n → run_command(command: npm test -- scan)\n ? Run `npm test -- scan`? [y/N] y\n ✔ exit 0 … 12 passing\n\n ✔ added a --timeout flag to scan and covered it with tests\n +6 -1 across 1 file(s) · via ollama/qwen2.5-coder:7b\n```\n\nWhat happened, step by step:\n\n1. The code map is built or refreshed incrementally — only changed files re-parse.\n2. The model catalog loads and you pick a local model or a hosted provider. Before pulling a local model, a memory pre-flight compares its estimated footprint against available RAM/VRAM and refuses a model this machine cannot run.\n3. Vibgrate Graph (`vg serve`) starts as a child process for the life of the session and stops when you exit. Every graph call is attributed to VG Code and the model in use.\n4. The agent loops: search → read → assess impact → edit → run.\n5. You approve each mutating step, or it runs unattended under `--auto`.\n6. Edits land through a deterministic merge, so the change goes exactly where it was meant to.\n\n### Approval modes\n\n| Mode | Behavior |\n| --- | --- |\n| **Interactive** (default) | Read-only steps run freely. Every edit and every command asks first. |\n| **`--auto`** | No prompts. A denylist blocks catastrophic commands — filesystem wipes, `curl … \\| sh`, force-push, `sudo`. For CI and scripted runs. |\n| **`--single`** | One-shot: propose a diff and stop. No tool loop, no commands. Dry-run unless you pass `--apply --yes`. |\n\n`--max-steps ` caps the loop (default 24). `--worktree` runs the whole session in an isolated git worktree so nothing touches your main tree until you apply it.\n\n### Which model — local, or hosted through Relay\n\n**Code Modes** pick a local model that actually fits this machine, checked against your real RAM, VRAM, and disk before anything downloads:\n\n| Mode | Intent |\n| --- | --- |\n| **Spark** | Fast, small footprint — quick edits and tight memory |\n| **Flow** | Balanced default for day-to-day coding |\n| **Forge** | Heavier pack when you have headroom and want more capacity |\n\n```bash\nvg models # what's set, and what fits this machine\nvg models install flow # install the pack (--dry-run to preview)\nvg models pull qwen2.5-coder:7b\n```\n\n**[Vibgrate Relay](https://vibgrate.com/relay)** is the hosted tier that supplements those local models when a task needs more capacity than the machine has. One Vibgrate account and endpoint, a curated catalog of hosted models, per-token metering against prepaid credit — and no per-provider API keys to manage:\n\n```bash\nexport VIBGRATE_RELAY_TOKEN=… # Relay is then preferred, with local fallback\nvg code --provider vibgrate-relay --model \n```\n\nYou are not locked to it. `--provider` also takes `ollama`, `lmstudio`, `foundry-local`, `llama-cpp`, `openrouter`, `litellm`, `openai`, and `together`; those API keys are read from the environment only (`OPENROUTER_API_KEY` and friends), never passed as flags. With no `--provider`, `vg code` uses what you have already configured — Relay first if its token is set, then another hosted key, then a local model — and never dials an endpoint you did not set up. `--local` keeps it on-device.\n\n### Tools the agent has\n\n| Tool | What it does | Approval |\n| --- | --- | --- |\n| `search_code` | Search the code graph — symbols and relations, plus a literal sweep for exact phrases | free |\n| `read_file` / `list_files` | Read a file or line range; list files in the map | free |\n| `graph_impact` | Blast radius of changing a symbol | free |\n| `library_docs` | Version-correct docs for a dependency you actually have installed | free |\n| `edit_file` / `create_file` / `delete_file` / `apply_patch` | Change the working tree | **approved** |\n| `run_command` | Run tests, builds, anything else | **approved** |\n| `web_fetch` / `web_search` | Fetch or search the public web — untrusted, secret-redacted, size-capped | **approved** |\n| `browser_*` / `read_notebook` / `spawn_subagent` | Drive a browser, work in Jupyter notebooks, delegate a sub-task | **approved** |\n| `mcp____` | Tools from your configured MCP servers | free if read-only, else **approved** |\n\n### In-session commands\n\n| Command | What it does |\n| --- | --- |\n| `/undo` | Revert the files changed by the last task |\n| `/diff` | Show the last change |\n| `/model` | Switch model without leaving the session |\n| `/cost` | Running token and dollar cost (local models are free) |\n| `/compact` | Condense the session so far into one checkpoint recap |\n| `/help` / `/exit` | List commands / quit |\n\n### Where state lives\n\n| On disk | In the session |\n| --- | --- |\n| The code map (`.vibgrate/`), gitignored | Conversation and step history |\n| Your config (`.vibgrate/code.json`) | The `/undo` stack |\n| The edits themselves — local and git-reversible | The token/$ meter |\n| Session store, so `--continue` can resume | The `vg serve` child process |\n\n`--continue` resumes your most recent session: it recaps what was already done for the model and restores `/undo`.\n\n### Configure once\n\n`.vibgrate/code.json` — flags still override:\n\n```json\n{\n \"provider\": \"ollama\",\n \"model\": \"qwen2.5-coder:7b\",\n \"testCommand\": \"npm test\",\n \"auto\": false,\n \"denyCommands\": [\"deploy\", \"kubectl\\\\s+delete\"],\n \"maxSteps\": 24,\n \"mcpServers\": {\n \"playwright\": { \"command\": \"npx\", \"args\": [\"-y\", \"@playwright/mcp\"] }\n }\n}\n```\n\nFull key reference — including `securityTier`, `capsule`, and `modelProfile` — is in [DOCS.md](./DOCS.md#vg-code).\n\n### Safety\n\n- Secrets files (`.env`, `.npmrc`, `.netrc`, key material) are never read into a prompt, and credential shapes are redacted from any file the agent does read.\n- Under `--auto`, a denylist blocks catastrophic commands. Interactively you see and approve every command yourself.\n- Every change is local and git-reversible. `/undo` reverts the last task; `--worktree` keeps the whole session off your main tree.\n- Web and browser results are treated as untrusted content, never as instructions.\n\n---\n\n## Measure and manage upgrade drift\n\n```bash\nvg scan # drift score + risk level + ranked priorities\nvg scan --push # same, and upload to Vibgrate Cloud for trend tracking\nvg baseline # snapshot current drift for regression gating\nvg report # generate a report from a saved scan artifact\n```\n\nOne scan gives you:\n\n- **Overall score** (0–100) and risk level (**Low / Moderate / High**)\n- **Score breakdown** — runtime, frameworks, dependencies, EOL\n- **Per-project detail** across Node.js/TypeScript, .NET, Python, and Java\n- **Actionable findings** ranked by likely impact\n- **[SBOM](https://vibgrate.com/glossary/sbom) export** (CycloneDX / SPDX)\n- **Known vulnerabilities** (opt in with `--vulns`) — severity, CVSS, the fixing version, and, in a git repo, who introduced them\n\n---\n\n## Find known vulnerabilities and who introduced them\n\n`vg scan --vulns` checks your installed dependencies against the public [OSV](https://vibgrate.com/glossary/osv) database and reports each known vulnerability with its severity, CVSS score, and the version that fixes it — as text, JSON, or SARIF. Add `--package-manifest` to run it fully offline from a local advisory bundle.\n\n```bash\nvg scan --vulns # drift score + known vulnerabilities\nvg scan --full # drift + vulnerabilities + a banned-dependency report\n```\n\nIn a git repository, every finding is attributed from history: who introduced the vulnerable version, in which commit, and how long you have been exposed. Those exposure windows roll up into per-severity time-exposed and SLA-breach metrics, framed around the [EU Cyber Resilience Act (CRA)](https://vibgrate.com/cra) — so \"are we fixing things fast enough?\" has a number.\n\nThat answers the question about *this checkout*. For the question a regulator asks — which **shipped** products contain it — see [Vibgrate Evidence](#vibgrate-evidence--answer-which-shipped-products-contain-this) below.\n\n```bash\nvg why lodash # who added a dependency, every version since, and any open vulnerabilities\nvg bisect lodash 4.17.21 # the commit where lodash crossed a version line (e.g. reached the fix)\n```\n\nDetection and attribution span the whole npm ecosystem (npm, pnpm, yarn) plus pip/poetry, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle — read from each project's lockfile, so it works whatever you build in.\n\nYour AI assistant sees this too: `vg serve` exposes `list_vulnerabilities`, `vuln_attribution`, and an `upgrade_impact` tool that tells an agent what an upgrade will cost — version distance, how many files import the package, the vulnerabilities it fixes, and (online, opt in) the breaking-change notes between your version and the latest.\n\n---\n\n## Vibgrate Evidence — answer \"which shipped products contain this?\"\n\nA scanner tells you about the code in front of you. A regulator asks about the code you **shipped** — eighteen months ago, at version 3.2.1, into Germany and France, still in its support window. **[Vibgrate Evidence](https://vibgrate.com/evidence)** answers that question as a signed artifact a third party can verify offline, with no account and no network.\n\nIt produces **evidence, not a verdict.** It will not tell you that you are compliant, and it is not legal advice. It gives you a defensible, reproducible answer and the audit trail behind it; the determination and the filing stay yours.\n\n```bash\nvg evidence init --regime cra # who files, and to which coordinator\nvg evidence product add \"Acme Gateway\" --markets DE,FR --in-scope\nvg evidence release acme-gateway 3.2.1 --from sbom.cdx.json --ship-date 2025-02-14\nvg evidence exposure CVE-2025-12345 --bundle ./ev # signed answer, exit code for CI\n```\n\n### Why freeze a manifest instead of scanning again?\n\n- **Ships are immutable; your tree is not.** `exposure` matches against the manifest **frozen at ship time**, not `HEAD`. Re-scanning today tells you what you would ship now, which is not the question asked.\n- **It refuses to guess.** A product bound to a release with no frozen manifest comes back `undetermined` **with a reason**, never a confident-looking `not affected`. That distinction is the whole value of the artifact.\n- **Jurisdiction-neutral by design.** Reporting duties are modeled as **regimes**: the EU CRA (`--regime cra`, applies from **11 September 2026**) and DORA incident reporting (`--regime dora-incident`) ship today. A new jurisdiction is a regime profile, not a new command or a new tool.\n- **No model touches a figure.** Nothing in the evidence path is generated by a language model. Every number is computed from frozen manifests and advisory data.\n- **Offline end to end.** `--offline` with a local advisory file needs no network, and `vg evidence verify` works on a machine that has never heard of Vibgrate.\n\n**Trade-off:** the answer is only as good as the manifests you froze. Evidence cannot reconstruct what you shipped before you started recording it — a release you never froze is `undetermined`, permanently. The value compounds from the day you start, which is the argument for starting now rather than in September.\n\n### The lifecycle\n\n| Step | Command | What it does |\n| --- | --- | --- |\n| 1. Set up | `vg evidence init` | Org, coordinator CSIRT, and the person with filing authority |\n| 2. Register | `vg evidence product add` | A product with digital elements — markets, classification, scope rationale |\n| 3. Freeze | `vg evidence release` | Pin a shipped version to an immutable component manifest, from an SBOM or scan |\n| 4. Ask | `vg evidence exposure ` | Which shipped products contain it, at which versions, in which markets, still in support |\n| 5. Prove | `vg evidence verify ` | Re-check the signed answer offline, on any machine |\n\nBetween those: `vg evidence readiness` is a deterministic gap report against the regime's obligations, `vg evidence regimes` lists the regimes and their clocks, `vg evidence drill` runs a timed rehearsal against a simulated advisory, `vg evidence watch` joins the CISA KEV catalog to your frozen manifests, `vg evidence pack` builds the submission pack a human pastes into the reporting platform, and `vg evidence export` writes an air-gapped bundle of everything.\n\n### What is in a bundle, and what \"verified\" means\n\n`--bundle ` writes `result.json`, a DSSE/Ed25519 in-toto attestation over it (`evidence.intoto.jsonl`), a `VERIFY.md` a third party can follow, and — with `--tsa ` — an RFC 3161 trusted-timestamp token (`timestamp.tsr`).\n\n`vg evidence verify` reports one of three honest states, and the middle one matters:\n\n| State | Meaning |\n| --- | --- |\n| `verified` | Signature checks, the signer is pinned to a trust root you supplied with `--pub`, **and** the result digest still matches |\n| `unverified` | Cryptographically intact and unmodified, but the signer is not pinned — real, and not yet trusted by you |\n| `failed` | Bad signature, or a `result.json` that no longer matches what was signed |\n\nExit codes make it a CI gate: **0** no exposure · **2** exposure found · **3** undetermined, needs manual review · **1** operational error.\n\nEvidence state lives in `.vibgrate/evidence/`. The Ed25519 signing key is minted on first use at `.vibgrate/attest-key.pem` (mode `0600`, with a `.pub` beside it) unless you point at your own with `VG_ATTEST_KEY` — back it up, and never commit it.\n\n---\n\n## Track drift over time → create a free workspace\n\nThe CLI is fully useful offline. When you want **trends across runs and repos** — so drift becomes a metric you manage, not a surprise you discover — push scans to a [Vibgrate Cloud](https://vibgrate.com/cloud) workspace:\n\n1. **Create a workspace** at **[dash.vibgrate.com](https://dash.vibgrate.com)** and copy your DSN.\n2. **Connect and push:**\n\n```bash\nVIBGRATE_DSN=\"vibgrate+https://:@us.ingest.vibgrate.com/\" \\\n vg scan --push\n```\n\nUpload is opt-in — nothing leaves your machine until you run `--push`. Store the DSN as a CI secret, never commit it.\n\n**[→ Create your workspace](https://dash.vibgrate.com)**\n\n---\n\n## CI integration\n\nDrop `vg` into any pipeline to turn drift scoring into a quality gate:\n\n```yaml\n# GitHub Actions — drift gate + SARIF upload\n- name: Vibgrate scan\n env:\n VIBGRATE_DSN: ${{ secrets.VIBGRATE_DSN }}\n run: npx @vibgrate/cli scan --push --format sarif --out vibgrate.sarif --fail-on error\n\n- name: Upload SARIF\n if: always()\n uses: github/codeql-action/upload-sarif@v3\n with:\n sarif_file: vibgrate.sarif\n```\n\nGate on drift budgets and regression relative to a baseline:\n\n```bash\nvg baseline\nvg scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5\n```\n\n- `--drift-budget ` fails the build if drift exceeds your budget.\n- `--drift-worsening ` fails the build if drift worsens by more than X% vs baseline.\n\nCopy-paste CI templates live in `examples/github-actions/`. Azure DevOps and GitLab CI snippets are in [DOCS.md](./DOCS.md#ci-integration).\n\n---\n\n## Version-correct library docs\n\n`vg lib` fetches usage docs pinned to the **exact version in your lockfile** — never a newer API your code can't call yet:\n\n```bash\nvg lib react # React docs at your installed version\nvg lib express --fn middleware # specific function reference\n```\n\nAI assistants connected via MCP use `vg lib` automatically when answering questions about library APIs in your project.\n\n---\n\n## SBOM and OpenVEX\n\n```bash\nvg sbom export --format cyclonedx --out sbom.cdx.json\nvg sbom export --format spdx --out sbom.spdx.json\nvg sbom delta --from .vibgrate/baseline.json --to .vibgrate/scan_result.json --out delta.txt\nvg vex # generate an OpenVEX document for attestation\n```\n\n---\n\n## Privacy & offline-first\n\n- No data leaves your machine unless you run `--push` / `vg push` / `vg share`.\n- Drift scoring reads manifests and configs only. The code graph (`vg build`/`vg map`) and a few extended scanners (code quality, database schema, UI text) read your source **locally** to compute structural facts and metrics — never a raw source line, and never uploaded as-is; see [DOCS.md](./DOCS.md#extended-scanners) for exactly what each one reads.\n- Works without login and without any SaaS dependency.\n- `--offline` disables registry/network lookups; `--package-manifest ` feeds drift scoring a local version bundle.\n- `--max-privacy` suppresses local artifact writes and high-context scanners; `--no-local-artifacts` skips writing `.vibgrate/*.json` to disk.\n- `vg code --local` keeps model inference on-device: a local model, the local graph, no hosted call and no model-catalog fetch. The agent's own web tools stay available and, like every network step, are approved by you before they run.\n- `vg code` never reads a secrets file into a prompt, and redacts credential shapes from files it does read.\n- `vg evidence` runs locally: `--offline` with a local advisory file needs no network, and `vg evidence verify` checks a bundle on a machine with no account and no connection. Nothing reaches Vibgrate Cloud until you run `vg evidence push`.\n\n```bash\nvg scan --offline --package-manifest ./package-versions.zip --max-privacy --format json --out scan.json\n```\n\nAdd `.vibgrate/` to your `.gitignore` — those are regenerated local outputs.\n\nMore on how Vibgrate handles code and data: [vibgrate.com/security](https://vibgrate.com/security), and the [subprocessor register](https://vibgrate.com/subprocessors).\n\n---\n\n## Quick start with AI assistants\n\nPaste this into your AI coding tool (Claude, Cursor, Copilot, Gemini CLI, …):\n\n```\nSet up Vibgrate for local codebase intelligence:\n1. Install: npm install -g @vibgrate/cli@latest\n2. Build the graph: vg build\n3. Wire your assistant: vg install\n4. Ask: vg ask \"what are the main entry points?\"\nThen explain the architecture and my top 3 upgrade priorities.\n```\n\nSee [docs/QUICKSTART-PROMPT.md](./docs/QUICKSTART-PROMPT.md) for the full prompt.\n\n---\n\n## Command reference\n\nUnder each set, commands are listed A–Z. A short **typical path** (usual order) is called out where it helps.\n\n### Code graph\n\n**Typical path:** `vg build` → `vg status` → `vg ask` → `vg impact` → `vg share`\n\n| Command | Description |\n| --- | --- |\n| `vg ask \"\"` | Query the map in natural language |\n| `vg build [path]` | Build / update the code map (incremental, deterministic); `--policy hexagonal-v1\\|layered-v1` picks the boundary rules the architecture module evaluates (default from `.vibgrate/architecture.toml`; the two packs are compared in [docs/architecture-policies.md](./docs/architecture-policies.md)) |\n| `vg bundle` | Build an air-gapped bundle (grammars + graph + library catalog) |\n| `vg code [\"\"]` | Graph-grounded coding agent — local or hosted model, every edit and command approved (`--auto` for CI, `--single` for a one-shot diff) |\n| `vg embed` | Precompute the semantic index for instant `vg ask` |\n| `vg export` | Export the map (json / ndjson / graphml / dot / cypher / md / html / SBOM) |\n| `vg facts ` | Deterministic facts for a node (contracts, invariants) |\n| `vg guide ` | Cited standards / practices for a node (free pack) |\n| `vg impact ` | What breaks if you change it — and the tests to run |\n| `vg install` / `vg uninstall` | Wire (or remove) **Vibgrate AI Context** + skill in your AI assistant (`--detect`, `--all`, `--list`) |\n| `vg lib ` | Version-correct, drift-annotated library docs |\n| `vg locale` | Manage your app's translations — locale projects, keys, and translations in Vibgrate Cloud (`push` / `pull` / `status`; `vg localize` is an alias) |\n| `vg map` / `vg hubs` / `vg areas` / `vg oddities` | Map insights: overview, most-depended-on code, natural groupings, cross-area smells |\n| `vg models` | Code Modes (Spark / Flow / Forge) + local fleet (Ollama / LM Studio / gguf); `install` / `pull` by default (`--dry-run` to preview) |\n| `vg module` | Manage optional local modules (`relevance`, `hcs`): `status`, `install`, `remove` |\n| `vg path ` | How A connects to B (shortest path) |\n| `vg savings` | Local report of tokens/$ saved vs a grep baseline (estimates) |\n| `vg watch` | Rebuild the map when files change |\n| `vg serve` | Start **Vibgrate AI Context** (local-first MCP: code map + drift + version-correct docs) |\n| `vg share` | Make the graph committable + auto-updating for your team |\n| `vg show ` | Explain a node: what it is, what it calls, what calls it |\n| `vg status` | Cache/freshness, counts, staleness |\n| `vg tests ` | Which tests cover a node |\n| `vg tree ` | Call tree rooted at a node |\n| `vg unknowns` | What the graph cannot resolve, ranked by blast radius |\n\n### Holistic Code Specification (`vg hcs`)\n\nDeterministic code facts for **Rust, Ruby, PHP, Dart, Swift, Scala, C++, COBOL, and VB6** — one NDJSON line per fact, reproducible on any machine, so a fact stream is something you can commit, diff, and gate CI on. Extraction is incremental by default: re-running over an existing stream costs only the delta.\n\nAll HCS computation runs in an optional, separately-licensed engine module that executes in a local WASM sandbox — no network calls, no process spawns. It is fetched on first use, or ahead of time with `vg module install hcs`. When it is unavailable, every `vg hcs` command exits `6` — never `2`, so a CI gate can't mistake \"engine missing\" for a verdict.\n\n**Typical path:** `vg hcs extract` → `vg hcs digest` / `vg hcs map` / `vg hcs gate`\n\n| Command | Description |\n| --- | --- |\n| `vg hcs extract [dir]` | Extract facts into an NDJSON stream (incremental by default; `--full` to re-extract) |\n| `vg hcs digest` | Render a fact stream as a readable specification (`md` / `json` / `html`) |\n| `vg hcs gate` | Governance gate: diff two streams, fail (exit `2`) on material structural regressions |\n| `vg hcs map` | Build the System Map from a fact stream (`json` / `md` / `mermaid`) |\n| `vg hcs validate ` | Validate a stream against the HCS spec (Appendix-I conformance code) |\n\n### Diagnostics, IDE & runtime\n\n**Typical path:** `vg doctor` → `vg lsp` → `vg daemon`\n\n| Command | Description |\n| --- | --- |\n| `vg daemon` | Local workspace daemon for multi-root graph sessions (IDE / agents): `status`, `ensure`, `publish`, `query`, `impact`, … |\n| `vg doctor` | Read-only diagnosis: config, credentials (redacted), map freshness, hosted reachability, MCP launch |\n| `vg llm-host` | Isolated local inference host process (`serve`, `status`) for enterprise process isolation |\n| `vg lsp` | Language server (stdio) — engine behind Vibgrate for VS Code and other thin IDE clients |\n| `vg policy` | Show production context-policy pin; `vg policy verify ` for signed learning patches |\n\n### Drift scoring & supply chain\n\n**Typical path:** `vg init` → `vg scan` → `vg baseline` → `vg report` → `vg fix`\n\n| Command | Description |\n| --- | --- |\n| `vg baseline [path]` | Create a drift baseline |\n| `vg bisect ` | The commit where a dependency crossed a version line (`--assert` to gate CI) |\n| `vg drift` | What is outdated across dependencies (offline; `--online` for currency) |\n| `vg evidence` | Signed, reproducible regulatory evidence — jurisdiction-neutral regimes (EU CRA first, DORA incident reporting too): `init`, `product`, `release`, `exposure`, `readiness`, `drill`, `watch`, `pack`, `verify`, `push`, `export` |\n| `vg fix` | Ranked, risk-tiered upgrade plans from the hosted planner — then apply the one you choose |\n| `vg init [path]` | Initialise config and `.vibgrate/` |\n| `vg report` | Generate a report from a scan artifact |\n| `vg review` | **Vibgrate Review** — architecture + security-control review of the current change, locally. One decision (`pass` / `needs_review` / `fail` / `undetermined`) in a signed receipt; protected findings cannot be blessed into a pass. Reports change integrity, not a proof of security. Builds or refreshes the code map itself when it is missing or stale (`--no-auto-build` opts out) |\n| `vg sbom export` / `delta` / `vex` | Export CycloneDX/SPDX SBOM, diff two artifacts, or emit an OpenVEX document |\n| `vg scan [path]` | Scan for upgrade drift |\n| `vg scan --full` | Comprehensive scan: drift + vulnerabilities + a banned-dependency report |\n| `vg scan --push` | Scan and push results to Vibgrate Cloud |\n| `vg scan --vulns` | Also detect known vulnerabilities (OSV; offline via `--package-manifest`) |\n| `vg update` | Check for and install updates |\n| `vg why ` | Who introduced a dependency, its version history, and any open vulnerabilities |\n\n### Workspace auth & cloud upload\n\nLocal scoring does not require this — nothing leaves your machine until you push.\n\n**Typical path:** `vg login` → `vg dsn create` → `vg push` → `vg logout`\n\n| Command | Description |\n| --- | --- |\n| `vg dsn create` | Generate a DSN token |\n| `vg login` / `vg logout` | Authenticate the CLI with your Vibgrate workspace (or clear stored credentials) |\n| `vg push` | Upload scan results to Vibgrate Cloud |\n\n```bash\nvg scan [path] [--vulns] [--full] [--format text|json|sarif|md] [--out ] [--fail-on warn|error|architecture-finding|architecture-warning] \\\n [--offline] [--package-manifest ] [--no-local-artifacts] [--max-privacy] \\\n [--drift-budget ] [--drift-worsening ] [--baseline ]\n```\n\nFull flag and configuration reference: **[DOCS.md](./DOCS.md)** · **[vibgrate.com/cli](https://vibgrate.com/cli)** · [help center](https://vibgrate.com/help) · [glossary](https://vibgrate.com/glossary).\n\n---\n\n## Why teams adopt Vibgrate\n\nMost systems don't fail all at once — they accumulate upgrade debt and architectural [drift](https://vibgrate.com/glossary/code-drift) silently until migrations become expensive. `vg` makes that debt measurable and repeatable — the practice we call [Code Drift Intelligence](https://vibgrate.com/code-drift-intelligence) — and gives AI assistants the local context they need to be useful. See how it lands for [teams](https://vibgrate.com/solutions/teams) and [enterprises](https://vibgrate.com/solutions/enterprise), or compare it with what you already run: [vs Renovate](https://vibgrate.com/vs/renovate) · [vs Dependabot](https://vibgrate.com/vs/dependabot) · [vs Snyk](https://vibgrate.com/vs/snyk).\n\n| Mode | What you get | Best for |\n| --- | --- | --- |\n| **One-off scan** | Fast snapshot of drift score, lag, and findings | Audits, due diligence, migration planning |\n| **CI-integrated scan** | Continuous drift signal, SARIF annotations, regression guardrails | Keeping upgrade debt under control long-term |\n| **MCP + graph** | AI assistant with real-time, offline codebase context | Day-to-day development, code review, refactoring |\n| **VG Code** | A coding agent grounded in the graph — terminal or VS Code panel, local model or Relay, governed edit by edit | Making the change, not just planning it |\n\nRecommended rollout: `vg build` + `vg install` now, add `vg scan` to CI this week, try `vg code` on one small task.\n\n---\n\n## Known limits\n\n- **Drift and risk scores are estimates**, computed from manifests, lockfiles, and public advisory data. They are a prioritization signal, not a compliance determination or a certification.\n- **VG Code quality tracks the model you choose.** No model ships with the CLI. A small local model handles mechanical edits well and struggles with cross-cutting design changes; `vg models` tells you what fits this machine, not what will do the job. Reach for Relay or another hosted model when the task is bigger than the machine.\n- **Guided `vg code` needs a terminal.** In CI, pass an instruction plus `--auto` (or `--mock`) — the interactive picker never appears, and the agent refuses to run unattended without it.\n- **The map is the ceiling.** Anything the resolver could not tie to a definition is invisible to `search_code` and `graph_impact`. Run `vg unknowns` to see what the graph is missing, ranked by blast radius.\n- **`--auto` is a denylist, not a sandbox.** It blocks known-catastrophic commands; it does not confine the agent. Run untrusted instructions in a container, or under `--worktree` with `--security-tier L1`.\n- **`--verify` re-runs your tests; it does not prove correctness.** Failures are fed back for a repair attempt. Passing tests mean passing tests.\n- **Vulnerability data is only as current as its source.** `--vulns` reports what OSV knows at scan time; offline runs report what is in the bundle you supplied.\n- **Vibgrate Evidence produces evidence, not a compliance determination.** It supports your obligations under a regime; it does not decide that you meet them, does not certify anything, and is not legal advice. The filing is yours.\n- **Evidence cannot look backwards.** Exposure is answered from manifests frozen at ship time. A release you never froze stays `undetermined` — there is no way to reconstruct it after the fact.\n- **`vg evidence watch` surfaces a KEV listing, not a determination.** Whether a vulnerability is \"actively exploited\" for the purposes of a filing is your call, not the tool's.\n- **`vg evidence verify` does not re-verify the TSA certificate chain.** It confirms the RFC 3161 token's imprint binds to `result.json` and surfaces the trusted time. For the full chain, use `openssl ts -verify -in timestamp.tsr -data result.json -CAfile `.\n\n---\n\n## Requirements\n\n- Node.js **22+**\n- macOS, Linux, Windows\n- VG Code additionally needs a model: a local runtime (a Code Mode pack, Ollama, LM Studio, or a GGUF on disk), a [Vibgrate Relay](https://vibgrate.com/relay) token, or an API key for another hosted provider. Run `vg models` to see what fits this machine.\n\n## Command name conflicts\n\n`vg` is short and occasionally conflicts with other tools (`virtualgo`, `vugu`, the oh-my-zsh `git verify-commit` alias, custom shell aliases, etc.).\n\n**`vibgrate` is an identical alias** — same binary, same flags, same behavior. If `vg` is taken on your system, use `vibgrate` everywhere instead:\n\n```bash\nvibgrate scan # same as: vg scan\nvibgrate build # same as: vg build\nvibgrate serve # same as: vg serve\n```\n\nWhen `@vibgrate/cli` is installed, it registers **both** bin entries unconditionally. If it detects at install time that `vg` is already claimed by another tool, it prints a one-line notice pointing you to `vibgrate`.\n\n---\n\n## Everything else Vibgrate makes\n\n| | |\n|---|---|\n| [**Vibgrate CLI**](https://vibgrate.com/cli) | This package — scan, score, and map any repository. [Live demo](https://vibgrate.com/cli) · [benchmarks](https://vibgrate.com/cli/benchmarks) · [token savings](https://vibgrate.com/cli/benchmarks/token-savings) |\n| [**Vibgrate for VS Code**](https://vibgrate.com/vscode) | The same score in your editor, plus the **[VG Code](https://vibgrate.com/vgcode)** panel — the graphical surface for `vg code`, running this same agent. [Marketplace](https://marketplace.visualstudio.com/items?itemName=vibgrate.vibgrate-vscode) · [Open VSX](https://open-vsx.org/extension/vibgrate/vibgrate-vscode) |\n| [**Vibgrate Relay**](https://vibgrate.com/relay) | Hosted models for VG Code on one Vibgrate account — no per-provider API keys, prepaid per-token credit, local models still the offline path |\n| [**Vibgrate Graph**](https://vibgrate.com/graph) | The deterministic local code map behind `vg map`, `vg impact` and `vg show` |\n| [**Vibgrate AI Context**](https://vibgrate.com/library) | `vg serve` — version-correct library docs, your code map, and offline drift, served to any assistant. [Supported assistants](https://vibgrate.com/skills) · [on mcp.so](https://mcp.so/servers/cli-a2b26f) |\n| [**Vibgrate Cloud MCP**](https://vibgrate.com/mcp) | The hosted MCP server over your workspace data (OAuth 2.1) |\n| [**Vibgrate Cloud**](https://vibgrate.com/cloud) | History, trends, and team rollups. [Create a workspace](https://dash.vibgrate.com) · [pricing](https://vibgrate.com/pricing) |\n| [**Vibgrate Review**](https://vibgrate.com/cli/docs/review-command) | `vg review` — did this change move the system toward its declared architecture, or weaken a security control? Runs locally from the code map; the receipt, not the repository, is what gets pushed |\n| [**Vibgrate Evidence**](https://vibgrate.com/evidence) | `vg evidence` — freeze shipped releases, then answer \"which shipped products contain this vulnerability?\" as signed, offline-verifiable evidence. Jurisdiction-neutral regimes, [EU CRA](https://vibgrate.com/cra) first |\n\n**How the scores work:** [DriftScore](https://vibgrate.com/driftscore) · [RiskScore](https://vibgrate.com/riskscore) · [DriftRisk Index](https://vibgrate.com/driftrisk) · [published methodology](https://vibgrate.com/whitepapers/software-risk-and-drift-scoring-methodology) · [public index of real scans](https://vibgrate.com/driftrisk/index) · [README badges](https://vibgrate.com/badges)\n\n**Reference:** [package registry](https://vibgrate.com/packages) · [integrations marketplace](https://vibgrate.com/marketplace) · [glossary](https://vibgrate.com/glossary) · [help center](https://vibgrate.com/help) · [security](https://vibgrate.com/security) · [mission](https://vibgrate.com/mission)\n\n

\n Create a free workspace →\n  · \n Try the live demo\n  · \n VG Code\n  · \n Evidence\n  · \n Full docs\n

\n\n

\n Apache-2.0 licensed · Copyright © 2026 Vibgrate\n

\n", "bytes": 45781, "sha": "6b67a06536efb56c1ed47bc0d00263d6431f03902c217c3b56357e3f847ecb7d", "repo_slug": "vibgrate/cli", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_com_vibgrate_ai_context_03bc95a7/readme" }