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. Entries ever copied from (install scripts, store-linker=copy, a cache on another drive) stay: copies do not show use.

$ vlt cache prune-store

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 hardlink package files from it instead of unpacking tarballs again. By default (store-linker=auto) this happens on Linux only: macOS and Windows unpack tarballs as before, unless store-linker is set to hardlink or copy. Packages with install scripts are always copied.

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. 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 ever copied from.

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