Overview
vg lib <pkg> prints usage docs for one library. When a lockfile in the project root lists that package, the version label is that pin.
vg lib react
Usage
vg lib # List the local catalog
vg lib <name> # Docs for one library
vg lib add <source> # Ingest docs from a local source
vg lib publish <name> # Upload private library docs to the hosted catalog
vg lib resolve <name> # Resolve name → catalog id + version
vg lib refresh # Re-ingest local sources
| Flag | Default | Description |
|---|---|---|
--name <name> | — | Library name (for add) |
--version <v> | — | Pin the doc version (for add/publish) |
-b, --budget <n> | — | Trim docs to ~N tokens |
--readme <path> | ./README.md | README path (for publish) |
--dts <path> | — | TypeScript declaration path (for publish) |
--language <lang> | — | Primary language (for publish) |
--region <region> | us | Data-residency region for the hosted catalog |
--ingest <url> | — | Hosted catalog URL override (wins over --region) |
-C, --cwd <dir> | . | Directory whose lockfiles and manifests are read |
--json | — | Machine-readable JSON, including source and version_mismatch |
--offline | off | Skip the hosted catalog |
--local | off | On-device only; implies --offline, so the hosted catalog is skipped |
Lockfile pin
A pin is looked up when the name is a declared dependency. For npm that is dependencies and devDependencies in package.json. A name that exists only inside a lockfile has no pin from this command.
The label uses the first version it can read:
- The lockfile pin, from the files in the table below.
- The installed copy, when those files have no entry.
- The range written in the manifest, when there is no pin and no installed copy.
--json reports that choice as source: lockfile, installed, declared, or unknown.
Readers open these filenames in the directory you run from (-C changes it). A lockfile that lives only in a subdirectory is left unread. For npm, the first file that contains the name wins.
| Ecosystem | File | What is read |
|---|---|---|
| npm | package-lock.json | v2/v3: packages["node_modules/<name>"].version. v1: dependencies.<name>.version. |
| npm | pnpm-lock.yaml | The importer entry's version. A peer suffix such as (zod@4.0.0) is removed. |
| npm | yarn.lock | The version line in the block whose header names the package. |
| Python | poetry.lock, then uv.lock | version on the [[package]] table with that name. Matching ignores case and treats -, _, and . as the same character. |
| Python | Pipfile.lock | version under default or develop, with a leading == removed. Same name matching as Poetry. |
| Rust | Cargo.lock | version on the [[package]] table. Crate names are matched case-insensitively. |
| Ruby | Gemfile.lock | The concrete version in the specs block (name (1.2.3)). |
| PHP | composer.lock | version in packages or packages-dev, with a leading v removed. |
| .NET | packages.lock.json | resolved under dependencies.<framework>.<id>. Ids are matched case-insensitively. |
| Swift | Package.resolved | state.version for a matching identity (v1 object.pins, or v2/v3 pins). |
| Dart | pubspec.lock | The version field on that package. |
| Java | gradle.lockfile | The version in a group:artifact:version= line. Pass the name as group:artifact. |
The pin lookup skips go.sum (Go keeps the version declared in go.mod), pdm.lock, npm-shrinkwrap.json, bun.lock, and Maven lockfiles. A Java dependency declared only in pom.xml uses that declared version.
The text is chosen separately from the label:
- A catalog entry from
vg lib addis printed with the version stored on that entry. - Otherwise, for an npm package, the command reads the installed package:
llms.txt, then a README, then markdown underdocs/, then thedescriptioninpackage.json. The label stays the lockfile pin when one exists, so the words can be the installed copy while the heading shows the pin. - When that text is missing or too thin, and the run may use the network, the hosted catalog is asked by library name. The heading then shows the version the catalog returned. When the catalog omits a version, the heading keeps the lockfile label.
When a lookup fails
Missing lockfile entry. The lockfile is absent, or it has no row for that name. The label moves to the installed version, then to the declared range. --json sets source to installed, declared, or unknown.
Lockfile and install disagree. When both a pin and an installed version are readable and they differ, the label stays the pin. The command prints a warning that names both versions: the lockfile pins one version and the installed tree has the other. Reinstall from the lockfile, or commit the lockfile that matches what is installed. The warning is omitted when the two versions agree. --json puts the same pair on version_mismatch (lockfile, installed, note), or null when they agree. The installed copy is node_modules/<name>/package.json for npm, a .dist-info directory under .venv, venv, env, or .tox for Python, and vendor/composer/installed.json for PHP. Other ecosystems can show a pin without this comparison.
Offline or --local. --local and --offline both skip the hosted catalog. A catalog entry and installed npm docs still print. When neither exists, the command exits 3:
no library docs for "<name>" — add with `vg lib add <path|url> --name <name>` or install the package (or retry with --online for the hosted catalog)
The error text mentions --online. Remove --local or --offline and run the command again; those two flags are what keep the hosted catalog off. The network is on unless you pass one of them.
Network fetch fails. A timeout, a connection error, a non-success response, or an empty body counts as no hosted answer. The message leaves out the response body and any credential. A failed attempt is not saved. A successful answer can be reused for about a day, so a later outage can still show that earlier text. When local text exists, it is printed, with a note that the local docs look thin and the hosted catalog had nothing better. When no local text exists either, the command exits 3 with the not-found message above, without the --online hint.
Unreadable lockfile. A lockfile that is present but truncated, invalid, or unreadable stops the command and exits 1. The message names the file and tells you to restore or regenerate it with your package manager. File contents stay out of the message.
Related
- vg serve — Serve docs to AI assistants via MCP