# Affected Dependencies (/client/affected)

In a monorepo, a change to one workspace rarely stays there. The
*affected* set is the workspace you touched **plus everything that
depends on it** — the packages whose tests, builds and publishes could
break because of your change.

vlt has no `affected` command. Affected is inherited state, so it is
expressed with [Dependency Selector Syntax](/client/selectors)
instead: [`:diff()`](/client/selectors/pseudo-classes/diff) finds what
changed, and [`:has()`](/client/selectors/pseudo-classes/has) walks
back up to what depends on it.

## What changed

[`:diff()`](/client/selectors/pseudo-classes/diff) matches packages
whose files changed against a git commitish, defaulting to `HEAD`:

Terminal:

```bash
# uncommitted changes
$ vlt query ':workspace:diff()'
```

Terminal:

```bash
# everything this branch changed
$ vlt query ':workspace:diff(main...HEAD)'
```

Use the three-dot form. `:diff(<ref>)` runs
`git diff --name-only <ref>`, which compares that ref to your working
tree in *both* directions — as soon as `main` moves ahead, everything
changed on `main` is reported as changed here too. `main...HEAD` diffs
against the merge base instead, which is what "changed on this branch"
means.

Quote any ref containing a `/`: `:diff("origin/main...HEAD")`. Bare,
the selector parser rejects the slash and the query exits non-zero.

`git diff` also ignores untracked files, so a brand new file only
counts once it is staged or committed.

## Why the `:workspace` prefix

`:diff()` matches the project root whenever *anything* in the repo
changed, so a bare `:diff(main...HEAD)` almost always includes `.` as
well. `:workspace` drops it.

The trade-off: a change to root-level files only — `tsconfig.json`, a
CI workflow, the lockfile — maps to the root package alone, so
`:workspace:diff()` returns nothing at all for it. A gate built on
`:workspace` skips the job on those changes.

## What depends on what changed

[`:has()`](/client/selectors/pseudo-classes/has) matches packages with
a **direct** dependency on a match:

Terminal:

```bash
$ vlt query ':workspace:has(:diff(main...HEAD))'
```

Nest it to reach further up the graph. Each level of `:has()` is one
more hop away from the change:

Terminal:

```bash
# dependents of the dependents
$ vlt query ':workspace:has(:has(:diff(main...HEAD)))'
```

## The affected set

Combine both with a comma. Selector lists are unioned, so this is
"changed, or depending on something changed":

Terminal:

```bash
$ vlt query ':workspace:diff(main...HEAD),
  :workspace:has(:diff(main...HEAD))'
```

Given a monorepo where `packages/utils` changed on your branch:

```
my-monorepo
├── packages/utils/       ← files changed
├── packages/core/          depends on utils
├── packages/cli/           depends on core
└── apps/docs/              depends on nothing
```

that union selects:

```
my-monorepo
├── packages/utils/       ✅ changed
├── packages/core/        ✅ depends on utils
├── packages/cli/            depends on core, two hops away
└── apps/docs/
```

`packages/cli` is two hops from the change, so it needs another level
of `:has()`. Add one selector per hop your graph is deep:

Terminal:

```bash
$ vlt query ':workspace:diff(main...HEAD),
  :workspace:has(:diff(main...HEAD)),
  :workspace:has(:has(:diff(main...HEAD)))'
```

## Running scripts on the affected set

`vlt run` takes the same selector via `--scope`, so a CI job can test
only what your branch could have broken:

Terminal:

```bash
$ vlt run test --scope=':workspace:diff(main...HEAD),
  :workspace:has(:diff(main...HEAD)),
  :workspace:has(:has(:diff(main...HEAD)))'
```

Matched workspaces run in dependency order, so changed workspaces run
before their dependents.

Workspaces without the script are skipped rather than failing:
`--scope` implies `--if-present`, as do `--workspace`,
`--workspace-group` and `--recursive`.

`--workspace` and `--workspace-group` narrow by path glob or named
group instead of by query, but they are not combinable with `--scope`
— when `--scope` is given it wins and both are ignored.

## Gating a CI job

`--expect-results` turns a query into a check: `vlt query` exits
non-zero when the result count does not match, so a job can bail out
early when nothing relevant changed.

Terminal:

```bash
$ vlt query ':workspace:diff("origin/main...HEAD")' --expect-results='>0' \\
|| echo 'nothing affected, skipping'
```

Keep the ref quoted here. A parse error also exits non-zero, so an
unquoted `origin/main` would be swallowed by the `||` and report
"nothing affected" forever.

Results are counted as graph edges, not as packages: one workspace
depended on from several places counts more than once. `--view=json`
emits those same edges — each entry is an edge with the package under
`to` — so workspace paths need extracting and deduping:

Terminal:

```bash
$ vlt query ':workspace:diff("origin/main...HEAD")' --view=json \\
| jq -r '.[].to.location' | sort -u
```

## See also

* [`:diff()`](/client/selectors/pseudo-classes/diff) — match packages
  by git changes
* [`:has()`](/client/selectors/pseudo-classes/has) — match packages by
  their dependencies
* [Workspaces](/client/workspaces) — defining workspaces and groups
* [`vlt run`](/client/commands/run) — running scripts across
  workspaces

# Authentication (/client/auth)

The vlt client supports logging into multiple different registries.
When more than one is configured, scope an auth command to a specific
one with [`vlt registry <alias> <command>`](/client/commands/registry)
(for example `vlt registry main whoami`). See
[Targeting a specific registry](/client/registries#targeting-a-specific-registry).

If you're setting up a vlt.io account for the first time, start with
[`vlt setup`](/client/registries#getting-started-with-vlt-setup) — it
authenticates and configures your account's registry aliases in one
step. The commands below cover logging into individual registries
directly.

## npm Web Login

To log into a registry that supports the npm web login, such as the
public npm registry, use the `vlt login` command.

For example, to log into the default registry:

Terminal:

```bash
$ vlt login
```

To log into a custom registry that supports npm web login, run the
same command, specifying the registry to log into:

Terminal:

```bash
$ vlt login --registry=https://my-custom-registry.mycompany.local/
```

To remove your authorization to a given registry, including attempting
to destroy the token on the server side, use the `vlt logout` command.

## Other Registries

If your registry provides a bearer token that should be presented for
authentication, it can be added using the `vlt token add` command.

This will prompt you to paste in the token.

To remove a token from vlt's keychain, use the `vlt token rm` command.
Note that this will *not* delete the token from the server; it only
removes it from the local keychain store.

A token follows redirects that stay on the same origin (scheme, host
and port), even to paths outside the registry URL, and is dropped when
a redirect changes origin.

## CI (and Other Headless Environments)

A token for the default registry can be provided in the `VLT_TOKEN`
environment variable.

For example:

```
VLT_TOKEN="helloworldtokendeadbeef" vlt install
```

To provide a token for other registries, set a `VLT_TOKEN_{...}`
variable named after the registry URL: drop the trailing `/` and
replace each run of non-alphanumeric characters with `_`. The path is
part of the name, e.g. `https://registry.vlt.io/acme/main/` becomes
`VLT_TOKEN_https_registry_vlt_io_acme_main`.

```
VLT_TOKEN_https_my_custom_registry_mycompany_local="helloworldtokendeadbeef" vlt install
```

These variables apply to configured registries (`registry`,
`registries`, `scoped-registries` and `jsr-registries`, built-in `gh`
and `jsr` included) and to registries you've logged in to. The token
is only sent to URLs under that registry URL (plus same-origin
redirects, see above).

## OIDC (OpenID Connect)

If your CI provider supports OpenID Connect, vlt can authenticate with
the registry automatically — no static tokens needed. vlt detects the
CI environment, requests an OIDC ID token from the provider, and
exchanges it with the registry for a short-lived publish token.
Everything happens behind the scenes.

Note that this requires a registry that supports OIDC trusted
publishing. The vlt.io registry currently does not — use a
[service token](/registry/publishing/ci) there.

### Supported Providers

* **GitHub Actions** — native support, no extra config
* **GitLab CI** — via `NPM_ID_TOKEN` environment variable
* **CircleCI** — via `NPM_ID_TOKEN` environment variable

### GitHub Actions

Add `id-token: write` to the job's permissions and vlt handles the
rest:

github-actions.yml:

```yaml
jobs:
publish:
  runs-on: ubuntu-latest
  permissions:
    contents: read
    id-token: write
  steps:
    - uses: actions/checkout@v4
    - uses: vltpkg/setup-vlt@v1
    - run: vlt publish
```

### GitLab CI / CircleCI

Set the `NPM_ID_TOKEN` environment variable with the OIDC ID token
provided by your CI platform. vlt reads it automatically and exchanges
it for a publish token.

### How It Works

When you run `vlt publish`, vlt checks for an available OIDC ID token
from the CI environment. It sends that token to the registry's token
endpoint, which verifies the token and returns a short-lived
credential. vlt uses that credential for the publish request. No
tokens are stored, and nothing persists after the job finishes.

### Fallback Behavior

If OIDC isn't available — for example, the registry doesn't support
it, or the required permissions aren't configured — vlt silently falls
back to `VLT_TOKEN` or keychain-based auth. No errors, no
interruptions.

## OTP

One-time password (OTP) and MFA is supported for non-headless
environments by opening a web browser or prompting on the command line
for a OTP from your authenticator app, when the registry prompts for
multifactor auth.

For headless environments, an OTP token may be provided in the
`VLT_OTP` environment variable.

## Why Environment Variables and Not Config

The vlt client is designed to make it less likely that passwords are
leaked in configuration files that might be checked into source
control, which is a surprisingly common security failure mode.

With vlt, sensitive information is *only* kept in a tightly restricted
keychain file, or in the environment. Of course, perfect security is
often impossible, but it is nevertheless important to do our best to
make it less likely that passwords can be leaked by accident.

## Credential Management

Each "identity" in vlt is a set of authentication tokens for known
registries.

For example, you could have a `corp` identity with the credentials
that you use for the work on corporate projects, and a `personal`
account with your own personal npm registry login credentials.

Running `vlt config set identity=corp` will switch into `corp` mode.
`vlt config set identity=personal` will switch into `personal` mode.

This can also be set in a project root with a `vlt.json` config file,
to make it easier to set per project. For example, you could have this
in your `vlt.json` in the project root:

```json
{
  "identity": "corp"
}
```

# Using Catalogs for Dependency Management (/client/catalogs)

The vlt client provides robust catalog support for managing dependency
versions across your projects and workspaces. This feature, heavily
inspired by pnpm's implementation, allows you to define centralized
dependency specifications that can be reused throughout your project,
reducing duplication and simplifying version orchestration across
shared dependencies.

## What are Catalogs?

Catalogs are centralized repositories of dependency specifications
defined in your `vlt.json` file. They allow you to:

* **Centralize version management**: Define dependency versions once
  and reuse them across multiple workspaces
* **Reduce duplication**: Eliminate the need to specify the same
  version ranges in multiple `package.json` files
* **Simplify updates**: Update a dependency version in one place and
  have it apply everywhere it's used
* **Maintain consistency**: Ensure all workspaces use the same
  versions of shared dependencies

## Catalog Configuration

Catalogs are configured in your project's `vlt.json` file using two
main fields:

### Default Catalog (`catalog`)

The `catalog` field defines a default catalog of dependency
specifications:

vlt.json:

```json

```

### Named Catalogs (`catalogs`)

The `catalogs` field allows you to define multiple named catalogs for
different purposes:

vlt.json:

```json

```

You can combine both approaches in the same configuration:

vlt.json:

```json

```

## Using the `catalog:` Protocol

Once you've defined catalogs in your `vlt.json`, you can reference
them in your `package.json` files using the `catalog:` protocol.

### Default Catalog Reference

To reference a dependency from the default catalog, use `catalog:`
without specifying a catalog name:

package.json:

```json

```

### Named Catalog Reference

To reference a dependency from a named catalog, use
`catalog:<catalog-name>`:

package.json:

```json

```

## Installation Examples

### Installing from Catalogs

You can install packages directly using the catalog protocol:

Terminal:

```bash
$ vlt install typescript@catalog:
```

Terminal:

```bash
$ vlt install vitest@catalog:testing
```

### Adding Dependencies to Catalogs

When you install a new dependency, you can add it to a catalog by
first updating your `vlt.json`:

vlt.json:

```json

```

Then reference it in your `package.json`:

package.json:

```json

```

## Real-World Example

Here's how the vlt project itself uses catalogs in its `vlt.json`:

vlt.json:

```json

```

And how it's used in workspace packages:

src/spec/package.json:

```json

```

## Updating a Catalog Entry

Editing a catalog value in `vlt.json` is applied by the next
`vlt install`: every dependency that reads the entry is re-resolved
and the new value is recorded in `vlt-lock.json`, even when no
resolution changes. Until that install runs,
`vlt install --frozen-lockfile` and `vlt ci` fail and name the entry
that differs:

Terminal:

```bash
Lockfile is out of sync with package.json. Run "vlt install" to update.
Configuration options have changed:
  catalog: typescript "^5.0.0" -> "^5.9.0"
```

## Advanced Usage

You can even chain catalog references with other protocols. For
example, using catalog with named registries:

package.json:

```json

```

Where your `vlt.json` might look like:

vlt.json:

```json

```

## Best Practices

1. **Group Related Dependencies**: Use named catalogs to group
   dependencies by purpose (build tools, testing, etc.)

2. **Use Semantic Versioning**: Define version ranges in catalogs
   using semantic versioning principles

3. **Keep Catalogs Updated**: Regularly review and update catalog
   entries to maintain security and compatibility

4. **Start with Common Dependencies**: Begin by cataloging
   dependencies that are used across multiple workspaces

## Error Handling

If you reference a catalog or dependency that doesn't exist, vlt will
provide helpful error messages:

* **Missing default catalog**: `Default catalog not found for <spec>`
* **Missing named catalog**: `Catalog "<name>" not found for <spec>`
* **Missing dependency in catalog**:
  `Package "<dep>" not found in default catalog` or
  `Package "<dep>" not found in catalog "<name>"`
* **Catalog entry using `catalog:`**:
  `Catalog entry "<dep>" in catalog "<name>" cannot be a catalog: spec`

For example:

```
Config Error: Default catalog not found for abbrev@catalog:
  From: ./packages/a/package.json (dependencies)
  Wanted: [ 'catalog:dev' ]
  Valid Options: [ 'catalog:dev', 'catalog:tools' ]
```

`From` is the `package.json` and dependency type declaring the spec
(prefixed with `vlt-lock.json` when the spec was read from the
lockfile, eg: `vlt ci`), `Wanted` lists the catalogs that define the
dependency and `Valid Options` lists all defined catalogs.

## Migration from Other Package Managers

If you're migrating from pnpm, the catalog syntax is largely
compatible. Simply move your pnpm catalog definitions from
`pnpm-workspace.yaml` to the `catalog` and `catalogs` fields in
`vlt.json`.

# vlt bugs (/client/commands/bugs)

Usage:

Terminal:

```bash
$ vlt bugs [<spec>] [--target=<query>]
```

Open bug tracker for a package in a web browser.

## How It Works

The `vlt bugs` command locates and opens the bug tracker for any
package in your dependency graph. It follows the following resolution
strategy to find the best bug tracker URL:

1. **Bugs field (string)** – Uses the `bugs` property directly if it's
   a string URL
2. **Bugs field (object with url)** – Uses `bugs.url` if available
3. **Bugs field (object with email)** – Creates a `mailto:` link if
   only email is provided
4. **Repository Resolution** – Falls back to the package's
   `repository` field. For known git hosts (GitHub, GitLab, Bitbucket,
   etc.), generates the canonical issues URL
5. **Fallback** – If no bugs or repository info is found, falls back
   to the [vlt.io](https://vlt.io) package page

This means you always get taken to the most relevant bug tracker.

## Basic Usage

### Open bugs for current project

When run without arguments, `vlt bugs` reads your local `package.json`
and opens the bug tracker for your current project:

Terminal:

```bash
$ vlt bugs
```

This is particularly useful when working on a project and you want to
quickly access your own issue tracker.

### Open bugs for any package

Provide a package spec to open the bug tracker for any package,
whether it's installed in your project or not:

Terminal:

```bash
# Open bugs for a specific package
$ vlt bugs express

# Open bugs for a specific version

$ vlt bugs typescript@5.0.0

# Open bugs for a scoped package

$ vlt bugs @vltpkg/graph
```

The command fetches the package manifest from the registry and
determines the best bug tracker URL to open.

### Query packages using --target

Use the `--target` option with DSS query syntax to find bug trackers
for packages in your dependency graph:

Terminal:

```bash
# Open bugs for a specific package in your graph
$ vlt bugs --target="#lodash"

# List bug tracker URLs for all direct dependencies

$ vlt bugs --target=":root > \*"

# Find bugs for all packages from a specific scope

$ vlt bugs --target="[name^=@types]"
```

Note: When the query matches multiple packages, bug tracker URLs are
listed instead of being opened automatically.

## Use Cases

### Reporting Issues

Quickly report bugs in dependencies:

Terminal:

```bash
# Found a bug in a package? Report it
$ vlt bugs problematic-package

# Report issues for packages in your graph

$ vlt bugs --target="#problematic-package"
```

### Checking for Known Issues

Before diving into debugging, check if others have reported the same
issue:

Terminal:

```bash
# Check issues for a troublesome dependency
$ vlt bugs --target="#failing-dep"

# Check issues for multiple packages

$ vlt bugs --target=":root > \*"
```

## Options

### `--target=<query>`

Filter packages using DSS query syntax. When a single package matches,
its bug tracker opens in your browser. When multiple packages match,
their URLs are listed.

Terminal:

```bash
# Open bugs for a single package
$ vlt bugs --target="#express"

# List bugs for all direct dependencies

$ vlt bugs --target=":root > \*"

# List bugs for dev dependencies

$ vlt bugs --target=":type(dev)"
```

# vlt build (/client/commands/build)

Usage:

Terminal:

```bash
$ vlt build [options]
```

The `vlt build` command represents a fundamental shift in how
JavaScript package managers handle post-installation tasks. By
separating the build phase from installation, `vlt` gives you
unprecedented control over which packages run lifecycle scripts in
your project.

## Breaking the Traditional Model

Traditional package managers conflate installation with building –
when you run `npm install`, packages are downloaded, extracted, and
their lifecycle scripts run automatically. This monolithic approach
has several drawbacks:

* **Security risks**: Malicious packages can execute arbitrary code
  during installation
* **Limited control**: You can't selectively enable or disable scripts
  for specific packages

With `vlt`, we've reimagined this process as two distinct phases:

1. **`vlt install`** – Downloads and extracts packages into
   `node_modules`
2. **`vlt build`** – Runs lifecycle scripts and performs additional
   binary linking when needed

This separation leverages the full power of our Dependency Selector
Syntax (DSS) query language, allowing you to precisely control which
packages are allowed to execute scripts.

## Basic Usage

The simplest workflow mirrors traditional package managers but with
explicit steps:

Terminal:

```bash
# Step 1: Install packages (no scripts run)
$ vlt install

# Step 2: Build all packages that need building

$ vlt build
```

The build process is idempotent – it only performs work that's
actually needed based on the current state of your dependency graph.
If a package has already been built, `vlt build` skips it
automatically.

## Selective Building with DSS Queries

The real power of `vlt build` comes from its integration with our
query language. You can use any DSS selector to target specific
packages as a positional argument to the `vlt build` command:

Terminal:

```bash
# Build only packages matching a specific target query
$ vlt build ":root > *"

# Build all packages except those marked as dev dependencies

$ vlt build ":not(:dev)"
```

### Using the target option

Use the `--target` option to control precisely which packages to
build. This gives you fine-grained control over script execution:

Terminal:

```bash
# Build only a specific package
$ vlt build --target="#my-package"

# Build everything except packages with no author

$ vlt build --target=":not([author])"
```

If you want to persist target configuration you can store it to your
`vlt.json` config file using the `vlt config` command:

Terminal:

```bash
# Persists a target query to the project vlt.json file
$ vlt config set "command.build.target=<query>"

# Build (with no args) uses the target info from vlt.json

$ vlt build
```

## Default build target

By default `vlt build` uses a target value of
`:scripts:not(:built):not(:malware)` targetting only not build
packages that have lifecycle scripts (or a root `binding.gyp`) and do
not have any malware alerts associated with it.

npm registry packages with no security data, because the request timed
out or Socket has not scanned them yet, are skipped and reported as
not built. See
[Understanding Security Data](/client/security#understanding-security-data).

## Examples

### Excluding malware and any package not from a specific scope

In this example we're only allowing scripts from packages that do not
have a `malware` alert associated to it and packages from a specific,
well known scope name.

Terminal:

```bash
# Install without running any scripts
$ vlt install

# Look up if there are packages with malware alerts in my current install

$ vlt query ":malware"

# Look up what packages have build scripts and are not from a known scope

$ vlt query ":scripts:not([name^=@myscope])"

# Build only packages from my known scope that are NOT flagged as malware

$ vlt build --target="\*[name^=@myscope]:not(:malware)"
```

### Exact dependency names

Maybe you only trust certain critical build tools to run scripts:

Terminal:

```bash
# Install packages
$ vlt install

# Only build the specific tools you trust

$ vlt build --target="#esbuild, #typescript"
```

## Options

### `--target`

The `--target` option accepts any valid DSS query to filter which
packages to build:

Terminal:

```bash
# Build only direct dependencies
$ vlt build --target=":root > *"

# Build only packages with native bindings

$ vlt build --target=":has-binary"
```

It's usage is interchangeable with a positional argument, you should
use either one or the other.

### Build State Persistence

The build state is tracked in vlt's `node_modules` metadata. Each
package node stores its build state (`needed`, `built`, or `failed`).

It's possible to retrieve the already built files using the `:built`
query selector:

Terminal:

```bash
# Query all built packages
$ vlt query ":built"

# Return all packages that have scripts that needs to be built

$ vlt query ":scripts:not(:built)"
```

## Best Practices

1. **Start with `vlt install`** – Always install first, then decide
   what to build
2. **Use queries for precision** – Target specific packages or
   patterns rather than building everything
3. **Persist your choices** – Save your target query to `vlt.json` for
   consistent builds
4. **Review regularly** – Periodically audit your target query to
   ensure it matches your security requirements, continuing to
   maintain and evolve it as you add and update packages

## Migration from Traditional Package Managers

If you're coming from npm, running install followed by build is the
functional equivalent of the traditional package manager behavior:

Terminal:

```bash
# Traditional approach
$ vlt install
$ vlt build
```

The difference being that, as mentioned previously, `vlt build` by
default protects you from running scripts of dependencies with known
malware.

If you are really trying to emulate the legacy npm behavior of running
all lifecycle scripts, you can use the `--allow-scripts="*"` options
to opt-in to all scripts and have the `vlt` client work as a
traditional package manager would:

Terminal:

```bash
# Bad: Legacy npm-style installation (not recommended)
$ vlt install --allow-scripts="*"
```

# vlt cache (/client/commands/cache)

Usage:

Terminal:

```bash
$ vlt cache <command> [flags]
```

Work with vlt cache folders

## Subcommands

### add

Resolve the referenced package identifiers and ensure they are cached.

Terminal:

```bash
$ vlt cache add <package-spec> [<package-spec>...]
```

### ls

Show cache entries. If no keys are provided, then a list of available
keys will be printed. If one or more keys are provided, then details
will be shown for the specified items.

Terminal:

```bash
$ vlt cache ls [<key>...]
```

### info

Print metadata details for the specified cache key to stderr, and the
response body to stdout.

Terminal:

```bash
$ vlt cache info <key>
```

### clean

Purge expired cache entries. If one or more keys are provided, then
only those cache entries will be considered.

Terminal:

```bash
$ vlt cache clean [<key>...]
```

### delete

Purge items explicitly, whether expired or not. If one or more keys
are provided, then only those cache entries will be considered.

Terminal:

```bash
$ vlt cache delete <key> [<key>...]
```

### delete-before

Purge all cache items from before a given date, and global store
entries written before it. Date can be provided in any format that
JavaScript can parse.

Terminal:

```bash
$ vlt cache delete-before <date>
```

### delete-all

Delete the entire cache folder to make vlt slower.

Terminal:

```bash
$ vlt cache delete-all
```

### verify

Check global store entries against their cached tarballs (file list,
contents, exec bits) and remove any that differ or have no cached
tarball, e.g. after a file in `node_modules` was edited in place.

Terminal:

```bash
$ vlt cache verify <package-spec> [<package-spec>...]
$ vlt cache verify --all
```

### prune-store

Remove global store entries that no `node_modules` folder links to.
Copies do not show use: an entry copied or cloned from (install
scripts, `store-linker=copy`, macOS, a cache on another drive) stays
if that last happened after `<date>`, or in the last 30 days without
one.

Terminal:

```bash
$ vlt cache prune-store
$ vlt cache prune-store 2026-01-01
```

## Global store

The global store holds cached registry package tarballs unpacked,
under `<cache>/store`. A background process fills it after each
install, and later installs place package files from it instead of
unpacking tarballs again: hardlinked on Linux, cloned copy-on-write
(`clonefile`) on macOS with a Node that has `node:ffi` (26.1 and
later, and `--allow-ffi` under `--permission`). By default
(`store-linker=auto`) that is all: Windows, and macOS without
`node:ffi`, unpack tarballs as before, unless `store-linker` is set to
`hardlink`, `clone` or `copy`. Where a clone fails (a volume without
clones, a project on another volume), the package is unpacked. A
hardlinked package is copied right before its install scripts run, so
they don't change its files in the store; a cloned one needs no copy.

When installed with `auto` on Linux or with `hardlink`, files in
`node_modules` are hardlinks into the global store, so editing one in
place changes it for every project on the machine. To edit
`node_modules` in place (debugging, patching), set
[`store-linker=copy`](/client/configuring#--store-linkerauto--hardlink--clone--copy--unpack)
and reinstall from scratch (remove `node_modules` first), so its files
are copies. If files were already edited through a hardlink, run
`vlt cache verify --all` to drop the changed entries, then remove
`node_modules` and reinstall in every project that linked them: their
files are still the edited ones. A clone shares storage with the
global store only until it is written to, so editing a cloned
`node_modules` in place is safe. `store-linker=unpack` (or
`VLT_STORE_LINKER=unpack`) skips the global store entirely.

The global store is a cache: deleting it, whole or in part, never
breaks an installed project. `delete`, `delete-before` and `clean`
also remove the global store entries of the tarballs they remove,
`delete-all` removes the whole global store, and `prune-store` removes
entries no project links to and no install copied or cloned from
lately. Nothing links to the global store on macOS, where packages are
cloned, so there `prune-store` (or `delete-before`) is what keeps it
from growing.

## Examples

Show cache metadata for a given registry URL:

Terminal:

```bash
$ vlt cache ls https://registry.npmjs.org/typescript
```

Add a given package specifier to the cache by fetching its resolved
value:

Terminal:

```bash
$ vlt cache add eslint@latest
```

Print the cache metadata to stderr, and write the tarball on stdout,
redirecting to a file:

Terminal:

```bash
$ vlt cache info https://registry.npmjs.org/eslint/-/eslint-9.25.1.tgz > eslint.tgz
```

Delete all entries created before Jan 1, 2025:

Terminal:

```bash
$ vlt cache delete-before 2025-01-01
```

Check every global store entry:

Terminal:

```bash
$ vlt cache verify --all
```

# vlt ci (/client/commands/ci)

Usage:

Terminal:

```bash
$ vlt ci
```

Clean install for CI pipelines. Removes `node_modules` and installs
dependencies exactly as specified in `vlt-lock.json`, failing if the
lockfile is missing or out of date.

## Lifecycle scripts

Like [`vlt install`](/client/commands/install), `vlt ci` runs **no
lifecycle scripts** of dependencies by default. To opt in:

Terminal:

```bash
# Allow scripts for specific packages
$ vlt ci --allow-scripts="#esbuild"

# Persist the query for ci in vlt.json

$ vlt config set "command.ci.allow-scripts=#esbuild"

# Or build after install (skips packages with malware alerts)

$ vlt ci && vlt build
```

See [`vlt build`](/client/commands/build) for build targets.

## Workspaces

`vlt ci` reads workspaces from `vlt.json` only. If they are declared
only in `package.json` or `pnpm-workspace.yaml`, it warns and ignores
them: run `vlt install` and commit `vlt.json` (see
[Workspaces](/client/workspaces#saving-workspaces-to-vltjson)).

## Options

| Flag                      | Description                                                                                           |
| ------------------------- | ----------------------------------------------------------------------------------------------------- |
| `--allow-scripts=<query>` | Allow matching packages to run lifecycle scripts                                                      |
| `--allow-skills=<query>`  | Link the agent skills of matching packages (never saved), see [`vlt skills`](/client/commands/skills) |
| `--skills-dir=<path>`     | Dirs to link agent skills into, see [`vlt skills`](/client/commands/skills)                           |

# vlt config (/client/commands/config)

Usage:

Terminal:

```bash
$ vlt config <command> [flags]
```

Work with vlt configuration

When no subcommand is provided, displays help information for the
config command.

## Subcommands

### get

Print the named config value(s). When no keys are provided, shows all
configuration settings. When a single key is provided with
`--config=all` (default), returns the merged configuration value. Use
`--config=user` or `--config=project` to get values from specific
configuration files only.

Terminal:

```bash
$ vlt config get [<key> [<key> ...]] [--config=<all | user | project>]
```

### pick

Select and display specific configuration values. Similar to `get` but
optimized for retrieving multiple specific keys.

Terminal:

```bash
$ vlt config pick [<key> [<key> ...]] [--config=<all | user | project>]
```

### list

Print all configuration settings currently in effect as key=value
pairs. Use `--config` to specify which configuration source to
display.

Terminal:

```bash
$ vlt config list [--config=<all | user | project>]
```

Aliases: `ls`

### set

Set config values. By default, these are written to the project config
file, `vlt.json` in the root of the project. To set things for all
projects, run with `--config=user`. Note that `--config=all` defaults
to `project` for write operations.

Terminal:

```bash
$ vlt config set <key>=<value> [<key>=<value> ...] [--config=<all | user | project>]
```

### delete

Delete the named config fields. If no values remain in the config
file, delete the file as well. By default, operates on the `vlt.json`
file in the root of the current project. To delete a config field from
the user config file, specify `--config=user`. Note that
`--config=all` defaults to `project` for write operations.

Terminal:

```bash
$ vlt config delete <key> [<key> ...] [--config=<all | user | project>]
```

Aliases: `del`, `rm`, `remove`, `unset`

### edit

Edit the configuration file. Note that `--config=all` defaults to
`project` for write operations.

Terminal:

```bash
$ vlt config edit [--config=<all | user | project>]
```

### location

Print the file path of the configuration file being used.

Terminal:

```bash
$ vlt config location [--config=<user | project>]
```

## Examples

Get all configuration (merged from user and project):

Terminal:

```bash
$ vlt config get
```

Get a specific configuration value:

Terminal:

```bash
$ vlt config get registry
```

Get configuration from user config only:

Terminal:

```bash
$ vlt config get --config=user
```

Set a configuration value in the project config:

Terminal:

```bash
$ vlt config set registry=https://my-registry.com
```

Set a configuration value in the user config:

Terminal:

```bash
$ vlt config set color=true --config=user
```

List all configuration as key=value pairs:

Terminal:

```bash
$ vlt config list
```

List configuration using alias:

Terminal:

```bash
$ vlt config ls
```

Delete a configuration value:

Terminal:

```bash
$ vlt config delete registry
```

Delete a configuration value using alias:

Terminal:

```bash
$ vlt config del registry
```

Find the location of the project config file:

Terminal:

```bash
$ vlt config location --config=project
```

# vlt create (/client/commands/create)

## Usage

Terminal:

```bash
$ vlt create <initializer> [args...]
```

Initialize a new project from a template package.

## Description

The `vlt create` command works like `npm create` and `bun create`,
automatically prepending "create-" to the package name and executing
it.

For example, running:

Terminal:

```bash
$ vlt create react-app my-app
```

Will fetch and execute the `create-react-app` package with the
arguments `my-app`.

If a satisfying instance of the create package exists in the local
`node_modules` folder, then that will be used. Otherwise, vlt will
install the package to its XDG data directory without modifying your
local dependencies.

## Examples

### Start a Next.js Project

Terminal:

```bash
$ vlt create next-app my-app
```

This fetches and runs `create-next-app my-app`. You can also pass
options through:

Terminal:

```bash
$ vlt create next-app my-app --typescript --tailwind --eslint
$ vlt create next-app my-app --use-pnpm  # or any create-next-app flag
```

### Create a React App

Terminal:

```bash
$ vlt create react-app my-app
```

This executes `create-react-app my-app`

### Create a Vite Project

Terminal:

```bash
$ vlt create vite my-project
```

This executes `create-vite my-project`

### Create a SvelteKit Project

Terminal:

```bash
$ vlt create svelte@latest my-app
```

This executes `create-svelte@latest my-app`

### Use a Scoped Template

Terminal:

```bash
$ vlt create @scope/template my-app
```

This executes `@scope/create-template my-app`

### Skip Confirmation Prompts

Use `--yes` to automatically accept the install prompt:

Terminal:

```bash
$ vlt create next-app my-app --yes
```

## Options

### `--allow-scripts <query>`

Filter which packages are allowed to run lifecycle scripts using DSS
query syntax.

Terminal:

```bash
$ vlt create vite my-app --allow-scripts='create-*'
```

## See Also

* [vlt exec](/client/commands/exec) - Execute a command from a package
* [vlt init](/client/commands/init) - Initialize a new package.json

# vlt docs (/client/commands/docs)

Usage:

Terminal:

```bash
$ vlt docs [<spec>] [--target=<query>]
```

Open documentation for a package in a web browser.

## How It Works

The `vlt docs` command locates and opens the documentation for any
package in your dependency graph. It follows the following resolution
strategy to find the best documentation URL:

1. **Homepage field** – Checks the package's `home` property in its
   `package.json`
2. **Repository Resolution** – Checks the package's `repository` field
   in its `package.json`. For known git hosts (GitHub, GitLab,
   Bitbucket, etc.), generates the canonical documentation URL
3. **Fallback** – If no repository is found or the git host is
   unknown, falls back to the [vlt.io](https://vlt.io) package page

This means you always get taken to the most relevant documentation.

## Basic Usage

### Open docs for current project

When run without arguments, `vlt docs` reads your local `package.json`
and opens the documentation for your current project:

Terminal:

```bash
$ vlt docs
```

This is particularly useful when working on a project and you want to
quickly view your own documentation or verify your repository URL is
correctly configured.

### Open docs for any package

Provide a package spec to open documentation for any package, whether
it's installed in your project or not:

Terminal:

```bash
# Open docs for a specific package
$ vlt docs express

# Open docs for a specific version

$ vlt docs typescript@5.0.0

# Open docs for a scoped package

$ vlt docs @vltpkg/graph
```

The command fetches the package manifest from the registry and
determines the best documentation URL to open.

### Query packages using --target

Use the `--target` option with DSS query syntax to find documentation
for packages in your dependency graph:

Terminal:

```bash
# Open docs for a specific package in your graph
$ vlt docs --target="#lodash"

# List documentation URLs for all direct dependencies

$ vlt docs --target=":root > \*"

# Find docs for all packages from a specific scope

$ vlt docs --target="[name^=@types]"
```

Note: When the query matches multiple packages, documentation URLs are
listed instead of being opened automatically.

## Use Cases

### Package Discovery

Quickly research packages:

Terminal:

```bash
# Compare test frameworks
$ vlt docs tap
$ vlt docs jest
$ vlt docs vitest
```

### Debugging and Support

Access documentation when troubleshooting issues:

Terminal:

```bash
# Error with a package? Read the docs
$ vlt docs --target="#problematic-package"

# Need API reference?

$ vlt docs @vltpkg/spec
```

### Learning and Exploration

Explore the ecosystem and learn about packages:

Terminal:

```bash
# Learn about vlt packages
$ vlt docs @vltpkg/graph
$ vlt docs @vltpkg/query

# Explore popular packages

$ vlt docs express $ vlt docs react
```

## Options

### `--target=<query>`

Filter packages using DSS query syntax. When a single package matches,
its documentation opens in your browser. When multiple packages match,
their documentation URLs are listed.

Terminal:

```bash
# Open docs for a single package
$ vlt docs --target="#express"

# List docs for all direct dependencies

$ vlt docs --target=":root > \*"

# List docs for packages with build scripts

$ vlt docs --target=":scripts"
```

# vlt exec-cache (/client/commands/exec-cache)

Usage:

Terminal:

```bash
$ vlt exec-cache <command> [flags]
```

Work with vlt exec-cache folders

## Aliases

```
xc
```

## Subcommands

### ls

Show previously installed packages used for `vlt exec`. Key provided
can be either the package name, or the full key.

Terminal:

```bash
$ vlt exec-cache ls
```

### delete

Delete previously installed packages used for `vlt exec`. If no keys
are provided, then all entries will be deleted.

Terminal:

```bash
$ vlt exec-cache delete [<key>...]
```

### info

Show extended information about a given `vlt exec` installation.

Terminal:

```bash
$ vlt exec-cache info <key>
```

### install

Install the specified package(s) in the `vlt exec` central cache
location. Metadata info about each installation will be printed.

Terminal:

```bash
$ vlt exec-cache install <spec>...
```

## Examples

Show all the keys for the installations in the `vlt exec` cache:

Terminal:

```bash
$ vlt exec-cache ls
```

Delete all versions of typescript installed for vlt exec:

Terminal:

```bash
$ vlt exec-cache delete typescript
```

Show extended info about a specific version of typescript:

Terminal:

```bash
$ vlt exec-cache info typescript-695bf962
```

# vlt exec-local (/client/commands/exec-local)

Usage:

Terminal:

```bash
$ vlt exec-local [command]
```

Run an arbitrary command, with the local installed packages first in
the PATH. Ie, this will run your locally installed package bins.

If no command is provided, then a shell is spawned in the current
working directory, with the locally installed package bins first in
the PATH.

Note that any vlt configs must be specified *before* the command, as
the remainder of the command line options are provided to the exec
process.

## Aliases

```
xl
```

# vlt exec (/client/commands/exec)

Usage:

Terminal:

```bash
$ vlt exec [--package=<pkg>] [--call=<cmd>] [command...]
```

Run a command defined by a package, installing it if necessary. Also
available as `vlx`.

* If `--package` is set, that package's bins are used.
* Otherwise, if the first argument is a bin in the local
  `node_modules/.bin`, it runs without installing anything.
* Otherwise, the first argument is treated as the package, and its
  default bin is run: its single bin, or the bin named after the
  package.

With no command, a shell is spawned with the bins in `PATH`. Flags for
the bin go after `--`.

Installs go to vlt's XDG data directory. Local `node_modules` is never
changed.

## Local packages

A path to a local directory (relative to the current directory) runs
its bins in place. Nothing is installed, and its own `node_modules` is
used as-is.

Terminal:

```bash
$ vlx .
$ vlx . -- --help
$ vlt exec --package=. other-bin
```

## Aliases

```
x
```

# vlt help (/client/commands/help)

Usage:

Terminal:

```bash
$ vlt help [<command>]
```

Print the full help output for the CLI, or help for a specific
command.

If no command is specified, shows general CLI help. If a command name
is provided, shows help for that specific command (equivalent to
running `vlt <command> --help`).

## Examples

Show general CLI help:

Terminal:

```bash
$ vlt help
```

Show help for the install command:

Terminal:

```bash
$ vlt help install
```

Show help for the run command:

Terminal:

```bash
$ vlt help run
```

## Aliases

```
h, ?
```

# CLI Commands (/client/commands)

* [cache](/client/commands/cache)
* [ci](/client/commands/ci)
* [config](/client/commands/config)
* [exec](/client/commands/exec)
* [exec-cache](/client/commands/exec-cache)
* [exec-local](/client/commands/exec-local)
* [help](/client/commands/help)
* [init](/client/commands/init)
* [install](/client/commands/install)
* [list](/client/commands/list)
* [login](/client/commands/login)
* [logout](/client/commands/logout)
* [outdated](/client/commands/outdated)
* [pkg](/client/commands/pkg)
* [query](/client/commands/query)
* [run-exec](/client/commands/run-exec)
* [run](/client/commands/run)
* [skills](/client/commands/skills)
* [token](/client/commands/token)
* [uninstall](/client/commands/uninstall)
* [view](/client/commands/view)
* [whoami](/client/commands/whoami)

# vlt init (/client/commands/init)

Usage:

Terminal:

```bash
$ vlt init
```

Create a new package.json file in the current directory.

# vlt install (/client/commands/install)

Usage:

Terminal:

```bash
$ vlt install [packages ...]
```

Install dependencies into `node_modules`, updating `package.json` and
`vlt-lock.json` appropriately.

By default, `vlt install` downloads and extracts packages **without
executing lifecycle scripts**—enhancing security by preventing
arbitrary code execution during installation. Use
[`vlt build`](/client/commands/build) after installation to run
scripts selectively.

## What is a Package?

* A folder containing a `package.json` file
* A gzipped tarball containing a folder with a `package.json` file
* A URL that resolves to a gzipped tarball
* A `<name>@<version>` that is published to a configured registry
* A `<name>@<semver-range>` that is published to a configured registry
* A `<name>@<tag>` that points to a package in a configured registry
* A `<name>` by itself, which defaults to using the `latest` tag from
  a registry
* A `<custom>:<name>@<version>` that points to a custom registry
  configured in `vlt.json`
* A `registry:URL#<name>@<version>` that points to a custom registry
  url
* A `<git remote url>` that resolves to a folder with a `package.json`
  file

## Basic Usage

### Install all dependencies

Terminal:

```bash
$ vlt install
```

Installs all dependencies from `package.json` without running scripts.

## Adding new packages

Using positional arguments that use the valid package specification
described above.

### Registry packages

Installing by name (a **bare spec**) requires a registry to be
configured — the `npm` alias has no built-in URL. Run
[`vlt setup`](/client/registries#getting-started-with-vlt-setup) once
to configure your account's registries. `vlt install` (and
`vlt update`, `vlt uninstall`, `vlt ci`, `vlx`/`vlt exec`) require
`registries.npm` specifically — or, if you changed
`default-registry-alias`, the alias it names — and fail with a config
error when it is missing.

Terminal:

```bash
# Latest version
$ vlt install express

# Scoped packages using semver ranges

$ vlt install @vltpkg/graph@^1.0.0
```

### Aliases

Install multiple versions of the same package side-by-side:

Terminal:

```bash
# Install react v18 as my-react
$ vlt install my-react@npm:react@18

# Install both major versions under aliased names

$ vlt install react18@npm:react@18 react19@npm:react@19
```

In the `vlt` cli the traditional aliases also enable installing from
custom registries:

Terminal:

```bash
# Install from vlt.json configured custom registry
$ vlt install custom:@org/pkg@^1.0.0

# Install using an aliased name, pointing to a custom registry

$ vlt install pkg@custom:@org/pkg
```

### Git repositories

Terminal:

```bash
# GitHub shorthand
$ vlt install github:user/repo
$ vlt install github:user/repo#v1.0.0
$ vlt install github:user/repo#semver:^1.0

# Full git URL

$ vlt install git+ssh://git@github.com:user/repo.git

# OR

$ vlt install git+https://github.com/user/repo.git#main

# GitLab

$ vlt install gitlab:user/repo

# Bitbucket

$ vlt install bitbucket:user/repo
```

When using `#semver:<range>`, vlt looks for matching tags/refs in the
remote repository.

### Tarballs

Terminal:

```bash
# Local tarball
$ vlt install ./package.tgz

# Remote tarball

$ vlt install https://example.com/package.tgz
```

### Local directories

Terminal:

```bash
# Relative path
$ vlt install ./my-local-package

# Install from parent directory

$ vlt install ../shared-lib
```

## Options

### Dependency type flags

| Flag              | Short | Description                                  |
| ----------------- | ----- | -------------------------------------------- |
| `--save-prod`     | `-P`  | Add to `dependencies` (default)              |
| `--save-dev`      | `-D`  | Add to `devDependencies`                     |
| `--save-optional` | `-O`  | Add to `optionalDependencies`                |
| `--save-peer`     |       | Add to `peerDependencies`                    |
| `--save-types`    |       | Add matching `@types/*` to `devDependencies` |

[`--save-types`](/client/configuring#--save-types) skips packages that
ship their own types:

Terminal:

```bash
# express ships no types: adds @types/express to devDependencies too
$ vlt install express --save-types

# zod ships its own types: adds zod only

$ vlt install zod --save-types
```

### Config options

| Flag            | Description                                                                                                                                                                                                |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--save-config` | Save registry and git host options given on the command line or via env to the project `vlt.json` (user one with `--config=user`), see [Registries](/client/registries#saving-registries-given-to-install) |

### Lockfile options

| Flag                | Description                                                         |
| ------------------- | ------------------------------------------------------------------- |
| `--frozen-lockfile` | Fail if lockfile is missing or out of sync with `package.json`      |
| `--expect-lockfile` | Fail if lockfile is missing or outdated                             |
| `--lockfile-only`   | Update only `vlt-lock.json` and `package.json`, skip `node_modules` |

### Script execution

| Flag                         | Description                                                     |
| ---------------------------- | --------------------------------------------------------------- |
| `--allow-scripts=<selector>` | Allow specific packages to run lifecycle scripts during install |

Terminal:

```bash
# Allow specific packages to run scripts during install
$ vlt install --allow-scripts="#esbuild, #node-gyp"

# Allow only direct dependencies to run scripts

$ vlt install --allow-scripts=":root > \*"
```

### Agent skills

| Flag                        | Description                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--allow-skills=<selector>` | Link the agent skills of matching packages into the agent skill dirs after install (default: none); saved to `vlt.json` |
| `--skills-dir=<path>`       | Dirs to link agent skills into, replacing detection (`--skills-dir=` links nothing)                                     |

Terminal:

```bash
# Link the agent skills of direct dependencies
$ vlt install --allow-skills=":root > *"
# Link one skill of one package
$ vlt install --allow-skills="#agent-browser:skill(agent-browser)"
```

See [`vlt skills`](/client/commands/skills).

### Registry options

| Flag              | Description                                    |
| ----------------- | ---------------------------------------------- |
| `--tag=<tag>`     | Default dist-tag to use (default: `latest`)    |
| `--before=<date>` | Install relative to the provided ISO 8601 date |

Terminal:

```bash
# Install from beta channel
$ vlt install express --tag=beta

# Install versions published before a specific date

$ vlt install lodash --before="2024-01-01"
```

### Workspace options

| Flag                        | Short | Description                            |
| --------------------------- | ----- | -------------------------------------- |
| `--workspace=<ws>`          | `-w`  | Limit operation to specific workspaces |
| `--workspace-group=<group>` | `-g`  | Operate on named workspace groups      |
| `--no-migrate-workspaces`   |       | Don't save workspaces to `vlt.json`    |

Terminal:

```bash
# Install in specific workspace
$ vlt install -w packages/core lodash

# Install in workspace group

$ vlt install -g apps express
```

## Phased Package Installations

Traditional package managers run lifecycle scripts automatically
during install—a security risk that allows malicious packages to
execute arbitrary code.

`vlt` separates installation into two distinct phases:

1. **Install phase**: Downloads and extracts packages (no scripts)
2. **Build phase**: Runs lifecycle scripts for selected packages

Terminal:

```bash
# Phase 1: Install packages safely
$ vlt install

# Phase 2: Build with control over what runs

$ vlt build
```

This separation enables you to:

* Inspect dependencies before any code execution
* Selectively allow scripts using DSS queries
* Protect against supply chain attacks

By default, `vlt build` uses `:scripts:not(:built):not(:malware)`
which excludes packages with known malware alerts.

For more details, see the [`vlt build`](/client/commands/build)
documentation.

## Graph Modifiers

Graph Modifiers provide precise control over dependency resolution
using [Dependency Selector Syntax (DSS)](/client/commands/query).
Configure them in your `vlt.json`:

vlt.json:

```json
{
  "modifiers": {
    "#react": "^19",
    ":root > #webpack > #browserslist": "^4.23.0"
  }
}
```

### Override all instances

Pin a package version across the entire dependency graph:

vlt.json:

```json
{
  "modifiers": {
    "#lodash": "^4.17.21"
  }
}
```

### Override transitive dependencies

Target specific dependency paths:

vlt.json:

```json
{
"modifiers": {
  ":root > #webpack > #terser-webpack-plugin > #terser": "^5.31.0"
}
}
```

When multiple selectors match, the most specific one wins.

For more details on Graph Modifiers, see the
[Graph Modifiers](/client/graph-modifiers) documentation.

## Peer Dependencies

vlt handles peer dependencies by isolating their contexts, allowing
multiple versions of the same package to coexist when necessary. When
different parts of your dependency tree require incompatible peer
versions, vlt automatically subdivides the graph into separate peer
dependency contexts.

**Key behavior:** vlt always attempts to use a single version of a
package for peer dependencies. When that's not possible, it duplicates
packages as needed, storing them in separate locations within
`node_modules/.vlt/` and linking appropriately so each package
resolves to its correct peer version.

This happens automatically during `vlt install`—no configuration
required.

For more details, see the
[Peer Dependencies](/client/peer-dependencies) documentation.

## Notes

* Running `vlt install` with no arguments installs all dependencies
  from `package.json`
* The lockfile (`vlt-lock.json`) ensures reproducible installs across
  environments
* Workspaces read from `package.json` or `pnpm-workspace.yaml` are
  saved to `vlt.json` (not with `--frozen-lockfile` /
  `--expect-lockfile`), see
  [Workspaces](/client/workspaces#saving-workspaces-to-vltjson)
* Use [`vlt ci`](/client/commands/ci) in CI pipelines: removes
  `node_modules`, installs exactly from `vlt-lock.json` (like
  `--expect-lockfile`) and, like `vlt install`, runs no dependency
  lifecycle scripts unless `--allow-scripts` is set; run `vlt build`
  after to build packages
* Peer dependencies are handled automatically with context isolation
  when version conflicts arise

## Local directories (Linked Folders)

Terminal:

```bash
# Relative path
$ vlt install ./my-local-package

# Install from parent directory

$ vlt install ../shared-lib
```

Local directories can be symlinked to a project via the `file:`
protocol. Note that these differ from local tarballs
(`file:./pkg.tgz`) which are extracted and treated as immutable.

### Installing from within a Linked Folder

When you `cd` into a linked folder and run `vlt install`, the vlt cli
allows you to add dependencies to that folder's `package.json`:

Terminal:

```bash
# Project has: "my-lib": "file:./libs/my-lib"

$ cd libs/my-lib $ vlt install lodash@^4.17.0

# Adds lodash to libs/my-lib/package.json
```

`vlt` detects your current working directory relative to the project
root and targets the appropriate `package.json`.

Note: to use `vlt install` or `vlt uninstall` to manage dependencies
of a local linked directory, that folder needs to be already in the
chain of dependencies of either the root project or one of its
workspaces in order for the `vlt` cli to properly manage the
operation.

### Relative paths in Linked Folders

File specs resolve relative to the linked folder's location:

Terminal:

```bash
# From libs/my-lib, reference ../shared
$ cd libs/my-lib
$ vlt install file:../shared
```

## Aliases

```
i, add
```

# vlt list (/client/commands/list)

Usage:

Terminal:

```bash
$ vlt ls
$ vlt ls <query> --view=[human | json | mermaid | svg | png | count]
```

List installed dependencies matching the provided query. Defaults to
listing direct dependencies of a project and any configured workspace.

The graph being listed is the one built by `vlt install`. In a project
installed by another client (an `npm install` or `pnpm install`
`node_modules`) there is no such graph, so the command errors instead
of reporting every dependency as missing. Run `vlt install` first.
`:host()` queries are the exception, since they load their graph from
somewhere else.

## Examples

List direct dependencies of the current project / workspace

Terminal:

```bash
$ vlt ls
```

List all dependencies for the current project / workspace

Terminal:

```bash
$ vlt ls *
```

List all dependencies named 'foo', 'bar', or 'baz'

Terminal:

```bash
$ vlt ls foo bar baz
```

Lists direct dependencies of a specific package

Terminal:

```bash
$ vlt ls '[name="@scoped/package"] > *'
```

List all peer dependencies of all workspaces

Terminal:

```bash
$ vlt ls '*:workspace > *:peer'
```

## Options

### view

Output format. Defaults to human-readable or json if no tty. Use `svg`
or `png` to render the dependency graph as an image and open it
automatically.

```
--view=[human | json | mermaid | svg | png | count]
```

# vlt login (/client/commands/login)

Usage:

Terminal:

```bash
$ vlt login
```

Authenticate against a registry, and store the token in the
appropriate config file for later use.

There is no default registry, so a registry must either already be
configured or be provided with `--registry=<url>`. On success the
registry is written to the project's `vlt.json`, so that it applies to
this project only.

## Options

| Flag                       | Description                                                        |
| -------------------------- | ------------------------------------------------------------------ |
| `--registry=<url>`         | Registry URL to authenticate against. Saved to `vlt.json`.         |
| `--identity=<name>`        | Identity namespace used to store auth tokens.                      |
| `--config=<user\|project>` | Which config file to write the registry to. Defaults to `project`. |

## See also

* [Working with Named Registries](/client/registries)
* [Authentication](/client/auth)
* [`vlt setup`](/client/commands/setup)

# vlt logout (/client/commands/logout)

Usage:

Terminal:

```bash
$ vlt logout
```

Log out of the default registry, deleting the token from the local
keychain, as well as destroying it on the server.

To target a specific configured registry by alias, use
[`vlt registry <alias> logout`](/client/commands/registry). See
[Targeting a specific registry](/client/registries#targeting-a-specific-registry).

# vlt outdated (/client/commands/outdated)

Usage:

Terminal:

```bash
$ vlt outdated
$ vlt outdated [package-names...]
$ vlt outdated [--target=<query>] [--workspace=<path>]
$ vlt outdated [--view=human | json | count]
```

List dependencies that have newer versions available, and what is
keeping them from being upgraded.

For every registry dependency, the installed version is compared
against the highest version that satisfies the declared range (wanted)
and against the registry's `latest` dist-tag (latest). Only
dependencies that are missing or behind on either count are reported.

Each report goes beyond the version numbers:

* the size of the jump (major, minor, patch)
* whether the installed version is deprecated
* security scores and alerts for the installed, wanted and latest
  versions, so an upgrade that fixes a vulnerability or one that
  introduces a flagged version stands out
* other dependents whose ranges hold the package back
* engine and peer dependency requirements of the latest version that
  this project does not meet
* the command that performs the upgrade

By default the direct dependencies of the project root and its
workspaces are checked; `--workspace` and `--workspace-group` narrow
that to the given workspaces. The `--target` option accepts a
[DSS query selector](/client/selectors) instead, which can reach any
dependency in the graph. Package names given as positional arguments
filter either selection.

The installed versions come from the graph built by `vlt install`, so
the project must be installed by vlt first. Dependencies that do not
resolve against a registry (git, file, remote tarball or workspace
specs) are not checked. Catalog specs are checked against the range
the catalog resolves them to.

## Examples

Report outdated direct dependencies of the project and all its
workspaces

Terminal:

```bash
$ vlt outdated
```

Only check the dependencies named `react` and `react-dom`

Terminal:

```bash
$ vlt outdated react react-dom
```

Only check the dependencies of a single workspace

Terminal:

```bash
$ vlt outdated --workspace=packages/app
```

Check every dependency in the graph, transitive ones included

Terminal:

```bash
$ vlt outdated --target="*"
```

Only check the dev dependencies of the project root

Terminal:

```bash
$ vlt outdated --target=":root > *:dev"
```

Only check dependencies with known vulnerabilities

Terminal:

```bash
$ vlt outdated --target="*:vuln"
```

Print the report as JSON

Terminal:

```bash
$ vlt outdated --view=json
```

## Output

The human-readable view is a table with one row per dependency and
dependent. The `Why` column summarizes the jump size, deprecation,
security changes between the installed version and the wanted or
latest one (high and critical severity alerts fixed or added, and
score drops), the dependents holding a transitive package back, and
the engine or peer requirements of the latest version that are not
met. The commands that perform the upgrades follow the table:
`vlt update` for versions within the declared ranges, `vlt install`
with new ranges for the rest, and the catalog entries to edit.

The JSON view is an array of entries with these fields:

* `name`, `spec`, `type`: the dependency as declared by its dependent
* `current`, `wanted`, `latest`: the installed version (absent when
  missing), the highest version satisfying the spec, and the
  registry's `latest`
* `dependent`, `location`: the importer name, or `name@version` of a
  transitive dependent, and its location
* `kind`: `missing`, `major`, `minor`, `patch` or `prerelease`
* `inRange`: whether `vlt update` picks up a newer version
* `deprecated`: the deprecation message of the installed version
* `heldBy`: transitive dependents whose ranges do not admit `latest`
* `requires`: the `node` engine range and `peers` ranges of `latest`
  that this project does not satisfy
* `security`: `score` (0 to 100) and `alerts` for `current`, `wanted`
  and `latest`, for the versions the security archive has reports on
* `action`: the command that performs the upgrade, for dependencies of
  an importer

## Options

### target

DSS query selector choosing the dependencies to check, in place of the
direct dependencies of the selected importers.

```
--target=<query>
```

### workspace

Limit the report to the dependencies of the given workspace(s).

```
--workspace=<path>
```

### workspace-group

Limit the report to the dependencies of the workspaces in the given
group(s).

```
--workspace-group=<name>
```

### view

Output format. Defaults to human-readable or json if no tty. `count`
outputs the number of outdated dependencies.

```
--view=[human | json | count]
```

# vlt pack (/client/commands/pack)

Usage:

Terminal:

```bash
$ vlt pack
```

Create a tarball from a package in the current directory or specified
folder. The tarball will be saved to the current directory with the
name `<name>-<version>.tgz`.

## Options

### dry-run

Show what would be packed without creating a tarball

Terminal:

```bash
$ vlt pack --dry-run
```

# vlt ping (/client/commands/ping)

Usage:

Terminal:

```bash
$ vlt ping
```

Ping all configured registries to verify connectivity and check
registry health. Registries that share the same URL as the default
registry are deduplicated and only pinged once.

## Ping a specific registry

Terminal:

```bash
$ vlt ping [<registry-alias>]
```

Ping a single registry by its alias. Registry aliases are configured
via the `registries` field in `vlt.json` or with the `--registries`
option.

# vlt pkg (/client/commands/pkg)

Usage:

Terminal:

```bash
$ vlt pkg [<command>] [<args>]
```

Get or manipulate package.json values

## Subcommands

### get

Get a single value

Terminal:

```bash
$ vlt pkg get [<key>]
```

### init

Initialize a new package.json file in the current directory

Terminal:

```bash
$ vlt pkg init
```

### pick

Get multiple values or the entire package

Terminal:

```bash
$ vlt pkg pick [<key> [<key> ...]]
```

### set

Set one or more key value pairs

Terminal:

```bash
$ vlt pkg set <key>=<value> [<key>=<value> ...]
```

### delete

Delete one or more keys from the package

Terminal:

```bash
$ vlt pkg delete <key> [<key> ...]
```

## Examples

Set a value on an object inside an array

Terminal:

```bash
$ vlt pkg set "array[1].key=value"
```

Append a value to an array

Terminal:

```bash
$ vlt pkg set "array[]=value"
```

# vlt publish (/client/commands/publish)

Usage:

Terminal:

```bash
$ vlt publish
```

Create a tarball from a package and publish it to the configured
registry. This command will pack the package in the current directory
or specified folder, and then upload it to the configured registry.

The registry is the package's `publishConfig.registry` if set, else
`--registry`, else a configured alias. `publishConfig.registry` alone
is enough.

## Options

### tag

Publish the package with the given tag

Terminal:

```bash
$ vlt publish --tag=<tag>
```

### access

Set access level (public or restricted)

Terminal:

```bash
$ vlt publish --access=<level>
```

### otp

Provide an OTP to use when publishing a package.

Terminal:

```bash
$ vlt publish --otp=<otp>
```

### publish-directory

Directory to use for pack and publish operations instead of the
current directory. The directory must exist and nothing will be copied
to it.

Terminal:

```bash
$ vlt publish --publish-directory=<path>
```

## Publishing in CI

### Service token

For the vlt.io registry, publish from CI with a **service token**. A
personal token answers every publish with a one-time-password
challenge and fails unattended with `EOTP`. Set it as `VLT_TOKEN`:

github-actions.yml:

```yaml
      - run: vlt publish
      env:
        VLT_TOKEN: ${{ secrets.VLT_TOKEN }}
```

See [CI & automation](/registry/publishing/ci) for the full workflow,
and
[Authentication — CI](/client/auth#ci-and-other-headless-environments)
for how token environment variables are named.

### OIDC

If your CI provider supports OpenID Connect, vlt can publish without
any stored tokens. On GitHub Actions, add `id-token: write` to your
job's permissions and vlt handles authentication automatically.

This requires a registry that supports OIDC trusted publishing. The
vlt.io registry currently does not — use a service token there.

See [Authentication — OIDC](/client/auth#oidc-openid-connect) for full
details on supported providers and configuration.

github-actions.yml:

```yaml
jobs:
publish:
  runs-on: ubuntu-latest
  permissions:
    contents: read
    id-token: write
  steps:
    - uses: actions/checkout@v4
    - uses: vltpkg/setup-vlt@v1
    - run: vlt publish
```

# vlt query (/client/commands/query)

Usage:

Terminal:

```bash
$ vlt query
$ vlt query <query> --view=[human | json | mermaid | svg | png | count]

```

List installed dependencies matching the provided query.

The graph being queried is the one built by `vlt install`. In a
project installed by another client (an `npm install` or
`pnpm install` `node_modules`) there is no such graph, so the command
errors instead of reporting every dependency as missing. Run
`vlt install` first. `:host()` queries are the exception, since they
load their graph from somewhere else.

## Examples

Query packages with the name "foo"

Terminal:

```bash
$ vlt query '#foo'
```

Query all peer dependencies of workspaces

Terminal:

```bash
$ vlt query '*:workspace > *:peer'
```

Query all direct project dependencies with a "build" script

Terminal:

```bash
$ vlt query ':project > *:attr(scripts, [build])'
```

Query packages with names starting with "@vltpkg"

Terminal:

```bash
$ vlt query '[name^="@vltpkg"]'
```

Find packages with uncommitted changes

Terminal:

```bash
$ vlt query ':diff()'
```

Find packages changed since main branch

Terminal:

```bash
$ vlt query ':diff(main)'
```

Find workspaces changed since last commit

Terminal:

```bash
$ vlt query ':workspace:diff(HEAD~1)'
```

Check for malware in dependencies

Terminal:

```bash
$ vlt query ':malware'
```

Find packages with critical security issues

Terminal:

```bash
$ vlt query ':malware(critical), :cve(*), :eval'
```

## Options

### view

Output format. Defaults to human-readable or json if no tty. Use `svg`
or `png` to render the dependency graph as an image and open it
automatically.

```
--view=[human | json | mermaid | svg | png | count]
```

### expect-results

Set expected result count for automation and CI/CD pipelines. Exits
with error code if expectation is not met.

```
--expect-results=<comparison>
```

**Examples:**

* `--expect-results=0` - Expect no results (useful for security
  checks)
* `--expect-results=">0"` - Expect at least one result
* `--expect-results="<5"` - Expect fewer than 5 results
* `--expect-results=">=10"` - Expect 10 or more results

Terminal:

```bash
# Security check that fails if malware is found
$ vlt query ':malware' --expect-results=0

# Ensure at least one workspace exists

$ vlt query ':workspace' --expect-results=">0"
```

# vlt registry (/client/commands/registry)

Usage:

Terminal:

```bash
$ vlt registry <alias> <command> [<args>]
```

Run an account command against a specific configured registry,
selected by its [`registries`](/client/registries) alias instead of a
full URL.

vlt has no default registry, so account and authentication commands
need to know *which* registry to act against.
`vlt registry <alias> <command>` scopes any of those commands to the
registry configured under `<alias>` in your `vlt.json` — handy when
you have more than one (for example the `npm` and `main` aliases
created by [`vlt setup`](/client/commands/setup)).

## Groupable commands

`<command>` is any of the account/authentication commands:

`whoami`, `logout`, `login`, `token`, `access`, `publish`,
`unpublish`, `deprecate`, `dist-tag`, `profile`, `ping`.

## Alias resolution

The registry is resolved in this order:

1. A `--registry=<url>` on the command line always wins.
2. An explicit `<alias>` (as in `vlt registry main whoami`) is looked
   up in `registries`; an unknown alias is an error.
3. With no explicit target and a single configured registry, that one
   is used.
4. With multiple configured registries and no explicit target:
   * on an interactive terminal you are prompted to pick one (the
     [`--default-registry-alias`](/client/registries#bare-specs-and---default-registry-alias)
     is pre-selected);
   * otherwise (CI, pipes) it falls back to
     `--default-registry-alias`, erroring if that alias is not
     configured.

The same resolution applies to the top-level commands, so `vlt whoami`
behaves like `vlt registry whoami`.

## Examples

Check who you are on the `main` registry:

Terminal:

```bash
$ vlt registry main whoami
```

List tokens for the `npm` registry:

Terminal:

```bash
$ vlt registry npm token list
```

Omit the alias to choose interactively (or fall back to the default
alias when non-interactive):

Terminal:

```bash
$ vlt registry whoami
```

## See also

* [Working with Named Registries](/client/registries)
* [`vlt setup`](/client/commands/setup)
* [Authentication](/client/auth)

# vlt repo (/client/commands/repo)

Usage:

Terminal:

```bash
$ vlt repo [<spec>] [--target=<query>]
```

Open repository page for a package in a web browser.

## How It Works

The `vlt repo` command locates and opens the source repository for any
package in your dependency graph. It follows the following resolution
strategy to find the best repository URL:

1. **Repository field (string)** – Uses the `repository` property
   directly if it's a string URL
2. **Repository field (object with url)** – Uses `repository.url` if
   available
3. **Hosted Git Info** – For known git hosts (GitHub, GitLab,
   Bitbucket, etc.), generates the canonical repository browse URL
4. **Raw URL fallback** – If hosted-git-info can't parse the URL, uses
   the raw repository URL
5. **Homepage fallback** – Falls back to the `homepage` field if no
   repository is found
6. **Fallback** – If no repository or homepage info is found, falls
   back to the [vlt.io](https://vlt.io) package page

This means you always get taken to the most relevant source
repository.

## Basic Usage

### Open repo for current project

When run without arguments, `vlt repo` reads your local `package.json`
and opens the repository for your current project:

Terminal:

```bash
$ vlt repo
```

This is particularly useful when working on a project and you want to
quickly access the source repository.

### Open repo for any package

Provide a package spec to open the repository for any package, whether
it's installed in your project or not:

Terminal:

```bash
# Open repo for a specific package
$ vlt repo express

# Open repo for a specific version

$ vlt repo typescript@5.0.0

# Open repo for a scoped package

$ vlt repo @vltpkg/graph
```

The command fetches the package manifest from the registry and
determines the best repository URL to open.

### Query packages using --target

Use the `--target` option with DSS query syntax to find repositories
for packages in your dependency graph:

Terminal:

```bash
# Open repo for a specific package in your graph
$ vlt repo --target="#lodash"

# List repository URLs for all direct dependencies

$ vlt repo --target=":root > \*"

# Find repos for all packages from a specific scope

$ vlt repo --target="[name^=@types]"
```

Note: When the query matches multiple packages, repository URLs are
listed instead of being opened automatically.

## Use Cases

### Exploring Source Code

Quickly navigate to the source code of a dependency:

Terminal:

```bash
# Browse source for a package
$ vlt repo some-package

# Browse source for packages in your graph

$ vlt repo --target="#some-package"
```

### Checking for Updates

Before updating a dependency, review recent commits and changelog:

Terminal:

```bash
# Check the repo for a dependency
$ vlt repo --target="#outdated-dep"

# Check repos for all direct dependencies

$ vlt repo --target=":root > \*"
```

## Options

### `--target=<query>`

Filter packages using DSS query syntax. When a single package matches,
its repository opens in your browser. When multiple packages match,
their URLs are listed.

Terminal:

```bash
# Open repo for a single package
$ vlt repo --target="#express"

# List repos for all direct dependencies

$ vlt repo --target=":root > \*"

# List repos for dev dependencies

$ vlt repo --target=":type(dev)"
```

# vlt run-exec (/client/commands/run-exec)

Usage:

Terminal:

```bash
$ vlt run-exec [command ...]
```

If the first argument is a defined script in package.json, then this
is equivalent to `vlt run`.

If not, then this is equivalent to `vlt exec`.

## Aliases

```
rx
```

# vlt run (/client/commands/run)

Run a script defined in your `package.json` file. Scripts are the
commands you define to automate common tasks like building, testing,
or starting your application.

## Usage

Terminal:

```bash
vlt run <script> [args ...]
```

## Aliases

```
r, run-script
```

## Description

The `vlt run` command executes scripts from the `scripts` section of
your `package.json` file. If you don't specify a script name, it lists
all available scripts in the current package.

### Basic Example

```json title="package.json"
{
  "scripts": {
    "build": "tsc",
    "test": "tap",
    "dev": "tsx watch src/index.ts"
  }
}
```

```bash
# Run the build script
vlt run build

# Run the tap binary with arguments (note the -- separator)
vlt run test -- --grep="pattern"

# List all available scripts
vlt run
```

### How it Works

When you run a script, vlt:

1. **Adds `node_modules/.bin` to PATH** - All locally-installed
   binaries become available without the `node_modules/.bin/` prefix
2. **Runs pre/post scripts** - Automatically executes `pre<script>`
   before and `post<script>` after your main script
3. **Sets environment variables** - Provides useful variables like
   `npm_lifecycle_event`, `npm_lifecycle_script`, and
   `npm_package_json`
4. **Executes in the package root** - Scripts always run from your
   package.json directory, regardless of your current working
   directory

## Passing Arguments

Arguments after the script name are passed directly to your script.
Use `--` to separate vlt options from script arguments:

```bash
# Pass --grep to the test script
vlt run test -- --grep="my-test"

# vlt options come BEFORE the script name
vlt run --if-present test
```

## Lifecycle Scripts

vlt automatically runs `pre` and `post` scripts if they exist:

```json title="package.json"
{
  "scripts": {
    "prebuild": "rm -rf dist",
    "build": "tsc",
    "postbuild": "cp package.json dist/"
  }
}
```

Running `vlt run build` executes all three scripts in order:
`prebuild` → `build` → `postbuild`.

## node-gyp Support

vlt automatically provides `node-gyp` support for packages that need
to compile native addons. When a script references `node-gyp`, vlt
creates a shim that redirects those calls to `vlx node-gyp@latest`, so
you don't need to manually install node-gyp globally.

This works transparently for:

* Direct calls: `"install": "node-gyp rebuild"`
* Complex commands:
  `"build": "echo 'start' && node-gyp configure && echo 'done'"`
* All platforms: Unix/Linux/macOS and Windows

## Workspaces

Run scripts across multiple workspaces in a monorepo:

### Run in Specific Workspaces

```bash
# Run in a single workspace a using a query scope
vlt run --scope="#a:workspace" lint

# Run in multiple workspaces using CLI args
vlt run test -w packages/app -w packages/lib
```

### Run in All Workspaces

```bash
# Run across all workspaces using a query scope
vlt run lint --scope=":workspace"

# Run across all workspaces using CLI args
vlt run build --recursive

# Or use workspace groups
vlt run test --workspace-group=frontend
```

### Advanced filtering with Queries

Use [DSS queries](/client/selectors) to target specific packages:

```bash
# Run tests only for packages matching a pattern
vlt run --scope=":has([name^='@myapp/'])" test
```

## Options

### `--workspace`, `-w`

Run the script in specific workspace(s). Can be a path or glob pattern
matching workspace directories.

```bash
vlt run build -w packages/app -w packages/lib
```

### `--workspace-group`, `-g`

Run the script in named workspace groups defined in your project
configuration.

```bash
vlt run test -g frontend -g api
```

### `--recursive`, `-r`

Run the script across all workspaces. Implied when using `--workspace`
or `--workspace-group`.

```bash
vlt run build --recursive
```

### `--if-present`

Don't fail if the script doesn't exist. Useful when running scripts
across workspaces where not all packages have the same scripts.

```bash
vlt run build --recursive --if-present
```

Defaults to `true` when using `--scope`, `--workspace`,
`--workspace-group`, or `--recursive`.

### `--scope`, `-s`

Filter packages using a [DSS query](/client/selectors) selector.

```bash
vlt run test --scope=":root > *"  # Direct dependencies only
```

Matched workspaces run in dependency order (a workspace runs after the
workspaces it depends on), like `--workspace`/`--recursive`. Otherwise
query order is kept where possible (a dependency may move ahead of
unrelated matches); non-workspace matches (e.g. `:root`) keep their
position.

### `--bail`, `-b` / `--no-bail`, `-B`

Control whether to stop on first failure when running across multiple
workspaces. Defaults to `true` (stop on failure).

```bash
# Continue running even if some packages fail
vlt run test --recursive --no-bail
```

### `--script-shell`

Override the shell used to run scripts. By default, uses `/bin/sh` on
Unix-like systems and `cmd.exe` on Windows.

```bash
vlt run build --script-shell=/bin/bash
```

### `--dry-run`

Show what would be executed without actually running the scripts.

```bash
vlt run build --dry-run
```

## Environment Variables

vlt sets several environment variables that your scripts can access:

* `npm_lifecycle_event` - The name of the script being run (e.g.,
  "build")
* `npm_lifecycle_script` - The actual command from package.json
* `npm_package_json` - Full path to the package.json file
* `NODE` - Path to the node executable
* `INIT_CWD` - The directory where you ran `vlt run` from
* `VLT_*` - All vlt configuration values

## Configuration

Script behavior can be configured in your `vlt.json` file:

```json title="vlt.json"
{
  "script-shell": "/bin/bash",
  "if-present": true,
  "command": {
    "run": {
      "bail": false
    }
  }
}
```

## Examples

### Run tests with coverage

```bash
vlt run test -- --coverage
```

### Build all workspace packages

```bash
vlt run build --recursive
```

### Run a script only where it exists

```bash
vlt run lint --recursive --if-present
```

### Run with custom shell

```bash
vlt run build --script-shell=/usr/bin/fish
```

### Preview what will run

```bash
vlt run deploy --dry-run --recursive
```

## See Also

* [`vlt exec`](/client/commands/exec) - Run arbitrary commands with
  enhanced PATH
* [`vlt run-exec`](/client/commands/run-exec) - Intelligently choose
  between run and exec
* [Workspaces](/client/selectors) - Dependency Selector Syntax query
  language reference
* [Workspaces](/client/workspaces) - Working with monorepos
* [Affected Dependencies](/client/affected) - Scoping a run to what a
  change could have broken

# vlt setup (/client/commands/setup)

Usage:

Terminal:

```bash
$ vlt setup [<account>]
```

Configure the registry aliases for your vlt.io account so that
`vlt install` and `vlx` work out of the box.

The `npm` registry alias has no built-in URL, so a fresh project can't
resolve bare specifiers (like `vlt install express`) until a registry
is configured. `vlt setup` is the guided way to do that: sign up or
log in at [https://www.vlt.io](https://www.vlt.io) first, then run the
wizard.

## What it does

1. Prompts for your vlt.io account (or organization) slug if not
   passed as an argument.
2. Stages the two registry aliases every account is provisioned with:
   * `npm` → `https://registry.vlt.io/<account>/npm/` (the default
     [bare-spec alias](/client/registries#bare-specs-and---default-registry-alias))
   * `main` → `https://registry.vlt.io/<account>/main/` (your
     account's primary private registry)
3. Optionally authenticates against those registries via the browser
   web-login flow. A single token covers every registry on your
   account, so the browser opens once and the token it returns is
   saved for both the public `npm` mirror and your private `main`
   registry.
4. Loops to let you add any additional custom aliases (for partner or
   team registries), optionally authenticating against each.
5. Writes the staged aliases into your user `vlt.json` (merging with,
   not clobbering, existing entries). Aliases that already live in a
   `vlt.json` are left where they are, so a project-local alias does
   not get copied into your user config (or the reverse).
6. If your keychain has a token for only one of `npm` / `main`, copies
   it to the other. Existing tokens are never overwritten, and
   `VLT_TOKEN*` environment tokens are never saved. This also runs
   with `--yes` or when you skip authentication.

If the project you run this in configures its own registries, the
output says so:
[project config takes precedence](/client/configuring#registry-selection-across-layers)
for registry selection, so writing your user config would not take
effect there. Re-run with `--config=project` to configure that
project.

## Options

| Flag                       | Description                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------- |
| `--config=<user\|project>` | Which config file to write to. Defaults to `user`; use `project` for the project.   |
| `--registries=<name=url>`  | Additional registry aliases to stage non-interactively. Can be set multiple times.  |
| `--yes`                    | Skip interactive prompts. Requires `<account>`, no browser auth; step 6 still runs. |

## Examples

Interactive setup for an account:

Terminal:

```bash
$ vlt setup my-account
```

Unattended setup (for CI or setup scripts):

Terminal:

```bash
$ vlt setup my-account --yes --registries team=https://registry.example.com/
```

Write to the project's `vlt.json` instead of your user config:

Terminal:

```bash
$ vlt setup my-account --config=project
```

## See also

* [Working with Named Registries](/client/registries)
* [Authentication](/client/auth)
* [`vlt login`](/client/commands/login)

# vlt skills (/client/commands/skills)

Usage:

Terminal:

```bash
$ vlt skills [list|link] [<query>] [--view=human|json|mermaid]
```

Manage the agent skills shipped by your installed dependencies.

An agent skill is a folder with a `SKILL.md` file, as defined by the
[Agent Skills specification](https://agentskills.io/specification).
Packages can ship them alongside their code, and `vlt skills` links
them into your project's agent skill dirs so coding agents can find
them.

## How `vlt` finds skills

`vlt` only looks in installed packages, it never downloads skills:

1. Install the package as usual, e.g. `vlt install agent-browser`.
2. A [DSS query](/client/selectors) picks the packages to look in:
   `allow-skills` on install, or the query given to `vlt skills` (`*`
   for `list` by default).
3. `vlt` scans each picked package for skills (below), then keeps the
   ones `:skill()` picks.
4. Each skill is linked into the project's
   [agent skill dirs](#where-skills-are-linked), named after the
   skill. Agents read skills from these dirs.

`vlt skills list` shows what `vlt` finds, and `vlt query ':skills'`
lists the packages that ship skills.

### Which packages

* Packages installed in the `node_modules/.vlt` store, direct or
  transitive.
* Not the project or its workspaces, and not `file:` dependencies
  (folders and tarballs).
* One version per package: the one the project depends on directly,
  else a workspace's, else the highest version, even if it ships no
  skills. Different origins (e.g. registry and git) are different
  packages.

### Where in a package

`vlt` looks for skills in each package, in this order:

1. `SKILL.md` at the package root – a single skill, named after the
   `name` field of its frontmatter (or the package name, without its
   scope)
2. `skills/<name>/SKILL.md` – one folder per skill, named `<name>`
3. `dist/skills/<name>/SKILL.md` – same, for built packages
4. `.agents/skills/<name>/SKILL.md` – same

A package can ship skills in several of these places. When the same
skill name (in any case) is in more than one, the first one in this
order is used.

### What counts as a skill

* A folder with a `SKILL.md` file, directly in one of the dirs above:
  `skills/group/<name>/SKILL.md` is not found.
* Folder names use letters, digits, `.`, `_` and `-`, and start with a
  letter or digit. Other folders, and one named `SKILL.md`, are
  skipped.
* Symlinks are not followed: a symlinked skill folder or `SKILL.md`,
  or a symlinked dir on the way (`skills/`, `dist/`, `dist/skills/`,
  `.agents/`, `.agents/skills/`), is skipped, so a skill always lives
  inside its package.
* A root `SKILL.md` is named after its frontmatter `name` when that is
  a valid skill name (lowercase letters, digits and single `-`, up to
  64 characters), else after the package.
* `vlt` reads `name` and `description` from the `SKILL.md`
  frontmatter. A missing or invalid frontmatter doesn't hide the
  skill. `:skill()` matches the skill name or the frontmatter `name`.

### Shipping skills in a package

Layout:

```text
my-tool/
├── package.json
├── dist/
└── skills/
  └── my-skill/
      └── SKILL.md
```

* Publish the skills: if `package.json` has `files`, add the skill
  dirs (or a root `SKILL.md`) to it. Check with `vlt pack --dry-run`.
* A package that is a single skill can put `SKILL.md` at its root.
* Skills built into `dist/skills/` are found too.

### Same name in different packages

When packages ship skills with the same name, one gets the link in
every dir: the package an existing link points to, while that skill is
installed, else a direct dependency, then the package id. The others
are reported. Installs keep a dir's link to another installed skill;
`vlt skills link` re-points it. Narrowing the query and running
`vlt skills link <query>` frees a name. A fresh clone (no links yet)
may pick another package than a machine with older links. `:skill()`
applies first: a skill the query doesn't pick never takes a name.

### A skill isn't found

* `vlt skills list "#<package>"` lists what `vlt` finds in it.
* Check the package is installed from a registry, git or a remote
  tarball, not a workspace or `file:` dependency.
* Check the layout and folder name rules above.
* `vlt skills link` and installs warn about a `:skill()` pattern that
  matches nothing, listing the skills its packages ship.
* With a security selector such as `:not(:malware)`, packages with no
  security data are left out and reported. See [Safety](#safety).

## Where skills are linked

Unless `skills-dir` is set, skills are linked into:

* `.agents/skills`, always. Codex, Cursor, GitHub Copilot, Gemini CLI
  and many other agents read it.
* `<folder>/skills` for each agent folder at the project root:
  `.claude/` gives `.claude/skills`, `.kiro/` gives `.kiro/skills`,
  and so on (`.tabnine/` gives `.tabnine/agent/skills`,
  `.posit/assistant/` gives `.posit/assistant/skills`). Missing dirs
  are created. Only the project root is checked, not workspaces.
* `.claude/skills` when run inside Claude Code (`CLAUDECODE` is set),
  even without a `.claude/` folder. Once created, `.claude/` keeps it
  a target outside Claude Code too.
* Any existing `.<name>/skills` dir, such as `.cursor/skills` or
  `.github/skills`. These are never created.

`.github/` alone is not an agent folder. Home dirs (`~/.claude`) are
not read, so in a plain terminal a project with no `.claude/` gets
`.agents/skills` only: run `mkdir .claude`, or set `skills-dir`.

Dirs are created only when the query picks a skill.

### `skills-dir`

Set `skills-dir` to a list of dirs, relative to the project root, to
replace detection:

Terminal:

```bash
# link into .claude/skills only
$ vlt config set skills-dir=.claude/skills
# or for one install
$ vlt install --allow-skills="*" --skills-dir=.claude/skills
```

* A dir outside the project or in `node_modules` is an error; one that
  links outside is skipped.
* `[]` in `vlt.json` (or `--skills-dir=`) links nothing.
* `null` in `vlt.json` goes back to detection.
* This is also how to drop `.agents/skills` or an unwanted agent dir.

Links in a dir that is no longer a target stay until the next
`vlt skills link`, which removes them. A custom dir dropped from
`skills-dir` (not named `.<name>/skills`) is no longer scanned: remove
its links by hand.

### Symlinked dirs

A symlinked dir or agent folder is followed when it points inside the
project, and skipped and reported when it points outside or into
`node_modules`. So is a dir that can't be read or created. A dir
reached twice (e.g. `.claude/skills -> ../.agents/skills`) gets each
link once.

## Pick skills

End a selector with `:skill(<name>, …)` to link only some of its
packages' skills:

Terminal:

```bash
# one skill of one package
$ vlt skills link "#skills:skill(find-skills)"
$ vlt skills link '#skills:skill("find-skills")'
# some skills of every direct dependency
$ vlt skills link ":root > *:skill(performance, find-skills)"
# globs
$ vlt skills link ":root > *:skill(vercel*, *-review)"
# any package, same as *:skill(find-skills)
$ vlt skills link ":skill(find-skills)"
```

* A pattern matches the skill name (its folder name, or the root
  `SKILL.md` name) or the `name` in its `SKILL.md` frontmatter, in any
  case. `*` matches any run of characters. Quote names with spaces:
  `:skill("my skill")`.
* A selector without `:skill()` picks every skill of its packages, and
  comma lists are a union. So `:root > *, #skills:skill(find-skills)`
  links every skill of every direct dependency, `skills` included. To
  narrow one package, leave it out of the other selectors:
  `:root > *:not(#skills), #skills:skill(find-skills)`.
* `:skill()` must end a top-level selector: `#a:skill(x) > *` is an
  error.
* [`:skills`](/client/selectors/pseudo-states#skills) (no `()`)
  matches packages that ship skills. `:skills(x)` is an error (did you
  mean `:skill(x)`?) on its own, and matches nothing inside a comma
  list.
* A pattern that matches no skill of its packages prints a warning
  listing the skills they ship. The install still succeeds.

Preview a query with `vlt skills list '<query>'` before `link` saves
it. See [`:skill()`](/client/selectors/pseudo-classes/skill).

## Layout

Each skill is linked into every dir, named after the skill:

Layout:

```text
.agents/skills/
├── lint-rules -> ../../node_modules/.vlt/~npm~foo@1.0.0/node_modules/foo/skills/lint-rules
└── bar -> ../../node_modules/.vlt/~npm~@scope+bar@2.0.0/node_modules/@scope/bar
.claude/skills/
├── lint-rules -> ../../node_modules/.vlt/~npm~foo@1.0.0/node_modules/foo/skills/lint-rules
└── bar -> ../../node_modules/.vlt/~npm~@scope+bar@2.0.0/node_modules/@scope/bar
```

On Windows, links are directory junctions. Junctions hold absolute
paths, so after moving or copying the project, run
`vlt skills link <query>` (or `vlt install` with `allow-skills` set)
to re-point them.

## Subcommands

### `list`

The default. Lists the skills of installed packages as a tree, like
`vlt ls`: `<skill> (<package>)`, marked `(linked)` when linked in
every agent skill dir, `(linked in <dirs>)` when only in some. With
colors on, linked skills are highlighted like the packages `vlt query`
selects. Warnings follow the tree. Selects all packages (`*`) by
default and applies `:skill()`. Creates and saves nothing.

Terminal:

```bash
$ vlt skills
my-project
├── find-skills (skills@1.7.2) (linked)
└── get-tsconfig (get-tsconfig@5.0.0-beta.6)
$ vlt skills list ":root > *"
$ vlt skills list "#skills:skill(find-*)"
```

* `--view=json`: each skill's `name` is the skill, then its
  `description`, `dependency-name` the dependency it is installed as,
  `package-id` its package id, `path` and the dirs it is `linked` in;
  `dirs` lists the agent skill dirs.
* `--view=mermaid`: a [Mermaid](https://mermaid.js.org/) flowchart of
  the dependency graph, as `vlt query --view=mermaid` draws it, from
  the project down to each package with skills, its skills as
  highlighted leaves. Warnings follow as `%%` comments. List only.

Terminal:

```bash
$ vlt skills list --view=mermaid
flowchart TD
a("root:my-project")
a -->|"skills#64;github:vercel-labs/skills"| b("git(github:vercel-labs/skills):skills#64;1.7.2")
b -->|"skills#64;1.7.2"| f("find-skills (linked)"):::b
b -->|"obuild#64;^0.4.22 (dev)"| c("npm:obuild#64;0.4.45")
c -->|"rolldown-plugin-dts#64;^0.28.8"| d("npm:rolldown-plugin-dts#64;0.28.8")
d -->|"get-tsconfig#64;5.0.0-beta.6"| e("npm:get-tsconfig#64;5.0.0-beta.6")
e -->|"get-tsconfig#64;5.0.0-beta.6"| g("get-tsconfig"):::b
classDef b fill:turquoise,color:#242424
```

### `link`

Sets, saves and applies `allow-skills`. Links what the query selects
and removes `vlt` links to other skills in every scanned dir: skills
the query doesn't pick, skills that are gone, and links in dirs that
are no longer targets. It is the only command that removes links to
installed skills. With no query, it uses the stored `allow-skills`,
else `:not(:malware)`, like [`vlt build`](/client/commands/build).

Then it saves the query when it changed: to the project `vlt.json`, or
to the user one with `--config=user`. A query in the other file is
never deleted: a project value shadows the user one.

| Query given | Stored | `-y` | TTY | Result                                                                            |
| ----------- | ------ | ---- | --- | --------------------------------------------------------------------------------- |
| yes         | no     | any  | any | link it, save it                                                                  |
| yes         | yes    | no   | yes | `Replace it? [y/N]`: **y** opens the editor with the query, **N** changes nothing |
| yes         | yes    | yes  | any | link it, save it                                                                  |
| no          | yes    | no   | yes | `Edit it? [y/N]`: **y** opens the editor with the stored query, **N** links it    |
| no          | yes    | yes  | any | link the stored query                                                             |
| no          | no     | no   | yes | the editor, prefilled with `:not(:malware)`                                       |
| no          | no     | yes  | any | link `:not(:malware)`, save it                                                    |
| yes         | yes    | no   | no  | error: pass `-y` to replace it                                                    |
| no          | yes    | no   | no  | link the stored query                                                             |
| no          | no     | no   | no  | link `:not(:malware)`, save it                                                    |

A query equal to the stored one links without asking or writing.

Terminal:

```bash
$ vlt skills link ":root > *:skill(find-skills)"
allow-skills is already set for this project (vlt.json): ":root > *". Replace it? [y/N] y
\n⚠️ The new allow-skills replaces the current one. Make sure it still
selects every skill you want: skills it no longer selects are unlinked.
\nCurrent allow-skills: :root > *
New allow-skills: :root > *:skill(find-skills)
1 agent skill already linked.
Saved allow-skills=":root > *:skill(find-skills)" to vlt.json
```

In the editor, the new query is prefilled: edit it and press Enter. An
empty answer cancels with no changes, and an invalid query prints the
error and asks again. `-y` skips the prompts. `Current` and `New` are
colored when colors are on.

Terminal:

```bash
# a single package, no prompts
$ vlt skills link "#my-package" -y
# save to the user vlt.json
$ vlt skills link "#my-package" --config=user
# remove every skill link
$ vlt skills link ":not(*)" -y
```

Select packages with a [DSS query](/client/selectors) after the
subcommand, or with `--target=<query>`, which wins over the positional
argument.

Add skill packages one at a time:

Terminal:

```bash
$ vlt install github:vercel-labs/skills
$ vlt skills link "#skills:skill(find-skills)"   # saved to vlt.json
$ vlt install agent-skills@github:vercel-labs/agent-skills
$ vlt skills link
# Edit it? y
# New allow-skills: #skills:skill(find-skills), #agent-skills:skill(react*)
# on another machine, both are linked
$ vlt ci
```

## Linking on install

With `allow-skills` unset (the default) or `:not(*)`, `vlt install`,
`vlt ci`, `vlt update` and `vlt uninstall` do no skills work at all:
nothing is scanned, created or removed, and leftover links stay until
`vlt skills link`.

With `allow-skills` set, on the command line or in `vlt.json`, they
link what it selects after a successful install:

Terminal:

```bash
# link, and save the query to vlt.json
$ vlt install --allow-skills="#agent-browser:skill(agent-browser)"
Saved allow-skills="#agent-browser:skill(agent-browser)" to vlt.json
```

* Installs only add links. They re-point a link to the new version of
  its package, in every dir, and remove links whose skill is gone:
  dangling, package removed, or skill no longer shipped. They never
  remove links to installed skills: after narrowing `allow-skills`,
  run `vlt skills link`.
* `vlt install` and `vlt update` save `--allow-skills=<query>` to the
  project `vlt.json`. When another query is stored (`:not(*)` too), it
  is kept and a hint says so: change it with `vlt skills link`.
* `vlt ci` never writes config: in a fresh clone, it links what
  `vlt.json` selects.
* `--lockfile-only` links and saves nothing.
* `vlt uninstall` with a stored query removes the removed package's
  links.
* Dir changes take effect for new links; old ones go on the next
  `vlt skills link`. An invalid query or `skills-dir` fails before
  anything is installed.

## Safety

* `vlt` only ever replaces or removes links that point into a
  `node_modules/.vlt` store. Anything else at a link path (your own
  skills, other tools' copies or links) is skipped and reported for
  that dir, never changed.
* Dirs are never removed.
* Security queries fail closed, like `allow-scripts`: with a security
  selector such as `:not(:malware)`, skills of npm registry packages
  with no security data (the request timed out, or Socket has not
  scanned them yet) are not linked and are reported. Installs keep
  their existing links, `vlt skills link` removes them: try again
  later. See [Security](/client/security).
* Linked skills are views of installed package files: don't edit them,
  a reinstall replaces them. Files hardlinked from the global store
  get private copies when linked, so edits stay in this project.

## Ignoring linked skills in git

Links dangle in a fresh clone until install, so `vlt` keeps their
names in a marked block of each dir's `.gitignore`:

.claude/skills/.gitignore:

```text
# >>> vlt agent skills (links into node_modules)
/bar
/lint-rules
# <<< vlt agent skills
```

Lines are added for new links and removed with them, or when your own
entry takes the name. The rest of the file is kept, and the file is
never deleted: committed, it keeps the dir in a fresh clone. A dir
with no `vlt` links is never touched. A `.gitignore` that is a
symlink, not a file or can't be written is left alone and reported.

## Limits

* Skills nested deeper than `<dir>/<name>/SKILL.md` are not found.
* Skills are linked at the project root only, not per workspace.

# vlt token (/client/commands/token)

Usage:

Terminal:

```bash
$ vlt token list
$ vlt token add
$ vlt token rm
```

Manage registry authentication tokens in the vlt keychain.

To target a specific configured registry by alias, use
[`vlt registry <alias> token <subcommand>`](/client/commands/registry).
See
[Targeting a specific registry](/client/registries#targeting-a-specific-registry).

## Subcommands

### list

List all tokens for configured registries. Queries each registry's
token API and displays token metadata including key, creation date,
and permissions.

Terminal:

```bash
$ vlt token list
```

### add

Add a token for the specified registry. You will be prompted to paste
the bearer token.

Terminal:

```bash
$ vlt token add
```

### rm

Remove the stored token for the specified registry.

Terminal:

```bash
$ vlt token rm
```

# vlt uninstall (/client/commands/uninstall)

Usage:

Terminal:

```bash
$ vlt uninstall [package ...]
```

The opposite of `vlt install`. Removes deps and updates vlt-lock.json
and package.json appropriately.

## Aliases

```
rm, u
```

# vlt version (/client/commands/version)

Usage:

Terminal:

```bash
$ vlt version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease]
```

Bump a package's version.

Run in a package directory to bump the version and write the new data
back to package.json.

The `<newversion>` argument should be a valid semver string or a valid
increment type (one of patch, minor, major, prepatch, preminor,
premajor, prerelease).

If run in a git repository, it will also create a version commit and
tag.

## Options

### no-git-tag-version

Bump the version without creating a git commit or tag.

Terminal:

```bash
$ vlt version patch --no-git-tag-version
```

Useful for bumping several workspaces and then committing all of the
changes together:

Terminal:

```bash
$ vlt version prerelease --workspace="./infra/cli*" --no-git-tag-version
$ git commit -am 'v1.2.3'
```

### no-commit

Create the git tag, but leave the version bump uncommitted.

Terminal:

```bash
$ vlt version patch --no-commit
```

# vlt view (/client/commands/view)

Usage:

Terminal:

```bash
$ vlt view <pkg>[@<version>] [<field>]
$ vlt view <pkg>[@<version>] [--view=human | json]
```

View registry information about a package: manifest of the resolved
version, dist-tags, maintainers, versions and, when available, vlt
security scores and alerts.

Aliases: `info`, `show`.

## Local package

`.` views the package in the current directory (nearest
`package.json`, walking up). Running `vlt view` with no arguments does
the same.

Terminal:

```bash
$ vlt view .
$ vlt view .@1.2.3
$ vlt view . version
```

* `.` looks up the local package name in the configured registry
  (default dist-tag); `.@<version>` picks a version or tag.
* Private packages (`"private": true`) are never looked up in the
  registry; their local `package.json` info is shown instead.
* Path specs (`./pkg`, `file:pkg`) show that directory's
  `package.json`, relative to the project root.

## Fields

Pass a field to print only its value. Nested fields use dot-prop
syntax:

Terminal:

```bash
$ vlt view express dist-tags.latest
$ vlt view express dependencies.debug
```

## Options

### `--view=<human | json>`

Output format. Defaults to `human`, or `json` when not a tty.

# vlt whoami (/client/commands/whoami)

Usage:

Terminal:

```bash
$ vlt whoami
```

Look up the username for the currently active token, when logged into
a registry.

To target a specific configured registry by alias, use
[`vlt registry <alias> whoami`](/client/commands/registry). See
[Targeting a specific registry](/client/registries#targeting-a-specific-registry).

# Configuring the vlt CLI (/client/configuring)

Usage:

Terminal:

```bash
$ vlt [<options>] [<cmd> [<args> ...]]
```

More documentation available at
[https://docs.vlt.io](https://docs.vlt.io)

## Subcommands

```
access, bugs, build, cache, ci, config, create, deprecate, dist-tag, docs, exec, exec-cache, exec-local, help, init, add, install, list, login, logout, pack, ping, pkg, profile, publish, query, registry, repo, run-script, run, run-exec, setup, skills, token, uninstall, unpublish, update, version, view, whoami
```

Run `vlt <cmd> --help` for more information about a specific command

## Configuration

The `vlt.json` file in the XDG specified config directory is loaded
first. Then, if a `vlt.json` file is present in the root of the
current project, the `config` field in that file is layered on top of
it. (The project file is also used to define workspaces and other
`vlt` behaviors.)

Scalar values are overridden by the innermost layer that sets them.
Object type values are merged together key by key, with the project
file winning on conflict. Set a field, or a key within an object
field, to `null` in the JSON configuration to explicitly remove it:

```json
// ~/.config/vlt/vlt.json
// User level config
{
  "config": {
    "registries": { "npm": "https://a/", "old": "https://b/" }
  }
}
```

```json
// ./vlt.json
// Project level config
{ "config": { "registries": { "npm": "https://c/", "old": null } } }
```

```json
// Effective parsed config
{ "registries": { "npm": "https://c/" } }
```

> Note: The user level config file uses XDG paths that are
> OS-specific, the example `~/.config/vlt/vlt.json` path used here
> might not be the same path used in your system, to learn what is the
> user level config location for your system, run:
> `vlt config location --config=user`

Object type values given via `VLT_*` environment variables or on the
command line are merged key by key over the config files, command line
winning over environment. Other values replace them. List values in
the environment are newline-delimited, e.g.
`VLT_REGISTRIES=$'a=https://a/\nb=https://b/'`.

### Registry selection across layers

Registry selection is an exception to plain per-field layering,
because `registry` outranks any `registries` alias. A layer that sets
any of `registry`, `registries`, or `default-registry-alias` owns
selection: the `registry` and `default-registry-alias` it does *not*
set are dropped rather than inherited from an outer layer.

So a project that configures its own registry is never quietly sent to
the user-level one:

```json
// ~/.config/vlt/vlt.json
// User level config
{
  "config": {
    "registry": "https://user/",
    "registries": { "main": "https://main/" }
  }
}
```

```json
// ./vlt.json
// Project level config
{ "config": { "registries": { "npm": "https://project/" } } }
```

resolves to `https://project/`. The user's `main` alias is still
addressable as `main:` in a specifier, or with
`vlt registry main <cmd>`.

`scoped-registries` and `jsr-registries` are purely additive, so they
do not take over selection.

Command-specific fields may be set in a nested `command` object that
overrides any options defined at the top level, following the same
rules.

For information about catalog configuration and the `catalog:`
protocol, see the [Catalogs documentation](/client/catalogs).

### `-c --color`

Use colors (Default for TTY)

### `-C --no-color`

Do not use colors (Default for non-TTY)

### `--registry=<url>`

Sets the registry for fetching packages, when no registry is
explicitly set on a specifier.

For example, `express@latest` will be resolved by looking up the
metadata from this registry.

There is **no default**. A registry must be configured in `vlt.json`,
with this flag, or via the `VLT_REGISTRY` environment variable.
Commands that need a registry fail with a config error when none is
set; [`vlt setup`](/client/registries#getting-started-with-vlt-setup)
or [`vlt login`](/client/commands/login) will configure one for you.
See [Registries](/client/registries).

Bare specifiers (like `express@latest`) resolve through the
`--default-registry-alias` (default `npm`) when this scalar is not
set.

### `--default-registry-alias=<name>`

The name of the entry in `--registries` that **bare specifiers** — and
transitive dependencies without an explicit registry protocol —
resolve through, when neither a `scoped-registries` entry nor the
`--registry` scalar applies. Precedence is `scoped-registries` >
`--registry` > `registries[<default-registry-alias>]`.

Defaults to `npm`. The `npm` alias itself has **no built-in URL** — it
must be configured (for example via
[`vlt setup`](/client/registries#getting-started-with-vlt-setup)),
otherwise bare specs cannot resolve. See
[Registries](/client/registries).

### `--registries=<name=url>`

Specify named registry hosts by their prefix. To set the default
registry used for non-namespaced specifiers, use the `--registry`
option.

Prefixes can be used as a package alias. For example:

Terminal:

```bash
​​$ vlt --registries loc=http://reg.local install foo@loc:foo@1.x
```

The `npm:` prefix is **not** pre-registered to any URL — configure it
(for example with `vlt setup`) before bare specs or `npm:` aliases can
resolve. The built-in `gh:` prefix is pre-registered but remains
overridable here. A name used by `--jsr-registries` or `--git-hosts`
(e.g. `jsr`, `github`), or a built-in protocol (e.g. `file`), is an
error.

Aliases given on the command line or in `VLT_REGISTRIES` merge with
the configured ones, later sources winning per key. Pass
[`--save-config`](#--save-config) to `vlt install`, `vlt add` or
`vlt update` to save them to `vlt.json`. See
[Registries](/client/registries#saving-registries-given-to-install).

Can be set multiple times

### `--scoped-registries=<@scope=url>`

Map package name scopes to registry URLs.

For example, `--scoped-registries @acme=https://registry.acme/` would
tell vlt to fetch any packages named `@acme/...` from the
`https://registry.acme/` registry.

Note: this way of specifying registries is more ambiguous, compared
with using the `--registries` field and explicit prefixes, because
instead of failing when the configuration is absent, it will instead
attempt to fetch from the default registry.

By comparison, using `--registries acme=https://registry.acme/` and
then specifying dependencies such as `"foo": "acme:foo@1.x"` means
that regardless of the name, the package will be fetched from the
explicitly named registry, or fail if no registry is defined with that
name.

However, custom registry aliases are not supported by other package
managers.

Can be set multiple times

### `-G<name=template> --git-hosts=<name=template>`

Map a shorthand name to a git remote URL template.

The `template` may contain placeholders, which will be swapped with
the relevant values.

`$1`, `$2`, etc. are replaced with the appropriate n-th path portion.
For example, `github:user/project` would replace the `$1` in the
template with `user`, and `$2` with `project`.

Can be set multiple times

### `-A<name=template> --git-host-archives=<name=template>`

Similar to the `--git-host <name>=<template>` option, this option can
define a template string that will be expanded to provide the URL to
download a pre-built tarball of the git repository.

In addition to the n-th path portion expansions performed by
`--git-host`, this field will also expand the string `$committish` in
the template, replacing it with the resolved git committish value to
be fetched.

Can be set multiple times

### `--cache=<path>`

Location of the vlt on-disk cache. Defaults to the platform-specific
directory recommended by the XDG specification.

### `--store-linker=<auto | hardlink | clone | copy | unpack>`

How packages are placed in `node_modules`. Every linker but `unpack`
fills a global store under `cache` in the background, then places
packages from it.

* auto: Default. On Linux, hardlink from the global store, copying any
  file that cannot be linked. On macOS, clone from it, on a Node with
  `node:ffi` (26.1 and later, and `--allow-ffi` under `--permission`);
  a hardlink is the slowest way to place a file on APFS, so macOS
  without it, and Windows, unpack by default.
* hardlink: Hardlink from the global store on every platform.
* clone: Clone each package directory from the global store
  copy-on-write (`clonefile`, macOS on APFS). Files share storage with
  the store until edited, so editing in place is safe. Unpacks where
  cloning fails.
* copy: Copy from the global store. Use this when editing files in
  `node_modules` in place, since a hardlink shares its content with
  every project.
* unpack: Unpack each package tarball, skipping the global store.

A hardlinked package is copied right before its install scripts run,
so they don't change its files in the store; a cloned one needs no
copy. An invalid `VLT_STORE_LINKER` warns and uses `unpack`. See
[Global store](/client/commands/cache#global-store).

Valid options: "auto", "hardlink", "clone", "copy", "unpack"

### `--brotli-tarballs`

Resolve to the Brotli (`.tar.br`) tarball when the registry advertises
one for a version, transferring far less than the gzip `.tgz`. On by
default; `--no-brotli-tarballs` always resolves to the `.tgz`.

A `.tar.br` is its own artifact, not a re-encoding of the `.tgz`: it
hashes differently, and the registry labels it with its own RFC 9530
`Repr-Digest`, which is what verifies the download. So a version
installed this way records *that* hash in `vlt-lock.json`, alongside a
flag marking which artifact the entry describes.

An existing lockfile keeps whichever artifact it already pinned, the
same as any other resolved URL — set `--no-brotli-tarballs` before the
versions are resolved to pin `.tgz` files instead.

Registries that advertise no alternates are unaffected.

### `--tag=<tag>`

Default `dist-tag` to install

### `--before=<date>`

Do not install any packages published after this date

### `--os=<os>`

The operating system to use as the selector when choosing packages
based on their `os` value.

### `--arch=<arch>`

CPU architecture to use as the selector when choosing packages based
on their `cpu` value.

### `--node-version=<version>`

Node version to use when choosing packages based on their
`engines.node` value.

### `--git-shallow`

Set to force `--depth=1` on all git clone actions. When set explicitly
to false with --no-git-shallow, then `--depth=1` will not be used.

When not set explicitly, `--depth=1` will be used for git hosts known
to support this behavior.

### `--fetch-retries=<n>`

Number of retries to perform when encountering network errors or
likely-transient errors from git hosts.

### `--fetch-retry-factor=<n>`

The exponential backoff factor to use when retrying requests due to
network issues.

### `--fetch-retry-mintimeout=<n>`

Number of milliseconds before starting first retry

### `--fetch-retry-maxtimeout=<n>`

Maximum number of milliseconds between two retries

### `-i<name> --identity=<name>`

Provide a string to define an identity for storing auth information
when logging into registries.

Authentication tokens will be stored in the XDG data directory, in
`vlt/auth/${identity}/keychain.json`.

If no identity is provided, then the default `''` will be used,
storing the file at `vlt/auth/keychain.json`.

May only contain lowercase alphanumeric characters.

### `-w<ws> --workspace=<ws>`

Set to limit the spaces being worked on when working on workspaces.

Can be paths or glob patterns matching paths.

Specifying workspaces by package.json name is not supported.

Can be set multiple times

### `-g<workspace-group> --workspace-group=<workspace-group>`

Specify named workspace group names to load and operate on when doing
recursive operations on workspaces.

Can be set multiple times

### `-r --recursive`

Run an operation across multiple workspaces.

No effect when used in non-monorepo projects.

Implied by setting --workspace or --workspace-group. If not set, then
the action is run on the project root.

### `-b --bail`

When running scripts across multiple workspaces, stop on the first
failure.

### `-B --no-bail`

When running scripts across multiple workspaces, continue on failure,
running the script for all workspaces.

### `--config=<all | user | project>`

Specify which configuration to show or operate on when running
`vlt config` commands, and which file `vlt skills link` saves
`allow-skills` to.

For read operations (`get`, `pick`, `list`): `all` shows merged
configuration from both user and project files (default).

For write operations (`set`, `delete`, `edit`): defaults to `project`.
`user` shows/modifies only user-level configuration, `project`
shows/modifies only project-level configuration.

Valid options: "all", "user", "project"

### `--editor=<program>`

The blocking editor to use for `vlt config edit` and any other cases
where a file should be opened for editing.

Defaults to the `EDITOR` or `VISUAL` env if set, or `notepad.exe` on
Windows, or `vi` elsewhere.

### `--script-shell=<program>`

The shell to use when executing `package.json#scripts` (either as
lifecycle scripts or explicitly with `vlt run`) and `vlt exec`.

If not set, defaults to `/bin/sh` on POSIX systems, and `cmd.exe` on
Windows.

When no argument is provided to `vlt exec`, the `SHELL` environment
variable takes precedence if set.

### `--fallback-command=<command>`

The command to run when the first argument doesn't match any known
commands.

For pnpm-style behavior, set this to 'run-exec'. e.g:

Terminal:

```bash
​​$ ​​vlt config set fallback-command=run-exec
```

Valid options:

```
"cache", "config", "exec", "exec-local",
"help", "init", "install", "login", "logout",
"list", "ls", "pkg", "query", "run-exec", "run", "serve",
"token", "uninstall", "exec-cache", "whoami"
```

### `--package=<p>`

When running `vlt exec`, this allows you to explicitly set the package
to search for bins. If not provided, then vlt will interpret the first
argument as the package, and attempt to run the default executable.

### `--view=<output>`

Configures the output format for commands. Valid options: "human",
"json", "mermaid", "count"

### `--dashboard-root=<path>`

The root directory to use for the dashboard browser-based UI. If not
set, the user home directory is used.

Can be set multiple times

### `-D --save-dev`

Save installed packages to a package.json file as devDependencies

### `-O --save-optional`

Save installed packages to a package.json file as optionalDependencies

### `--save-peer`

Save installed packages to a package.json file as peerDependencies

### `-P --save-prod`

Save installed packages into dependencies specifically. This is useful
if a package already exists in devDependencies or
optionalDependencies, but you want to move it to be a non-optional
production dependency.

### `--save-types`

For each added registry package that ships no TypeScript types of its
own (no `types`, `typings` or `typesVersions` field, no `types`
condition in its root `exports` entry), also save the newest
non-deprecated `@types/*` package in the same major version
(major.minor for `0.x`) to `devDependencies` (`@scope/pkg` →
`@types/scope__pkg`). If that major has none, the `@types/*` `latest`
version is used when it is older and not deprecated. Skipped when
there is no such version, the `@types/*` package is already a
dependency (any version), or the package comes from a different
registry than `@types/*`.

Enable for every install with `"config": { "save-types": true }` in
`vlt.json`; turn off for one run with `--no-save-types`.

### `--migrate-workspaces`

On by default. `vlt install` saves workspaces read from the
`workspaces` field of the root `package.json` or from
`pnpm-workspace.yaml` to the project `vlt.json`, which then takes
precedence. Set `--no-migrate-workspaces` or
`"config": { "migrate-workspaces": false }` in `vlt.json` to skip
this; an already saved `workspaces` field stays until removed. See
[Workspaces](/client/workspaces#saving-workspaces-to-vltjson).

### `--save-config`

Save the registry and git host options given on the command line or
via `VLT_*` env (`--registry`, `--registries`,
`--default-registry-alias`, `--scoped-registries`, `--jsr-registries`,
`--git-hosts`, `--git-host-archives`) to the project `vlt.json` (or
the user one with `--config=user`) after a successful `install`, `add`
or `update`. Values a config file already has are left alone. See
[Registries](/client/registries#saving-registries-given-to-install).

### `--allow-skills=<query>`

Link the agent skills (folders with a `SKILL.md`) shipped by installed
packages matching this DSS query into the project's agent skill dirs
(see `--skills-dir`) after `install`, `ci`, `update` or `uninstall`.
End a selector with `:skill(<name>, …)` to pick single skills (`*`
globs, double-quoted names). Unset (the default) or `:not(*)` links
nothing and skips all skills work.

`vlt install --allow-skills=<query>` saves the query to the project
`vlt.json`; `vlt skills link [<query>]` sets, saves and applies it.

Example: `--allow-skills="#agent-browser:skill(agent-browser)"` links
the `agent-browser` skill from a package with the same name. See
[`vlt skills`](/client/commands/skills#pick-skills).

### `--skills-dir=<path>`

Dirs to link agent skills into, relative to the project root. Can be
set multiple times. Each dir must be inside the project, not in
`node_modules`.

| Value                      | Meaning                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------- |
| unset                      | detect, see [Where skills are linked](/client/commands/skills#where-skills-are-linked) |
| `[]` in `vlt.json`         | link nothing                                                                           |
| `--skills-dir=`            | link nothing                                                                           |
| `null` in `vlt.json`       | back to detection                                                                      |
| a list on the command line | replaces the `vlt.json` list                                                           |

### `-v --version`

Print the version

### `-h --help`

Print helpful information

# Graph Modifiers (/client/graph-modifiers)

Graph Modifiers are a recent addition to the **vlt client** that allow
you to dynamically alter and refine how the package dependency graph
is traversed and evaluated. This feature gives you granular control
over installed packages, including their transitive dependencies,
letting you target exactly which parts of the graph to operate on.

***

## Overview

Graph Modifiers extend the existing dependency graph traversal logic
in **vlt** using our [Dependency Selector Syntax](/client/selectors).
These selectors let you modify the behavior of an existing
`vlt install` operation, allowing you to target specific packages and
their dependencies.

**Note:** In its initial release, Graph Modifiers support a limited
subset of the Dependency Selector Syntax:

* `:root`
* `:project`
* `:workspace`
* ID selectors (`#package-name`)
* Semantic version selectors (`:v(^1.0.0)`)
* Direct dependency combinator (`>`)

### Understanding how Graph Modifiers work

User-defined Graph Modifier entries will be read and applied during
the graph build phase. In order to apply new modifier entries the
graph build will be retriggered every time the `"modifiers"` property
is changed in the `vlt.json` file

***

## Usage

Graph Modifiers are configured via the `modifiers` field in your
`vlt.json` configuration file. Below are some examples on how to use
it:

### Basic Overrides

```json
{
  "modifiers": {
    ":root > #express": "^4.18.0",
    "#lodash": "^4.17.21"
  }
}
```

The keys are selectors that identify which dependency to override, and
the values specify the versions to enforce.

### Universal Selector

```json
{
  "modifiers": {
    "#react": "^18.2.0"
  }
}
```

Replaces **every** occurrence of `react` in the dependency tree with
version `^18.2.0`.

### Path-Specific Selector

```json
{
  "modifiers": {
    ":root > #next > #react": "^17.0.0"
  }
}
```

Only overrides `react` when it’s a direct dependency of `next`, which
is a direct dependency of the root project.

### Removing Dependencies

```json
{
  "modifiers": {
    ":root > #left-pad": "-",
    "#some-pkg > #unwanted-dep": "-"
  }
}
```

The value `"-"` removes the selected dependency: it is not resolved,
installed or saved to `vlt-lock.json`, nor is anything only it pulled
in. Its `package.json` entry is left as is. An explicit
`vlt install left-pad` fails with a config error until the modifier is
removed. Normal selector rules apply: the most specific matching
modifier wins, whatever its value (see
[Specificity Resolution](#specificity-resolution)).

### Adding Comments to Selectors

```json
{
  "modifiers": {
    "/* pin down exact version */ :root > #express > #body-parser > #qs": "=6.10.0"
  }
}
```

Inline comments can be added to selector keys for clarity.

### Specificity Resolution

```json
{
  "dependencies": {
    "express": "^4.17.0"
  },
  "modifiers": {
    ":root > #express > #cookie": "^0.5.0",
    "#cookie": "^0.4.0"
  }
}
```

CSS-like specificity rules determine which modifier applies when
multiple selectors match the same dependency. Here, the more specific
`:root > #express > #cookie` takes precedence over `#cookie`.

### Semver Pseudo-Selectors

```json
{
  "modifiers": {
    "#lodash:v(^4.0.0)": "^4.17.21"
  }
}
```

This only affects `lodash` dependencies matching the semver range
`^4.0.0`.

### Integration with Catalogs

```json
{
  "catalogs": {
    "tools": {
      "react": "^18.2.0"
    }
  },
  "modifiers": {
    "#react": "catalog:tools"
  }
}
```

It's possible to point to configured catalogued versions from
modifiers.

### Using with workspaces

```json
{
  "workspaces": "packages/*",
  "modifiers": {
    ":workspace > #typescript": "^5.0.0",
    "#core:workspace > #typescript": "~5.1.0"
  }
}
```

You may use the `:workspace` selector to target workspaces. In the
example above we target a specific workspace named `core` by combining
the `#core` ID selector with the `:workspace` selector.

***

## Best Practices

* **Start Small:** Test modifiers incrementally to understand how you
  are modifying your install,
* **Combine wisely:** Use path-specific and universal selectors to
  control installations accurately.

***

## See Also

* [Workspaces](/client/workspaces)
* [Catalogs](/client/catalogs)

***

Graph Modifiers enable precise and efficient package management in
vlt. Future updates will expand selector support and add advanced
capabilities.

# Getting Started with the vlt CLI (/client)

## Installation

Terminal:

```bash
$ curl -fsSL https://install.vlt.sh | bash
```

`vlt` requires Node.js 22.22 or later.

# Migrating from npm to vlt (/client/migration/from-npm)

## Quick Start

Terminal:

```bash
# Install vlt globally
$ npm install -g vlt

# Configure the npm registry alias -- vlt has no default

$ vlt config set registries=npm=https://registry.npmjs.org/

# In your existing project, run:

$ vlt install $ vlt build
```

That's it for basic usage. vlt reads your existing `package.json` and
resolves dependencies. Below are the details on what's different and
how to handle specific scenarios.

### First: configure your registry

Unlike npm, **vlt has no default registry**. Commands that resolve or
fetch packages fail with a config error until one is set:

```
Config Error: Missing registry configuration.

vlt has no default registry. Run `vlt setup` to get configured.

See https://docs.vlt.sh/cli for other ways to set a registry.
```

If you have a vlt.io account, the guided path is
[`vlt setup`](/client/registries#getting-started-with-vlt-setup),
which configures your account's registry aliases for you.

To instead keep npm's behavior, point the `npm` alias at the public
npm registry:

Terminal:

```bash
$ vlt config set registries=npm=https://registry.npmjs.org/
```

Commands that install packages (`vlt install`, `vlt update`,
`vlt uninstall`, `vlt ci`, `vlx`/`vlt exec`) require that alias
specifically (or the one named by `default-registry-alias`, if you
changed it). A scalar `--registry` / `VLT_REGISTRY` is enough for
other registry-hitting commands (for example `vlt ping`), but not for
install.

Or set it in `vlt.json`, pass `--registries npm=<url>` per command, or
export `VLT_REGISTRIES`. See [Registries](/client/registries).

***

## Command Mapping

| npm                            | vlt                                        | Notes                                           |
| ------------------------------ | ------------------------------------------ | ----------------------------------------------- |
| `npm install`                  | `vlt install`                              | Does **not** run lifecycle scripts              |
| `npm install <pkg>`            | `vlt install <pkg>`                        | Same behavior                                   |
| `npm install -D <pkg>`         | `vlt install -D <pkg>`                     | Same flags                                      |
| `npm uninstall <pkg>`          | `vlt uninstall <pkg>`                      | Aliases: `rm`, `u`                              |
| `npm run <script>`             | `vlt run <script>`                         | Aliases: `r`, `run-script`                      |
| `npm test`                     | `vlt run test`                             | No `vlt test` shorthand                         |
| `npm start`                    | `vlt run start`                            | No `vlt start` shorthand                        |
| `npx <pkg>`                    | `vlx <pkg>`                                | Run remote packages                             |
| `npm exec <cmd>`               | `vlt exec <cmd>`                           | Local bins on PATH                              |
| `npm init`                     | `vlt init`                                 | Creates `package.json`                          |
| `npm pack`                     | `vlt pack`                                 |                                                 |
| `npm publish`                  | `vlt publish`                              |                                                 |
| `npm login`                    | `vlt login`                                |                                                 |
| `npm whoami`                   | `vlt whoami`                               |                                                 |
| `npm ls`                       | `vlt list`                                 | Alias: `ls`                                     |
| `npm query`                    | `vlt query`                                | Uses DSS, not CSS selectors                     |
| `npm ci`                       | `vlt install --expect-lockfile`            | Strict lockfile mode                            |
| `npm install --ignore-scripts` | `vlt install`                              | Default behavior                                |
| `npm audit`                    | `vlt query ':malware'`                     | More powerful; see [Security](/client/security) |
| `npm config set <key>=<val>`   | `vlt config set <key>=<val>`               | Writes to `vlt.json`                            |
| `npm overrides`                | [Graph Modifiers](/client/graph-modifiers) | DSS-based, more precise                         |

***

## Configuration

### .npmrc → vlt.json

npm reads configuration from `.npmrc` files (INI format, multiple
locations). vlt uses a single `vlt.json` file in your project root,
plus an optional user-level `vlt.json` in the XDG config directory.

.npmrc:

```ini
# .npmrc (npm)
registry=https://registry.internal.company.com/
@mycompany:registry=https://npm.mycompany.com/
save-exact=true
```

vlt.json:

```json

```

To create this file interactively:

Terminal:

```bash
$ vlt config set registry=https://registry.internal.company.com/
$ vlt config set scoped-registries=@mycompany=https://npm.mycompany.com/
```

### User vs Project Config

| npm                          | vlt                           |
| ---------------------------- | ----------------------------- |
| `~/.npmrc` (user)            | XDG config dir `vlt/vlt.json` |
| `.npmrc` (project)           | `vlt.json` (project root)     |
| `$PREFIX/etc/npmrc` (global) | No global config file         |

View config locations:

Terminal:

```bash
$ vlt config location --config=user
$ vlt config location --config=project
```

***

## Registry Configuration

vlt handles registries similarly to npm, with some additions.

### Scoped Registries

npm's scoped registries map directly:

.npmrc:

```ini
# npm (.npmrc)
@mycompany:registry=https://npm.mycompany.com/
```

vlt.json:

```json

```

### Named Registry Aliases

vlt also supports [named registry aliases](/client/registries), which
are more explicit than scope-based mapping. This is a vlt-specific
feature:

vlt.json:

```json

```

Then reference packages explicitly:

Terminal:

```bash
$ vlt install internal:@mycompany/utils@^2.0
```

***

## Authentication

### Tokens

npm stores auth tokens in `.npmrc`. vlt stores them in an
XDG-compliant keychain file, which is less likely to be accidentally
committed to source control.

Terminal:

```bash
# npm: tokens live in .npmrc (risky if committed)
//registry.npmjs.org/:_authToken=npm_abc123

# vlt: log in interactively

$ vlt login

# vlt: or for custom registries

$ vlt login --registry=https://npm.mycompany.com/
```

### CI Environments

Terminal:

```bash
# npm
NPM_TOKEN=abc123 npm install

# vlt

VLT_TOKEN=abc123 vlt install
```

For non-default registries, replace non-alphanumeric characters in the
URL with `_`:

Terminal:

```bash
VLT_TOKEN_https_npm_mycompany_com=abc123 vlt install
```

See [Authentication](/client/auth) for full details.

***

## Lockfile

npm uses `package-lock.json`. vlt uses `vlt-lock.json`.

When you first run `vlt install`, vlt resolves from your
`package.json` and creates `vlt-lock.json`. Your existing
`package-lock.json` is not read or migrated — vlt performs a fresh
resolution.

**What to do:**

1. Run `vlt install` to generate `vlt-lock.json`
2. Commit `vlt-lock.json` to source control
3. Optionally remove `package-lock.json` (or keep it if you're running
   both tools during a transition period)

### CI / Frozen Lockfile

Terminal:

```bash
# npm
$ npm ci

# vlt

$ vlt install --expect-lockfile
```

***

## Install Script Protection

This is the biggest behavioral difference from npm.

**npm** runs all lifecycle scripts (`preinstall`, `install`,
`postinstall`) automatically during `npm install`. This is a known
supply chain attack vector.

**vlt** separates installation into two phases:

1. **`vlt install`** — Downloads and extracts packages. No scripts
   run.
2. **`vlt build`** — Runs lifecycle scripts selectively.

Terminal:

```bash
# Install packages (safe — no code executes)
$ vlt install

# Run build scripts, automatically excluding packages flagged as malware

$ vlt build
```

By default, `vlt build` uses the target
`:scripts:not(:built):not(:malware)`, which skips packages with known
malware alerts.

You can be more selective:

Terminal:

```bash
# Only allow specific packages to run scripts
$ vlt build --target="#esbuild, #node-gyp"

# Or allow scripts for direct dependencies only

$ vlt build --target=":root > :scripts"
```

If you need legacy npm behavior (not recommended):

Terminal:

```bash
$ vlt install --allow-scripts='*'
```

See [`vlt build`](/client/commands/build) for full details.

***

## Workspaces

**Your existing npm workspaces just work.** vlt reads the `workspaces`
field of the root `package.json`, and `vlt install` copies it to
`vlt.json`:

package.json:

```json

```

Exclusion patterns such as `!packages/legacy` are honored and copied
too. `package.json` is left as-is for npm. Commit `vlt.json`: `vlt ci`
reads workspaces from it only.

Edit `vlt.json` to use vlt's named groups, which let you run
operations against a subset of your workspaces:

vlt.json:

```json

```

### Key Differences

* **Precedence** — if `vlt.json` has a `workspaces` field it wins
  outright, and the `package.json` field is ignored rather than
  merged. Once copied, later `package.json` edits are ignored by vlt:
  update `vlt.json` too.
* **Named groups** — supported only in `vlt.json`, since a
  `package.json` using them would be meaningless to npm.

### Workspace Commands

| npm                               | vlt                               |
| --------------------------------- | --------------------------------- |
| `npm run test -w packages/a`      | `vlt run test -w packages/a`      |
| `npm run test --workspaces`       | `vlt run test --recursive`        |
| `npm install <pkg> -w packages/a` | `vlt install <pkg> -w packages/a` |

See [Workspaces](/client/workspaces) for full details.

***

## Overrides → Graph Modifiers

npm uses `overrides` in `package.json` to force dependency versions.
vlt uses [Graph Modifiers](/client/graph-modifiers) in `vlt.json`,
which are powered by DSS selectors and offer more precise targeting.

package.json (npm):

```json

```

vlt.json:

```json

```

Graph Modifiers use CSS-like specificity rules when multiple selectors
match the same dependency.

***

## Migration Checklist

1. Install vlt: `npm install -g vlt`
2. In your project root, create `vlt.json` with your registry config
   (or use `vlt config set`)
3. Move any scoped registry config from `.npmrc` to `vlt.json`
4. Leave your `workspaces` field in `package.json` — `vlt install`
   copies it to `vlt.json`
5. Move `overrides` from `package.json` to `modifiers` in `vlt.json`
6. Run `vlt install` then `vlt build`
7. Commit `vlt.json` and `vlt-lock.json`
8. Update CI scripts: replace `npm ci` with
   `vlt install --expect-lockfile && vlt build`
9. Update CI auth: replace `NPM_TOKEN` with `VLT_TOKEN`
10. Update any `npx` usage to `vlx`

# Migrating from pnpm to vlt (/client/migration/from-pnpm)

## Quick Start

Terminal:

```bash
# Install vlt globally
$ npm install -g vlt

# Configure a registry -- vlt has no default

$ vlt config set registry=https://registry.npmjs.org/

# In your existing project, run:

$ vlt install $ vlt build
```

Unlike pnpm, **vlt has no default registry** — commands that resolve
or fetch packages fail with a config error until one is set. The
snippet above points it at the public npm registry; if you have a
vlt.io account, run
[`vlt setup`](/client/registries#getting-started-with-vlt-setup)
instead to configure your account's registry aliases. See
[Registries](/client/registries).

vlt reads your existing `package.json` files and resolves
dependencies. The `pnpm-lock.yaml` file is not migrated — vlt performs
a fresh resolution and creates `vlt-lock.json`.

***

## Command Mapping

| pnpm                             | vlt                             | Notes                                                                 |
| -------------------------------- | ------------------------------- | --------------------------------------------------------------------- |
| `pnpm install`                   | `vlt install`                   | Does **not** run lifecycle scripts                                    |
| `pnpm add <pkg>`                 | `vlt install <pkg>`             |                                                                       |
| `pnpm add -D <pkg>`              | `vlt install -D <pkg>`          |                                                                       |
| `pnpm remove <pkg>`              | `vlt uninstall <pkg>`           |                                                                       |
| `pnpm run <script>`              | `vlt run <script>`              |                                                                       |
| `pnpm <script>`                  | `vlt run <script>`              | See [fallback-command](/client/configuring#--fallback-commandcommand) |
| `pnpm dlx <pkg>`                 | `vlx <pkg>`                     | Run remote packages                                                   |
| `pnpm exec <cmd>`                | `vlt exec <cmd>`                |                                                                       |
| `pnpm init`                      | `vlt init`                      |                                                                       |
| `pnpm pack`                      | `vlt pack`                      |                                                                       |
| `pnpm publish`                   | `vlt publish`                   |                                                                       |
| `pnpm login`                     | `vlt login`                     |                                                                       |
| `pnpm whoami`                    | `vlt whoami`                    |                                                                       |
| `pnpm list`                      | `vlt list`                      |                                                                       |
| `pnpm why <pkg>`                 | `vlt query '#<pkg>'`            | DSS query; see [Selectors](/client/selectors)                         |
| `pnpm install --frozen-lockfile` | `vlt install --frozen-lockfile` |                                                                       |
| `pnpm audit`                     | `vlt query ':malware'`          | More powerful; see [Security](/client/security)                       |
| `pnpm config set <key> <val>`    | `vlt config set <key>=<val>`    |                                                                       |

### Shorthand Script Execution

pnpm lets you run scripts without `run` (e.g., `pnpm build`). vlt
supports this via the `fallback-command` config:

Terminal:

```bash
$ vlt config set fallback-command=run-exec
```

After setting this, `vlt build` will first check for a vlt command
named `build`, and if none matches, look for a `package.json` script.

***

## Configuration

### .npmrc + pnpm-workspace.yaml → vlt.json

pnpm reads registry config from `.npmrc` and workspace config from
`pnpm-workspace.yaml`. vlt consolidates everything into `vlt.json`.
vlt also reads the `packages` list of `pnpm-workspace.yaml`, and
`vlt install` copies it to `vlt.json`.

**pnpm configuration:**

.npmrc:

```ini
# .npmrc (pnpm)
registry=https://registry.internal.company.com/
@mycompany:registry=https://npm.mycompany.com/
auto-install-peers=true
```

pnpm-workspace.yaml:

```yaml
# pnpm-workspace.yaml
packages:
- "packages/*"
- "apps/*"
```

**vlt equivalent (single file):**

vlt.json:

```json

```

***

## Registry Configuration

### Scoped Registries

pnpm's scoped registries (from `.npmrc`) map directly to vlt's
`scoped-registries`:

vlt.json:

```json

```

### Named Registry Aliases

vlt also supports [named registry aliases](/client/registries) which
remove the ambiguity of scope-based mapping:

vlt.json:

```json

```

Then reference packages explicitly in `package.json`:

package.json:

```json

```

***

## Authentication

pnpm stores auth tokens in `.npmrc`, same as npm. vlt stores them in
an XDG-compliant keychain file, keeping secrets out of project config
files.

Terminal:

```bash
# Log in to default registry
$ vlt login

# Log in to custom registry

$ vlt login --registry=https://npm.mycompany.com/
```

### CI Environments

Terminal:

```bash
# pnpm
NPM_TOKEN=abc123 pnpm install

# vlt

VLT_TOKEN=abc123 vlt install
```

See [Authentication](/client/auth) for full details.

***

## Lockfile

pnpm uses `pnpm-lock.yaml`. vlt uses `vlt-lock.json`.

When you first run `vlt install`, vlt creates `vlt-lock.json` from a
fresh resolution of your `package.json` files. The `pnpm-lock.yaml` is
not read.

**What to do:**

1. Run `vlt install` to generate `vlt-lock.json`
2. Commit `vlt-lock.json`
3. Optionally remove `pnpm-lock.yaml` once you've fully switched

***

## Install Script Protection

pnpm runs lifecycle scripts by default during install (same as npm).
pnpm v9+ added `onlyBuiltDependencies` in `package.json` as an
allowlist, but scripts still run by default for listed packages.

**vlt** takes a different approach: `vlt install` runs **no scripts at
all** by default. Building is a separate, explicit step:

Terminal:

```bash
# Phase 1: Install (no code executes)
$ vlt install

# Phase 2: Build (runs scripts, skipping known malware)

$ vlt build
```

By default, `vlt build` uses the target
`:scripts:not(:built):not(:malware)` — it automatically skips packages
flagged as malware by [Socket](https://socket.dev/).

### pnpm onlyBuiltDependencies vs vlt build --target

package.json (pnpm):

```json

```

Terminal (vlt):

```bash
$ vlt build --target='#esbuild, #node-gyp'
```

You can persist the target:

Terminal:

```bash
$ vlt config set "command.build.target=#esbuild, #node-gyp"
```

See [`vlt build`](/client/commands/build) for full details.

***

## Workspaces

### pnpm

pnpm defines workspaces in `pnpm-workspace.yaml`:

pnpm-workspace.yaml:

```yaml
packages:
- "packages/*"
- "apps/*"
```

### vlt

vlt reads that `packages` list, and `vlt install` copies it to
`vlt.json`, vlt's own place for workspaces (see
[Workspaces](/client/workspaces#saving-workspaces-to-vltjson)).
`pnpm-workspace.yaml` is left as-is. Commit `vlt.json`: `vlt ci` reads
workspaces from it only, and later `pnpm-workspace.yaml` edits are
ignored by vlt:

vlt.json:

```json

```

vlt also supports **named workspace groups**:

vlt.json:

```json

```

### Workspace Commands

| pnpm                               | vlt                                               |
| ---------------------------------- | ------------------------------------------------- |
| `pnpm --filter <name> <cmd>`       | `vlt <cmd> -w <path>` or `cd <path> && vlt <cmd>` |
| `pnpm --filter ./packages/* <cmd>` | `vlt <cmd> -w packages/*`                         |
| `pnpm -r <cmd>`                    | `vlt <cmd> --recursive`                           |
| `pnpm -r run test`                 | `vlt run test --recursive`                        |

**Note:** vlt's `--workspace` (`-w`) flag takes paths or glob
patterns, not package names.

Terminal:

```bash
# Run tests in a specific workspace
$ vlt run test -w packages/core

# Run build across a workspace group

$ vlt run build -g libs
```

See [Workspaces](/client/workspaces) for full details.

***

## Catalogs

If you use pnpm's catalog feature (`pnpm-workspace.yaml`), vlt has
direct support for [catalogs](/client/catalogs) with compatible
syntax. vlt doesn't read `catalog`/`catalogs` from
`pnpm-workspace.yaml`; move them to `vlt.json`, else `catalog:` specs
fail with a [catalog error](/client/catalogs#error-handling).

**pnpm:**

pnpm-workspace.yaml:

```yaml
# pnpm-workspace.yaml
packages:
- "packages/*"

catalog: typescript: "^5.0.0" eslint: "^8.0.0"

catalogs: testing: vitest: "^1.0.0"
```

**vlt:**

vlt.json:

```json

```

The `catalog:` protocol in `package.json` works the same way:

package.json:

```json

```

See [Catalogs](/client/catalogs) for full details.

***

## Overrides → Graph Modifiers

pnpm uses `pnpm.overrides` in `package.json`. vlt uses
[Graph Modifiers](/client/graph-modifiers) in `vlt.json`.

package.json (pnpm):

```json

```

vlt.json:

```json

```

Graph Modifiers use DSS selectors, giving you more precise control
(e.g., target by path, workspace, or semver range).

pnpm's `"-"` override value maps to the same `"-"` modifier value, see
[Removing Dependencies](/client/graph-modifiers#removing-dependencies).

***

## node\_modules Layout

pnpm uses a content-addressable store with symlinks to create a strict
`node_modules` layout where packages can only access their declared
dependencies.

vlt also creates a `node_modules` directory but uses a different
internal layout (under `node_modules/.vlt/`). The result is similar in
that packages resolve correctly at runtime — your application code
doesn't need to change.

***

## Features Not in vlt

Some pnpm-specific features don't have direct equivalents:

* **Side-effects cache** — Not available in vlt
* **`pnpm patch`** — Not yet available in vlt
* **`pnpm deploy`** — Not available; use standard deployment tooling
* **`pnpm.peerDependencyRules`** — vlt handles peer dependencies
  automatically with [context isolation](/client/peer-dependencies)

***

## Migration Checklist

1. Install vlt: `npm install -g vlt`
2. Create `vlt.json` with your `.npmrc` registry config (`vlt install`
   copies `pnpm-workspace.yaml` `packages` to it)
3. Move scoped registry config from `.npmrc` to `vlt.json`
4. Move catalogs from `pnpm-workspace.yaml` to `vlt.json` (`catalog`
   and `catalogs` fields)
5. Move `pnpm.overrides` from `package.json` to `modifiers` in
   `vlt.json`
6. Run `vlt install` then `vlt build`
7. Commit `vlt.json` and `vlt-lock.json`
8. Update CI scripts: replace `pnpm install --frozen-lockfile` with
   `vlt install --frozen-lockfile && vlt build`
9. Update CI auth: replace `NPM_TOKEN` with `VLT_TOKEN`
10. Update any `pnpm dlx` usage to `vlx`
11. Remove `pnpm-workspace.yaml` and pnpm-specific `.npmrc` settings
    once no other tool reads them

# Migrating from yarn to vlt (/client/migration/from-yarn)

This guide covers migration from both &#x2A;*yarn v1 (classic)** and &#x2A;*yarn
v2+ (berry)**. Key differences are called out where they apply.

## Quick Start

Terminal:

```bash
# Install vlt globally
$ npm install -g vlt

# Configure a registry -- vlt has no default

$ vlt config set registry=https://registry.npmjs.org/

# In your existing project, run:

$ vlt install $ vlt build
```

Unlike yarn, **vlt has no default registry** — commands that resolve
or fetch packages fail with a config error until one is set. The
snippet above points it at the public npm registry; if you have a
vlt.io account, run
[`vlt setup`](/client/registries#getting-started-with-vlt-setup)
instead to configure your account's registry aliases. See
[Registries](/client/registries).

vlt reads your existing `package.json` files and resolves
dependencies. The `yarn.lock` file is not migrated — vlt performs a
fresh resolution and creates `vlt-lock.json`.

***

## Command Mapping

| yarn                             | vlt                             | Notes                                                                 |
| -------------------------------- | ------------------------------- | --------------------------------------------------------------------- |
| `yarn` / `yarn install`          | `vlt install`                   | Does **not** run lifecycle scripts                                    |
| `yarn add <pkg>`                 | `vlt install <pkg>`             |                                                                       |
| `yarn add -D <pkg>`              | `vlt install -D <pkg>`          |                                                                       |
| `yarn remove <pkg>`              | `vlt uninstall <pkg>`           |                                                                       |
| `yarn run <script>`              | `vlt run <script>`              |                                                                       |
| `yarn <script>`                  | `vlt run <script>`              | See [fallback-command](/client/configuring#--fallback-commandcommand) |
| `yarn dlx <pkg>` / `npx <pkg>`   | `vlx <pkg>`                     | Run remote packages                                                   |
| `yarn exec <cmd>`                | `vlt exec <cmd>`                |                                                                       |
| `yarn init`                      | `vlt init`                      |                                                                       |
| `yarn pack`                      | `vlt pack`                      |                                                                       |
| `yarn npm publish`               | `vlt publish`                   |                                                                       |
| `yarn npm login`                 | `vlt login`                     |                                                                       |
| `yarn npm whoami`                | `vlt whoami`                    |                                                                       |
| `yarn workspaces list`           | `vlt list`                      |                                                                       |
| `yarn why <pkg>`                 | `vlt query '#<pkg>'`            | DSS query; see [Selectors](/client/selectors)                         |
| `yarn install --frozen-lockfile` | `vlt install --frozen-lockfile` |                                                                       |
| `yarn install --immutable`       | `vlt install --expect-lockfile` |                                                                       |
| `yarn config set <key> <val>`    | `vlt config set <key>=<val>`    |                                                                       |
| `yarn up <pkg>`                  | `vlt install <pkg>`             | Re-resolves to latest matching                                        |

### Shorthand Script Execution

Yarn lets you run scripts without `run` (e.g., `yarn build`). vlt
supports this via the `fallback-command` config:

Terminal:

```bash
$ vlt config set fallback-command=run-exec
```

After setting this, `vlt build` will first check for a vlt command
named `build`, and if none matches, look for a `package.json` script.

***

## Configuration

### .yarnrc.yml / .yarnrc → vlt.json

yarn v1 uses `.yarnrc` and `.npmrc`. yarn v2+ uses `.yarnrc.yml`. vlt
uses `vlt.json`.

**yarn v2+ example:**

.yarnrc.yml:

```yaml
# .yarnrc.yml (yarn berry)
npmRegistryServer: "https://registry.internal.company.com/"
npmScopes:
mycompany:
  npmRegistryServer: "https://npm.mycompany.com/"
  npmAuthToken: "abc123"
```

**vlt equivalent:**

vlt.json:

```json

```

Auth tokens are stored separately in vlt's keychain, not in config
files. See [Authentication](#authentication) below.

**yarn v1 example:**

.npmrc:

```ini
# .npmrc (yarn classic)
registry=https://registry.internal.company.com/
@mycompany:registry=https://npm.mycompany.com/
```

Same `vlt.json` as above.

***

## Registry Configuration

### Scoped Registries

Both yarn and vlt support scope-to-registry mapping:

vlt.json:

```json

```

### Named Registry Aliases

vlt also supports [named registry aliases](/client/registries), which
are more explicit than scoped registries. Dependencies reference a
named registry directly, removing ambiguity:

vlt.json:

```json

```

package.json:

```json

```

***

## Authentication

yarn v1 stores tokens in `.npmrc`. yarn v2+ stores them in
`.yarnrc.yml`. Both approaches risk accidental commits of secrets.

vlt stores auth tokens in an XDG-compliant keychain file, separate
from project configuration.

Terminal:

```bash
# Log in to default registry
$ vlt login

# Log in to a custom registry

$ vlt login --registry=https://npm.mycompany.com/
```

### CI Environments

Terminal:

```bash
# yarn v2+
YARN_NPM_AUTH_TOKEN=abc123 yarn install

# vlt

VLT_TOKEN=abc123 vlt install
```

See [Authentication](/client/auth) for full details.

***

## Lockfile

yarn v1 uses `yarn.lock` (custom format). yarn v2+ also uses
`yarn.lock` (YAML-based). vlt uses `vlt-lock.json`.

When you first run `vlt install`, vlt creates `vlt-lock.json` from a
fresh resolution. Your `yarn.lock` is not read.

**What to do:**

1. Run `vlt install` to generate `vlt-lock.json`
2. Commit `vlt-lock.json`
3. Optionally remove `yarn.lock` once you've fully switched

***

## Install Script Protection

This is a major difference from yarn.

**yarn v1** runs all lifecycle scripts automatically. &#x2A;*yarn v2+**
runs scripts for direct dependencies but blocks transitive dependency
scripts by default (you can allowlist via `.yarnrc.yml`).

**vlt** goes further: `vlt install` runs **no scripts at all** by
default. The build step is completely separate:

Terminal:

```bash
# Phase 1: Install (no code executes)
$ vlt install

# Phase 2: Build (runs scripts, skipping known malware)

$ vlt build
```

By default, `vlt build` uses the target
`:scripts:not(:built):not(:malware)` — it only runs scripts for
packages that need building and aren't flagged as malware by
[Socket](https://socket.dev/).

You can target scripts precisely:

Terminal:

```bash
# Only allow specific trusted packages
$ vlt build --target="#esbuild, #node-gyp"

# Persist your choice

$ vlt config set "command.build.target=#esbuild, #node-gyp"
```

See [`vlt build`](/client/commands/build) for full details.

***

## Workspaces

### yarn v1

yarn v1 defines workspaces in the root `package.json`:

package.json (yarn v1):

```json

```

### yarn v2+

yarn v2+ is similar but also supports the `workspaces` field in
`.yarnrc.yml` for additional filtering.

### vlt

**Your existing yarn workspaces just work.** vlt reads the
`workspaces` field of the root `package.json`, in both the array form
above and the object form, where the `nohoist` key is parsed and
ignored. `vlt install` copies the globs to `vlt.json` as a plain
array, dropping `nohoist`:

package.json (yarn v1, object form):

```json

```

Exclusion patterns such as `!packages/legacy` are honored and copied
too. `package.json` is left as-is for yarn. Commit `vlt.json`:
`vlt ci` reads workspaces from it only. The `workspaces` field of
`.yarnrc.yml` is not read, so any yarn v2+ filtering defined there
needs to move.

Edit `vlt.json` to use vlt's **named workspace groups** for targeted
operations. If `vlt.json` has a `workspaces` field it wins outright,
and the `package.json` field is ignored rather than merged, so later
`package.json` edits need copying too:

vlt.json:

```json

```

Terminal:

```bash
# Run tests only in the libs group
$ vlt run test -g libs

# Run build across all workspaces

$ vlt run build --recursive
```

### Workspace Commands

| yarn                            | vlt                                               |
| ------------------------------- | ------------------------------------------------- |
| `yarn workspace <name> <cmd>`   | `cd <path> && vlt <cmd>` or `vlt <cmd> -w <path>` |
| `yarn workspaces foreach <cmd>` | `vlt <cmd> --recursive`                           |

See [Workspaces](/client/workspaces) for full details.

***

## Resolutions → Graph Modifiers

yarn uses `resolutions` in `package.json` to force dependency
versions. vlt uses [Graph Modifiers](/client/graph-modifiers) in
`vlt.json`.

package.json (yarn):

```json

```

vlt.json:

```json

```

Graph Modifiers use DSS selectors, which give you more precise control
over which instances of a dependency are affected.

***

## Plug'n'Play (PnP)

If you're using yarn v2+ with Plug'n'Play (no `node_modules`), the
switch to vlt means going back to a `node_modules`-based layout. This
is generally straightforward — vlt creates a standard `node_modules`
directory.

If your project relies on PnP-specific features (like `.pnp.cjs`
loaders), you'll need to remove those references from your build
tooling and runtime configuration.

***

## Features Not in vlt

Some yarn-specific features don't have direct equivalents:

* **Plug'n'Play / Zero-Installs** — vlt uses `node_modules`
* **Constraints** — Use vlt's [DSS query system](/client/selectors)
  for dependency policy enforcement
* **Patches** (`yarn patch`) — Not yet available in vlt
* **Protocols** (`portal:`, `patch:`) — vlt supports `file:`,
  `workspace:`, `git:`, and `registry:` specifiers

***

## Migration Checklist

1. Install vlt: `npm install -g vlt`
2. Create `vlt.json` with your registry configuration
3. Move scoped registry config from `.yarnrc.yml` / `.npmrc` to
   `vlt.json`
4. Leave your `workspaces` field in `package.json` — `vlt install`
   copies it to `vlt.json`
5. Move `resolutions` from `package.json` to `modifiers` in `vlt.json`
6. If using PnP, remove `.pnp.cjs`, `.pnp.loader.mjs`, and related
   `.yarnrc.yml` settings
7. Run `vlt install` then `vlt build`
8. Commit `vlt.json` and `vlt-lock.json`
9. Update CI scripts: replace `yarn install --immutable` with
   `vlt install --expect-lockfile && vlt build`
10. Update CI auth: replace `YARN_NPM_AUTH_TOKEN` with `VLT_TOKEN`
11. Update any `yarn dlx` usage to `vlx`

# Migrating to vlt (/client/migration)

## Migrating to vlt from Other Package Managers

This section covers how to switch from npm, yarn, or pnpm to vlt. Each
guide walks through the concrete steps: configuration, commands,
lockfiles, workspaces, and the key differences to be aware of.

### Choose Your Migration Path

* [**From npm**](/client/migration/from-npm) — Migrate from npm to vlt
* [**From yarn**](/client/migration/from-yarn) — Migrate from yarn (v1
  classic or v2+ berry) to vlt
* [**From pnpm**](/client/migration/from-pnpm) — Migrate from pnpm to
  vlt

### What Changes

Regardless of which package manager you're coming from, the core
changes are:

1. **Configuration moves to `vlt.json`** — A single JSON file replaces
   `.npmrc`, `.yarnrc.yml`, or `.npmrc` + `pnpm-workspace.yaml`
2. **Lockfile format changes** — vlt uses `vlt-lock.json` instead of
   `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`
3. **Install scripts don't run by default** — vlt separates
   installation from build. `vlt install` downloads packages without
   executing any lifecycle scripts. Use `vlt build` to selectively run
   scripts afterward
4. **Security is built in** — vlt integrates with
   [Socket](https://socket.dev/) for malware detection, and the query
   system lets you audit your dependency graph before any code runs

### What Stays the Same

* Your `package.json` files don't change (dependencies, scripts, etc.)
* Workspaces declared in the root `package.json` (npm, yarn) or in
  `pnpm-workspace.yaml` `packages` (pnpm) are read, and `vlt install`
  copies them to `vlt.json` (commit it; `vlt ci` reads `vlt.json`
  only)
* `node_modules` structure is compatible — your code runs the same way
* Registry authentication uses tokens, just stored differently
* Workspace packages still use `workspace:` protocol references

# Peer Dependencies Support (/client/peer-dependencies)

The vlt client handles peer dependencies by isolating their contexts,
allowing multiple versions of the same package to coexist when
necessary.

***

## Overview

Peer dependencies declare that a package expects a, often times,
unique version of another package to be present in the consuming
application. When different parts of your dependency tree require
incompatible peer versions, vlt automatically isolates these contexts.

**Key behavior:** The vlt client will always try to use an unique
version of a package for peer dependencies, when that is not possible
it subdivides your dependency graph into groups of peer dependency
contexts, allowing for duplicating packages in cases where it would be
impossible to resolve to a single, unique version of a package.

***

## How It Works

When vlt encounters packages with peer dependencies:

1. **Analyzes the current peer context** to reuse a single version
   that satisfy all occurrences of the peer dependency
2. When needed, **Fork the current peer context** so that a peer
   dependency can use a different version
3. **Duplicates packages** that need different versions of its peer
   dependencies
4. **Stores duplicates** in separate locations within the
   `node_modules/.vlt/` folder
5. **Links appropriately** so each package resolves to its correct
   peer version

This happens automatically during `vlt install`.

***

## Example: Multiple React Versions

Consider two packages (a and b) in your project that depend on
different React major versions. In the image below you can see the
difference in the resolved graph in case a common dependency (c) of
both packages adds a peer dependency on `react@*`:



In both scenarios:

* Dependency `a` has a regular dependency on `react@18` and `c`
* Dependency `b` has a regular dependency on `react@19` and `c`

In this example, when `c` has no peer dependencies, both `a` and `b`
will have edges pointing to the same resolved `c` node in the graph.

In the scenario in which `c` has a peer dependency on `react@*`, the
`c` node will be duplicated in order to accomodate reuse of its
ancestor's React version dependency.

***

## Inspecting Peer Dependencies

Use `vlt query` with the
[Dependency Selector Syntax](/client/selectors) to inspect peer
dependencies in your project.

### List All Peer Dependencies

Terminal:

```bash
$ vlt query :peer
```

Returns every package installed as a peer dependency.

### List Optional Peer Dependencies

Terminal:

```bash
$ vlt query ':peer:optional'
```

Shows peer dependencies marked as optional. These may or may not be
installed depending on whether they're used elsewhere in your
dependency tree.

### Find Packages with Peer Dependencies

Terminal:

```bash
$ vlt query ":has(:peer)"
```

Returns packages that declare direct peer dependencies, helping
identify which dependencies might get duplicated across different
contexts.

***

## Important Considerations

### Multiple Versions Are Normal

Unlike some expectations, peer dependencies **do not guarantee a
single version** in your final `node_modules` structure.

vlt's default behavior is to subdivide peer dependency contexts. If
different parts of your tree require incompatible peer versions,
multiple versions will be installed.

This is an intentional trade-off: each package gets exactly the peer
version it expects, avoiding runtime errors from version mismatches at
the expense of potentially having duplicate versions of that peer
dependency.

***

## See Also

* [Query Selectors](/client/selectors)
* [Graph Modifiers](/client/graph-modifiers)
* [Workspaces](/client/workspaces)

# Working with Named Registries (/client/registries)

The vlt client supports working with multiple registries in a variety
of ways.

> For a conceptual overview, see
> [Named Registries](/concepts/named-registries).

## Setting the Registry

**vlt has no default registry.** Before running any command that
resolves or fetches packages, you have to say which registry to use.
Commands that need one and do not have one fail with a config error:

```
Config Error: Missing registry configuration.

vlt has no default registry. Run `vlt setup` to get configured.

See https://docs.vlt.sh/cli for other ways to set a registry.
```

The guided path is [`vlt setup`](#getting-started-with-vlt-setup),
which configures your account's registry aliases so that
`vlt install <pkg>` and `vlx` work out of the box.

Commands that install packages (`vlt install`, `vlt update`,
`vlt uninstall`, `vlt ci`, `vlx`/`vlt exec`) additionally require the
`registries.npm` alias — or, when `default-registry-alias` is set to
something else, the alias it names. A scalar `--registry` /
`VLT_REGISTRY` is not enough. When that alias is missing they fail
with:

```
Config Error: Missing npm registry configuration.

Install commands require the `registries.npm` alias.
Run `vlt setup` to get configured.

See https://docs.vlt.sh/cli for other ways to set a registry.
```

There are four ways to configure the registry directly, in increasing
order of precedence:

1. **The `vlt.json` in your user config directory**, which applies to
   every project. Either write it by hand:

   ```json
   {
     "config": {
       "registry": "https://registry.npmjs.org/"
     }
   }
   ```

   or set it with the CLI:

   ```bash
   vlt config set registry=https://registry.npmjs.org/ --config=user
   ```

2. **The `vlt.json` in your project root**, which applies to that
   project only:

   ```bash
   vlt config set registry=https://registry.npmjs.org/
   ```

3. **The `VLT_REGISTRY` environment variable**, which is handy in CI:

   ```bash
   VLT_REGISTRY=https://registry.npmjs.org/ vlt install
   ```

4. **The `--registry` flag**, for a single command:

   ```bash
   vlt install --registry=https://registry.npmjs.org/
   ```

### Project vs. user registry configuration

A project's registry configuration always wins over the user-level
one. Because `registry` outranks any `registries` alias, that holds
even when the two layers use different fields: a project that sets
`registries` (or `default-registry-alias`) and no `registry` drops the
user-level `registry`, rather than being sent to it.

```json
// ~/.config/vlt/vlt.json
{
  "config": {
    "registry": "https://user/",
    "registries": { "main": "https://main/" }
  }
}
```

```json
// ./vlt.json
{ "config": { "registries": { "npm": "https://project/" } } }
```

> Note: The user level config file uses XDG paths that are
> OS-specific, the example `~/.config/vlt/vlt.json` path used here
> might not be the same path used in your system, to learn what is the
> user level config location for your system, run:
> `vlt config location --config=user`

In that project, bare specs and account commands resolve to
`https://project/`. The user's `main` alias is still merged in and
addressable as `main:` in a specifier, or with
[`vlt registry main …`](/client/commands/registry) — only the
*selection* is taken over. See [Configuring](/client/configuring) for
the full layering rules.

### Saving registries given to install

With `--save-config`, registry and git host options passed on the
command line or via `VLT_*` env to `vlt install`, `vlt add` or
`vlt update` are saved to the project `vlt.json` after a successful
install, so a fresh clone installs with a plain `vlt install`:

Terminal:

```bash
​​$ vlt install --save-config --registries loc=http://reg.local foo@loc:foo@1.x
```

```json
// ./vlt.json
{ "config": { "registries": { "loc": "http://reg.local/" } } }
```

* Without `--save-config` the options only apply to that run.
* Values already in effect from the user or project `vlt.json` are not
  copied.
* A different value for the same key in the target file (or its
  `command.<cmd>` block) is an `ECONFIG` error, nothing is installed.
  Change it with `vlt config set registries.loc=<url>` first. A
  missing or invalid name, or a missing value, is an `ECONFIG` error
  too.
* `--config=user` saves to the user `vlt.json` instead.
* When the project file had no `registry`, `registries` or
  `default-registry-alias`, the user's `registry` and
  `default-registry-alias` (with that alias's URL) are copied along,
  since the project now owns registry selection.
* A `vlt install` run by a vlt script (`vlt run`, `vlt exec`, ...)
  inherits `--save-config`, but only saves what was given to the
  parent vlt or set for the child, not config the parent read from its
  own files.

### Bootstrapping with `vlt login`

If you are starting from nothing, `vlt login` is the guided path. It
authenticates against the registry you give it and then writes that
registry into your project's `vlt.json`, so subsequent commands are
already configured:

```bash
vlt login --registry=https://registry.vlt.io/myorg/
```

Pass `--config=user` to configure it for every project instead.

There can be only one registry configured this way, and it is used as
the fallback for all package registry resolutions. Normally, if an
internal registry is used for all fetches, it effectively must serve
*all* packages, meaning it has to be a caching proxy, as well as the
repository for any of your organization's internal code.

Note that the built-in registry aliases (`gh:`, `jsr:`) and the `@jsr`
scope mapping still have built-in URLs. The `npm:` alias, however, is
**no longer built-in** — it has no baked-in URL and must be configured
(see [The `npm:` alias](#npm) below). All built-in aliases are
overridable within their own map (`registries.gh`,
`jsr-registries.jsr`, `git-hosts.github`, ...).

## Bare specs and `--default-registry-alias`

A **bare spec** — a dependency written without a registry protocol,
like `vlt install foo` or `"foo": "^1.0.0"` in `package.json`, as well
as any transitive dependency that omits a registry — resolves its
registry in the following order of precedence:

1. a matching `scoped-registries` entry (for scoped names)
2. the `registry` scalar (`--registry` / `VLT_REGISTRY`)
3. `registries[<default-registry-alias>]`

`--default-registry-alias` defaults to `npm`, so by default a bare
`foo` resolves through your configured `registries.npm`. Change it to
route bare specs (including transitive deps without an explicit
registry) through a different alias:

```bash
vlt config set default-registry-alias=main
```

Because the `npm` alias has no built-in URL, a fresh, unconfigured
project cannot resolve bare specs until you configure one — the guided
way to do that is `vlt setup`.

Note that a project which sets `registries` without also setting
`default-registry-alias` gets the default `npm` back, even if your
user config points it somewhere else. Set it in the project `vlt.json`
to route that project's bare specs through a different alias.

## Getting started with `vlt setup`

`vlt setup` is the onboarding wizard for a vlt.io account. Sign up or
log in at [https://www.vlt.io](https://www.vlt.io) first, then run:

```bash
vlt setup
```

It authenticates against your account and writes the two account
registry aliases into your user `vlt.json`:

```json
{
  "registries": {
    "npm": "https://registry.vlt.io/<account>/npm/",
    "main": "https://registry.vlt.io/<account>/main/"
  }
}
```

* `npm` is the default bare-spec alias, so `vlt install <pkg>` and
  `vlx` work immediately.
* `main` is your account's primary private registry (named `main:` to
  match the service).

The wizard then loops to let you add any additional custom aliases
(for partner or team registries), optionally authenticating against
each. To run it unattended (for example in CI or a setup script):

```bash
vlt setup my-account --yes --registries team=https://registry.example.com/
```

Only the account aliases, aliases passed on the command line, and
aliases you type at the prompt are written. Aliases that already live
in a `vlt.json` are left where they are, so a project-local alias does
not become a global one.

Pass `--config=project` to write to the project's `vlt.json` instead
of your user config. If you run `vlt setup` inside a project that
configures its own registries, it will say so — the project config
takes precedence, so writing your user config would have no effect
there.

## Targeting a specific registry

Account and authentication commands (`whoami`, `logout`, `login`,
`token`, `access`, `publish`, `unpublish`, `deprecate`, `dist-tag`,
`profile`, `ping`) need to know which registry to act against. When
you have more than one configured, scope a command to a single alias
with [`vlt registry <alias> <command>`](/client/commands/registry):

```bash
# act against the registry configured as `main`
vlt registry main whoami

# list tokens for the `npm` registry
vlt registry npm token list
```

You can also run the top-level command directly (`vlt whoami`). Either
way, when the target is ambiguous vlt prompts you to pick a registry
on an interactive terminal, and otherwise falls back to
[`--default-registry-alias`](#bare-specs-and---default-registry-alias).
A `--registry=<url>` on the command line always takes precedence,
except that `publish` (and `unpublish` of the package in the current
directory) use the package's `publishConfig.registry` when set, with
no other registry config needed.

## Named Scope Registries (npm Compatibility)

Like the npm client, the vlt client allows you to map a given scope to
a specific registry.

For example, you could make it so that all packages whose names start
with `@mycompany/...` are served from your internal registry.

This can be a convenient way to make only *certain* packages come from
internal private registries, while all the *other* packages come from
a default public registry, meaning that you do not need to proxy
everything.

To do this in vlt, use the `scoped-registries` configuration.

```bash
vlt config set scoped-registries=@mycompany=https://registry.local/
```

When you do this in your project, you will see that it adds the option
to a `vlt.json` file in your project root.

```bash
$ cat vlt.json
{
  "scoped-registries": {
    "@mycompany": "https://registry.local/",
  }
}
```

If you run this command multiple times, you can set different
registries for various different scopes.

## Registry Aliases

Another way to provide very explicit registry behavior is to use a
registry alias.

Similar to how a named package can be aliased to another name and
version, the vlt client allows you to indicate that you want a given
package to come from a specific named registry.

First, create a registry alias by adding an entry to the `registries`
config:

```bash
$ vlt config set registries=bar=https://registry.example.com/
```

This will add the appropriate entry to the `vlt.json` file:

```bash
$ cat vlt.json
{
  "registries": {
    "bar": "https://registry.example.com/"
  }
}
```

Now, if you have this in your `package.json` file:

```json
{
  "dependencies": {
    "bloo": "bar:bloo@1.2"
  }
}
```

then the `bloo` package will always come from my defined `bar:`
registry alias.

You can also of course use this to install packages from a known
registry by alias on the command line:

```bash
$ vlt install bar:bloo@1.2
```

### Alias names must be unique

Each spec prefix maps to one alias. A name set in more than one of
`registries`, `jsr-registries` or `git-hosts` (counting the built-in
`gh`, `jsr`, `github`, `gitlab`, `bitbucket` and `gist`), or a
built-in protocol name like `file` or `https`, is a config error. Fix
it by renaming the alias, or remove it with
`vlt config delete <field>.<name>` (`--config=user` for the user
config).

### Special Aliases:

#### `npm:`

The `npm:` alias is the default bare-spec alias (see
[`--default-registry-alias`](#bare-specs-and---default-registry-alias)),
but it has **no built-in URL** — you must configure it. This is
because real traffic is expected to flow through a per-account vlt
mirror whose URL isn't known ahead of time.

The easiest way to configure it is
[`vlt setup`](#getting-started-with-vlt-setup), which points
`registries.npm` at your account's mirror. You can also set it
directly, for example to the public npm registry or an internal
caching proxy:

```bash
vlt config set registries=npm=https://registry.npmjs.org/
```

Until `npm` is configured, bare specs like `foo@1.2.3` and
`foo@npm:bar@1.2.3` have no registry to resolve against and will fail
with the missing-registry error.

#### `jsr:`

The `jsr:` alias is a special alias that allow you to install packages
from [JavaScript Registry (jsr)](https://jsr.io).

For example, you can install a package from the JSR registry like
this:

```bash
$ vlt install jsr:@am/neuralNetwork@1.0.0
```

The `jsr:` alias has a built-in URL (`https://npm.jsr.io/`). Unlike a
bare spec, it is resolved from its own alias map and is *not* affected
by the `registry` scalar; to point it at a different host (such as a
caching proxy in your organization's network), override it with
`--jsr-registries`:

```bash
vlt config set jsr-registries=jsr=https://jsr.local/
```

#### `gh:`

The `gh:` alias is a special alias that allows you to install packages
from [GitHub Package Registry](https://docs.github.com/en/packages).

For example, you can install a package from the GitHub package
registry like this:

```bash
$ vlt install gh:@octocat/hello-world@1.0.0
```

This will fetch the package from `https://npm.pkg.github.com/` instead
of the registry a bare spec would use. Like `jsr:`, the built-in `gh:`
URL can be overridden via `--registries`.

### Registry Consistency

There is a common question that is brought up when discussing the use
of multiple registries, which vlt handles properly.

The concern is this:

Consider a package `foo` that you wish to fetch from the registry
`https://registry.foo.com/`. This package `foo` depends on a package
`bar`, also in that same registry, with the expectation that you're
fetching *all* of your packages from that registry, and so, it does
not use any kind of prefix or specifier to indicate where it can be
found.

That is, inside of the `foo` package's `package.json` file, it
contains this:

```json
{
  "name": "foo",
  "version": "1.2.3",
  "dependencies": {
    "bar": "1.x"
  }
}
```

On the public npm registry a *different* package by the name of `bar`
exists, which is *not* compatible with `foo`'s usage.

So the concern is, if I do `vlt install foo:foo@1.2.3`, then it'll
fetch the `foo` package from the `foo` registry just fine. So far so
good. However, then it will attempt to resolve the dependencies of the
foo package, `bar@1.x`. Because `bar@1.x` does not *also* have a
registry specifier, you might think that it will attempt to fetch from
the public npm registry, which would be wrong!

The vlt client handles this by defaulting every dependency to the same
registry where its dependent came from, when resolving the dependency
graph, so they are safe to use in your applications, without fear that
the dependencies will be fetched from the incorrect registry later
down the resolution process.

### Caution: Registry Aliases Are Not For Published Packages

Except for the `npm:` alias, it is generally *not* advised to use
registry alias specifiers in published package dependencies.

At the time of this writing, only the vlt client supports arbitrary
registry alias specifiers, and there is no broad consensus on which
aliases point to which registries, or even any clear understanding
about how such consensus might be found.

While they are perfectly safe to use within your own application, they
should *not* be used in library code that you publish for wider
consumption by the open source community.

## Registry URL Specifiers

The vlt client supports
[`registry:` Dependency Specifiers](https://github.com/npm/rfcs/blob/main/accepted/0035-registry-spec.md).
This means that, even without a configured alias, the registry can
always be specified explicitly by URL within any context where a
dependency is defined.

In fact, this is what registry aliases desugar to, and they have the
exact same behavior.

For example, like in the `foo:foo@1` example above, we could have also
done:

```bash
$ vlt install "foo@registry:https://foo.com#foo@1"
```

While `registry:` specifiers are quite verbose and ugly, they are also
very explicit and can only be interpreted a single way, without
requiring any special configuration.

While broad consensus on configuration would not be required in this
case, it is still not recommended to use them in published library
code, because currently only the vlt client has support for this type
of specifier.

We hope that other package managers add support for `registry:`
specifiers in the future. If they do, then it will be safe to use them
in published open source library code as well.

## See Also

If you are using custom registries, you are very likely going to be
interested in setting up [Authentication](/client/auth) at some point.

# Security & Malware Detection (/client/security)

vlt provides powerful security analysis capabilities through
integration with [Socket](https://socket.dev/), enabling you to
identify and assess security risks in your dependencies. This guide
covers how to use vlt's security-focused selectors to detect malware,
vulnerabilities, and other security issues.

## Quick Security Scan

### Check for Any Malware

The simplest way to check for malware in your dependencies is using
the parameterless `:malware` selector:

Terminal:

```bash
$ vlt query ':malware'
```

This command finds packages with **medium or higher severity** malware
alerts (critical, high, medium) but excludes low-severity alerts to
focus on more serious threats.

### Check for All Security Issues

Get a comprehensive overview of all security-related packages:

Terminal:

```bash
$ vlt query ':scanned'
```

This shows all packages that have been analyzed by Socket's security
scanning.

## Malware Detection

The `:malware` selector is **binary** — it takes no parameters. Any
matching result may have alerts or CVEs assigned to it.

Terminal:

```bash
# Find any malware
$ vlt query ':malware'

# Find direct dependencies with malware

$ vlt query ':root > :malware'

# Find malware in production dependencies

$ vlt query ':prod :malware'

# Find malware in workspaces

$ vlt query ':workspace :malware'
```

## Vulnerability Detection

### Severity-Based Filtering

Use `:vuln` for severity-based vulnerability detection with four
severity levels: **critical**, **high**, **medium**, and **low**.

Terminal:

```bash
# Find critical vulnerabilities only
$ vlt query ':vuln(critical)'

# Find high severity and above

$ vlt query ':vuln(">=high")'

# Find medium or lower vulnerabilities

$ vlt query ':vuln(">=medium")'

# Include low severity alerts

$ vlt query ':vuln(low)'

# Parameterless :vuln matches severity >= medium

$ vlt query ':vuln'
```

### CVE, CWE, and Severity-Based Searches

Terminal:

```bash
# Find packages affected by specific CVEs
$ vlt query ':cve(CVE-2023-1234)'

# Find packages with specific weakness types (CWE)

$ vlt query ':cwe(CWE-79)'

# Find packages based on CVE severity

$ vlt query ':severity(critical)' $ vlt query ':severity(">medium")'
```

## Behavioral Security Risks

### Code Execution Risks

Terminal:

```bash
# Dynamic code execution
$ vlt query ':eval'

# Shell access

$ vlt query ':shell'

# Install scripts

$ vlt query ':scripts'
```

### Data Access Risks

Terminal:

```bash
# File system access
$ vlt query ':fs'

# Network access

$ vlt query ':network'

# Environment variables

$ vlt query ':env'
```

### Code Quality Concerns

Terminal:

```bash
# Obfuscated code
$ vlt query ':obfuscated'

# Minified code

$ vlt query ':minified'

# High entropy strings

$ vlt query ':entropic'
```

## Package Trust & Maintenance

### Package Legitimacy

Terminal:

```bash
# Typosquatting detection
$ vlt query ':squat(critical)'

# Abandoned packages

$ vlt query ':abandoned'

# Manifest confusion

$ vlt query ':confused'
```

### Maintenance Status

Terminal:

```bash
# Deprecated packages
$ vlt query ':deprecated'

# Unmaintained packages

$ vlt query ':unmaintained'

# Unstable ownership

$ vlt query ':unstable'
```

## License Compliance

### License Issues

Terminal:

```bash
# Unlicensed packages
$ vlt query ':license(unlicensed)'

# Restricted licenses

$ vlt query ':license(restricted)'

# Copyleft licenses

$ vlt query ':license(copyleft)'
```

## Security Scoring

Terminal:

```bash
# Find packages with low overall security scores\n$ vlt query \':score("<0.5")\'\n\n# Find packages with low vulnerability scores\n$ vlt query \':score("<0.7", "vulnerability")\'\n\n# Find packages with low maintenance scores\n$ vlt query \':score("<0.6", "maintenance")\'
```

## Comprehensive Security Audit

Terminal:

```bash
# Multi-criteria security check - combine multiple selectors\n$ vlt query ':malware, :eval, :shell, :obfuscated'\n\n# Production dependencies security audit\n$ vlt query ':prod (:malware, :cve(*), :deprecated, :abandoned)'\n\n# Workspace security overview\n$ vlt query ':workspace (:malware, :score(\"<0.5\"), :unmaintained)'
```

## Cross-Project Security Analysis

### Cross-Project Security Scanning

Terminal:

```bash
# Scan multiple projects using host\n$ vlt query ':host(local) :malware'\n\n# Specific project security check\n$ vlt query ':host(\"file:~/my-project\") :malware'
```

## Best Practices

### Regular Security Audits

1. **Daily Quick Check**: `vlt query ':malware'`
2. **Weekly Comprehensive Scan**:
   `vlt query ':host(local) :is(:malware, :not(:scanned))'`
3. **Before Releasing Projects**:
   `vlt query ':root :is(:malware, :score("<0.6"))'`

### Automated Security Monitoring

Consider integrating these queries into your CI/CD pipeline:

security-check.sh:

```bash
#!/bin/bash
# Exit with error if any malware is found (using --expect-results)
vlt query ':malware' --expect-results=0 || {
echo "WARNING: Malware detected in dependencies!"
vlt query ':malware'
exit 1
}

# Alternative: Traditional approach with jq

if vlt query ':malware' --view=json | jq -e '.nodes | length > 0';
then echo "WARNING: Malware detected in dependencies!" vlt query
':malware' exit 1 fi
```

### Automation with --expect-results

The `--expect-results` flag is perfect for CI/CD pipelines and
automated security checks:

Terminal:

```bash
# Security gates that fail builds if issues are found
$ vlt query ':malware' --expect-results=0
$ vlt query ':cwe(1333)' --expect-results=0 # CWE-1333 is a ReDoS vulnerability
$ vlt query ':deprecated' --expect-results=0

# Quality gates with thresholds

$ vlt query ':score("<0.5")' --expect-results=0 $ vlt query
':unmaintained' --expect-results="<3"

# Ensure security scans are working

$ vlt query ':workspace' --expect-results=">0"
```

### Security-First Development

* Always check new dependencies:
  `vlt query '#<new-package>:malware, #<new-package> :malware'`
* Monitor transitive dependencies: `vlt query ':root > * :malware'`
* Regular maintenance updates:
  `vlt query ':deprecated, :unmaintained'`

## Understanding Security Data

Security data is provided by [Socket](https://socket.dev/) and
requires network access to fetch the latest threat intelligence. The
first query may take longer as security metadata is downloaded and
cached locally. Results are cached for 3 hours; stale data is used
while it refreshes in the background.

Requests to Socket time out after 30 seconds, retries included. Set
`VLT_SECURITY_ARCHIVE_TIMEOUT=<ms>` (a positive integer, other values
are ignored) to wait longer. On timeout vlt prints a warning and
continues, treating the affected packages as unscanned: `:scanned`
excludes them and security selectors such as `:malware` don't match
them, but `:not(:malware)` does. In `vlt ls` and `vlt query`, combine
with `:scanned`, e.g. `:scanned:not(:malware)`.

Scripts fail closed: when a `vlt build` target or `--allow-scripts`
query uses security selectors, eligible packages (see below) with no
security data never run their scripts, be it because the request timed
out or because Socket has not scanned them yet, e.g. a version
published minutes ago. `vlt build` reports them as not built along
with the reason; run `vlt build` later to build them. `allow-skills`
queries fail closed the same way: those packages' skills are reported
and not linked, and [`vlt skills link`](/client/commands/skills)
removes their links.

Packages are eligible when their origin is the public npm registry
(`https://registry.npmjs.org/`) or whatever URL is configured as
`registries.npm` (for example a vlt.io npm mirror from
[`vlt setup`](/client/commands/setup)). Packages from other registries
have no security data.

`vlt login --registry=<url>` writes only the scalar `registry` option.
If that URL is not `https://registry.npmjs.org/` and `registries.npm`
is unset, those packages are not scanned. Use `vlt setup` or
`vlt config set registries=npm=<url>` instead.

For more detailed information about specific security selectors, see
the [Dependency Selector Syntax](/client/selectors/security-insights)
reference.

# Attribute Selectors (/client/selectors/attribute-selectors)

Attribute selectors match packages based on values found in their
`package.json` metadata. They work similarly to
[CSS attribute selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors)
but operate on package metadata fields instead of HTML attributes.

## Syntax

| Selector         | Description                                                       |
| ---------------- | ----------------------------------------------------------------- |
| `[attr]`         | Has the property `attr`                                           |
| `[attr=value]`   | Property `attr` exactly equals `value`                            |
| `[attr^=value]`  | Property `attr` starts with `value`                               |
| `[attr$=value]`  | Property `attr` ends with `value`                                 |
| `[attr~=value]`  | Property `attr` is a whitespace-separated list containing `value` |
| `[attr\|=value]` | Property `attr` equals `value` or starts with `value-`            |
| `[attr*=value]`  | Property `attr` contains `value`                                  |
| `[attr=value i]` | Case-insensitive comparison                                       |
| `[attr=value s]` | Case-sensitive comparison (default)                               |

## Examples

### Match by name

Select a package with an exact name:

Terminal:

```bash
$ vlt query '[name=react]'
```

Select all scoped packages:

Terminal:

```bash
$ vlt query '[name^="@"]'
```

Select packages in the `@vltpkg` scope:

Terminal:

```bash
$ vlt query '[name^="@vltpkg"]'
```

### Match by version

Select packages on a specific version:

Terminal:

```bash
$ vlt query '[version=1.0.0]'
```

Select packages with major version 2:

Terminal:

```bash
$ vlt query '[version^=2]'
```

### Match by any property

Select packages that have a `repository` field:

Terminal:

```bash
$ vlt query '[repository]'
```

Select packages with a specific license:

Terminal:

```bash
$ vlt query '[license=MIT]'
```

Select packages whose description mentions "parser":

Terminal:

```bash
$ vlt query '[description*=parser]'
```

### Case-insensitive matching

Find packages with "React" in the description regardless of case:

Terminal:

```bash
$ vlt query '[description*=react i]'
```

### What gets selected

Given a project with these dependencies:

```
my-app
├── @vltpkg/cli@1.0.0
├── react@18.2.0
├── react-dom@18.2.0
└── typescript@5.3.0
```

The query `[name^=react]` selects:

```
my-app
├── @vltpkg/cli@1.0.0
├── react@18.2.0          ✅ name starts with "react"
├── react-dom@18.2.0      ✅ name starts with "react"
└── typescript@5.3.0
```

## Combining with other selectors

Attribute selectors can be combined with
[combinators](/client/selectors/combinators) and
[pseudo-classes](/client/selectors/pseudo-classes):

Terminal:

```bash
$ vlt query ':root > [license=MIT]'
```

This selects only direct dependencies with an MIT license.

## Nested properties

For nested `package.json` properties (like `engines.node` or
`peerDependenciesMeta`), use the
[`:attr()` pseudo-class](/client/selectors/pseudo-classes/attr):

Terminal:

```bash
$ vlt query ':attr(peerDependenciesMeta, foo, [optional=true])'
```

## See also

* [`:attr()` pseudo-class](/client/selectors/pseudo-classes/attr) —
  match nested `package.json` properties
* [ID Selectors](/client/selectors/id-selectors) — shorthand for
  `[name=value]`

# Combinators (/client/selectors/combinators)

Combinators define relationships between packages in the dependency
graph. They work similarly to
[CSS combinators](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selectors_and_combinators#combinators)
but describe dependency relationships instead of DOM hierarchy.

## Syntax

| Combinator  | Name       | Description                                                            |
| ----------- | ---------- | ---------------------------------------------------------------------- |
| `>`         | Child      | Direct dependencies of the previously selected nodes                   |
| ` ` (space) | Descendant | All direct & transitive dependencies                                   |
| `~`         | Sibling    | Direct dependencies of all dependents of the previously selected nodes |

## Child combinator `>`

Matches packages that are **direct dependencies** of the previously
selected nodes. Only one level deep.

Terminal:

```bash
$ vlt query ':root > *'
```

Given this dependency graph:

```
my-app
├── react@18.2.0
│   └── loose-envify@1.4.0
│       └── js-tokens@4.0.0
└── typescript@5.3.0
```

`:root > *` selects only direct dependencies:

```
my-app
├── react@18.2.0          ✅ direct dependency of root
│   └── loose-envify@1.4.0
│       └── js-tokens@4.0.0
└── typescript@5.3.0      ✅ direct dependency of root
```

### Chaining child combinators

You can chain `>` to select at specific depths:

Terminal:

```bash
$ vlt query ':root > * > *'
```

```
my-app
├── react@18.2.0
│   └── loose-envify@1.4.0    ✅ grandchild of root
│       └── js-tokens@4.0.0
└── typescript@5.3.0
```

## Descendant combinator (space)

Matches **all** packages that are direct or transitive dependencies of
the previously selected nodes. Any depth.

Terminal:

```bash
$ vlt query ':root [name=js-tokens]'
```

```
my-app
├── react@18.2.0
│   └── loose-envify@1.4.0
│       └── js-tokens@4.0.0   ✅ transitive dependency of root
└── typescript@5.3.0
```

### Descendant vs. child

Terminal:

```bash
# Direct deps only
$ vlt query ':root > [name=js-tokens]'
# → no results (js-tokens is not a direct dependency)

# All transitive deps

$ vlt query ':root [name=js-tokens]'

# → js-tokens@4.0.0 (found transitively)
```

## Sibling combinator `~`

Matches packages that are **direct dependencies of all dependents** of
the previously selected nodes. In other words: "other packages that
share the same parent."

Terminal:

```bash
$ vlt query '[name=react] ~ *'
```

Given:

```
my-app
├── react@18.2.0
├── react-dom@18.2.0
└── typescript@5.3.0
```

`[name=react] ~ *` selects siblings of react (other direct deps of the
same parent):

```
my-app
├── react@18.2.0
├── react-dom@18.2.0       ✅ sibling of react
└── typescript@5.3.0       ✅ sibling of react
```

## Combining with selectors

Combinators are most powerful when combined with
[attribute selectors](/client/selectors/attribute-selectors) and
[pseudo-classes](/client/selectors/pseudo-classes):

Find all direct dependencies that are outdated:

Terminal:

```bash
$ vlt query ':root > :outdated'
```

Find workspaces that depend on packages with CVEs:

Terminal:

```bash
$ vlt query ':workspace > :cve'
```

Find all transitive dependencies of a specific package:

Terminal:

```bash
$ vlt query '[name=react] *'
```

## See also

* [Pseudo-state Selectors](/client/selectors/pseudo-states) — `:root`,
  `:project`, `:workspace`
* [`:has()` pseudo-class](/client/selectors/pseudo-classes/has) —
  filter by descendant relationships

# ID Selectors (/client/selectors/id-selectors)

ID selectors are a shorthand for selecting packages by name. They work
like
[CSS ID selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/ID_selectors)
but match the `name` field in `package.json`.

## Syntax

```
#package-name
```

This is equivalent to `[name=package-name]`.

ID selectors only work for **unscoped** packages. For scoped
packages (e.g. `@vltpkg/cli`), use [attribute
selectors](/client/selectors/attribute-selectors) instead:
`[name=@vltpkg/cli]`.

## Examples

Select a package by name:

Terminal:

```bash
$ vlt query '#react'
```

This is the same as:

Terminal:

```bash
$ vlt query '[name=react]'
```

### Combining with combinators

Find all dependencies of `react`:

Terminal:

```bash
$ vlt query '#react > *'
```

Find direct deps that have `react` as a sibling:

Terminal:

```bash
$ vlt query '#react ~ *'
```

### Combining with pseudo-classes

Check if a specific package is outdated:

Terminal:

```bash
$ vlt query '#typescript:outdated'
```

## When to use attribute selectors instead

Use `[name=value]` instead of `#value` when:

* The package is scoped: `[name=@vltpkg/cli]`
* You need partial matching: `[name^=react]` (starts with "react")
* You need case-insensitive matching: `[name=React i]`

## See also

* [Attribute Selectors](/client/selectors/attribute-selectors) — full
  attribute matching syntax

# Dependency Selector Syntax (/client/selectors)

The vlt query syntax enables usage of CSS-selector-like strings to
filter and select packages in your dependency graph.

Terminal:

```bash
$ vlt query ':root > [name^=@vltpkg]'
```

Many of the common elements of the CSS language are available,
notably:

* `*` Universal selector — matches all selected items.
* `&` Nesting selector — allows for nesting selectors.
* `{}` Curly braces — when querying, can be used to nest selectors.

## Quick Reference

| Category                                                     | Examples                                      | Description                                      |
| ------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------ |
| [Attribute Selectors](/client/selectors/attribute-selectors) | `[name=foo]`, `[version^=2]`                  | Match by `package.json` metadata                 |
| [Combinators](/client/selectors/combinators)                 | `>`, ` `, `~`                                 | Traverse the dependency graph                    |
| [ID Selectors](/client/selectors/id-selectors)               | `#foo`                                        | Shortcut for `[name=foo]`                        |
| [Pseudo-class Selectors](/client/selectors/pseudo-classes)   | `:has()`, `:outdated()`, `:semver()`          | Functional selectors with arguments              |
| [Pseudo-state Selectors](/client/selectors/pseudo-states)    | `:root`, `:workspace`, `:dev`                 | State-based selectors                            |
| [Security Insights](/client/selectors/security-insights)     | `:malware`, `:vuln()`, `:cve()`, `:license()` | Security data from [Socket](https://socket.dev/) |

## Selector Categories

- [Attribute Selectors](/client/selectors/attribute-selectors): Match packages by package.json fields like name, version, or any custom property.

- [Combinators](/client/selectors/combinators): Traverse the dependency graph with child, descendant, and sibling combinators.

- [ID Selectors](/client/selectors/id-selectors): Quick shorthand to select packages by name.

- [Pseudo-class Selectors](/client/selectors/pseudo-classes): Functional selectors like :has(), :outdated(), :semver(), :type(), and more.

- [Pseudo-state Selectors](/client/selectors/pseudo-states): State-based selectors like :root, :workspace, :dev, :prod, :private.

- [Security Insights](/client/selectors/security-insights): Socket-powered security selectors for malware, CVEs, obfuscation, and more.

## Examples

Find all outdated direct dependencies:

Terminal:

```bash
$ vlt query ':root > :outdated'
```

Find all packages that depend on a vulnerable package:

Terminal:

```bash
$ vlt query ':has(:cve)'
```

Find all dev-only dependencies that use eval:

Terminal:

```bash
$ vlt query ':dev:eval'
```

Combine multiple selectors:

Terminal:

```bash
$ vlt query ':workspace > :type(git), :root > :outdated(major)'
```

# :attr() (/client/selectors/pseudo-classes/attr)

The `:attr()` pseudo-class selects packages based on **nested
properties** of their `package.json` metadata. While
[attribute selectors](/client/selectors/attribute-selectors) match
top-level fields, `:attr()` lets you drill into nested objects.

## Syntax

```
:attr(key, [attr=value])
:attr(key, nestedKey, [attr=value])
```

Arguments are a path of property keys, ending with a standard
attribute selector.

## Examples

### Optional peer dependencies

Select packages that declare `foo` as an optional peer dependency:

Terminal:

```bash
$ vlt query ':attr(peerDependenciesMeta, foo, [optional=true])'
```

This is equivalent to checking:

```json
{
  "peerDependenciesMeta": {
    "foo": {
      "optional": true
    }
  }
}
```

### Engine requirements

Select packages that have a `node` engine requirement:

Terminal:

```bash
$ vlt query ':attr(engines, [node])'
```

### Scripts

Select packages that have a `build` script:

Terminal:

```bash
$ vlt query ':attr(scripts, [build])'
```

Select packages that have a `test` script using `vitest`:

Terminal:

```bash
$ vlt query ':attr(scripts, [test*=vitest])'
```

### What gets selected

Given this dependency graph:

```
my-app
├── react@18.2.0
│   └── loose-envify@1.4.0  ← has scripts.postinstall
├── typescript@5.3.0         ← has engines.node
└── vite@5.0.0               ← has engines.node
```

The query `:attr(engines, [node])` selects:

```
my-app
├── react@18.2.0
│   └── loose-envify@1.4.0
├── typescript@5.3.0          ✅ has engines.node
└── vite@5.0.0                ✅ has engines.node
```

### Combining with combinators

Find direct dependencies that have a `build` script:

Terminal:

```bash
$ vlt query ':project > :attr(scripts, [build])'
```

## See also

* [Attribute Selectors](/client/selectors/attribute-selectors) —
  top-level property matching
* [`:semver()`](/client/selectors/pseudo-classes/semver) — compare
  semver values in nested properties

# :diff() (/client/selectors/pseudo-classes/diff)

The `:diff()` pseudo-class matches packages whose files have changed
between the current working tree and a specified git commitish
reference. It uses `git diff --name-only` to determine changed files,
then maps them to packages by their file path location.

## Syntax

```
:diff()
:diff(<commitish>)
```

When called with no argument, defaults to `HEAD` (uncommitted
changes). Untracked files are not seen — `git diff` only reports
tracked ones.

The comparison is two-dot: the ref's tree against your working tree,
in both directions. To compare against the merge base instead — "what
this branch changed", regardless of how far `main` has moved — use the
three-dot form, `:diff(main...HEAD)`.

Refs containing a `/` must be quoted, `:diff("origin/main")`;
unquoted, the selector parser rejects the slash.

## Examples

### Uncommitted changes

Find packages with uncommitted changes:

Terminal:

```bash
$ vlt query ':diff()'
```

### Changes since a branch

Find packages changed since the `main` branch:

Terminal:

```bash
$ vlt query ':diff(main)'
```

### Changes since last commit

Terminal:

```bash
$ vlt query ':diff(HEAD~1)'
```

### Changes since a tag

Terminal:

```bash
$ vlt query ':diff("v1.0.0")'
```

### Only workspaces that changed

Terminal:

```bash
$ vlt query ':workspace:diff(main)'
```

### What gets selected

Given a monorepo where you changed files in `packages/core/` and
`packages/utils/` since `main`:

```
my-monorepo
├── packages/core/        ← files changed
├── packages/utils/       ← files changed
├── packages/cli/
└── apps/web/
```

`:diff(main)` selects:

```
my-monorepo
├── packages/core/        ✅ has changed files
├── packages/utils/       ✅ has changed files
├── packages/cli/
└── apps/web/
```

### CI use cases

Run tests only for changed workspaces:

Terminal:

```bash
$ vlt run test --scope=':workspace:diff(main...HEAD)'
```

Find packages that depend on changed packages:

Terminal:

```bash
$ vlt query ':has(:diff(main))'
```

## See also

* [Affected Dependencies](/client/affected) — testing only what a
  change could have broken
* [`:path()`](/client/selectors/pseudo-classes/path) — match by file
  path
* [`:has()`](/client/selectors/pseudo-classes/has) — find packages
  that depend on changed packages

# :dist() (/client/selectors/pseudo-classes/dist)

The `:dist()` pseudo-class matches packages whose installed version
corresponds to a specific dist-tag in the registry.

## Syntax

```
:dist(<tag>)
```

### Parameters

| Parameter | Description                        | Default    |
| --------- | ---------------------------------- | ---------- |
| `tag`     | The dist-tag name to match against | (required) |

## How it works

When a package is published to a registry, it can be associated with
one or more dist-tags (e.g. `latest`, `nightly`, `beta`). The
`:dist()` selector fetches the packument for each installed package
and checks whether the node's installed version matches the version
pointed to by the given dist-tag.

For example, given a package `foo` with:

```json
{
  "dist-tags": {
    "latest": "1.3.0",
    "nightly": "1.2.1"
  }
}
```

* If `foo@1.3.0` is installed, `:dist(latest)` will match it.
* If `foo@1.0.0` is installed, `:dist(latest)` will **not** match it.

## Examples

### Find packages at their latest version

Terminal:

```bash
vlt query ':dist(latest)'
```

### Find packages at a pre-release dist-tag

Terminal:

```bash
vlt query ':dist(nightly)'
```

### Exclude nightly-tagged packages

Terminal:

```bash
vlt query ':not(:dist(nightly))'
```

### Find a specific package at a dist-tag

Terminal:

```bash
vlt query '#foo:dist(latest)'
```

## Notes

* Only registry packages are matched. File, git, workspace, and remote
  dependencies are filtered out since they do not have dist-tags.
* The selector makes network requests to the registry to fetch
  dist-tag information. Results depend on the current state of the
  registry.
* If a dist-tag does not exist for a package, that package will not
  match.

## See also

* [`:semver()`](/client/selectors/pseudo-classes/semver) — match by
  semver comparison
* [`:outdated()`](/client/selectors/pseudo-classes/outdated) — match
  packages with newer versions available

# :has() (/client/selectors/pseudo-classes/has)

The `:has()` pseudo-class matches packages that **depend on** a match
for a given selector expression. It's the dependency graph equivalent
of the
[CSS `:has()` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:has).

## Syntax

```
:has(<selector-list>)
```

The selector list is evaluated against the whole graph, then packages
with a direct dependency on one of its matches are kept. Nest `:has()`
to walk further up the graph, one dependency hop per level.

## Examples

### Packages with a peer dependency on react

Terminal:

```bash
$ vlt query ':has(:peer[name=react])'
```

Given this dependency graph:

```
my-app
├── react@18.2.0
├── react-dom@18.2.0
│   └── react@18.2.0 (peer)
└── @testing-library/react@14.0.0
    └── react@18.2.0 (peer)
```

`:has(:peer[name=react])` selects packages that have a peer dependency
on react:

```
my-app
├── react@18.2.0
├── react-dom@18.2.0                 ✅ has peer dep on react
│   └── react@18.2.0 (peer)
└── @testing-library/react@14.0.0   ✅ has peer dep on react
    └── react@18.2.0 (peer)
```

### Packages that depend on vulnerable packages

Terminal:

```bash
$ vlt query ':has(:cve)'
```

This finds packages whose **direct dependencies** have known CVEs.

### Packages that depend on outdated packages

Terminal:

```bash
$ vlt query ':has(:outdated(major))'
```

### Packages that depend on changed packages

Find packages that have a dependency that was modified:

Terminal:

```bash
$ vlt query ':has(:diff(main))'
```

See [Affected Dependencies](/client/affected) for using this to test
only what a branch could have broken.

### Reaching further than one hop

`:has()` only looks one dependency deep, so `>` inside it is redundant
— these select the same packages:

Terminal:

```bash
$ vlt query ':has(> [name=lodash])'
$ vlt query ':has([name=lodash])'
```

To match packages that depend on lodash *through* another package,
nest another `:has()`:

Terminal:

```bash
# depends on something that depends on lodash
$ vlt query ':has(:has([name=lodash]))'
```

## See also

* [`:not()`](/client/selectors/pseudo-classes/not) — negation
  pseudo-class
* [`:is()`](/client/selectors/pseudo-classes/is) — forgiving selector
  list matching
* [Combinators](/client/selectors/combinators) — `>`, ` `, `~`
* [Affected Dependencies](/client/affected) — what a change breaks

# :host() (/client/selectors/pseudo-classes/host)

The `:host()` pseudo-class switches the current graph context to a new
set of graphs loaded from a specific host context. This allows
querying across multiple projects or switching to different project
scopes.

## Syntax

```
:host(<context>)
```

The context parameter can be:

* A specific project folder path (e.g., `"file:~/my-project"`)
* The special `local` context — loads all configured projects from
  your vlt dashboard

## Examples

### Find malware across all projects

Terminal:

```bash
$ vlt query ':host(local) :malware'
```

### Query a specific project

Terminal:

```bash
$ vlt query ':host("file:~/my-app") :outdated'
```

### Bump version for a remote project

Terminal:

```bash
$ vlt version patch --scope=':host("file:~/tmp/test-vite")'
```

### Get all direct deps across local projects

Terminal:

```bash
$ vlt pkg pick name version --scope=':host(local) > :root > *'
```

## How it works

When you use `:host()`, vlt:

1. Resolves the context to one or more project directories
2. Loads the dependency graph for each project
3. Runs the rest of the selector against all loaded graphs

This is particularly useful for organization-wide audits and
cross-project dependency analysis.

## See also

* [`:diff()`](/client/selectors/pseudo-classes/diff) — find changed
  packages
* [`:outdated()`](/client/selectors/pseudo-classes/outdated) — find
  packages with newer versions

# :hostname() (/client/selectors/pseudo-classes/hostname)

The `:hostname()` pseudo-class matches packages based on the hostname
of the registry or git remote they were fetched from.

## Syntax

```
:hostname(<domain>)
```

### Parameters

| Parameter | Description                                               |
| --------- | --------------------------------------------------------- |
| `domain`  | The hostname to match against (e.g. `npm.pkg.github.com`) |

## How it works

The selector extracts the hostname from each package's source:

* **Registry packages**: hostname from the registry URL
* **Git packages**: hostname from the git remote (supports named hosts
  like `github` → `github.com`)
* **Remote packages**: hostname from the tarball URL
* **File/workspace packages**: never match (no hostname)

## Examples

Find all packages served from the public npm registry:

Terminal:

```bash
$ vlt query ':hostname(registry.npmjs.org)'
```

Note that registry nodes are matched against the resolved registry
URL. Since vlt has no [default registry](/client/registries), a node
whose spec carries no registry has no hostname to compare and will not
match.

Find packages from GitHub's package registry:

Terminal:

```bash
$ vlt query ':hostname(npm.pkg.github.com)'
```

Find git dependencies hosted on GitHub:

Terminal:

```bash
$ vlt query ':hostname(github.com)'
```

Find packages from a custom registry:

Terminal:

```bash
$ vlt query ':hostname(registry.example.com)'
```

## See also

* [`:registry()`](/client/selectors/pseudo-classes/registry) — match
  by registry configuration name
* [`:type()`](/client/selectors/pseudo-classes/type) — match by
  package type (registry, git, file, etc.)

# Pseudo-class Selectors (/client/selectors/pseudo-classes)

Pseudo-class selectors are functional selectors that accept arguments
to filter packages. They work similarly to
[CSS pseudo-classes](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes)
but operate on dependency graph nodes.

## Available pseudo-class selectors

- [:attr()](/client/selectors/pseudo-classes/attr): Match packages by nested package.json properties

- [:dist()](/client/selectors/pseudo-classes/dist): Match packages by registry dist-tag

- [:has()](/client/selectors/pseudo-classes/has): Match packages that depend on a match for a selector

- [:host()](/client/selectors/pseudo-classes/host): Switch graph context to another project or scope

- [:is()](/client/selectors/pseudo-classes/is): Match any element in a forgiving selector list

- [:not()](/client/selectors/pseudo-classes/not): Negation — exclude packages matching a selector

- [:outdated()](/client/selectors/pseudo-classes/outdated): Match packages with newer versions available

- [:published()](/client/selectors/pseudo-classes/published): Match packages by publication date

- [:semver()](/client/selectors/pseudo-classes/semver): Match packages by semver comparisons

- [:spec()](/client/selectors/pseudo-classes/spec): Match edges by their package specifier

- [:path()](/client/selectors/pseudo-classes/path): Match workspace and file packages by file path

- [:type()](/client/selectors/pseudo-classes/type): Match packages by type (registry, file, git, etc.)

- [:diff()](/client/selectors/pseudo-classes/diff): Match packages whose files have changed

- [:hostname()](/client/selectors/pseudo-classes/hostname): Match packages by upstream hostname

- [:registry()](/client/selectors/pseudo-classes/registry): Match packages by registry configuration name

- [:skill()](/client/selectors/pseudo-classes/skill): Pick agent skills of matched packages

## Quick reference

| Selector                                                     | Description           | Example                   |
| ------------------------------------------------------------ | --------------------- | ------------------------- |
| [`:attr()`](/client/selectors/pseudo-classes/attr)           | Nested property match | `:attr(engines, [node])`  |
| [`:dist()`](/client/selectors/pseudo-classes/dist)           | By registry dist-tag  | `:dist(latest)`           |
| [`:has()`](/client/selectors/pseudo-classes/has)             | Depends on a match    | `:has(:peer[name=react])` |
| [`:host()`](/client/selectors/pseudo-classes/host)           | Switch graph context  | `:host(local) :malware`   |
| [`:is()`](/client/selectors/pseudo-classes/is)               | Match any in list     | `:is([name=a], [name=b])` |
| [`:not()`](/client/selectors/pseudo-classes/not)             | Negation              | `:not([license=MIT])`     |
| [`:outdated()`](/client/selectors/pseudo-classes/outdated)   | Newer version exists  | `:outdated(major)`        |
| [`:published()`](/client/selectors/pseudo-classes/published) | By publish date       | `:published(">2024")`     |
| [`:semver()`](/client/selectors/pseudo-classes/semver)       | Semver comparison     | `:semver(^1.0.0)`         |
| [`:spec()`](/client/selectors/pseudo-classes/spec)           | By specifier string   | `:spec(^1.0.0)`           |
| [`:path()`](/client/selectors/pseudo-classes/path)           | By file path          | `:path("packages/**")`    |
| [`:type()`](/client/selectors/pseudo-classes/type)           | By package type       | `:type(git)`              |
| [`:diff()`](/client/selectors/pseudo-classes/diff)           | Changed files         | `:diff(main)`             |
| [`:hostname()`](/client/selectors/pseudo-classes/hostname)   | By upstream hostname  | `:hostname(github.com)`   |
| [`:registry()`](/client/selectors/pseudo-classes/registry)   | By registry name      | `:registry(npm)`          |
| [`:skill()`](/client/selectors/pseudo-classes/skill)         | Pick agent skills     | `#pkg:skill(find-skills)` |

## See also

* [Pseudo-state Selectors](/client/selectors/pseudo-states) — simple
  state-based selectors (`:root`, `:dev`, etc.)
* [Security Insights](/client/selectors/security-insights) —
  Socket-powered security pseudo-selectors

# :is() (/client/selectors/pseudo-classes/is)

The `:is()` pseudo-class takes a forgiving selector list and matches
any element that can be selected by one of the selectors in that list.
It works like the
[CSS `:is()` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:is)
and is useful for writing compact selectors.

## Syntax

```
:is(<forgiving-selector-list>)
```

The selector list is **forgiving** — any invalid selectors in the list
are silently ignored rather than causing the entire selector to fail.

## Examples

### Compact selector lists

Without `:is()`:

Terminal:

```bash
$ vlt query ':root > [name=react], :root > [name=vue], :root > [name=svelte]'
```

With `:is()`:

Terminal:

```bash
$ vlt query ':root > :is([name=react], [name=vue], [name=svelte])'
```

Both queries produce the same result — direct dependencies named
`react`, `vue`, or `svelte`.

### Forgiving behavior

Invalid selectors in the list are ignored:

Terminal:

```bash
$ vlt query ':is([name=react], :nonexistent, [name=vue])'
```

This still matches `react` and `vue` — the `:nonexistent` pseudo-class
is silently skipped.

## See also

* [`:not()`](/client/selectors/pseudo-classes/not) — negation
  pseudo-class
* [`:has()`](/client/selectors/pseudo-classes/has) — dependency
  matching

# :not() (/client/selectors/pseudo-classes/not)

The `:not()` pseudo-class is a negation selector — it matches packages
that **do not match** the given selector list. It works like the
[CSS `:not()` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:not).

## Syntax

```
:not(<selector-list>)
```

## Examples

### Exclude by name

Find all packages except react:

Terminal:

```bash
$ vlt query ':root > :not([name=react])'
```

### Exclude by license

Find packages without an MIT license:

Terminal:

```bash
$ vlt query ':not([license=MIT])'
```

### Exclude by type

Find all non-registry dependencies:

Terminal:

```bash
$ vlt query ':not(:type(registry))'
```

### What gets selected

Given this dependency graph:

```
my-app
├── react@18.2.0         ← license: MIT
├── typescript@5.3.0     ← license: Apache-2.0
└── vite@5.0.0           ← license: MIT
```

`:root > :not([license=MIT])` selects:

```
my-app
├── react@18.2.0
├── typescript@5.3.0      ✅ license is NOT MIT
└── vite@5.0.0
```

### Combining with other pseudo-classes

Find non-dev dependencies that are outdated:

Terminal:

```bash
$ vlt query ':not(:dev):outdated'
```

Find packages that are not private and not workspaces:

Terminal:

```bash
$ vlt query ':not(:private):not(:workspace)'
```

## See also

* [`:is()`](/client/selectors/pseudo-classes/is) — forgiving selector
  list matching
* [`:has()`](/client/selectors/pseudo-classes/has) — dependency
  matching

# :outdated() (/client/selectors/pseudo-classes/outdated)

The `:outdated()` pseudo-class matches packages that have newer
versions available on the registry. An optional type parameter
controls how "outdated" is defined.

## Syntax

```
:outdated
:outdated(<type>)
```

### Type parameter

| Type            | Description                                                           |
| --------------- | --------------------------------------------------------------------- |
| `any` (default) | A version exists greater than the current one                         |
| `in-range`      | A greater version exists that satisfies the parent's dependency range |
| `out-of-range`  | A greater version exists that does NOT satisfy the parent's range     |
| `major`         | A semver major version bump is available                              |
| `minor`         | A semver minor version bump is available                              |
| `patch`         | A semver patch version bump is available                              |

## Examples

### Find all outdated packages

Terminal:

```bash
$ vlt query ':outdated'
```

### Find major version bumps

Terminal:

```bash
$ vlt query ':outdated(major)'
```

### Find safe updates (in-range)

Updates that satisfy the existing dependency range:

Terminal:

```bash
$ vlt query ':outdated(in-range)'
```

### Find breaking updates (out-of-range)

Updates that would require changing the dependency range:

Terminal:

```bash
$ vlt query ':outdated(out-of-range)'
```

### What gets selected

Given:

```
my-app
├── react@17.0.2          ← latest: 18.2.0 (major)
├── typescript@5.2.0      ← latest: 5.3.0 (minor)
├── vite@5.0.0            ← latest: 5.0.12 (patch)
└── lodash@4.17.21        ← latest: 4.17.21 (up to date)
```

| Query              | Selected                |
| ------------------ | ----------------------- |
| `:outdated`        | react, typescript, vite |
| `:outdated(major)` | react                   |
| `:outdated(minor)` | typescript              |
| `:outdated(patch)` | vite                    |

### Combining with combinators

Find outdated direct dependencies only:

Terminal:

```bash
$ vlt query ':root > :outdated'
```

Find outdated direct dependencies with major bumps:

Terminal:

```bash
$ vlt query ':root > :outdated(major)'
```

## See also

* [`:semver()`](/client/selectors/pseudo-classes/semver) — custom
  semver comparisons
* [`:published()`](/client/selectors/pseudo-classes/published) —
  filter by publication date

# :path() (/client/selectors/pseudo-classes/path)

The `:path()` pseudo-class matches workspace and file packages based
on their file path relative to the project root. Patterns use glob
syntax and must be quoted strings.

## Syntax

```
:path("<glob>")
```

## Examples

### Match all workspace packages

Terminal:

```bash
$ vlt query ':path("*")'
```

### Match a specific path

Terminal:

```bash
$ vlt query ':path("./packages/foo")'
```

### Match with glob patterns

Terminal:

```bash
$ vlt query ':path("packages/**")'
```

### What gets selected

Given a monorepo:

```
my-monorepo/
├── packages/
│   ├── core/           ← workspace
│   ├── utils/          ← workspace
│   └── cli/            ← workspace
└── apps/
    └── web/            ← workspace
```

| Query                      | Selected              |
| -------------------------- | --------------------- |
| `:path("*")`               | core, utils, cli, web |
| `:path("packages/**")`     | core, utils, cli      |
| `:path("apps/**")`         | web                   |
| `:path("./packages/core")` | core                  |

### Combining with other selectors

Find workspaces in `packages/` that have changed since main:

Terminal:

```bash
$ vlt query ':path("packages/**"):diff(main)'
```

## See also

* [`:workspace`](/client/selectors/pseudo-states) — match all
  workspace packages
* [`:type()`](/client/selectors/pseudo-classes/type) — match by
  package type
* [`:diff()`](/client/selectors/pseudo-classes/diff) — match by
  changed files

# :published() (/client/selectors/pseudo-classes/published)

The `:published()` pseudo-class matches packages based on their
publication date. Useful for auditing when dependencies were last
released.

## Syntax

```
:published(<date>)
:published("<comparator><date>")
```

The date parameter supports:

* Full dates: `2024-01-01`
* Year only: `2024`
* Year-month: `2024-06`

When using a comparator (`>`, `<`, `>=`, `<=`), the value must be
quoted.

## Examples

### Exact date match

Terminal:

```bash
$ vlt query ':published(2024-01-01)'
```

### After a date

Terminal:

```bash
$ vlt query ':published(">2024")'
```

### Before a date

Terminal:

```bash
$ vlt query ':published("<=2023-12-31")'
```

### What gets selected

Given:

```
my-app
├── react@18.2.0         ← published: 2022-06-14
├── typescript@5.3.0     ← published: 2023-11-20
└── vite@5.0.0           ← published: 2023-11-16
```

The query `:published(">2023")` selects:

```
my-app
├── react@18.2.0
├── typescript@5.3.0      ✅ published after 2023
└── vite@5.0.0            ✅ published after 2023
```

### Finding old packages

Find packages published more than 2 years ago:

Terminal:

```bash
$ vlt query ':published("<2024")'
```

### Combining with other selectors

Find outdated packages that were published before 2023:

Terminal:

```bash
$ vlt query ':outdated:published("<2023")'
```

## See also

* [`:outdated()`](/client/selectors/pseudo-classes/outdated) — find
  packages with newer versions
* [`:unmaintained`](/client/selectors/security-insights) — packages
  not updated in 5+ years

# :registry() (/client/selectors/pseudo-classes/registry)

The `:registry()` pseudo-class matches packages that belong to a
specific named registry configuration.

## Syntax

```
:registry(<name>)
```

### Parameters

| Parameter | Description                                             |
| --------- | ------------------------------------------------------- |
| `name`    | The registry configuration alias (e.g. `npm`, `custom`) |

## How it works

Packages are associated with a registry name based on the `registries`
configuration in your project. The default registry is typically named
`npm`. Custom registries configured via `--registries` or in
`vlt.json` can be matched by their alias name.

Only registry-type packages are matched — git, file, and workspace
packages are excluded.

## Examples

Find all packages from the `npm` registry alias (the default bare-spec
alias):

Terminal:

```bash
$ vlt query ':registry(npm)'
```

Find packages from a custom registry:

Terminal:

```bash
$ vlt query ':registry(custom)'
```

Combine with other selectors to find outdated packages from a specific
registry:

Terminal:

```bash
$ vlt query ':registry(npm):outdated'
```

## See also

* [`:hostname()`](/client/selectors/pseudo-classes/hostname) — match
  by upstream hostname
* [`:type()`](/client/selectors/pseudo-classes/type) — match by
  package type

# :semver() (/client/selectors/pseudo-classes/semver)

The `:semver()` pseudo-class matches packages based on semver
comparisons. By default it compares against the package `version`
field, but it can be configured to compare any semver-like value. It
also supports range-vs-range functions (`subset`, `intersects`) that
operate on edges by comparing dependency specifier ranges.

## Syntax

```
:semver(<range>)
:semver(<range>, <function>)
:semver(<range>, <function>, <custom-attribute-selector>)
```

### Parameters

| Parameter                   | Description                         | Default     |
| --------------------------- | ----------------------------------- | ----------- |
| `range`                     | The semver range to compare against | (required)  |
| `function`                  | Comparison function                 | `satisfies` |
| `custom-attribute-selector` | A different property to compare     | `version`   |

### Comparison functions

| Function     | Description                                     | Operates on |
| ------------ | ----------------------------------------------- | ----------- |
| `satisfies`  | Version satisfies the range (default)           | nodes       |
| `eq`         | Version exactly equals the range                | nodes       |
| `neq`        | Version does not equal the range                | nodes       |
| `gt`         | Version is greater than the range               | nodes       |
| `gte`        | Version is greater than or equal to the range   | nodes       |
| `lt`         | Version is less than the range                  | nodes       |
| `lte`        | Version is less than or equal to the range      | nodes       |
| `intersects` | Edge's range intersects with the provided range | edges       |
| `subset`     | Edge's range is a subset of the provided range  | edges       |

## Examples

### Basic range matching

Find packages satisfying `^1.0.0`:

Terminal:

```bash
$ vlt query ':semver(^1.0.0)'
```

### Exact version matching

Find packages at exactly version `2.0.0`:

Terminal:

```bash
$ vlt query ':semver(2.0.0, eq)'
```

### Version comparison

Find packages greater than version 5:

Terminal:

```bash
$ vlt query ':semver(5.0.0, gt)'
```

### Range-vs-range comparison

The `intersects` and `subset` functions compare two ranges rather than
a version against a range. By default they operate on **edges** using
the dependency specifier (`bareSpec`), making it possible to query
which declared dependency ranges relate to a given range.

Find edges whose declared range is a subset of `>=2`:

Terminal:

```bash
$ vlt query ':semver(>=2, subset)'
```

Find edges whose declared range intersects `^3`:

Terminal:

```bash
$ vlt query ':semver(^3, intersects)'
```

When a custom attribute is provided, `intersects` and `subset` compare
against that manifest property value as a range:

Terminal:

```bash
$ vlt query ':semver(>=20, subset, :attr(engines, [node]))'
```

### Custom property comparison

Match packages whose `engines.node` field satisfies `^22`:

Terminal:

```bash
$ vlt query ':semver(^22, satisfies, :attr(engines, [node]))'
```

### What gets selected

Given:

```
my-app
├── react@18.2.0
├── react-dom@18.2.0
├── typescript@5.3.0
└── lodash@4.17.21
```

| Query                 | Selected         |
| --------------------- | ---------------- |
| `:semver(^18.0.0)`    | react, react-dom |
| `:semver(5.0.0, gte)` | typescript       |
| `:semver(^4.0.0)`     | lodash           |

### Combining with other selectors

Find direct dependencies with version >= 18:

Terminal:

```bash
$ vlt query ':root > :semver(18.0.0, gte)'
```

## See also

* [`:outdated()`](/client/selectors/pseudo-classes/outdated) — find
  packages with newer versions available
* [Attribute Selectors](/client/selectors/attribute-selectors) — match
  the `version` field directly

# :skill() (/client/selectors/pseudo-classes/skill)

The `:skill()` pseudo-class picks
[agent skills](/client/commands/skills#pick-skills) by name from the
packages its selector matched. It only works in `--allow-skills` and
`vlt skills`.

## Syntax

```
<selector>:skill(<pattern>[, <pattern>…])
```

### Parameters

| Parameter | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `pattern` | Name (`find-skills`), quoted name (`"my skill"`) or glob (`vercel*`, `*-x`) |

## How it works

* The selector picks packages as usual. `:skill()` picks skills inside
  them and never filters packages.
* A pattern matches the skill name or the `name` in its `SKILL.md`,
  ignoring case. `*` matches any run of characters. Quote names with
  spaces, with double quotes only.
* A selector without `:skill()` picks every skill of its packages, the
  same as `:skill(*)`.
* `:skill(x)` alone is `*:skill(x)`. `#a :skill(x)` picks skill `x` of
  every descendant of `a`; use `#a > :skill(x)` for its direct
  dependencies only.
* It must end a top-level selector: `#a:skill(x) > *`,
  `#a:skill(x):prod` and `:not(#a:skill(x))` are errors.
* Comma lists are a union. `:root > *, #skills:skill(find-skills)`
  picks every skill of every direct dependency, `skills` included. The
  narrow form is `:root > *:not(#skills), #skills:skill(find-skills)`.
* A pattern that matches no skill prints a warning; the install still
  succeeds.
* Anywhere else (`vlt query`, `vlt ls`, `--allow-scripts`, …) it is an
  error. Preview a query with `vlt skills list '<query>'`.
* [`:skills`](/client/selectors/pseudo-states#skills) (no `()`)
  matches packages that ship skills. `:skills(x)` is an error (did you
  mean `:skill(x)`?) on its own, and matches nothing inside a comma
  list.

## Examples

Link the `agent-browser` skill of the `agent-browser` package:

Terminal:

```bash
$ vlt install --allow-skills='#agent-browser:skill(agent-browser)'
```

List the matching skills of every direct dependency:

Terminal:

```bash
$ vlt skills list ':root > *:skill(vercel*, *-review)'
```

Link skills by glob and by a quoted name:

Terminal:

```bash
$ vlt skills link '#agent-skills:skill(react*, "my skill")'
```

## See also

* [`vlt skills`](/client/commands/skills#pick-skills) — manage agent
  skills
* [`:not()`](/client/selectors/pseudo-classes/not) — exclude packages
* [`:skills`](/client/selectors/pseudo-states#skills) — packages that
  ship skills

# :spec() (/client/selectors/pseudo-classes/spec)

The `:spec()` pseudo-class matches edges where the package specifier
(bareSpec) equals the provided value. This filters dependencies by
their exact specification string — i.e., what's written in
`package.json`.

## Syntax

```
:spec(<specifier>)
```

## Examples

### Match by semver range

Terminal:

```bash
$ vlt query ':spec(^1.0.0)'
```

### Match wildcard dependencies

Terminal:

```bash
$ vlt query ':spec("*")'
```

### Match catalog dependencies

Find dependencies using the catalog protocol:

Terminal:

```bash
$ vlt query ':spec("catalog:")'
```

### What gets selected

Given `package.json`:

```json
{
  "dependencies": {
    "react": "^18.2.0",
    "lodash": "*",
    "my-lib": "catalog:"
  }
}
```

| Query               | Selected |
| ------------------- | -------- |
| `:spec(^18.2.0)`    | react    |
| `:spec("*")`        | lodash   |
| `:spec("catalog:")` | my-lib   |

## See also

* [Attribute Selectors](/client/selectors/attribute-selectors) — match
  resolved version values
* [`:type()`](/client/selectors/pseudo-classes/type) — match by
  dependency type

# :type() (/client/selectors/pseudo-classes/type)

The `:type()` pseudo-class matches packages based on their resolved
type — how the package is sourced.

## Syntax

```
:type(<type>)
```

### Available types

| Type        | Description                              |
| ----------- | ---------------------------------------- |
| `registry`  | Packages from npm or another registry    |
| `file`      | Local file dependencies (`file:../path`) |
| `git`       | Git repository dependencies              |
| `remote`    | Remote URL dependencies                  |
| `workspace` | Workspace packages in your monorepo      |

## Examples

### Find all git dependencies

Terminal:

```bash
$ vlt query ':type(git)'
```

### Find all workspace dependencies

Terminal:

```bash
$ vlt query ':type(workspace)'
```

### Find all file dependencies

Terminal:

```bash
$ vlt query ':type(file)'
```

### What gets selected

Given:

```
my-app
├── react@18.2.0             ← type: registry
├── my-utils (workspace)     ← type: workspace
├── my-fork (git)            ← type: git
└── ../shared-lib (file)     ← type: file
```

| Query              | Selected      |
| ------------------ | ------------- |
| `:type(registry)`  | react         |
| `:type(workspace)` | my-utils      |
| `:type(git)`       | my-fork       |
| `:type(file)`      | ../shared-lib |

### Combining with other selectors

Find all non-registry dependencies:

Terminal:

```bash
$ vlt query ':not(:type(registry))'
```

Find outdated git dependencies:

Terminal:

```bash
$ vlt query ':type(git):outdated'
```

## See also

* [`:workspace`](/client/selectors/pseudo-states) — shorthand for
  matching workspaces
* [`:spec()`](/client/selectors/pseudo-classes/spec) — match by
  specifier string

# Pseudo-state Selectors (/client/selectors/pseudo-states)

Pseudo-state selectors match packages based on their relationship to
the project or their dependency type. Unlike
[pseudo-classes](/client/selectors/pseudo-classes), they don't take
arguments.

## Graph structure states

| Selector     | Description                                 |
| ------------ | ------------------------------------------- |
| `:root`      | The root package (top-level `package.json`) |
| `:scope`     | The current scope of the selector           |
| `:project`   | Root node plus all workspaces               |
| `:workspace` | Workspace packages (listed in `vlt.json`)   |

### `:root`

Returns the root node — the package defined at the top-level
`package.json` of your project.

Terminal:

```bash
$ vlt query ':root'
```

Commonly used with [combinators](/client/selectors/combinators) to
select direct dependencies:

Terminal:

```bash
$ vlt query ':root > *'
```

### `:scope`

Returns the current scope of the selector. Useful when using the
`--scope` CLI flag to limit the query context.

### `:project`

Returns the root node along with any workspaces declared in your
project. Useful for selecting "your code" vs. third-party
dependencies.

Terminal:

```bash
$ vlt query ':project > *'
```

### `:workspace`

Matches workspace packages defined in your `vlt.json`.

Terminal:

```bash
$ vlt query ':workspace'
```

Find workspaces that have changed since main:

Terminal:

```bash
$ vlt query ':workspace:diff(main)'
```

## Dependency type states

| Selector      | Description                             |
| ------------- | --------------------------------------- |
| `:prod`       | Production dependencies                 |
| `:dev`        | Development-only dependencies           |
| `:optional`   | Optional dependencies                   |
| `:peer`       | Peer dependencies                       |
| `:missing`    | Dependencies declared but not installed |
| `:overridden` | Dependencies with an override applied   |

### `:prod`

Matches production dependencies:

Terminal:

```bash
$ vlt query ':prod'
```

### `:dev`

Matches packages that are only used as dev dependencies:

Terminal:

```bash
$ vlt query ':dev'
```

Find all dev dependencies that are outdated:

Terminal:

```bash
$ vlt query ':dev:outdated'
```

### `:optional`

Matches optional dependencies:

Terminal:

```bash
$ vlt query ':optional'
```

### `:peer`

Matches peer dependencies:

Terminal:

```bash
$ vlt query ':peer'
```

### `:missing`

Matches edges (dependency declarations) that are not resolved to any
installed package. This selector returns edges only — no nodes.

Terminal:

```bash
$ vlt query ':missing'
```

### `:overridden`

Matches dependencies that have an override applied (via the
`overrides` field in `package.json`):

Terminal:

```bash
$ vlt query ':overridden'
```

## Package property states

| Selector      | Description                              |
| ------------- | ---------------------------------------- |
| `:private`    | Packages with `"private": true`          |
| `:empty`      | Packages with no dependencies            |
| `:link`       | Linked packages                          |
| `:prerelease` | Packages with prerelease versions        |
| `:built`      | Packages successfully built during reify |
| `:scanned`    | Packages with security metadata          |
| `:skills`     | Packages that ship agent skills          |

### `:private`

Matches packages with `"private": true` in their `package.json`:

Terminal:

```bash
$ vlt query ':private'
```

### `:empty`

Matches packages that have no dependencies installed:

Terminal:

```bash
$ vlt query ':empty'
```

### `:link`

Matches linked packages only:

Terminal:

```bash
$ vlt query ':link'
```

### `:prerelease`

Matches packages whose version contains prerelease identifiers (e.g.,
`1.0.0-beta.1`, `2.0.0-rc.1+rev.2`, `0.0.0-canary`):

Terminal:

```bash
$ vlt query ':prerelease'
```

Find direct prerelease dependencies:

Terminal:

```bash
$ vlt query ':root > :prerelease'
```

### `:built`

Matches packages that have been successfully built during the reify
process (have `buildState` set to `'built'`):

Terminal:

```bash
$ vlt query ':built'
```

### `:scanned`

Matches packages that have [Socket](https://socket.dev/) security
metadata. See [Security Insights](/client/selectors/security-insights)
for security-specific selectors.

Terminal:

```bash
$ vlt query ':scanned'
```

### `:skills`

Matches installed packages that ship
[agent skills](/client/commands/skills): a root `SKILL.md`, or a
`<dir>/SKILL.md` in `skills/`, `dist/skills/` or `.agents/skills/`,
found as
[`vlt skills` finds them](/client/commands/skills#how-vlt-finds-skills).
The project and its workspaces never match, nor do `file:` packages.

Terminal:

```bash
$ vlt query ':skills'
```

Direct dependencies that ship skills:

Terminal:

```bash
$ vlt ls --target=':root > :skills'
```

Works in `vlt query`, `vlt ls`, `vlt build`, `--allow-skills`,
`--allow-scripts` and `vlt skills`. Elsewhere (other commands'
`--target`/`--scope`) it is an error.

## What gets selected

Given a monorepo:

```
my-monorepo (root)
├── packages/core (workspace, private)
│   ├── react@18.2.0 (prod)
│   └── vitest@1.0.0 (dev)
├── packages/utils (workspace)
│   └── lodash@4.17.21 (prod)
└── typescript@5.3.0 (dev)
```

| Query                | Selected                     |
| -------------------- | ---------------------------- |
| `:root`              | my-monorepo                  |
| `:workspace`         | core, utils                  |
| `:project`           | my-monorepo, core, utils     |
| `:private`           | core                         |
| `:dev`               | vitest, typescript           |
| `:prod`              | react, lodash                |
| `:root > :dev`       | typescript                   |
| `:workspace:private` | core                         |
| `:prerelease`        | (packages with pre-versions) |
| `:missing`           | (edges with no resolved pkg) |

## See also

* [Pseudo-class Selectors](/client/selectors/pseudo-classes) —
  functional selectors with arguments
* [Combinators](/client/selectors/combinators) — traverse the graph
* [Security Insights](/client/selectors/security-insights) — security
  pseudo-selectors

# Security Insights (/client/selectors/security-insights)

Security insight selectors rely on data provided by
[Socket](https://socket.dev/). Using any of these selectors triggers a
network call to fetch package report data.

Security selectors require fetching data from Socket's API. This
adds latency to queries — the data is fetched before the query runs.
Keep this in mind for interactive use.

## Malware & threats

### `:malware`

Matches packages that contain malware. This is a binary selector — a
package either has malware or it doesn't:

Terminal:

```bash
$ vlt query ':malware'
```

`:malware` matches only high-confidence malware alerts (`malware`
and `gptMalware`). For broader vulnerability detection with
configurable severity levels, use [`:vuln`](#vulnerable--vuln).

### `:squat` / `:squat(<type>)`

Matches packages with names similar to popular packages
(typosquatting).

Terminal:

```bash
$ vlt query ':squat'
```

`:squat` without arguments matches any severity. Filter with:

| Type              | Description               |
| ----------------- | ------------------------- |
| `critical` or `0` | High-confidence typosquat |
| `medium` or `2`   | Possible typosquat        |
| `none`            | Not a typosquat           |

### `:suspicious`

Matches packages with artificially inflated GitHub stars (bots,
crowdsourcing, etc.):

Terminal:

```bash
$ vlt query ':suspicious'
```

### `:confused`

Matches packages affected by manifest confusion — the published
`package.json` differs from what's in the tarball:

Terminal:

```bash
$ vlt query ':confused'
```

## Vulnerabilities

### `:vulnerable` / `:vuln`

Matches packages with vulnerability or security anomaly alerts with
severity >= medium (excludes low-severity alerts by default):

Terminal:

```bash
$ vlt query ':vulnerable'
```

The `:vuln` alias works identically:

Terminal:

```bash
$ vlt query ':vuln'
```

#### `:vuln(<level>)`

Filter by severity level:

| Level             | Alert types matched                     |
| ----------------- | --------------------------------------- |
| `critical` or `0` | `criticalCVE`                           |
| `high` or `1`     | `cve`                                   |
| `medium` or `2`   | `potentialVulnerability`, `gptSecurity` |
| `low` or `3`      | `mildCVE`, `gptAnomaly`                 |

Comparators are supported:

Terminal:

```bash
$ vlt query ':vuln(critical)'
$ vlt query ':vuln(">1")'
$ vlt query ':vuln(">=medium")'
```

### `:cve(<id>)`

Matches packages with a specific CVE alert:

Terminal:

```bash
$ vlt query ':cve(CVE-2023-1234)'
```

Match packages with any CVE:

Terminal:

```bash
$ vlt query ':cve'
```

### `:cwe(<id>)`

Matches packages with a specific CWE alert:

Terminal:

```bash
$ vlt query ':cwe(CWE-79)'
```

### `:severity(<level>)`

Matches packages by CVE severity level:

| Level             | Description            |
| ----------------- | ---------------------- |
| `critical` or `0` | Critical severity CVEs |
| `high` or `1`     | High severity CVEs     |
| `medium` or `2`   | Medium severity CVEs   |
| `low` or `3`      | Low severity CVEs      |

Comparators are supported:

Terminal:

```bash
$ vlt query ':severity(critical)'
$ vlt query ':severity(">1")'
$ vlt query ':severity(">=medium")'
```

## Licensing

### `:license(<type>)`

Matches packages based on license issues:

| Type         | Description                              |
| ------------ | ---------------------------------------- |
| `unlicensed` | No license                               |
| `misc`       | Fine-grained license problems            |
| `restricted` | Non-permissive license                   |
| `ambiguous`  | Ambiguous licensing                      |
| `copyleft`   | Copyleft license (GPL, etc.)             |
| `unknown`    | License data found but type undetermined |
| `none`       | No license data at all                   |
| `exception`  | SPDX license exception                   |

Terminal:

```bash
# Find packages with copyleft licenses
$ vlt query ':license(copyleft)'

# Find unlicensed packages

$ vlt query ':license(unlicensed)'

# Find packages with any license

$ vlt query ':license'
```

## Code behavior signals

### `:eval`

Packages using dynamic code execution (`eval()`, `new Function()`,
etc.):

Terminal:

```bash
$ vlt query ':eval'
```

### `:network`

Packages that access the network:

Terminal:

```bash
$ vlt query ':network'
```

### `:fs`

Packages that access the file system:

Terminal:

```bash
$ vlt query ':fs'
```

### `:env`

Packages that access environment variables:

Terminal:

```bash
$ vlt query ':env'
```

### `:shell`

Packages that access the system shell:

Terminal:

```bash
$ vlt query ':shell'
```

### `:scripts`

Packages with install scripts (postinstall, preinstall, etc.), or
marked by install as needing a build (e.g. a root `binding.gyp`):

Terminal:

```bash
$ vlt query ':scripts'
```

### `:debug`

Packages using debug, reflection, or dynamic code execution features:

Terminal:

```bash
$ vlt query ':debug'
```

### `:dynamic`

Packages using dynamic imports:

Terminal:

```bash
$ vlt query ':dynamic'
```

## Obfuscation & hiding

### `:obfuscated`

Packages with intentionally obfuscated code:

Terminal:

```bash
$ vlt query ':obfuscated'
```

### `:minified`

Packages containing minified code:

Terminal:

```bash
$ vlt query ':minified'
```

### `:entropic`

Packages with high-entropy strings (possibly encrypted data, leaked
secrets, or obfuscated code):

Terminal:

```bash
$ vlt query ':entropic'
```

### `:native`

Packages containing native code (compiled binaries, shared libraries):

Terminal:

```bash
$ vlt query ':native'
```

### `:shrinkwrap`

Packages containing a shrinkwrap file that may bypass normal install
procedures:

Terminal:

```bash
$ vlt query ':shrinkwrap'
```

## Package health

### `:deprecated`

Packages marked as deprecated:

Terminal:

```bash
$ vlt query ':deprecated'
```

### `:unmaintained`

Packages not updated in more than 5 years:

Terminal:

```bash
$ vlt query ':unmaintained'
```

### `:unpopular`

Packages that are not widely used:

Terminal:

```bash
$ vlt query ':unpopular'
```

### `:trivial`

Packages with less than 10 lines of code:

Terminal:

```bash
$ vlt query ':trivial'
```

### `:abandoned`

Packages published by an npm account that no longer exists:

Terminal:

```bash
$ vlt query ':abandoned'
```

### `:unknown`

Packages with a new npm collaborator publishing for the first time:

Terminal:

```bash
$ vlt query ':unknown'
```

### `:unstable`

Packages with unstable ownership (new collaborator publishing):

Terminal:

```bash
$ vlt query ':unstable'
```

## Other

### `:tracker`

Packages containing telemetry:

Terminal:

```bash
$ vlt query ':tracker'
```

### `:undesirable`

Packages that are jokes, parodies, or include undocumented behavior:

Terminal:

```bash
$ vlt query ':undesirable'
```

### `:score(<rate>, <kind>)`

Match packages by security score:

| Parameter | Description                                          |
| --------- | ---------------------------------------------------- |
| `rate`    | Score value 0–100 (or 0–1), with optional comparator |
| `kind`    | Score category (optional, default: `overall`)        |

Available kinds: `overall`, `license`, `maintenance`, `quality`,
`supplyChain`, `vulnerability`.

Terminal:

```bash
# Packages with exactly 0.8 overall score
$ vlt query ':score(80)'

# Packages with score > 0.8

$ vlt query ':score(">0.8")'

# Low maintenance score

$ vlt query ':score("<=0.5", "maintenance")'
```

## Common audit queries

Run a comprehensive security audit:

Terminal:

```bash
# Critical issues
$ vlt query ':malware, :cve, :obfuscated'

# Vulnerability scan with severity

$ vlt query ':vuln(critical), :vuln(high)'

# Supply chain risks

$ vlt query ':abandoned, :unmaintained, :unknown'

# License compliance

$ vlt query ':license(copyleft), :license(unlicensed)'

# Code behavior audit

$ vlt query ':eval, :shell, :network, :fs'
```

## See also

* [`:scanned`](/client/selectors/pseudo-states) — check if packages
  have security metadata
* [vlt security overview](/client/security) — security features in vlt

# Using Workspaces in a Monorepo Project with vlt (/client/workspaces)

## Using Workspaces in a Monorepo Project with vlt

When using the `vlt` client, you can define multiple different
workspaces in a single monorepo project.

The `vlt` client supports workspaces defined by glob patterns, and you
can also define named groups to perform vlt operations on a specific
subset of your workspaces.

## Getting Started

It's possible to use the `vlt init` command to create new workspaces
by using the `--workspace` (or `-w` for short) option, e.g:

```bash
$ vlt init -w packages/a
```

This will ensure the folder is created and a `package.json` file is
added to it, along with adding the required configuration to the
`vlt.json` file if needed.

### Manually defining Workspaces

If you want to set up new workspaces, it's also possible to use the
`vlt.json` file in the root of your project with a `workspaces` field.

At its most explicit, the `workspaces` field can be an object with
`group` names as the keys, and either a single string or an array of
strings to identify the workspace paths in each group. The strings are
interpreted as glob patterns, so if a path has glob special characters
that should be interpreted literally, use the `\` character to escape
them.

For example:

```json
{
  "workspaces": {
    "www": "www/*"
    "utils": [
      "utils/*",
      "www/utils"
    ],
  }
}
```

It's perfectly fine for a workspace to be found in multiple groups,
like the `www/utils` workspace in the example above.

If that level of group detail isn't needed, then you can also just
point the `workspaces` field at a string or array of string glob
patterns. For example:

```json
{
  "workspaces": ["www/*", "utils/*"]
}
```

Or even:

```json
{
  "workspaces": "packages/*"
}
```

### Using npm/yarn workspaces from package.json

If your project already declares workspaces the npm or yarn way, in
the `workspaces` field of the root `package.json`, vlt reads them, and
`vlt install` saves them to `vlt.json` (see
[Saving workspaces to vlt.json](#saving-workspaces-to-vltjson)):

```json
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["packages/*"]
}
```

The yarn-classic object form is also understood, including the
`nohoist` key, which vlt parses and ignores (and drops when saving to
`vlt.json`):

```json
{
  "workspaces": {
    "packages": ["packages/*"]
  }
}
```

`vlt.json` takes precedence: if it has a `workspaces` field, that is
the definition vlt uses and the `package.json` field is ignored
entirely. The two are **not** merged. Note that this is keyed on the
field, not the file — a `vlt.json` that exists but says nothing about
workspaces still falls through to `package.json`.

Named groups are a `vlt.json` feature. They are deliberately rejected
in `package.json`, because a `package.json` using them would be
meaningless to every other package manager:

```json
{
  "workspaces": {
    "apps": "apps/*"
  }
}
```

Putting that in `package.json` is an error; put it in `vlt.json`
instead.

### Using pnpm workspaces from pnpm-workspace.yaml

If neither `vlt.json` nor the root `package.json` declares workspaces,
vlt reads the `packages` list of a root `pnpm-workspace.yaml`, and
`vlt install` saves it to `vlt.json`:

```yaml
packages:
  - 'packages/*'
  - '!packages/legacy'
```

Other keys in that file are ignored, so `catalog:` specs still need a
`catalog` in `vlt.json` (see [Catalogs](/client/catalogs)). Only a
plain list of strings is read; anything else (anchors, tags, unquoted
`!` patterns) makes vlt ignore the whole list, so declare the
workspaces in `vlt.json` instead. Workspace names must be unique (pnpm
allows duplicates); otherwise list workspaces in `vlt.json` without
them.

### Saving workspaces to vlt.json

`vlt install` copies workspaces read from `package.json` or
`pnpm-workspace.yaml` to the `workspaces` field of the project
`vlt.json` (created if missing, other fields kept), in order, `!`
exclusions included, and prints:

```
Saved workspaces from pnpm-workspace.yaml to vlt.json
```

The source file is left untouched, so other tools keep reading it. An
existing `workspaces` field in `vlt.json` is never overwritten.
`vlt init -w` copies them the same way before adding a workspace
outside these globs. Nothing is written by `vlt ci`,
`--frozen-lockfile` or `--expect-lockfile`. Commit the updated
`vlt.json`.

From then on `vlt.json` takes precedence: later edits to
`package.json` or `pnpm-workspace.yaml` workspaces are ignored by vlt,
so update `vlt.json` as well. To keep the original file as the only
source, opt out before the first `vlt install` (or remove the saved
`workspaces` field) with `--no-migrate-workspaces` or in `vlt.json`:

```json
{
  "config": { "migrate-workspaces": false }
}
```

`vlt ci` reads workspaces from `vlt.json` only, even with
`--no-migrate-workspaces`. If they are declared only in `package.json`
or `pnpm-workspace.yaml`, it warns and ignores them; run `vlt install`
and commit `vlt.json` first.

### Excluding paths

A pattern beginning with `!` excludes the paths it matches, in
`vlt.json`, `package.json` and `pnpm-workspace.yaml`:

```json
{
  "workspaces": ["packages/*", "!packages/legacy"]
}
```

Following npm's behavior, `!packages/legacy` excludes only that
directory, while `!packages/legacy/**` excludes everything beneath it
as well. A later positive pattern overrides an earlier exclusion, so
`["packages/**", "!packages/b/**", "packages/b/a"]` keeps
`packages/b/a`. To match a directory whose name genuinely begins with
`!`, escape it as `\!`.

## Working with Workspaces

The simplest way to peform an option on a single workspace is to just
`cd` into that folder, and then use whatever vlt operation as you
would normally. Any installations will be added as dependencies to
that single workspace, scripts will be run in that workspace only,
etc.

If you want to work with *multiple* workspaces at one time, there are
a few options.

### Running Commands on All Workspaces

You can use the `-r --recursive` flag to run a script across all
workspaces in the monorepo project.

For example:

```bash
$ vlt run --recursive test
```

will run the `test` script in all workspaces.

### Running Commands on Specific Workspaces By Path

To run a command on certain workspaces by their path, you can use the
`-w<path> --workspace=<path>` configuration option.

For example, to run the tests on certain workspaces by path name, you
can run this:

```bash
$ vlt --workspace=src/* --workspace=www/components run test
```

would run the `test` command on all the workspaces under `src/*`, as
well as the `www/components` workspace.

Note that glob patterns may have to be quoted so that the shell does
not expand them incorrectly.

### Running Commands on Specific Workspaces By Group

If you had configured your workspaces into named groups, then you can
reference those groups using the `-g<name> --workspace-group=<name>`
configuration option.

For example, with the `vlt.json` defined above:

```json
{
  "workspaces": {
    "www": "www/*"
    "utils": [
      "utils/*",
      "www/utils"
    ],
  }
}
```

we could do:

```bash
$ vlt -g utils run test
```

to run tests on all our `utils` workspaces.

### Execution Order

Commands that target multiple workspaces (`run`, `run-exec`, `exec`,
`exec-local`, `version`, `pack`, `publish`, `pkg`) process them in
dependency order: a workspace comes after the workspaces it depends
on. This applies to `--recursive`, `--workspace`, `--workspace-group`
and `--scope`.

With `--scope`, query order is kept where possible (a dependency may
move ahead of unrelated matches), and dependencies through workspaces
the query did not match still count. `--workspace` and
`--workspace-group` only see dependencies among the selected
workspaces. Cycles are broken, so order within a cycle is not
guaranteed.

## See also

* [Affected Dependencies](/client/affected) — running scripts on only
  the workspaces a change could have broken

# Dependencies (/concepts/dependencies)

**Dependencies** are external packages of code your project uses to
function.

In the Node.js ecosystem, developers use `package.json` at the root of
the project to declare a list of **direct dependencies** in the
`dependencies` (e.g., `"express": "^4.18.0"`). Each of those most
likely have **transitive dependencies** (i.e., express pulls in
body-parser, accepts, cookie respectively.). This list of packages,
and their dependencies are what constitutes a dependency tree for a
project.

## Direct vs. transitive

| Type           | What it is                               | Example                          |
| -------------- | ---------------------------------------- | -------------------------------- |
| **Direct**     | Listed in your `package.json`            | `express@^4.18.0`                |
| **Transitive** | A dependency of one of your dependencies | `body-parser` (express needs it) |

For example, after running `vlt install express typescript`, this is
what your filesystem might look like:

{/* prettier-ignore */}

* package.json list `express@^4.18.0` directly
* node\_modules
  * express ← **direct dependency** (you installed it)
    * index.js
    * node\_modules
      * body-parser ← **transitive** (express needs it)
      * accepts ← **transitive**
      * cookie ← **transitive**
      * …
  * typescript ← **direct dependency** (dev)

## Dependency types

Packages in `package.json` can be declared under several categories:

| Field in `package.json` | Purpose                                                                        |
| ----------------------- | ------------------------------------------------------------------------------ |
| `dependencies`          | Production dependencies needed at runtime                                      |
| `devDependencies`       | Development-only tools (testing, building)                                     |
| `peerDependencies`      | Expected host dependency (e.g., a component library that is built off `react`) |
| `optionalDependencies`  | Non-failing — install skipped if resolution fails                              |

Familiar with CSS selectors? Then you'll like DSS.

The vlt CLI provides handy colon-prefixed commands to query and filter
by dependency types
[pseudo-state selectors](/client/selectors/pseudo-states) like
`:prod`, `:dev`, `:peer`, and `:optional`.

# Concepts (/concepts)

These are some package publishing concepts and problems in the Node
ecosystem that vlt builds upon.

- [Package Registry](/concepts/package-registry): How do you share your libraries or tools with others? A registry!

- [Named Registries](/concepts/named-registries): Alias registry URLs for multi-registry workflows and explicit resolution.

- [Dependencies](/concepts/dependencies): Branch and leaf; all kinds of dependencies make up the favorite software you use.

- [Manifest](/concepts/manifest): What is a package.json? What's inside it?

- [Packuments](/concepts/packuments): The complete registry metadata document containing all versions, dist-tags, and timestamps.

# Manifest (/concepts/manifest)

A **manifest** is the metadata file that describes your package to the
package manager and registry — its name, version, entry point,
dependencies, scripts, and more. In Node, this is always
`package.json`.

## Common manifest fields

| Field                  | Example                      | Purpose                                       |
| ---------------------- | ---------------------------- | --------------------------------------------- |
| `name`                 | `"express"`                  | Package name (used in `require()` / `import`) |
| `version`              | `"4.18.2"`                   | Semver version                                |
| `type`                 | `"module"` or `"commonjs"`   | Module system                                 |
| `main` / `exports`     | `"./dist/index.js"`          | Entry point(s)                                |
| `scripts`              | `{ "start": "node app.js" }` | Runable commands                              |
| `dependencies`         | `{ "express": "^4.18.0" }`   | Production deps                               |
| `devDependencies`      | `{ "vitest": "^1.0.0" }`     | Dev-only deps                                 |
| `peerDependencies`     | `{ "react": "^18.0.0" }`     | Expected host deps                            |
| `optionalDependencies` | `{ "bufferutil": "^4.0.0" }` | Non-failing deps                              |
| `engines`              | `{ "node": ">=20" }`         | Runtime requirement                           |

## Example

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node app.js",
    "test": "vitest"
  },
  "dependencies": {
    "express": "^4.18.0"
  },
  "devDependencies": {
    "vitest": "^1.0.0"
  }
}
```

## vlt.json

vlt also supports its own configuration file (`vlt.json`) for
workspace configuration, catalogs, and graph modifiers. For more
details, see [Configuring vlt](/client/configuring).

# Named Registries (/concepts/named-registries)

A **named registry** is an alias you assign to a registry URL, so you
can refer to it by a short name instead of the full URL.

For example, instead of writing `https://registry.example.com/` every
time, you can configure an alias:

```bash
vlt config set registries=myreg=https://registry.example.com/
```

Now you can use `myreg:` as a prefix to explicitly specify that a
package should come from that registry:

```bash
vlt install myreg:my-package@1.0.0
```

Or in `package.json`:

```json
{
  "dependencies": {
    "my-package": "myreg:my-package@1.0.0"
  }
}
```

## Why use named registries?

* **Multi-registry workflows** — Configure different registries for
  different scopes or purposes (e.g., `npm:` for public packages,
  `internal:` for private company packages)
* **Explicit resolution** — Ensure a specific package comes from a
  specific registry, avoiding ambiguity
* **Portability** — Share configuration via `vlt.json` so team members
  use the same registry aliases

## Built-in aliases

vlt provides these built-in registry aliases:

| Alias  | Registry                      | Notes                                      |
| ------ | ----------------------------- | ------------------------------------------ |
| `npm:` | Configurable (no default)     | Default for bare specs; must be configured |
| `jsr:` | `https://npm.jsr.io/`         | JavaScript Registry                        |
| `gh:`  | `https://npm.pkg.github.com/` | GitHub Packages                            |

## See also

* [Registry Aliases](/client/registries#registry-aliases) — Full
  configuration details
* [Scoped Registries](/client/registries#named-scope-registries-npm-compatibility)
  — Map scopes like `@mycompany/` to specific registries
* [Registry URL Specifiers](/client/registries#registry-url-specifiers)
  — Inline `registry:https://...` syntax

# Package Registry (/concepts/package-registry)

Think of a **package registry** as an app store for code.

It is a server that provides the metadata and artifacts for a package
manager to install.

The most popular package registry is the public npm registry, which
JavaScript package managers use for the bulk of their content.

## What happens when you run `npm install`

When you run this command in your terminal: `npm install react`

{/* prettier-ignore */}

```markdown
Here's what happens behind the scenes:
Your terminal
    │
    │  "Hey registry, I want to use react"
    │
    ▼
registry.npmjs.org  (the public npm registry)
    │
    │  "Here's react's metadata + a download link"
    │
    ▼
Your project's node_modules/react/
    (package downloaded and saved locally)
```

The registry is just a server that:

1. Stores every version of every published package
2. Responds to requests like "give me react version 18.2.0"
3. Authenticates publishers (so only you can update your own packages)
4. Verifies integrity (checks that the file you downloaded hasn't been
   tampered with)

# Packuments (/concepts/packuments)

A **packument** (package document) is the complete metadata document
returned by a package registry for a given package. It contains all
published versions, dist-tags, timestamps, maintainers, and other
registry-level metadata.

When you query a registry for a package (e.g., `vlt pkg react` or
`npm view react`), the registry returns a packument — not a single
package manifest.

## What's in a packument

A packument includes:

* **`name`** — the package name
* **`versions`** — a record mapping each version string to its full
  [manifest](/concepts/manifest)
* **`dist-tags`** — named aliases like `latest`, `next`, `canary`
  pointing to specific versions
* **`time`** — publication timestamps for each version, plus `created`
  and `modified` for the package itself
* **`maintainers`** — list of users with publish access
* **`readme`** — the package's README content
* **`contributors`** — contributors listed in package.json

## Packument vs. Manifest

| Aspect   | Packument                                        | Manifest                                |
| -------- | ------------------------------------------------ | --------------------------------------- |
| Scope    | Entire package (all versions)                    | Single version                          |
| Source   | Registry response                                | `package.json` + registry metadata      |
| Includes | `dist-tags`, `time`, `maintainers`, all versions | `name`, `version`, `dependencies`, etc. |
| Used for | Version resolution, dist-tag lookup              | Installation, runtime                   |

When you install a package, vlt fetches the packument, resolves the
requested specifier (version, range, or dist-tag) to a specific
version, then fetches that version's manifest and tarball.

## Minified packuments

Registries may return a **minified packument** (npm's abbreviated
"corgi" format) — containing only install-critical fields — to reduce
payload size. vlt can parse both full and minified packuments, but
always *requests* the full document (`application/json`). Abbreviated
responses omit `license` and other metadata that is persisted onto
graph manifests and queried later; the registry-client cache also
cannot yet distinguish representations of the same URL.

## Related concepts

* [Package Registry](/concepts/package-registry) — the server that
  stores and serves packuments
* [Manifest](/concepts/manifest) — the per-version package metadata
* [Dependencies](/concepts/dependencies) — how versions are resolved
  from packuments

# Share feedback (/feedback)

Got questions about how things work? Join our
[Discord](https://discord.com/invite/qdbXTqxZzZ).

## Report an issue

1. Check whether the issue already exists by searching our
   [GitHub issue tracker](https://github.com/vltpkg/vltpkg/issues). If
   you find a matching report, add a 👍 or a comment with your details
   instead of opening a duplicate.

2. If nothing matches, open a new issue as a
   [feature request](https://github.com/vltpkg/vltpkg/issues/new?template=feature_request.yml)
   or a
   [bug report](https://github.com/vltpkg/vltpkg/issues/new?template=bug_report.yml).

If the `vlt` CLI runs into an unexpected error, it writes the full
details to an `error-<pid>.log` file and points you to the same
tracker — attach that log to your bug report to help us reproduce it.

# npm interoperability (/npm-interoperability)

Keep your package manager. Point its registry at vlt & nothing else
about your setup changes: same `package.json`, same `node_modules`,
same commands.

```bash
npm config set registry=<your-vlt-registry-url>
```

vlt's registry speaks the npm registry API, so pnpm, Yarn, & Bun
switch the same way with their own registry config. You get your
registry URL when you [sign up](https://www.vlt.io/sign-up).

## What stays the same

vlt serves the same packages as
[the public npm registry](https://registry.npmjs.org/). Names, semver
ranges, & `dist-tag`s like `latest` resolve as they do today, &
installs land in a standard `node_modules`. Your `package.json` stays
the source of truth.

## Mixing registries

Route a single scope to a private registry & let everything else keep
resolving publicly, so you don't proxy the whole ecosystem:

```bash
npm config set @mycompany:registry=<your-vlt-registry-url>
```

The full set of options, including per-registry auth, is in
[Working with Named Registries](/client/registries).

## Prefer the vlt client?

You don't need it to use the registry, but the vlt CLI adds
[catalogs](/client/catalogs),
[Dependency Selector Syntax](/client/selectors), & safer installs.
Install it with the official install script:

```bash
curl -fsSL https://install.vlt.sh | bash
```

vlt requires Node.js 22.22 or later.

# Reference (/reference)

## Artefact / Artifact

Artifacts serve as outputs of the development process. In context of
Javascript these are the bundled and minified .app.js files within a
dist/ folder, the `.tgz` tarball produced when you run `npm run pack`.
A package can be an artifact, but not all packages are artifacts since
there are also libraries, extensions, tools that can be packaged, but
might require a totally different way to use and distribute.

## Ecosystem

The world of tools, libraries, and conventions that has grown up
around a programming language. The JavaScript ecosystem, for example,
includes frameworks, package managers, lint and build tools, monorepo
setups, editor extensions, and the conventions everyone loosely
follows. When you pick a language to ship an app in, you're also
joining its ecosystem — the collection of libraries and tools that
make creating and shipping apps easier.

## Library

Code written to be *used* by other code, not to be run on its own.
Libraries are intended for reuse across different codebases. They are
focused sets of code that concentrate functionality and convention, so
other developers can leverage the same functionality.

## Mirror

A read-only copy of a registry. A mirror stays in sync with an
upstream registry and serves the same packages, often from a server
closer to you (or behind your company firewall). You use it the same
way you'd use the original registry; you just can't publish new
packages to it.

## Module

A unit of code inside a language's import/export system — the thing
you `import` from or `export` functionality from. People sometimes use
"module" to mean the same thing as "package," and sometimes to mean a
smaller piece *inside* a package. Because the word gets used two ways,
you usually need a little context to know which one someone means.

## Package

An artifact that contains code, and metadata for resolving
dependencies and running its scripts effectively.

Artifacts are often made to be shared and reused by other developers,
but can also play a role in audit and traceability. Packages are what
you publish to a registry and what you install into a project. If
you've ever run `npm install react`, you installed a package!

## Package Metadata

The data *about* a piece of software, collocated with its code. For a
Javascript package it's most prominently the
[manifest](/concepts/manifest), `package.json` and
`package-lock.json`. It's the label on the tin: it tells tools and
humans what's inside before anyone opens it.

## Project

Software defined by what it's trying to *do*, not by whether parts of
it get reused. An app or service you ship to users is a project. It
might depend on a pile of packages, or vendor in some code, or in rare
cases pull in nothing at all — what makes it a project is its goal.

## Registry

A server (or service) that hosts packages and lets you publish and
download them. Most languages have several prominent public registries
where open source developers share code. For JavaScript that's the npm
registry — and many teams also run private registries inside their
company. When your package manager "goes to fetch" something, the
registry is where it goes.

## Named Registry

An alias for a registry URL (e.g., `npm:`, `internal:`, `myreg:`).
Configured via `vlt config set registries=name=url`. Used to
explicitly specify which registry a package comes from:
`vlt install myreg:pkg`.

See [Named Registries concept](/concepts/named-registries) and
[Working with Named Registries](/client/registries).

## Version

The label pinned to a specific release of some software, usually found
in its metadata. Most ecosystems use *semantic versioning*
(`major.minor.patch`, like `2.1.3`) to indicate how much changed and
whether you should expect breaking differences. How strictly that's
enforced varies a lot between languages, but the version is always
what tells you *which* release of a package you're getting.

* **Major** (e.g. `3.0.0`): breaking changes — updating may require
  code changes in your project.
* **Minor** (e.g. `2.1.0`): new features added in a
  backwards-compatible way.
* **Patch** (e.g. `2.1.3`): backwards-compatible bug fixes or small
  tweaks.

# Members & Access Control (/registry/access)

Access to a vlt account — its registries, packages, tokens, and
settings — is managed through account membership. Roles and token
privileges apply account-wide; on top of that, individual packages
carry a visibility level, and teams can be granted access to specific
packages.

## Roles

Every member has one of three roles:

| Role       | What it can do                                                             |
| ---------- | -------------------------------------------------------------------------- |
| **Owner**  | Everything, including billing, account settings, and member management     |
| **Admin**  | Same capabilities as owner, including billing and account settings         |
| **Member** | Read and publish packages, and create and revoke their own personal tokens |

The account's creator is its owner. Owners and admins can also create
**service tokens** for CI and trigger upstream package syncs; members
can't.

## Inviting members

Owners and admins invite new members from the **Members** page in the
dashboard. Invitations are sent by email, assign either the `member`
or `admin` role, and expire after 7 days if not accepted.

Owners and admins can also change an existing member's role between
`member` and `admin` from the same page. An owner's role can't be
changed, and no one can change their own role.

## How permissions are evaluated

Capabilities are expressed as privileges — for example `package:read`,
`package:write`, `token:create`, `member:write`, `billing:read`. Each
role maps to a set of privileges, and each token carries its own set
(see [Authentication & Tokens](/registry/tokens)).

A request is allowed only when **both** the member's role and the
token grant the required privilege. That means a read-only token is
safe to hand to CI even if it was created by an owner, and a token can
never do more than the person who created it.

## Package access

* Members of an account can install from and publish to the account's
  `main` registry.
* People outside the account have no access to its **restricted**
  packages.
* Packages published as **public** are installable by anyone, without
  a token — see
  [Package visibility](/registry/publishing#package-visibility) for
  how to set and change the level.
* The account's `npm` mirror serves public packages and is readable by
  any authenticated account member.

### Granting a team access to a package

Beyond the account-wide roles, a team can be given access to
individual packages:

```bash
$ vlt access grant read-only @acme:frontend @acme/utils
$ vlt access revoke @acme:frontend @acme/utils
```

Permissions are `read-only` or `read-write`. Omit the package name to
apply the grant to every package in the scope. Run these against your
account registry — `vlt registry main access grant ...` if you have
more than one configured.

## Two-factor enforcement

By default, package writes (publish, deprecate, unpublish, dist-tag
changes) made with a personal token require a one-time password.
Owners and admins can toggle this requirement under **Settings →
General**. Service tokens are exempt, so CI publishes are unaffected —
see
[Publishing — Two-factor authentication](/registry/publishing#two-factor-authentication).

# Dashboard (/registry/dashboard)

![vlt Registry Dashboard showing the account overview, recent publishes, and navigation menu](/images/dashboard.png)

## Around the dashboard

* **Dashboard** — an onboarding checklist for new accounts, usage at a
  glance, recent releases on the npm mirror, and your team's recent
  publishes.
* **Registries** — browse the npm mirror and your private packages.
* **Tokens** — create, inspect, and revoke access tokens. See
  [Authentication & Tokens](/registry/tokens).
* **Members** — invite people and manage their roles. See
  [Members & Access Control](/registry/access).
* **Settings → General** — account avatar, display name, slug, and the
  account-wide two-factor requirement for package writes.

## Registries

Every vlt account comes by default with two registries:

* **`main`** — your account's private registry, served at
  `https://registry.vlt.io/<account>/main/`. Packages published here
  are scoped to your account slug (`@<account>/...`) and readable only
  by account members. See [Publishing Packages](/registry/publishing).
* **`npm`** — a secure mirror of the public npm registry, served at
  `https://registry.vlt.io/<account>/npm/`. It is read-only and
  populated from `registry.npmjs.org`, giving your installs and CI a
  consistent, fast source for public packages.

## Accounts

An account has a display name and a **slug** — a unique, URL-safe
identifier of lowercase letters, numbers, and hyphens, chosen during
account setup.

The slug appears in your registry URLs and in your package scope, so
pick it carefully.

You can belong to more than one account, and create additional
accounts — for example, you can have a personal account and one per
organization. Switch between them with the account switcher in the
dashboard sidebar.

## Installing through your registries

Point your client's default registry at your npm mirror, and map your
account scope to your private registry:

Note You don't have to change package
managers; [find out how](/registry#set-up-your-package-manager)

Terminal:

```bash
$ vlt config set registry=https://registry.vlt.io/acme/npm/
$ vlt config set scoped-registries=@acme=https://registry.vlt.io/acme/main/
```

The npm equivalent:

.npmrc:

```ini
registry=https://registry.vlt.io/acme/npm/
@acme:registry=https://registry.vlt.io/acme/main/
```

With that in place, public packages will resolve through your mirror
and `@acme/...` packages resolve from your private registry. Both
registries accept the same account token — see
[Authentication & Tokens](/registry/tokens).

The **Setup Instructions** button in the dashboard's **Registries**
section generates these instructions for your account, tailored to
your package manager.

# Quick Start (/registry)

## Sign Up

You need a vlt.io account to publish, and also to **install** through
your account's `npm` mirror: the mirror requires a token, even for
public npm packages.

For a team, invite each developer
([Members & Access Control](/registry/access#inviting-members)); each
one logs in (or creates a personal token). Give CI and shared
environments (Vercel, coding-agent sandboxes) a service token with
only `package:read` (plus `package:write` if CI publishes), created by
an owner or admin — see
[Authentication & Tokens](/registry/tokens#personal-and-service-tokens).

[Sign up](https://www.vlt.io/sign-up):

1. **Create your account**

   You can sign up with Github, Google (Gmail) or with an email and
   password.

   ![Sign up form on vlt's sign up view with first name and last name fields, and login buttons connecting to Google and Github](/images/signin.png)

2. **Verify your email**

   If you signed up with an email and password, check your inbox for a
   one-time passcode (OTP). Paste it into the verification view to
   confirm your account.

   ![Screenshot of vlt signup one-time passcode email](/images/otp-email.png)

3. Set up your account

   ![Screenshot of vlt account setup view with display name and slug fields, and a grid of plans for user selection](/images/account-setup.png)

   Caution The slug appears in your
   registry URLs and in your package scope, so choose carefully.

4. You've signed up! You'll be logged into the Dashboard.

   ![Screenshot of vlt Dashboard view displaying left side side navigation where using can browse through registries and account settings](/images/dashboard.png)

## Log in

1. **Enter your credentials**

   Log in with your email address, or continue with Github or Google.
   You can also use a passkey if you've set one up.

   ![Login view on vlt.io with Email address input, continue button, and Github and Google login buttons. Below are links to Use passkey and a call to action to sign up if the user does not have an account](/images/login.png)

## Set up your package manager

Once you have an account, connect the package manager you already use
to your registries. The examples below use `acme` as the account slug
— replace it with your own, or use the **Setup Instructions** button
in the dashboard's **Registries** section, which generates these
instructions for your account.

If you're setting up a vlt.io account for the first time, start with
[`vlt setup`](/client/registries#getting-started-with-vlt-setup) — it
authenticates and configures your account's `npm` and `main` registry
aliases in one step:

```bash
vlt setup
```

Alternatively, configure a project manually:

1. **Set up your private `@acme` scope**

   Your private scope lives in a separate registry. To set it up in
   `vlt.json`, run:

   ```bash
   vlt config set scoped-registries=@acme=https://registry.vlt.io/acme/main/
   ```

   Then obtain an authentication token for your private scope:

   ```bash
   vlt login --registry=https://registry.vlt.io/acme/main/
   ```

   Now you can publish and install packages from your private `@acme`
   scope.

2. **Set up the vlt.io npm mirror**

   Change your default registry to your vlt.io mirror. This updates
   your `vlt.json` file to use the mirror for all packages in the
   current project:

   ```bash
   vlt config set registry=https://registry.vlt.io/acme/npm/ \
     registries.npm=https://registry.vlt.io/acme/npm/
   ```

   Then log in to obtain an authentication token:

   ```bash
   vlt login
   ```

   Then reinstall your dependencies from the vlt.io mirror:

   ```bash
   vlt install
   ```

1. **Set up the vlt.io npm mirror**

   Change your default registry to your vlt.io mirror. This updates
   your `.npmrc` file to use the mirror for all npm packages in the
   current project:

   ```bash
   npm config set registry https://registry.vlt.io/acme/npm/ --location=project
   ```

   Then log in to obtain an authentication token:

   ```bash
   npm login --registry=https://registry.vlt.io/acme/npm/
   ```

   Keep your `package-lock.json`: npm fetches its `registry.npmjs.org`
   entries from the mirror. Run a normal install:

   ```bash
   npm install
   ```

2. **Set up your private `@acme` scope**

   Your private scope lives in a separate registry. To set it up in
   `.npmrc`, run:

   ```bash
   npm config set @acme:registry https://registry.vlt.io/acme/main/ --location=project
   ```

   Then obtain an authentication token for your private scope:

   ```bash
   npm login --registry=https://registry.vlt.io/acme/main/ --scope=@acme
   ```

   Now you can publish and install packages from your private `@acme`
   scope.

1. **Set up the vlt.io npm mirror**

   Change your default registry to your vlt.io mirror. This updates
   your `.npmrc` file to use the mirror for all npm packages in the
   current project:

   ```bash
   pnpm config set registry https://registry.vlt.io/acme/npm/ --location=project
   ```

   Keep registry settings in `.npmrc`: pnpm before 11.10 ignores
   `registry` in `pnpm-workspace.yaml` and installs from npmjs.org,
   even if `pnpm config get registry` shows the mirror; pnpm 10 also
   logs in to npmjs.org. pnpm 11.10+ reads `registry` from either
   file. `_authToken` needs `.npmrc`.

   Then log in to obtain an authentication token:

   ```bash
   pnpm login
   ```

   `pnpm login` keeps the token out of the repo. In CI, don't put
   `${VLT_TOKEN}` in the project `.npmrc` — pnpm 11.5.3+ ignores it.
   See
   [pnpm in CI](/registry/publishing/ci#pnpm-needs-a-different-approach).

   Keep your `pnpm-lock.yaml`: it stores no tarball URLs, so a normal
   install fetches everything from the mirror:

   ```bash
   pnpm install
   ```

2. **Set up your private `@acme` scope**

   Your private scope lives in a separate registry. To set it up in
   `.npmrc`, run:

   ```bash
   pnpm config set @acme:registry https://registry.vlt.io/acme/main/ --location=project
   ```

   Then obtain an authentication token for your private scope:

   ```bash
   pnpm login --registry=https://registry.vlt.io/acme/main/ --scope=@acme
   ```

   Now you can publish and install packages from your private `@acme`
   scope.

These instructions are for yarn 2+ ("Berry"), the version you get from
`yarn set version berry` or a `packageManager` field in
`package.json`.

1. **Set up the vlt.io npm mirror**

   Change your default registry to your vlt.io mirror. This updates
   your project's `.yarnrc.yml` file to use the mirror for all npm
   packages:

   ```bash
   yarn config set npmRegistryServer "https://registry.vlt.io/acme/npm/"
   ```

   Then log in to obtain an authentication token:

   ```bash
   yarn npm login --web-login --always-auth
   ```

   Then to switch all your dependencies to the vlt.io mirror, delete
   your `yarn.lock` and reinstall:

   ```bash
   rm -rf yarn.lock
   yarn install
   ```

2. **Set up your private `@acme` scope**

   Your private scope lives in a separate registry. To set it up in
   `.yarnrc.yml`, run:

   ```bash
   yarn config set npmScopes.acme.npmRegistryServer "https://registry.vlt.io/acme/main/"
   yarn config set npmScopes.acme.npmPublishRegistry "https://registry.vlt.io/acme/main/"
   ```

   Then obtain an authentication token for your private scope:

   ```bash
   yarn npm login --scope acme --always-auth --web-login
   ```

   Now you can publish and install packages from your private `@acme`
   scope.

1. **Get a token**

   To authenticate Bun with your registries, first create an
   authentication token from your account's
   [Tokens page](https://www.vlt.io/tokens/acme) and define an
   environment variable. If you're using a `.env` file, define the
   token there:

   ```ini
   VLT_TOKEN=<your token>
   ```

   You can also add it to your `.bashrc` or `.zshrc`, or export it in
   your current shell for the duration of your session:

   ```bash
   export VLT_TOKEN=<your token>
   ```

   `VLT_TOKEN` is just a name: bun doesn't read it by itself, only
   through the `$VLT_TOKEN` reference in `bunfig.toml` below.

2. **Set up the vlt.io npm mirror**

   Create (or edit) `bunfig.toml` in your project root and point the
   default registry at your vlt.io mirror. Use a `$VLT_TOKEN`
   placeholder for the token instead of a literal value — bun expands
   `$VAR` references from the environment at request time, so this
   file is safe to commit:

   ```toml
   [install]
   registry = { url = "https://registry.vlt.io/acme/npm/", token = "$VLT_TOKEN" }
   ```

   Then to switch all your dependencies to the vlt.io mirror, delete
   your `bun.lock` and `node_modules` folder and reinstall:

   ```bash
   rm -rf bun.lock node_modules
   bun install
   ```

3. **Set up your private `@acme` scope**

   Your private scope lives in a separate registry. Add it under
   `[install.scopes]` in `bunfig.toml`. vlt.io tokens are scoped to
   your account rather than to a specific registry, so the same
   `$VLT_TOKEN` works here too:

   ```toml
   [install.scopes.acme]
   url = "https://registry.vlt.io/acme/main/"
   token = "$VLT_TOKEN"
   ```

   Now you can publish and install packages from your private `@acme`
   scope — `bun publish` resolves the registry from the package name's
   scope automatically.

1. **Set up the vlt.io npm mirror**

   Create (or edit) `.npmrc` in your project root and point the
   default registry at your vlt.io mirror. Reference the token via
   `${VLT_TOKEN}` rather than a literal value — deno expands `${VAR}`
   references in `.npmrc` from the environment, so this file is safe
   to commit:

   ```bash
   cat >> .npmrc <<'EOF'
   registry=https://registry.vlt.io/acme/npm/
   //registry.vlt.io/acme/npm/:_authToken=${VLT_TOKEN}
   EOF
   ```

   Since there's no `deno login`, create a token from the vlt.io
   dashboard instead, then put it in a `.env` file (make sure `.env`
   is in your `.gitignore`):

   ```bash
   echo "VLT_TOKEN=<your token>" >> .env
   ```

   `VLT_TOKEN` is just a name: deno uses it only through the
   `${VLT_TOKEN}` lines in `.npmrc`.

   Then to switch all your dependencies to the vlt.io mirror, delete
   your `deno.lock` and `node_modules` folder and reinstall, passing
   `--env-file` so the token in `.env` is loaded:

   ```bash
   rm -rf deno.lock node_modules
   deno install --env-file
   ```

2. **Set up your private `@acme` scope**

   Your private scope lives in a separate registry. Add a scope
   mapping and a matching auth-token line — the token line's host/path
   must exactly match the scope's registry URL:

   ```bash
   cat >> .npmrc <<'EOF'
   @acme:registry=https://registry.vlt.io/acme/main/
   //registry.vlt.io/acme/main/:_authToken=${VLT_TOKEN}
   EOF
   ```

   vlt.io tokens are scoped to your account rather than to a specific
   registry, so the same `VLT_TOKEN` works here too. Now you can
   install packages from your private `@acme` scope with
   `deno install --env-file`.

   `deno publish` targets [JSR](https://jsr.io) only, but `deno pack`
   builds a real npm package from a Deno project, which you then
   upload with `npm publish`. See
   [the deno guide](/registry/publishing/deno) for the full workflow —
   including Deno's 24-hour dependency-age gate, which will otherwise
   hide a version you just published.

## CI and hosted environments

Only the vlt CLI reads `VLT_TOKEN` / `VLT_TOKEN_*` itself (see
[Authentication](/client/auth#ci-and-other-headless-environments)).
Other package managers need an auth line in their own config, and
Vercel builds use `NPM_RC`. For CI, Vercel and coding-agent sandboxes,
see [CI & automation](/registry/publishing/ci#who-reads-what).

# bun (/registry/publishing/bun)

Verified against **bun 1.4**.

## Quick start

```sh
export VLT_TOKEN=<your token>
```

Create `bunfig.toml` in your project root:

```toml
[install]
registry = { url = "https://registry.vlt.io/acme/npm/", token = "$VLT_TOKEN" }

[install.scopes]
acme = { url = "https://registry.vlt.io/acme/main/", token = "$VLT_TOKEN" }
```

Then `bun install` as usual.

In `bunfig.toml` bun expands only the unbraced form. The braced form
is sent literally and you get a `401`. This is the opposite of every
other package manager here — see [gotchas](#gotchas).

Because the token is a `$VAR` reference rather than a literal,
`bunfig.toml` is safe to commit.

## What each block does

* `[install] registry` — where all public npm packages come from.
  Points at your account mirror.
* `[install.scopes]` — per-scope overrides. `acme` routes `@acme/*` to
  your `main` registry. The scope key works with or without the `@`,
  and `[install.scopes.acme]` as a table header is equivalent:

  ```toml
  [install.scopes.acme]
  url = "https://registry.vlt.io/acme/main/"
  token = "$VLT_TOKEN"
  ```

Use whichever reads better; all three forms are verified working.

## Using `.npmrc` instead

bun also reads `.npmrc`, which is handy if you want one file that npm,
pnpm, deno and bun all share:

```ini
registry=https://registry.vlt.io/acme/npm/
@acme:registry=https://registry.vlt.io/acme/main/

//registry.vlt.io/acme/npm/:_authToken=${VLT_TOKEN}
//registry.vlt.io/acme/main/:_authToken=${VLT_TOKEN}
```

In `.npmrc` the braced `${VLT_TOKEN}` form **is** expanded.

If both files exist, `bunfig.toml` wins — but only on **bun 1.4 and
newer**. Bun 1.3 and earlier gave `.npmrc` priority, so a project
carrying both files changes behaviour across those versions. Pick one
file and delete the other.

## Install from the npm mirror

```sh
bun add abbrev
```

To move an existing project onto the mirror:

```sh
rm -rf bun.lock node_modules
bun install
```

## Install from your `main` registry

```sh
bun add @acme/my-package
```

### Public packages

Public packages on `main` install without a token — the URL alone is
enough, with no `token`:

```toml
[install.scopes]
acme = { url = "https://registry.vlt.io/acme/main/" }
```

## Publish to `main`

```sh
bun publish
```

bun resolves the publish registry from your scope config, so with the
`[install.scopes]` block above, `@acme/my-package` goes to `main`
automatically — no `publishConfig` needed.

Add `--access public` for a package anyone can install, and
`--dry-run` to preview.

With a personal token, every publish returns a one-time-password
challenge with a `vlt.io` URL — open it, approve, re-run. A **service
token** skips the prompt and is what you want in CI; see
[CI & automation](/registry/publishing/ci).

## Gotchas

* **Never omit the trailing slash.** In bun 1.4, a registry URL that
  has a path and no trailing slash **silently loses its last path
  segment** — `https://registry.vlt.io/acme/npm` resolves against
  `https://registry.vlt.io/acme/`, and you get confusing 401s or 404s.
  This affects `bunfig.toml`, `.npmrc` and `[install.scopes]` alike.
  Our URLs all have paths, so this matters every time.
* **`$VLT_TOKEN` in `bunfig.toml`, `${VLT_TOKEN}` in `.npmrc`.**
  Getting this backwards produces a confusing `401` with a token that
  "looks" configured. An unset variable is sent as a literal string
  rather than failing, which looks the same from the registry's side.
* **Quote the scope key if you include the `@`.** `"@acme" = { ... }`
  is fine; unquoted `@acme = { ... }` is a hard
  `SyntaxError: failed to load bunfig` that aborts the install.
* **`publishConfig.registry` alone is not enough for `bun publish`.**
  bun will find the URL but not the credentials, and fails with
  `error: missing authentication (run `bunx npm login`)`. Set the
  registry in `bunfig.toml` (or as `registry=` in `.npmrc`) so the
  token travels with it.
* **Auth paths must match exactly.** A host-wide
  `//registry.vlt.io/:_authToken=...` works in npm and deno but
  **not** in bun — bun needs the full registry path, trailing slash
  included.
* bun has no `login` command. Authentication comes from `bunfig.toml`,
  `.npmrc`, or the environment.

# CI & automation (/registry/publishing/ci)

Store your token as a secret named `VLT_TOKEN` and expose it to the
job as an env var. The config files in these guides reference it
(`${VLT_TOKEN}`, or `$VLT_TOKEN` in `bunfig.toml`), so nothing else
changes between your laptop and CI — except pnpm, see
[below](#pnpm-needs-a-different-approach).

Personal tokens require an interactive browser confirmation on every
publish and will fail with `EOTP`. See
[Publishing from CI](#publishing-from-ci).

## Who reads what

Only the vlt CLI reads `VLT_TOKEN` itself (with `VLT_REGISTRY`, or
per-registry `VLT_TOKEN_*`; see
[Authentication](/client/auth#ci-and-other-headless-environments)).
Other tools see the secret only through an auth line that references
it (pnpm: `~/.npmrc` or a `pnpm_config_…` env var), so setting the
secret alone sends no credentials.

| Tool          | Auth from                                | Token reference in committed project file                 |
| ------------- | ---------------------------------------- | --------------------------------------------------------- |
| vlt           | keychain or env vars                     | n/a, `.npmrc` not read                                    |
| npm, npx      | `.npmrc`                                 | expanded                                                  |
| pnpm          | `~/.npmrc`, or `pnpm_config_…` env var   | **ignored** ([11.5.3+](#pnpm-needs-a-different-approach)) |
| yarn          | `.yarnrc.yml` (Classic: `.npmrc`)        | expanded                                                  |
| bun           | `bunfig.toml` (`$VLT_TOKEN`) or `.npmrc` | expanded                                                  |
| deno          | `.npmrc`                                 | expanded                                                  |
| Vercel builds | `.npmrc` written from `NPM_RC`           | see [Vercel](#vercel)                                     |

## GitHub Actions

```yaml
name: ci
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      VLT_TOKEN: ${{ secrets.VLT_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm ci
      - run: npm test
```

Commit the `.npmrc` / `bunfig.toml` / `.yarnrc.yml` from the relevant
guide. Because they reference `${VLT_TOKEN}` rather than a literal
token, they are safe in version control and need no rewriting step in
CI (pnpm: see [below](#pnpm-needs-a-different-approach)).

## Per package manager

```sh
# npm — commit .npmrc with ${VLT_TOKEN}
npm ci

# pnpm — pin to 11.26.0, and pass the token as a config env var (see below)
env "pnpm_config_//registry.vlt.io/acme/npm/:_authToken=$VLT_TOKEN" \
  pnpm install --frozen-lockfile

# yarn — commit .yarnrc.yml with ${VLT_TOKEN}
yarn install --immutable

# bun — commit bunfig.toml with $VLT_TOKEN
bun install --frozen-lockfile

# deno — commit .npmrc with ${VLT_TOKEN}
deno ci

# vlt — one VLT_TOKEN_<registry> per registry
VLT_TOKEN_https_registry_vlt_io_acme_npm=$VLT_TOKEN \
VLT_TOKEN_https_registry_vlt_io_acme_main=$VLT_TOKEN \
vlt install --frozen-lockfile
```

### Generating `.npmrc` at runtime instead

If you would rather not commit the file, write it in a step:

```yaml
- run: |
    cat > .npmrc <<'EOF'
    registry=https://registry.vlt.io/acme/npm/
    @acme:registry=https://registry.vlt.io/acme/main/
    //registry.vlt.io/acme/npm/:_authToken=${VLT_TOKEN}
    //registry.vlt.io/acme/main/:_authToken=${VLT_TOKEN}
    EOF
```

Keep the quotes on `<<'EOF'` so the shell leaves `${VLT_TOKEN}` intact
for the package manager to expand — never write the literal token into
a project `.npmrc`. pnpm ignores `${VLT_TOKEN}` here too; see below.

### pnpm needs a different approach

pnpm ignores `${VLT_TOKEN}` in a project `.npmrc` on purpose, so the
committed-file pattern above does not carry credentials for it. Commit
only the routing, and supply the token as a config environment
variable:

```yaml
- run:
    env
    "pnpm_config_//registry.vlt.io/acme/npm/:_authToken=$VLT_TOKEN"
    pnpm install --frozen-lockfile
```

Use `env` rather than `export`: the variable name contains `/`, `:`
and `.`, which the shell will not accept in an assignment. This needs
**pnpm 11.6.0 or newer**; see
[the pnpm guide](/registry/publishing/pnpm) for the full version
matrix.

Or write the auth lines to the user-level `~/.npmrc`, where pnpm still
expands `${VLT_TOKEN}`:

```yaml
- run: |
    cat >> ~/.npmrc <<'EOF'
    //registry.vlt.io/acme/npm/:_authToken=${VLT_TOKEN}
    //registry.vlt.io/acme/main/:_authToken=${VLT_TOKEN}
    EOF
- run: pnpm install --frozen-lockfile
```

`PNPM_CONFIG_NPMRC_AUTH_FILE=<path>` (env form of `--npmrc-auth-file`)
does the same with an auth file outside the repo (verified on pnpm
11.26 and 12).

Pin pnpm by exact version in `packageManager`, not by range. Corepack
resolves a range against its local cache first, so `pnpm@11` can
produce different versions on different runners.

### Two notes on the other tools

* **deno** — `deno ci` (Deno 2.8+) is the equivalent of `npm ci`: it
  installs strictly from `deno.lock` and fails rather than updating
  it.
* **deno** — Deno's default 24-hour dependency-age gate will block a
  package you published minutes earlier. If CI installs your own fresh
  releases, configure `minimumDependencyAge` as shown in
  [the deno guide](/registry/publishing/deno).

## Vercel

Vercel doesn't read `VLT_TOKEN`. Builds install with an `.npmrc`
Vercel writes from the `NPM_RC` env var. Set `NPM_RC` to your routing
and auth lines with a `package:read` service token, and keep a
`registry.npmjs.org` line — Vercel installs its runtimes from the
public registry. For multi-line values, set it with the Vercel CLI to
keep the line breaks. Use `NPM_RC`, not `NPM_TOKEN` (meant for private
packages on npm's own registry; `NPM_RC` wins if both are set). See
Vercel's
[private dependencies guide](https://vercel.com/kb/guide/using-private-dependencies-with-vercel).

## Coding-agent sandboxes

Each cloud agent or dev environment (Cursor, Claude Code, Devin,
Codespaces, …) needs the token set up separately — treat each like a
CI runner:

* Give it its own `package:read` service token (owners and admins
  create them), so you can revoke one without breaking the others.
* Store the token in that environment's secrets (these guides call it
  `VLT_TOKEN`).
* Commit the routing: default `registry` → the `npm` mirror, `@acme`
  scope → `main` (`.npmrc` / `.yarnrc.yml` / `bunfig.toml` /
  `vlt.json`).
* Provide auth for both registry URLs: committed `${VLT_TOKEN}` lines
  (npm, yarn, deno; `$VLT_TOKEN` in `bunfig.toml`), a setup step
  writing `~/.npmrc` (pnpm,
  [above](#pnpm-needs-a-different-approach)), or, for vlt, the env
  vars in
  [Authentication](/client/auth#ci-and-other-headless-environments).

## Publishing from CI

**Use a service token.** When you create the token at
[vlt.io → Tokens](https://www.vlt.io), choose *This is a service
token* rather than *This token is for myself*, and give it
`package:read` and `package:write`.

That choice is what makes unattended publishing work. A **personal**
token answers every publish with a one-time-password challenge and
fails in CI with:

```
npm error code EOTP
npm error This operation requires a one-time password.
```

A **service** token has no such challenge — verified with npm, pnpm,
yarn, bun and vlt, all publishing to `main` with no prompt.

```yaml
- run: npm publish
  env:
    VLT_TOKEN: ${{ secrets.VLT_TOKEN_CI }}
```

Nothing else about the config changes; a service token is a drop-in
replacement in every snippet in these guides. Store it as a separate
secret from your personal token so it is obvious which one CI uses.

Three per-tool notes:

* **yarn** needs `yarn install` before `yarn npm publish`, or it
  aborts with
  `This package doesn't seem to be present in your lockfile`.
* **pnpm** needs `--no-git-checks` in CI, since the checkout is often
  not on the publish branch.
* **deno** publishes in two steps — `deno pack` then
  `npm publish <tarball>`. Set `publish.include` in `deno.json` first,
  or `deno pack` may bundle your `.npmrc` into the tarball. See
  [the deno guide](/registry/publishing/deno).

If you are stuck with a personal token, `vlt publish` can take a
pre-obtained code:

```sh
VLT_OTP=<code> vlt publish
```

## Read-only installs of public packages

A job that installs only public packages from `main` needs no secret
at all — just the registry URL:

```ini
@acme:registry=https://registry.vlt.io/acme/main/
```

The npm mirror always requires a token, so this only helps if every
one of your dependencies is a public package from `main`.

## Checklist

* `VLT_TOKEN` is set as a masked secret, not a plaintext variable.
* The committed config uses `${VLT_TOKEN}` (or `$VLT_TOKEN` for
  `bunfig.toml`; pnpm: routing only) — never a literal token.
* The secret is really set in the job: npm, bun and deno send an unset
  token variable literally, which looks like a bad token.
* After switching registries: npm and pnpm lockfiles kept;
  `vlt-lock.json`, `yarn.lock`, `bun.lock` and `deno.lock` regenerated
  (see each guide).
* Installs use the frozen-lockfile flag for the package manager.

# deno (/registry/publishing/deno)

Verified against **deno 2.9**.

Deno reads npm registry configuration from `.npmrc`, so setup is the
same shape as npm. Deno installs from both registries. It can also
**build** a publishable npm package from a Deno project with
`deno pack`, though the upload itself runs through `npm publish` — see
[publishing](#publishing).

## Quick start

```sh
export VLT_TOKEN=<your token>
```

Create `.npmrc` in your project root:

```ini
registry=https://registry.vlt.io/acme/npm/
@acme:registry=https://registry.vlt.io/acme/main/

//registry.vlt.io/acme/npm/:_authToken=${VLT_TOKEN}
//registry.vlt.io/acme/main/:_authToken=${VLT_TOKEN}
```

Then install as usual:

```sh
deno install
```

Deno expands `${VLT_TOKEN}` from the environment, so this file
contains no secrets and is safe to commit.

## Install from the npm mirror

```sh
deno install npm:abbrev
```

Every bare `npm:` specifier resolves through your account mirror,
including transitive dependencies. To move an existing project onto
the mirror:

```sh
rm -rf deno.lock node_modules
deno install
```

## Install from your `main` registry

```sh
deno install npm:@acme/my-package
```

Then import it as normal:

```ts
import myPackage from 'npm:@acme/my-package'
```

### Public packages

Public packages on `main` install without a token — the registry line
alone is enough, with no auth line:

```ini
@acme:registry=https://registry.vlt.io/acme/main/
```

## Brand-new versions are hidden for 24 hours

Like Yarn, Deno 2.9 ships a supply-chain protection that skips very
recent releases — the minimum dependency age, on by default with a
**24-hour** window. It applies to custom registries too, so right
after publishing to `main` an install fails:

```
error: Could not find npm package '@acme/my-package' matching '*'.

A newer matching version was found, but it was not used because it was newer
than the specified minimum dependency date of 2026-09-09 06:54:51 UTC.
```

Deno names the policy and the flags in its hint text, so this one is
easy to diagnose. To unblock a one-off install:

```sh
deno install --min-dep-age=0
```

For a permanent fix, exempt your own scope while keeping the
protection for everything else, in `deno.json`:

```jsonc
{
  "minimumDependencyAge": {
    "age": "P1D",
    "exclude": ["npm:@acme/*"],
  },
}
```

**The `npm:` prefix in `exclude` is required.** `"@acme/*"` on its own
silently fails to match and the install stays blocked.

To switch the gate off entirely instead, either put this in `.npmrc`:

```ini
min-release-age=0
```

or set `NPM_CONFIG_MIN_RELEASE_AGE=0` in the environment, which is the
more convenient form in CI.

## Loading the token from a `.env` file

If you keep the token in a file rather than your shell profile:

```sh
echo 'VLT_TOKEN=<your token>' >> .env
echo '.env' >> .gitignore
```

Deno does not read `.env` automatically — pass `--env-file` so the
variable is available for `.npmrc` expansion:

```sh
deno install --env-file
```

## Publishing

`deno publish` targets [JSR](https://jsr.io) only — it has no
`--registry` flag and cannot upload to `main&#x60;. But **`deno pack`
builds a real npm package from a Deno project**, so publishing to
`main` takes two steps: pack with deno, upload with npm.

This works from a Deno-native project with no `package.json` at all.
Given a `deno.json` like this:

```json
{
  "name": "@acme/my-package",
  "version": "1.0.0",
  "exports": "./mod.ts",
  "license": "MIT",
  "publish": { "include": ["mod.ts", "README.md", "LICENSE"] }
}
```

pack and publish:

```sh
deno pack
npm publish acme-my-package-1.0.0.tgz
```

`deno pack` transpiles your TypeScript and writes a tarball containing
generated `.js`, `.d.ts` &#x2A;*and a generated `package.json`** with
correct `exports`, `main` and `types` fields. The result is an
ordinary npm package: verified end-to-end by publishing to `main` and
then consuming it from both `deno run` and plain Node.

The `npm publish` step needs the `.npmrc` from the top of this guide
so the scope resolves to `main`. Useful `deno pack` flags:
`--set-version <v>` to override the version, `--dry-run` to preview,
and `-o` to name the output file.

Unlike `npm pack`, `deno pack` has no built-in exclusion list — it
sweeps up stray files in the project directory, &#x2A;*including `.npmrc`
and `bunfig.toml`**. If either holds a literal token rather than a
`${VLT_TOKEN}` placeholder, packing without an allowlist publishes
your registry credentials inside the tarball. npm refuses to include
`.npmrc`; deno will happily do it.

An allowlist is the reliable fix — either `publish.include` in
`deno.json` as above, or naming the files on the command line
(`deno pack mod.ts`). Avoid relying on `--ignore=.npmrc`: it excludes
that one file and still pulls in anything else lying around.

`bun publish <tarball>` can also upload a prebuilt tarball, but it
aborts with `MissingPackageJSON` in a Deno-only project, so use npm
unless you keep a `package.json` too.

## Gotchas

* **Use `${VAR}`, not `$VAR`.** Only the braced form is expanded.
* **An unset variable is left as literal text, not emptied.** A
  missing `VLT_TOKEN` is sent as the literal string `${VLT_TOKEN}`, so
  a forgotten CI secret produces a bogus credential rather than a
  clear "no token" error. Use `${VLT_TOKEN?}` if you want an empty
  value instead.
* **Most registry failures report `was not found`.** A refused
  connection, a 404 and a bad token all surface as
  `error: npm:<pkg> was not found.`, so check the registry URL and the
  token before concluding the package is missing. The age gate is the
  exception — it produces its own clearly-labelled error.
* **Switching registries requires regenerating `deno.lock`.** Unlike
  installs from npmjs, a custom-registry install records the full
  tarball URL in the lockfile. A stale lockfile will keep fetching
  tarballs from the old host — silently, and unauthenticated if you no
  longer have credentials for it. Delete `deno.lock` when you change
  registries.
* Trailing slashes must match between the registry URL and the auth
  line.
* A host-wide `//registry.vlt.io/:_authToken=${VLT_TOKEN}` also works
  in deno and covers both registries, but the explicit per-registry
  lines above stay portable if you later add bun to the project.
* **Registry and auth settings go in `.npmrc`; the age gate goes in
  `deno.json`.** `deno.json` has no registry or token field, so the
  two halves of this setup live in different files.
* In a monorepo, deno looks for `.npmrc` next to the `deno.json` it
  loaded and then upward from there — not from the directory you
  happened to run the command in. Keep `.npmrc` beside `deno.json` at
  the workspace root.

# Publishing Packages (/registry/publishing)

Your account's `main` registry hosts your private packages. On a
private account, every package published to it must be scoped to your
account slug — for example, an account with the slug `acme` publishes
packages named `@acme/utils`, `@acme/app`, and so on.

The registry speaks the npm registry protocol, so you can publish with
whichever package manager you already use.

## Guides

Each guide covers configuring the package manager against your
account's two registries, installing from both, and publishing to
`main` — along with the version requirements and gotchas specific to
that tool. They use `acme` as the account slug; replace it with your
own, or use the **Setup Instructions** button in the dashboard's
**Registries** section, which generates them for your account.















Whichever client you use, you'll need to authenticate — see
[Authentication & Tokens](/registry/tokens).

## What the registry validates

Your package manager packs the package into a tarball and uploads it
along with its manifest. The registry then validates every publish:

* On a private account, the package name must be scoped to your
  account: `@acme/utils` publishes, but an unscoped name like `utils`,
  or a name under someone else's scope like `@other-team/utils`, is
  rejected with a `403 Forbidden` error.
* The name and version in the request, the manifest, and the tarball's
  `package.json` must all agree, which protects consumers against
  manifest confusion.
* The tarball's integrity hash is recomputed and verified on the
  server.
* Tarballs are limited to 100 MB by default.

## Versions are immutable

Exactly one version is published at a time, and once a version is
published it can never be replaced. Publishing an existing version
again fails with a conflict error. If you unpublish a version, that
version number is permanently reserved and cannot be reused — publish
a new version instead.

## Dist-tags

If you don't specify a tag, a publish updates `latest`. Use a tag to
publish pre-releases without affecting the default install:

Terminal:

```bash
$ vlt publish --tag=beta
```

Tags can only reference versions that exist, and the standard npm
`dist-tag` endpoints are supported for listing, adding, and removing
tags.

## Two-factor authentication

By default, accounts require a one-time password (OTP) for publishes
and other package writes made with a personal token. When the registry
asks for it, your client opens a browser where you confirm the write
with the second factor enrolled on your vlt.io account. You'll need
one enrolled before your first publish.

Service tokens are not subject to the OTP prompt, which is what makes
unattended publishes from CI possible — see
[CI & automation](/registry/publishing/ci). Account owners and admins
can adjust the two-factor requirement under **Settings → General**.

The vlt registry does not currently support OIDC trusted publishing.
Use a service token in CI.

## Deprecating and unpublishing

Deprecation and unpublish follow the standard npm protocol, so
`vlt deprecate` and `vlt unpublish` — and their `npm` equivalents —
work against your registry. Deprecating a version attaches a warning
message that installers display; it can be reversed by deprecating
again with an empty message. Unpublishing removes a version (or an
entire package), and as noted above, unpublished version numbers can
never be reused.

## Package visibility

By default, packages on a private account's `main` registry are
readable only by members of that account. Individual packages can be
made **public**, which makes them installable by anyone — with no
token at all, and no auth line in the consumer's config. Each guide
above shows the minimal configuration a public package needs.

Set the level when you publish:

Terminal:

```bash
$ vlt publish --access=public
```

Or record it with the package, so it doesn't depend on who runs the
publish. Every package manager in the guides above reads this field:

package.json:

```json
{
"name": "@acme/utils",
"publishConfig": { "access": "public" }
}
```

To read or change the level of a package that's already published:

Terminal:

```bash
$ vlt access get status @acme/utils
$ vlt access set status=restricted @acme/utils
$ vlt access list packages @acme
```

The two levels are `public` and `restricted`. Access changes made with
a personal token are subject to the same OTP requirement as a publish.

Teams can also be granted read-only or read-write access to individual
packages with `vlt access grant` and `vlt access revoke` — see
[Members & Access Control](/registry/access).

# npm (/registry/publishing/npm)

Verified against **npm 12**.

## Quick start

```sh
export VLT_TOKEN=<your token>

npm config set registry https://registry.vlt.io/acme/npm/ --location=project
npm config set @acme:registry https://registry.vlt.io/acme/main/ --location=project
npm config set //registry.vlt.io/acme/npm/:_authToken '${VLT_TOKEN}' --location=project
npm config set //registry.vlt.io/acme/main/:_authToken '${VLT_TOKEN}' --location=project
```

That writes the `.npmrc` below. Then `npm install` as usual.

## The config file

Everything lives in `.npmrc`. Create it in your project root:

```ini
; all public npm packages come from your account mirror
registry=https://registry.vlt.io/acme/npm/

; your own packages come from your main registry
@acme:registry=https://registry.vlt.io/acme/main/

; auth — ${VLT_TOKEN} is read from the environment, so this file is safe to commit
//registry.vlt.io/acme/npm/:_authToken=${VLT_TOKEN}
//registry.vlt.io/acme/main/:_authToken=${VLT_TOKEN}
```

npm expands `${VLT_TOKEN}` from the environment at read time. Use the
braces — bare `$VLT_TOKEN` is **not** expanded and gets sent
literally.

Drop the `@acme:registry` line if you only want the mirror, or the
`registry` line if you only want your own packages.

## Install from the npm mirror

```sh
npm install abbrev
```

Resolves through `https://registry.vlt.io/acme/npm/`. To move an
existing project onto the mirror, keep `package-lock.json` and
reinstall. npm's `replace-registry-host` (on by default) fetches
locked `registry.npmjs.org` URLs from your configured registry:

```sh
npm install
```

## Install from your `main` registry

Anything matching `@acme/*` is routed to `main` by the
`@acme:registry` line:

```sh
npm install @acme/my-package
```

### Public packages

Public packages on `main` install without a token — the registry line
alone is enough, with no auth line:

```ini
@acme:registry=https://registry.vlt.io/acme/main/
```

## Publish to `main`

Point the package at the registry in `package.json`, so publishing can
never go to the wrong place:

```json
{
  "name": "@acme/my-package",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://registry.vlt.io/acme/main/"
  }
}
```

Then:

```sh
npm publish
```

Setting it in `package.json` keeps the destination with the package
instead of depending on whoever's machine runs the publish.

For a **scoped** package, npm resolves the publish registry in this
order:

1. `@acme:registry`
2. `--registry=<url>` on the command line
3. `publishConfig.registry`
4. the default `registry`

The surprise is that `@acme:registry` wins over an explicit
`--registry` flag, so `--registry` will not redirect a scoped publish.
In the setup above both point at `main`, so there is nothing to trip
over — but don't rely on `--registry` to override it, and don't set
`@acme:registry` and `publishConfig.registry` to different places.

Add `--access public` to make the package readable without a token.
Use `--dry-run` first to see exactly what would be uploaded and where.

### The one-time password prompt

With a **personal** token, every publish stops with:

```
npm error code EOTP
npm error This operation requires a one-time password.
npm error Open this URL in your browser to authenticate:
npm error   https://www.vlt.io/auth/otp/...
```

Open the URL, approve, and re-run `npm publish`. This is expected —
the registry requires an interactive confirmation for writes made with
a personal token.

A **service token** skips the prompt, which is how you publish from
CI. Create one at [vlt.io → Tokens](https://www.vlt.io) by choosing
*This is a service token*, with the `package:write` scope. Nothing
else in this guide changes — it is a drop-in replacement for
`VLT_TOKEN`. See [CI & automation](/registry/publishing/ci).

## Log in instead of using a token

```sh
npm login --registry=https://registry.vlt.io/acme/main/
```

npm 12 defaults to `--auth-type=web`, so this opens the browser and
stores a token in your **user** `.npmrc` — no token juggling. Add
`--scope=@acme` to also record the scope-to-registry mapping.

Two things to avoid:

* **Don't pass `--otp` to `npm login`.** Supplying an `otp` config
  forces `--auth-type=legacy`, and username/password login is **not**
  supported by the registry.
* **`--location` does not work with `npm login`.** It is accepted and
  ignored; the token always lands in your user `.npmrc`. To write it
  into the project file instead, use `--userconfig=./.npmrc`.

If `npm login` ever prompts you for a *username*, it has fallen back
to the legacy flow — that means it could not reach the registry's web
login endpoint, not that you should type your credentials.

## Useful checks

```sh
npm whoami --registry=https://registry.vlt.io/acme/main/   # who am I
npm config list                                            # what is npm reading
npm view @acme/my-package                                   # inspect a package
```

## Gotchas

* **Trailing slashes matter.**
  `//registry.vlt.io/acme/npm/:_authToken` must match the registry URL
  exactly, slash included.
* **Use `${VAR}`, not `$VAR`.** Only the braced form is expanded.
* One auth line per registry. A host-wide
  `//registry.vlt.io/:_authToken=${VLT_TOKEN}` does work for npm, but
  it is not portable to bun, so prefer the explicit per-registry lines
  above.
* **Never commit a literal token.** Keep `${VLT_TOKEN}` in the file
  and the real value in your environment.

# pnpm (/registry/publishing/pnpm)

Verified against **pnpm 10, 11 and 12**.

pnpm 12 rejects every version in the mirror's metadata and fails with
`no version found for the latest tag`. pnpm **11 and older work
fine**.

This affects the **mirror only**. Publishing to `main` and installing
your own packages from `main` work correctly on pnpm 12 — so if you
only consume your own packages, you can stay on 12. If you install
public npm packages through the mirror, pin the project to the latest
11.x:

```sh
corepack use pnpm@11.26.0
```

That writes `"packageManager": "pnpm@11.26.0"` into your
`package.json`, so everyone on the project gets the same version.
&#x2A;*Pin an explicit version rather than the range `pnpm@11`.** Corepack
satisfies a range from its local cache first, so on a machine that has
an old 11.x cached, `pnpm@11` can quietly resolve to something as old
as `11.0.0` — and then pin it. Version matters here: see the table
below.

To change the pnpm on your `PATH` instead, pass the version explicitly
— a bare `pnpm self-update` refuses to downgrade:

```sh
pnpm self-update 11.26.0
```

This is a bug on our side, not yours, and a fix is in progress.

## Quick start

```sh
export VLT_TOKEN=<your token>

pnpm config set registry https://registry.vlt.io/acme/npm/ --location=project
pnpm config set @acme:registry https://registry.vlt.io/acme/main/ --location=project
```

Then add auth by logging in through the browser:

```sh
pnpm login --registry=https://registry.vlt.io/acme/npm/
pnpm login --registry=https://registry.vlt.io/acme/main/ --scope=@acme
```

Now `pnpm install` works.

## The config file

pnpm reads registry and auth settings from `.npmrc`, same keys as npm.
Commit the **routing** only, with no credentials:

```ini
registry=https://registry.vlt.io/acme/npm/
@acme:registry=https://registry.vlt.io/acme/main/
```

Registry and auth keys belong in `.npmrc`; every other pnpm setting
now lives in `pnpm-workspace.yaml`. pnpm before 11.10 ignores
`registry` in `pnpm-workspace.yaml` when installing.

### `${VLT_TOKEN}` does not work in a project `.npmrc`

Unlike npm, yarn, bun and deno, pnpm **deliberately ignores `${...}`
placeholders** in a repository `.npmrc` for registry, proxy and
credential values. A file containing
`//registry.vlt.io/acme/npm/:_authToken=${VLT_TOKEN}` sends no
`Authorization` header at all — you get a `401` that looks like a bad
token, with no warning explaining why.

This is a supply-chain fix (a malicious repo could otherwise redirect
your token to a registry it controls), landed in **pnpm 11.5.3**, so
it applies to every current version. Use one of the two options below
instead.

Which option is available depends on the version, and there is one
unlucky release with neither:

| pnpm version     | `${VLT_TOKEN}` in project `.npmrc` | `pnpm_config_…` env var |
| ---------------- | ---------------------------------- | ----------------------- |
| 11.5.2 and older | works                              | **not supported**       |
| 11.5.3           | blocked                            | **not supported**       |
| 11.6.0 – 11.26.0 | blocked                            | works                   |
| 12.x             | blocked                            | works                   |

So on the pinned 11.26.0 above, use `pnpm login` or the environment
variable — never a placeholder in the project file.

### Option 1 — log in (recommended for laptops)

```sh
pnpm login --registry=https://registry.vlt.io/acme/npm/
pnpm login --registry=https://registry.vlt.io/acme/main/ --scope=@acme
```

Browser-based, and the credential is stored in your global pnpm config
rather than in the repo.

### Option 2 — pass the token as an environment variable (recommended for CI)

pnpm accepts any config key as a `pnpm_config_`-prefixed variable,
which sidesteps the placeholder restriction entirely:

```sh
env "pnpm_config_//registry.vlt.io/acme/npm/:_authToken=$VLT_TOKEN" pnpm install
```

Two notes:

* Use `env` rather than `export` — the variable name contains `/`, `:`
  and `.`, which the shell will not accept in an assignment.
* **Needs pnpm 11.6.0 or newer.** On older versions the variable is
  ignored and you get
  `ERR_PNPM_FETCH_401 … No authorization header was set for the request`.

In CI you can also write the auth lines to the user-level `~/.npmrc`,
where `${VLT_TOKEN}` still expands — see
[CI & automation](/registry/publishing/ci#pnpm-needs-a-different-approach).

## Install from the npm mirror

```sh
pnpm add abbrev
```

To move an existing project onto the mirror, keep `pnpm-lock.yaml` —
it stores no tarball URLs — and run `pnpm install`:

```sh
pnpm install
```

## Install from your `main` registry

```sh
pnpm add @acme/my-package
```

### Public packages

Public packages on `main` install without a token — the registry line
alone is enough, with no auth line:

```ini
@acme:registry=https://registry.vlt.io/acme/main/
```

## Publish to `main`

```json
{
  "name": "@acme/my-package",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://registry.vlt.io/acme/main/"
  }
}
```

```sh
pnpm publish
```

`publishConfig.registry` decides the destination, and in pnpm it is
the **strongest** setting — it beats `@acme:registry` and even an
explicit `--registry` flag, which is the weakest of the four. (npm
resolves these in a different order, so don't assume a publish script
behaves identically under both.) Add `--access public` for a package
anyone can install.

Two flags you will probably want:

* `--no-git-checks` — pnpm refuses to publish unless the git tree is
  clean and you are on the publish branch. Verified: an uncommitted
  file fails with `ERR_PNPM_GIT_UNCLEAN`.
* `--dry-run` — pack and report without uploading.

With a personal token, every publish returns a one-time-password
challenge with a `vlt.io` URL — open it, approve, re-run. A **service
token** skips the prompt and is what you want in CI; see
[CI & automation](/registry/publishing/ci).

## Log in

```sh
pnpm login --registry=https://registry.vlt.io/acme/main/ --scope=@acme
```

This uses the browser login flow and prints an authentication URL.
`--scope` also records the scope-to-registry mapping for you. In
current pnpm the credential is written to your global pnpm config, not
to `.npmrc`.

`pnpm token` is not implemented in pnpm — it reports
`Not implemented in pnpm. Use the npm CLI directly`. Manage tokens at
[vlt.io](https://www.vlt.io) or with `npm token`.

## Gotchas

* **pnpm 12 + the npm mirror is broken.** See the note at the top.
* **`${VAR}` in a project `.npmrc` is ignored, silently.** See above.
* **`pnpm config set` writes to your machine-global config by
  default.** Always pass `--location=project`, or credentials end up
  in your user config unexpectedly. `--location` accepts only
  `project` and `global` — there is no `user`.
* **`always-auth` no longer exists in pnpm.** Setting it produces an
  unrecognized-setting warning and does nothing; it isn't needed.
* Trailing slashes must match between the registry URL and the auth
  line.
* `--npmrc-auth-file` (alias `--userconfig`) points pnpm at a
  different `.npmrc` for auth. That file is treated as trusted, so
  `${VAR}` expansion **does** work there — only use it in environments
  that build trusted repositories.

# vlt (/registry/publishing/vlt)

Verified against **vlt 1.0**.

## Quick start

One command configures both registries for your account:

```sh
vlt setup acme
```

That authenticates in the browser and writes the `npm` and `main`
registry aliases to your user config, so `vlt install` and `vlx` work
everywhere. Then:

```sh
vlt install
```

If you would rather not use the wizard, or you are scripting it, see
[manual configuration](#manual-configuration).

## Manual configuration

```sh
vlt config set registry=https://registry.vlt.io/acme/npm/ \
  registries.npm=https://registry.vlt.io/acme/npm/ \
  registries.main=https://registry.vlt.io/acme/main/ \
  scoped-registries.@acme=https://registry.vlt.io/acme/main/
```

That writes `vlt.json`. Add `--config=user` to apply it to every
project instead of just this one:

```json
{
  "config": {
    "registry": "https://registry.vlt.io/acme/npm/",
    "registries": {
      "npm": "https://registry.vlt.io/acme/npm/",
      "main": "https://registry.vlt.io/acme/main/"
    },
    "scoped-registries": {
      "@acme": "https://registry.vlt.io/acme/main/"
    }
  }
}
```

What each field does:

* `registry` — the default registry all packages resolve against.
  Pointing it at your mirror makes it a drop-in npm replacement.
* `registries` — named aliases. They power
  `vlt registry <alias> <command>` and the `<alias>:` specifier
  syntax.
* `scoped-registries` — routes a scope to a registry, like
  `@scope:registry` in npm. Note the key **keeps** the `@`.

## Authentication

The wizard stores a token in your system keychain. To add one by hand:

```sh
vlt login --registry=https://registry.vlt.io/acme/main/
```

Or set it in the environment, which is what you want for scripts and
CI:

```sh
export VLT_TOKEN=<your token>
export VLT_REGISTRY=https://registry.vlt.io/acme/npm/
```

`VLT_TOKEN` with `VLT_REGISTRY` covers the default registry. For
`scoped-registries`, also export that registry's
`VLT_TOKEN_<registry>`, e.g.
`VLT_TOKEN_https_registry_vlt_io_acme_main` (see
[Authentication](/client/auth#ci-and-other-headless-environments)).

## Install from the npm mirror

```sh
vlt install abbrev
```

To move an existing project onto the mirror, delete the lockfile: vlt
doesn't yet re-resolve a kept `vlt-lock.json` against a new registry
([#1579](https://github.com/vltpkg/vltpkg/issues/1579)).

```sh
rm -rf vlt-lock.json node_modules
vlt install
```

## Install from your `main` registry

With `scoped-registries` configured:

```sh
vlt install @acme/my-package
```

You can also pull from a named registry explicitly, without any scope
config, using the `<alias>:` specifier syntax:

```sh
vlt install @acme/my-package@main:@acme/my-package@1.0.0
```

which records the alias in `package.json`:

```json
{
  "dependencies": {
    "@acme/my-package": "main:@acme/my-package@1.0.0"
  }
}
```

### Public packages

Public packages on `main` install without a token — the registry
mapping alone is enough, with no token in the environment or keychain:

```json
{
  "config": {
    "scoped-registries": {
      "@acme": "https://registry.vlt.io/acme/main/"
    }
  }
}
```

## Publish to `main`

```sh
vlt publish --registry=https://registry.vlt.io/acme/main/
```

Or set `registry` in the project `vlt.json` (or
`publishConfig.registry` in `package.json`) and just run
`vlt publish`. Useful flags: `--access public`, `--tag`, `--dry-run`,
and `--recursive` to publish every workspace in a monorepo.

With a personal token, every publish returns a one-time-password
challenge with a `vlt.io` URL. Open it, approve, and re-run — or pass
the code through the environment:

```sh
VLT_OTP=<code> vlt publish
```

A **service token** skips the challenge, which is how you publish from
CI. See [CI & automation](/registry/publishing/ci).

## Working with a named registry

`vlt registry <alias> <command>` runs an account command against one
of your configured registries:

```sh
vlt registry main whoami
vlt registry main token list
vlt registry main access
vlt ping                     # check connectivity to every configured registry
```

Supported commands are `whoami`, `logout`, `login`, `token`, `access`,
`publish`, `unpublish`, `deprecate`, `dist-tag`, `profile` and `ping`.

## Gotchas

* **`vlt token add` needs an interactive terminal.** It reads the
  token with raw keyboard input, so piping it in
  (`echo $TOKEN | vlt token add`) fails with
  `stdin.setRawMode is not a function`. Use `VLT_TOKEN` in scripts.
* **`scoped-registries` keeps the `@`** — `scoped-registries.@acme`,
  unlike Yarn's `npmScopes`.
* The config key is `scoped-registries`, not `scope-registries`.
* `VLT_TOKEN` covers one registry only; scoped (and other) registries
  need their own `VLT_TOKEN_<registry>`.

# yarn (/registry/publishing/yarn)

Verified against **Yarn 4.18** (Yarn Modern / Berry). For Yarn Classic
1.x see [the bottom of this page](#yarn-classic-1x).

## Quick start

```sh
export VLT_TOKEN=<your token>

yarn config set npmRegistryServer "https://registry.vlt.io/acme/npm/"
yarn config set npmAlwaysAuth true
yarn config set npmAuthToken "\${VLT_TOKEN}"
```

Then `yarn install` as usual.

## The config file

Yarn keeps everything in `.yarnrc.yml` in your project root:

```yaml
# all public npm packages come from your account mirror
npmRegistryServer: 'https://registry.vlt.io/acme/npm/'
npmAlwaysAuth: true
npmAuthToken: '${VLT_TOKEN}'

# your own packages come from your main registry
npmScopes:
  acme:
    npmRegistryServer: 'https://registry.vlt.io/acme/main/'
    npmPublishRegistry: 'https://registry.vlt.io/acme/main/'
    npmAlwaysAuth: true
    npmAuthToken: '${VLT_TOKEN}'
    npmMinimalAgeGate: 0
```

Notes on that file, all of which matter:

* Scope keys under `npmScopes` are written **without** the `@`:
  `acme`, not `@acme`.
* `npmAlwaysAuth: true` is required — Yarn otherwise omits the token
  on some requests and you get a `401`.
* `npmRegistryServer` is used for **installing**. `npmPublishRegistry`
  is used for **publishing**, and Yarn will not fall back to
  `npmRegistryServer` for publishes. Set both.
* `npmMinimalAgeGate: 0` is explained
  [below](#brand-new-versions-are-hidden-for-24-hours) — you want it
  on any registry you publish to.
* `${VLT_TOKEN}` is expanded from the environment, so this file is
  safe to commit.

## Install from the npm mirror

```sh
yarn add abbrev
```

To move an existing project onto the mirror:

```sh
rm -rf yarn.lock
yarn install
```

## Install from your `main` registry

```sh
yarn add @acme/my-package
```

### Public packages

Public packages on `main` install without a token — the registry alone
is enough, with no `npmAuthToken` or `npmAlwaysAuth`:

```yaml
npmScopes:
  acme:
    npmRegistryServer: 'https://registry.vlt.io/acme/main/'
    npmMinimalAgeGate: 0
```

## Publish to `main`

With `npmPublishRegistry` set as above:

```sh
yarn install       # yarn refuses to publish without an up-to-date lockfile
yarn npm publish
```

Add `--access public` for a package anyone can install.

The `yarn install` is not optional. Without a lockfile entry for your
own workspace, `yarn npm publish` aborts before it uploads anything:

```
Internal Error: @acme/my-package@workspace:.: This package doesn't seem to be
present in your lockfile; run "yarn install" to update the lockfile
```

With a personal token, every publish returns a one-time-password
challenge with a `vlt.io` URL — open it, approve, re-run. A **service
token** skips the prompt and is what you want in CI; see
[CI & automation](/registry/publishing/ci).

You can also target the registry from `package.json` instead of
`.yarnrc.yml`:

```json
{
  "name": "@acme/my-package",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://registry.vlt.io/acme/main/"
  }
}
```

## Log in instead of using a token

```sh
yarn npm login --web-login --always-auth
```

**Requires Yarn 4.12.0 or newer.** The `--web-login` flag is mandatory
here: without it `yarn npm login` prompts for a username and password,
which this registry does **not** support. Yarn only attempts web login
automatically for npmjs itself.

Useful variants:

```sh
yarn npm login --web-login --scope acme     # log in to the scope's registry
yarn npm login --web-login --publish        # log in to the publish registry
```

`yarn npm login` writes the token to your **home** config, never to
the project.

On **Yarn 4.0–4.11, or Yarn 2 and 3**, there is no web login at all.
Either upgrade (`yarn set version stable`) or put a token in
`.yarnrc.yml` as shown above.

If Yarn ever drops to a `Username:` prompt, the web handshake failed
and it fell back to the legacy flow — that is not a prompt you can
satisfy.

## Brand-new versions are hidden for 24 hours

Yarn 4 ships a supply-chain protection called `npmMinimalAgeGate`,
defaulting to &#x2A;*1440 minutes (24 hours)**. Any version published more
recently than that is skipped, so right after your first publish you
get:

```
YN0016: The version for tag "latest" is quarantined, and no lower version is available
```

Set it to `0` for your own registry:

```yaml
npmScopes:
  acme:
    npmMinimalAgeGate: 0
```

**It must go under `npmScopes.<scope>`.** A top-level
`npmMinimalAgeGate: 0` is ignored for scoped packages — verified.
Scoping it this way also keeps the protection switched on for
everything coming from the public npm mirror, which is what you want.

## Selecting a Yarn version

Use **4.12.0 or newer** — that is the floor for browser login.
`stable` is well past it:

```sh
corepack use yarn@stable     # records packageManager in package.json
```

or set it directly:

```json
{ "packageManager": "yarn@4.18.0" }
```

`yarn set version stable` does the same thing without corepack. 4.18.0
is the current release; there is no Yarn 5.

## Gotchas

* **`npmPublishRegistry` is mandatory for publishing.** With only
  `npmRegistryServer` set, `yarn npm publish` goes to
  `registry.yarnpkg.com` and fails with a 404.
* **Run `yarn install` before `yarn npm publish`**, or Yarn errors
  with `This package doesn't seem to be present in your lockfile`.
* **`npmMinimalAgeGate` must be per-scope.** See above.
* **An `npmScopes` entry without `npmRegistryServer` silently routes
  that scope to `registry.yarnpkg.com`.** The key defaults to npmjs
  rather than inheriting your top-level `npmRegistryServer`, so a
  scope block that sets only `npmAuthToken` will fetch from the wrong
  registry and report `Package not found`. Always set
  `npmRegistryServer` inside every scope block.
* **`npmAlwaysAuth` must live in the same block as the token.** A
  top-level `npmAlwaysAuth: true` is ignored when the token comes from
  an `npmScopes` or `npmRegistries` entry.
* **Yarn Berry does not read `.npmrc` at all.** If you are migrating
  from npm, the token in your `.npmrc` is invisible to Yarn 2+; it
  must be in `.yarnrc.yml`.
* **An unset variable is a hard error**, unlike npm: `${VLT_TOKEN}`
  with nothing set fails with `Environment variable not found`. Use
  `${VLT_TOKEN:-}` if you want it to fall back to empty. There is no
  `${VAR:+...}` form.
* `yarn config set` prints `Successfully set ... to undefined` when
  writing nested `npmRegistries[...]` keys. The file is written
  correctly — the message is just wrong.
* Yarn blocks plain `http://` registries unless listed in
  `unsafeHttpWhitelist`. Not an issue for `https://registry.vlt.io/`,
  but it will bite you against a local registry.
* Scope keys in `npmScopes` omit the leading `@`.

## Yarn Classic (1.x)

Yarn 1 is end-of-life; prefer Yarn 4. If you must:

```sh
yarn config set registry https://registry.vlt.io/acme/npm/
yarn config set @acme:registry https://registry.vlt.io/acme/main/
```

Yarn Classic reads auth tokens from `.npmrc`, so add:

```ini
//registry.vlt.io/acme/npm/:_authToken=${VLT_TOKEN}
//registry.vlt.io/acme/main/:_authToken=${VLT_TOKEN}
```

# Authentication & Tokens (/registry/tokens)

Every request to the vlt registry is authenticated with a bearer
token, apart from the endpoints used by the login flow itself. Tokens
belong to an **account** — one token works for both of the account's
registries (`main` and `npm`).

## Log in from the CLI

The registry supports the npm web login flow. Point your client at
your registry and log in:

Terminal:

```bash
$ vlt login --registry=https://registry.vlt.io/acme/main/
```

Your browser opens vlt.io to confirm the login, and the client stores
the resulting token in the vlt keychain. npm works the same way:

Terminal:

```bash
$ npm login --auth-type=web --registry=https://registry.vlt.io/acme/main/
```

See [Authentication](/client/auth) for everything the vlt client
supports around credential storage and identities.

## Personal and service tokens

There are two kinds of tokens:

* **Personal tokens** are bound to your user. Writes made with a
  personal token are subject to the account's two-factor (OTP)
  requirement. Logging in from the CLI mints a personal token scoped
  to `package:read` and `package:write`.
* **Service tokens** belong to the account rather than a person. They
  are meant for CI and automation, and they are not subject to OTP
  prompts. Creating service tokens requires an owner or admin role.

Tokens start with the `vlt_1_` prefix. The registry stores only a hash
of each token, so the full value is shown once at creation — copy it
then.

## Privileges and expiry

Every token carries a set of privileges, such as `package:read`,
`package:write`, `token:read`, or `member:write`. A request succeeds
only if **both** the token and the requesting user's account role
grant the privilege, so a read-only token stays read-only no matter
who uses it, and a token can never grant more than its creator's own
role allows.

For example, a CI token that only installs packages needs just
`package:read`; a publish token needs `package:write` as well.

Tokens can optionally be given an expiration date, after which they
stop working. Expired and revoked tokens are rejected on every
request.

## Managing tokens

Create, inspect, and revoke tokens from your account's token settings
in the [dashboard](https://www.vlt.io/). Members can create and revoke
their own personal tokens; owners and admins can also manage service
tokens.

The dashboard is the easiest place to manage tokens, but the npm
`token` subcommands (`npm token list`, `npm token create`) also work
against your registry. `pnpm token` does not — pnpm reports `Not
  implemented in pnpm. Use the npm CLI directly`.

## Using tokens in CI

Provide a token through the environment rather than a config file. The
portable form is `VLT_TOKEN` alongside `VLT_REGISTRY`:

Terminal:

```bash
VLT_REGISTRY=https://registry.vlt.io/acme/main/ \\
VLT_TOKEN="<service token>" vlt install
```

To authenticate more than one registry, set a per-registry
`VLT_TOKEN_*` variable for each configured registry, named after its
URL with the trailing `/` dropped and each run of non-alphanumeric
characters replaced by `_`:

Terminal:

```bash
VLT_TOKEN_https_registry_vlt_io_acme_npm="<service token>" \\
VLT_TOKEN_https_registry_vlt_io_acme_main="<service token>" \\
vlt install
```

This applies to `registries` and `scoped-registries` alike.

See
[Authentication — CI](/client/auth#ci-and-other-headless-environments)
for details, and [CI & automation](/registry/publishing/ci) for the
publish workflow.

With npm, use the standard `.npmrc` auth entry, ideally referencing an
environment variable:

.npmrc:

```ini
@acme:registry=https://registry.vlt.io/acme/main/
//registry.vlt.io/acme/main/:_authToken=${NPM_TOKEN}
```

That form works for npm — an unset variable is sent as the literal
string, so a missing secret fails like a bad token. &#x2A;*pnpm ignores
`${...}` in a project `.npmrc`**; see
[pnpm in CI](/registry/publishing/ci#pnpm-needs-a-different-approach).
Never commit a literal token, or have CI write one into the project
`.npmrc`. For which tool reads what, Vercel and agent sandboxes, see
[CI & automation](/registry/publishing/ci#who-reads-what).

## Removing credentials

* `vlt logout --registry=...` removes the token from your keychain,
  under every registry key holding it (e.g. both `npm` and `main`).
  Revoke the token itself in the dashboard.
* `vlt token rm` removes a token from your local keychain only.
* Revoking a token in the dashboard invalidates it everywhere,
  immediately.

# Using Packages (/registry/using-packages)

Once your package manager is
[set up](/registry#set-up-your-package-manager), your project pulls
everything through vlt: public packages resolve through your account's
`npm` mirror, and packages under your account scope (`@acme/...`)
resolve from your private `main` registry.

## Public packages

Your `npm` registry is a read-only mirror of the public npm registry,
populated from `registry.npmjs.org`. With your default registry
pointed at it, installs work exactly as they always have — same
package names, same versions — while your projects and CI share one
consistent source.

## Private packages

Packages scoped to your account live in your `main` registry, and the
scope mapping from setup routes them there automatically. Install them
like any other dependency:

Terminal:

```bash
$ vlt install @acme/utils
```

Terminal:

```bash
$ npm install @acme/utils
```

Terminal:

```bash
$ pnpm add @acme/utils
```

Terminal:

```bash
$ yarn add @acme/utils
```

Terminal:

```bash
$ bun add @acme/utils
```

Terminal:

```bash
$ deno add npm:@acme/utils
```

Every member of your account can install its packages — see
[Members & Access Control](/registry/access) for how read access is
granted.

## Versions and dist-tags

The registry follows standard npm semantics, so version ranges,
`latest`, and custom dist-tags behave the way you expect:

Terminal:

```bash
$ vlt install @acme/utils@beta
```

Deprecation notices set by publishers surface as warnings when a
deprecated version is installed.

## Installing in CI

Create a **service token** with just the `package:read` privilege — a
read-only token can install but never publish, no matter where it
leaks. Provide it through the environment:

Terminal:

```bash
VLT_TOKEN_https_registry_vlt_io_acme_npm="<service token>" \\
VLT_TOKEN_https_registry_vlt_io_acme_main="<service token>" \\
vlt install
```

The same token works for both registries because tokens belong to your
account. See [Authentication & Tokens](/registry/tokens) for creating
tokens and
[Authentication — CI](/client/auth#ci-and-other-headless-environments)
for how the environment variables are named.

## Browsing packages

The dashboard's **Registries** section lets you browse and search both
registries: the npm mirror, and your private packages under your
account.

# Use cases (/use-cases)

The vlt platform was created with the needs of both open source
maintainers and professional development teams in mind.

1. **Private registry for internal packages** — Use the vlt Registry
   to share private packages within your org, while keeping them out
   of the public npm registry.

2. **Ensure deliverability of your software and own your pipeline** —
   The vlt Registry provides high-availability for critical
   open-source packages and libraries used by thousands of developers.

3. **Resiliency** — The vlt Registry infrastructure ensures your
   mirror stays up even when the npm public registry is down.

4. **Multi-registry workflows** — Configure named registries in the
   `vlt` CLI to pull from the public npm registry, a private mirror,
   and an internal registry simultaneously, while also keeping the
   ability to route specific scopes (e.g. `@internal/`) to the right
   source.

5. **Supply chain protection for your team** — vlt offers security
   scanning of dependencies. Run `vlt query ':malware'` with our CLI
   to detect malware, vulnerabilities, and license issues in your dep
   graph via Socket integration, without leaving the CLI. Stick with
   the vlt registry to also benefit from a registry that is safe by
   default.

6. **A JavaScript package manager client for JavaScript developers** —
   Our package manager internals are all published as open source
   packages under the `@vltpkg` scope on the npm public registry
   providing an SDK that works just the same as the real CLI app. Want
   to write a personalized script to help your team build a customized
   pipeline? Just point your agents at our SKILL files and get a
   script that you can also read and review. Do you prefer writing it
   yourself? All packages have conventional README.md files made for
   humans to read, just like the good old days.

# Why vlt? (/why-vlt)

Most registries treat your packages as files to store. vlt treats them
as a dependency graph to understand, and builds everything else on
that.

That's what makes vlt the package registry built for JavaScript:
install the same packages in less time, block malicious dependencies
before they reach your builds, publish privately, and query every
relationship in your graph.

## A new package registry

JavaScript packages aren't just files. They form dependency graphs
that decide what runs on every install, build, and deployment, yet
most registries were built to
[store files, not understand those relationships](https://www.vlt.io/blog/the-massive-hole-in-the-npm-ecosystem).
When the registry understands the graph, speed, security, and
observability become properties of the infrastructure, not features
bolted onto a file store.

> We're doing this because we expect more from the systems we've
> always counted on to host and distribute our software.

The team behind vlt has built and maintained the tools the ecosystem
runs on for years. vlt is where that experience goes next.

## Move fast without changing your tools

vlt serves npm-compatible packages through infrastructure tuned for
JavaScript metadata and install patterns, cutting download size, cache
misses, and CI time.

* **Real-project benchmarks.** Our benchmarks measure against popular
  project setups such as Next, Vue, and Svelte apps.
* **Faster clean installs.** vlt serves the same packages 3–6x faster
  than AWS CodeArtifact and 4–9x faster than GitHub Packages, and
  leads npm on typical framework apps (Astro 1.7x, Svelte 1.6x, Vue
  1.25x). Numbers move daily; see the
  [live benchmarks](https://benchmarks.vlt.sh/#/registries/average).
* **Slimmer packuments.** 76% smaller than the ten thousand
  most-downloaded npm packages, bloat big enough to have
  [blocked a library's releases for a month](https://www.vlt.io/blog/packument-size-limits).

## Stop unsafe packages before they reach your builds

Every public package request passes through a security layer that
flags known malware and vulnerabilities before the package is served.

It matters more every release: despite 63% download growth,
[Sonatype's 2026 supply-chain report](https://www.sonatype.com/state-of-the-software-supply-chain/introduction)
counted 838,778 packages published with a CVSS 9.0+ score.[^1]

### Reproducibility, not just provenance

[vlt/reproduce](https://github.com/vltpkg/reproduce) downloads,
rebuilds, and compares packages against their exact source commits to
confirm an artifact matches its source. Not security theatre, but
[verifiable outcomes](https://www.vlt.io/blog/reproducibility).

## Understand every dependency

Query your fully resolved dependency graph with selectors built for
JavaScript:

* **Explore.** Browse package and ecosystem relationships.
* **Trace.** See why and how a dependency resolved.
* **Query.** Match packages with Dependency Selector Syntax (DSS),
  including
  [security insights from Socket](https://www.vlt.io/blog/insights-selectors).
* **Control.** Turn queries into
  [enforceable CI rules](https://github.com/vltpkg/policies) and
  define custom
  [graph transformations](https://www.vlt.io/blog/introducing-graph-modifiers)
  to your project.

## Built in the open

vlt's stack is open source, built by a team that has maintained
ecosystem projects for years: the vlt CLI and its packages,
[vsr](https://github.com/vltpkg/vsr) (a serverless npm-compatible
registry), and [reproduce](https://github.com/vltpkg/reproduce).

## The private registry built for JavaScript teams

[Publish scoped and private packages](https://www.vlt.io/blog/pack-publish-version),
manage organizations and access, and give every developer and CI
environment one consistent source for public and private dependencies.

vlt is a strong fit if you publish packages others depend on, serve
dependencies at scale, need risky scripts contained by default, or
want every dependency accounted for from local installs through CI.

See how it holds up on your own dependencies.
[Start publishing.](https://www.vlt.io/sign-up)

[^1]: In 2025, attackers published \~455,000 malicious npm packages. In
    September 2025, phishing and wallet-hijacking campaigns targeted
    maintainers of packages with 2.6 billion daily downloads, and
    self-propagating worms compromised 500-800 packages across two
    waves, breaching 25,000+ repositories and exposing 40,000+
    credentials across AWS, Azure, and GCP.

# Migrate a repository to the vlt registry (/skills/vlt-registry-migration/SKILL.md)

Docs index: [llms.txt](https://docs.vlt.sh/llms.txt). Every docs page
is Markdown at its URL + `.md`; read the linked page before editing
config. Examples use the account slug `acme`; replace it with the
user's.

## Rules

- Confirm with the user before creating or revoking tokens, changing
  access, or publishing.
- Never commit or print a literal token, and never write one into a
  project config file.
- Change only registry routing and auth. Keep scripts, dependencies
  and `packageManager` unless the user agrees.
- Confirm before deleting or regenerating a lockfile.

## 1. Gather

- Account slug and private scope(s), e.g. `@acme`.
- Package manager and version (`packageManager`, lockfile); Turborepo?
  (see [Known limitations](#known-limitations)).
- Where installs run: laptops, CI provider, Vercel, coding-agent
  sandboxes.

Each account has two registries:

- `https://registry.vlt.io/acme/npm/`: npm mirror. Make it the default
  registry. Always needs a token, even for public packages.
- `https://registry.vlt.io/acme/main/`: the account's own packages.
  Map the scope to it.

Accounts ([sign up](https://docs.vlt.sh/registry.md#sign-up),
[tokens](https://docs.vlt.sh/registry/tokens.md#personal-and-service-tokens)):
invite each developer, who logs in (or creates a personal token). CI,
Vercel and each agent sandbox get their own `package:read` service
token, created by an owner or admin (add `package:write` only to
publish).

## 2. Route installs

Commit the routing (auth is step 4):

| Tool            | File          | Default → mirror              | `@acme` → `main`                   |
| --------------- | ------------- | ----------------------------- | ---------------------------------- |
| npm, pnpm, deno | `.npmrc`      | `registry=`                   | `@acme:registry=`                  |
| yarn 2+         | `.yarnrc.yml` | `npmRegistryServer`           | `npmScopes.acme.npmRegistryServer` |
| bun             | `bunfig.toml` | `[install] registry`          | `[install.scopes] acme`            |
| vlt             | `vlt.json`    | `registry` + `registries.npm` | `scoped-registries` `"@acme"`      |

Full config:
[vlt](https://docs.vlt.sh/registry/publishing/vlt.md#manual-configuration),
[npm](https://docs.vlt.sh/registry/publishing/npm.md#the-config-file),
[pnpm](https://docs.vlt.sh/registry/publishing/pnpm.md#the-config-file),
[yarn](https://docs.vlt.sh/registry/publishing/yarn.md#the-config-file),
[bun](https://docs.vlt.sh/registry/publishing/bun.md#quick-start),
[deno](https://docs.vlt.sh/registry/publishing/deno.md#quick-start).

- yarn: `npmScopes` keys drop the `@`; Classic 1.x uses `.npmrc`.
- vlt: write `vlt.json` with `vlt config set` (vlt guide).
  `vlt setup acme` only writes the `npm` / `main` aliases to user
  config.
- pnpm < 11.10 ignores `registry` in `pnpm-workspace.yaml` for
  installs: keep `registry` and `@acme:registry` in `.npmrc`
  (`pnpm config set … --location=project` writes it).
  `pnpm-workspace.yaml` can't hold auth either.

## 3. Lockfile

- npm: keep `package-lock.json`; `npm install` fetches its
  `registry.npmjs.org` entries from the mirror (other hosts aren't
  rewritten).
- pnpm: keep `pnpm-lock.yaml` (no tarball URLs); `pnpm install`.
- vlt: a kept `vlt-lock.json` still fetches from the old registry
  ([#1579](https://github.com/vltpkg/vltpkg/issues/1579)):
  `rm -rf vlt-lock.json node_modules && vlt install`.
- yarn, bun, deno: regenerate `yarn.lock` / `bun.lock` / `deno.lock`
  per their guide.

## 4. Auth: who reads what

Only the vlt CLI reads `VLT_TOKEN` itself. Other tools see the secret
only through an auth line that references it, so setting the secret
alone sends no credentials.

| Tool          | Auth from                                            | Token reference in committed project file |
| ------------- | ---------------------------------------------------- | ----------------------------------------- |
| vlt           | keychain or env vars (below)                         | n/a, `.npmrc` not read                    |
| npm, npx      | `.npmrc`                                             | expanded                                  |
| pnpm          | `pnpm login`, `~/.npmrc`, or `pnpm_config_…` env var | **ignored** (11.5.3+)                     |
| yarn          | `.yarnrc.yml` (Classic: `.npmrc`)                    | expanded                                  |
| bun           | `bunfig.toml` (`$VLT_TOKEN`) or `.npmrc`             | expanded                                  |
| deno          | `.npmrc`                                             | expanded                                  |
| Vercel builds | `.npmrc` written from `NPM_RC`                       | see step 5                                |

- Laptops: personal token per developer. Export `VLT_TOKEN` where
  committed files reference it; pnpm: `pnpm login --registry=<url>`
  per registry URL (`--scope=@acme` for `main`); vlt:
  `vlt setup acme`.
- npm, yarn, bun, deno: commit auth lines for both registry URLs
  referencing `${VLT_TOKEN}` (`$VLT_TOKEN` in `bunfig.toml`; yarn also
  `npmAlwaysAuth: true`). npm, bun and deno send an unset var
  literally, which fails like a bad token.
- pnpm: commit routing only. In CI use one of
  ([pnpm in CI](https://docs.vlt.sh/registry/publishing/ci.md#pnpm-needs-a-different-approach)):
  - `env "pnpm_config_//registry.vlt.io/acme/npm/:_authToken=$VLT_TOKEN" pnpm install --frozen-lockfile`
    (pnpm 11.6.0+; one var per registry URL);
  - a step appending
    `//registry.vlt.io/acme/npm/:_authToken=${VLT_TOKEN}` and the same
    `main` line to user-level `~/.npmrc` with a quoted heredoc
    (`<<'EOF'` keeps `${VLT_TOKEN}` literal; pnpm expands it there);
  - `PNPM_CONFIG_NPMRC_AUTH_FILE=<auth file outside the repo>`.
- vlt: per-registry
  `VLT_TOKEN_<registry URL, trailing / dropped, each run of non-alphanumerics → _>`,
  e.g. `VLT_TOKEN_https_registry_vlt_io_acme_npm` and
  `VLT_TOKEN_https_registry_vlt_io_acme_main`. See
  [Authentication](https://docs.vlt.sh/client/auth.md#ci-and-other-headless-environments).

## 5. CI and hosted environments

Details:
[CI & automation](https://docs.vlt.sh/registry/publishing/ci.md#who-reads-what).

- [GitHub Actions](https://docs.vlt.sh/registry/publishing/ci.md#github-actions):
  secret `VLT_TOKEN` in the job `env` (plus pnpm / vlt auth from step
  4); install with the frozen-lockfile flag.
- [Vercel](https://docs.vlt.sh/registry/publishing/ci.md#vercel):
  ignores `VLT_TOKEN`. Set `NPM_RC` (not `NPM_TOKEN`) to the routing
  and auth lines with a `package:read` service token, and keep a
  `registry.npmjs.org` line: Vercel installs its runtimes from it. Set
  multi-line values with the Vercel CLI.
- [Coding-agent sandboxes](https://docs.vlt.sh/registry/publishing/ci.md#coding-agent-sandboxes)
  (Cursor, Claude Code, Devin, Codespaces, …): treat each like a CI
  runner. Own service token in that environment's secrets, committed
  routing, auth for both registry URLs as in step 4.
- [Publishing from CI](https://docs.vlt.sh/registry/publishing/ci.md#publishing-from-ci):
  service token with `package:write`; a personal token fails with
  `EOTP`.

## Known limitations

- Turborepo doesn't support vlt as a package manager:
  `"packageManager": "vlt@…"` fails with
  `Invalid packageManager field`, and turbo requires `packageManager`
  or `devEngines.packageManager` (seen on turbo 2.10). In Turborepo
  repos keep npm, pnpm, yarn or bun as `packageManager` and use the
  vlt registry through that tool's config
  ([#1851](https://github.com/vltpkg/vltpkg/issues/1851)).

## Verify

- `npm config get registry` / `pnpm config get registry` print the
  mirror. pnpm < 11.10 still installs from npmjs.org if `registry` is
  only in `pnpm-workspace.yaml`, even when this passes: move it to
  `.npmrc`.
- `vlt ping` checks the default registry and `registries` aliases (not
  `scoped-registries`). Read its output: it exits 0 even when a ping
  fails.
- Clean frozen-lockfile install, locally and in CI: no `401`.

## Troubleshooting

| Symptom                                                     | Cause                                                                                                                    |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `401` / `No authorization header was set`                   | token not reaching the tool (step 4): pnpm `${VLT_TOKEN}` in a project `.npmrc`, or secret unset in that job             |
| `EOTP` when publishing from CI                              | personal token; use a service token                                                                                      |
| vlt still fetches from `registry.npmjs.org`                 | kept `vlt-lock.json` (step 3)                                                                                            |
| pnpm 12 `no version found for the latest tag` on the mirror | mirror bug on pnpm 12: [pnpm guide](https://docs.vlt.sh/registry/publishing/pnpm.md) pins `pnpm@11.26.0` (confirm first) |