lpm store

Use lpm store to find, verify, or remove the shared package store on your computer.

lpm store path [--json]
lpm store verify [--deep] [--fix] [--json]
lpm store clean [--json]

The --deep and --fix flags must follow verify. LPM CLI rejects --deep and --fix with path or clean.

Quickstart

Run a fast verification of every store version:

lpm store verify

Choose an action

What the shared store does

LPM CLI saves package data in ~/.lpm/store/. Projects link to this shared data instead of keeping a separate package cache.

The store reduces repeat downloads and duplicate data across projects. It also contains package security caches and reusable native-build artifacts.

A store version identifies the layout of saved data. It does not identify a package version or the lpm.lock format.

Store versions

v1

The v1 store keeps each extracted package under ~/.lpm/store/v1/<name>@<version>/. It reuses matching package names and versions.

v1 is the legacy layout. Select it only for compatibility or downgrade testing.

v2

The v2 store keeps package content in shared objects. It also keeps separate link entries for different dependency graphs.

Two projects can reuse the same package content. Each project can still have the dependency layout that its lockfile requires.

v2 is the current default. An unset or empty LPM_STORE_VERSION value selects v2.

v3

The v3 store divides package trees into reusable file blobs. Tree and source records describe how LPM CLI reconstructs each package.

Identical files can share stored data across different packages. v3 retains the dependency-link model from v2.

v3 is experimental. LPM CLI never selects it automatically.

Select a version for an install

Set LPM_STORE_VERSION for the install command:

LPM_STORE_VERSION=v1 lpm install  # use the legacy layout
LPM_STORE_VERSION=v3 lpm install  # use the experimental layout

The values 1, 2, and 3 are aliases for v1, v2, and v3. An unknown value produces a warning and selects v2.

lpm.json cannot select a store version. The LPM_STORE_VERSION environment variable is the only current selector.

The three versions can exist at the same time. lpm store verify and lpm store clean always act on all three versions.

Recipes

Print the store path

lpm store path

If a diagnostic tool or script needs the active store root, use this command.

Run a fast verification

lpm store verify

The fast verification examines package directories, manifests, link metadata, object references, and v3 store metadata.

Run a deep verification

Run this command from a project root:

lpm store verify --deep

Deep verification parses each package.json. It compares package names and versions with their store entries.

If the current directory contains lpm.lock, deep verification compares its integrity values with the saved values. It also rehashes v3 file blobs.

If lpm.lock is absent, LPM CLI skips the lockfile comparison. If the file is invalid or unreadable, verification fails.

Refresh security caches

lpm store verify --fix

--fix implies deep verification. It refreshes missing or stale .lpm-security.json files.

--fix does not restore missing packages or repair manifests and integrity errors. LPM CLI reports these errors for separate recovery.

Use verification in CI

lpm store verify --deep --json > store-report.json

If LPM CLI finds corruption, it writes the JSON report and then exits with status 1.

Inspect v3 orphan counts

lpm store verify --json

Read the cas.orphaned_* fields for unreachable v3 data. Verification reports this data but does not remove it.

Preview orphan removal

lpm cache prune          # preview removals
lpm cache prune --apply  # apply the removal plan

lpm cache prune uses project references to retain required store entries. The preview does not remove data.

Verification levels

JSON output

Use the global --json flag with each action. Each action returns a different JSON object.

path output

lpm store path --json

{
  "success": true,
  "path": "/Users/you/.lpm/store"
}

verify output

This example shows a successful deep verification:

lpm store verify --deep --json

{
  "success": true,
  "check_kind": "lockfile_marker_consistency",
  "legacy_check_kind": "lockfile_marker_consistency",
  "bytes_integrity_recomputed": true,
  "entries_verified": 32,
  "verified": 32,
  "unique_coords": 30,
  "duplicated_entries": 2,
  "corrupted": 0,
  "issues": [],
  "securityMismatches": 1,
  "securityReanalyzed": 0,
  "cas": {
    "check_kind": "content_hash",
    "sources": 8,
    "trees": 8,
    "blobs": 240,
    "blobs_rehashed": 240,
    "materialized": 8,
    "orphaned_sources": 0,
    "orphaned_trees": 0,
    "orphaned_blobs": 0,
    "orphaned_materialized": 0,
    "blob_integrity_recomputed": true
  }
}

Verification fields

securityMismatches and securityReanalyzed appear only during deep verification. A security mismatch alone does not set success to false.

v3 cas fields

clean output

CAUTION: This command removes all store versions without a confirmation prompt.

lpm store clean --json

{
  "success": true,
  "removed_bytes": 1048576,
  "removed": "1.0 MB",
  "path": "/Users/you/.lpm/store/v1",
  "v1_path": "/Users/you/.lpm/store/v1",
  "v2_path": "/Users/you/.lpm/store/v2",
  "v3_path": "/Users/you/.lpm/store/v3",
  "v1_removed_bytes": 0,
  "v2_removed_bytes": 1048576,
  "v3_removed_bytes": 0
}

Reset the complete store

CAUTION: If you need a complete reset, use lpm store clean. The command removes all store versions without a confirmation prompt.

lpm store clean
lpm install

The clean action removes package data, link entries, security caches, and native-build artifacts. It retains the outer ~/.lpm/store/ directory.

The next install downloads or rebuilds the required packages. For normal cleanup, use the reference-aware lpm cache prune command.

If verification reports corruption, first run:

lpm cache prune --apply
lpm install

If the error remains, use lpm store clean for a complete reset.

Concurrent operations

Verification can run with other read-only store operations. If another command changes or removes store data, verification waits.

The clean action waits for installs and other store readers to finish. New store readers wait while a clean action is queued.

After one second, a waiting command prints Waiting for another lpm store operation to finish.... LPM CLI releases its locks automatically.

Flags

See the global flags.

See also

• lpm cache prune — preview or remove unreferenced store data
• Content-addressable store — understand the package storage model
• lpm rebuild — reuse or refresh native-build artifacts
• lpm doctor — inspect store health with other project checks