vlt cache

Usage:

$ vlt cache <command> [flags]

Work with vlt cache folders

Subcommands

add

Resolve the referenced package identifiers and ensure they are cached.

$ 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.

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

info

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

$ vlt cache info <key>

clean

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

$ 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.

$ 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.

$ vlt cache delete-before <date>

delete-all

Delete the entire cache folder to make vlt slower.

$ 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.

$ 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.

$ 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 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:

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

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

$ vlt cache add eslint@latest

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

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

Delete all entries created before Jan 1, 2025:

$ vlt cache delete-before 2025-01-01

Check every global store entry:

$ vlt cache verify --all