lpm cache command reference

Inspect caches, clear reusable data, and preview or remove unused package-store entries.

lpm cache inspects reusable data and frees disk space. Use clean for temporary caches and prune for unused packages.

lpm cache <COMMAND>
lpm cache clean [CATEGORY]
lpm cache clear [CATEGORY]
lpm cache path [CATEGORY]
lpm cache status
lpm cache prune [--apply] [--max-age <MAX_AGE>] [--project <PATH>]

Quickstart

Inspect the task cache, then preview unused package data:

lpm cache status
lpm cache prune

After you review the preview, apply the cleanup:

lpm cache prune --apply

Choose an action

Action	Purpose
`path [CATEGORY]`	Print the cache root or one category path.
`clean [CATEGORY]`	Delete temporary cache data immediately. `clear` is an alias.
`status`	Show local task-cache usage and remote-cache status for the current directory.
`prune`	Preview unused package data and pending global-install cleanup.
`prune --apply`	Remove the eligible data without a confirmation prompt.

clean and path accept metadata, tasks, dlx, or mcp. Without a category, they select all four caches or the cache root.

The default cache root is ~/.lpm/cache/. The package store is separate at ~/.lpm/store/. LPM_HOME changes both locations, with the rest of the LPM home. See Environment variables.

Task-cache configuration

lpm.json configures task caching. It has no automatic cache-cleanup or prune policy.

This example caches a build that writes to dist/:

lpm.json

{
  "tasks": {
    "build": {
      "command": "tsc",
      "cache": true,
      "outputs": ["dist/**"],
      "inputs": ["src/**", "tsconfig.json", "package.json"],
      "cacheEnv": ["NODE_ENV"]
    }
  }
}

lpm run build
lpm cache status
lpm run build --no-cache

lpm run reuses matching task results. --no-cache disables task caching for one run.

Field	Effect
`cache`	Enable caching for this task. Default: `false`.
`outputs`	Files to save and restore. Caching requires a non-empty list.
`inputs`	Files that affect the cache key. An omitted or empty list uses the project defaults.
`cacheEnv`	Inherited environment variables that affect the cache key. Omit it to include all inherited variables. Use `[]` to exclude them.

Environment values loaded by the project remain cache inputs regardless of cacheEnv.

Add remoteCache.enabled: true to share task results through LPM.dev Registry. LPM_REMOTE_CACHE=0 disables remote caching for one process and keeps local caching available. See Remote task cache for authentication, team selection, input defaults, and upload policy.

Clear a cache

lpm cache path metadata
lpm cache clean metadata
lpm cache clean tasks
lpm cache clean dlx
lpm cache clean mcp

Category	Deleted data	Next use
`metadata`	Cached registry responses, and the version recorded for each Node executable.	Fetch package metadata again, and ask Node for its version again.
`tasks`	Local task results across projects.	Run the task again, or restore a remote result.
`dlx`	Cached packages for temporary commands.	Install the command again.
`mcp`	The verified MCP runtime.	Prepare the runtime again.

To clear all categories, run:

lpm cache clean

clean leaves the package store and remote task artifacts intact. It has no preview mode.

If a command uses the dlx or mcp cache, an all-category cleanup skips that category and reports it as in use. A targeted clean dlx or clean mcp fails. Stop the active command or editor connection, then retry.

Status

lpm cache status
lpm cache status --json

Status shows the shared local task-cache path and size. It reads lpm.json in the current directory for remote-cache configuration.

With remote caching enabled, status also shows service availability, usage, and quota. A remote lookup failure appears in remote.error without making the command fail.

Prune unused packages

lpm cache prune
lpm cache prune --max-age 30d
lpm cache prune --max-age 30d --apply

Prune inspects both supported store layouts, v2 and v3. The preview reports eligible paths and logical bytes. It leaves package contents and global recovery records unchanged.

With --apply, LPM CLI removes eligible entries and retries deferred cleanup from lpm uninstall -g. An incomplete cleanup returns a nonzero exit code.

What stays in the store

LPM CLI records installed projects in ~/.lpm/known-projects.json. Prune follows their node_modules links and keeps each reachable package, its dependencies, and its source data. These records include cached dlx tools and the managed MCP runtime. The prune --apply command waits until active tools and servers release the store. It does not use lockfiles as the root set.

A project with no node_modules does not retain packages through its lockfile alone. A later lpm install can download removed data again.

--max-age also retains recently referenced packages and their dependencies. It accepts positive whole numbers followed by d for days or h for hours. The age comes from package-store use, not the project registration date.

The age limit does not protect unrelated source objects that no retained package needs.

Build artifacts

Prune also cleans cached compatibility trees and native build artifacts. Incomplete artifacts are eligible immediately. Complete artifacts remain unless --max-age finds that their last use exceeds the limit.

This cleanup does not depend on the project registry. LPM CLI also removes associated lock files that no longer have a retained artifact or package entry.

Use one project as the root set

lpm cache prune --project ./my-app
lpm cache prune --project ./my-app --max-age 30d --apply

--project requires a directory. It replaces the registered project list with this one project's node_modules. It does not restrict cleanup to packages that the project previously installed.

Other projects do not protect their packages in this mode. If several projects share the store, use the default scan.

Recovery and incomplete state

If the project registry is missing or corrupt, prune skips package and source-data deletion. Artifact cleanup and deferred global-install cleanup remain available. The report identifies the registry problem.

Concurrent installs preserve each other's project registrations. A later install preserves an unusable registry instead of replacing it with an incomplete project list.

Before normal package pruning, restore a complete registry from backup. To rebuild it, move the damaged file aside and run lpm install in every project that shares the store. Include global tools that you still use. Do not apply package pruning until those registrations are complete.

If a preview reports unfinished global recovery, run lpm global list, then retry the preview.

Unreadable project directories, inconsistent package metadata, and redirected internal store directories stop prune. LPM CLI validates both store plans before it starts package deletion. Use lpm store verify to inspect store damage, then repair the affected installation.

Prune coordinates with installs through the store lock. A failure during deletion can leave completed cleanup in place. Correct the reported cause, then retry.

Non-interactive use

lpm cache clean metadata --json
lpm cache prune --max-age 30d --json
lpm cache prune --max-age 30d --apply --json

These commands do not prompt. --apply authorizes package deletion. For automation, inspect both the exit code and the JSON result.

Flags

Flag	Applies to	Effect
`--apply`	`prune`	Delete eligible entries and retry deferred global cleanup. Default: preview.
`--max-age <MAX_AGE>`	`prune`	Retain recent packages and dependencies. Evict complete artifacts older than this age. Examples: `30d`, `24h`.
`--project <PATH>`	`prune`	Use only this directory's installed packages as roots. Ignore the project registry.
`--json`	All actions	Emit structured output.

See Global flags for shared options.

JSON output

clean reports success, cleaned[], skipped[], total_bytes_freed, and total_freed. A busy dlx or MCP cache appears in skipped with reason: "in use".

status reports local.path, local.bytes, and local.size. Its remote object includes availability, usage, quota, and an error when a lookup fails.

The prune report includes:

Fields	Meaning
`success`, `applied`	Whether inspection or cleanup completed, and whether the command used `--apply`.
`projects_walked`, `registry_entries_dropped`	Project coverage and stale registrations. The preview does not rewrite the registry.
`link_entries_`, `object_entries_`	Counts and eligible package or source-object paths.
`cas_trees_total`, `cas_blobs_total`, `cas_materialized_total`	v3 source-data counts. Related `*_orphaned` arrays contain eligible paths.
`compat_islands_`, `build_artifacts_`	Artifact counts and eligible paths.
`bytes_freed_or_eligible`, `logical_bytes_freed_or_eligible`	Logical bytes eligible in the preview or removed during apply.
`observed_physical_bytes_freed`	Measured increase in free disk space, or `null` when unavailable.
`registry_missing`, `registry_corrupt`, `registry_corrupt_reason`	Why package-reachability cleanup was unavailable.
`tombstones_pending`, `tombstones_swept`, `tombstones_retained`, `tombstone_bytes_freed`	Deferred global-install cleanup results.
`tombstone_count_error`, `tombstone_sweep_error`	Errors that prevent inspection or cleanup of deferred global installs.

Logical bytes can exceed reclaimed disk space because files can share physical storage. Retained global tombstones make success false and produce exit code 1. A planning error can return a standard error envelope instead of a prune report.

lpm cache