lpm store

Use lpm store to inspect shared package data, diagnose corruption, or reset the store before a fresh install.

lpm store <COMMAND>
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

Store configuration

The default store path is ~/.lpm/store/. LPM_HOME changes the LPM home, the parent directory for LPM CLI data:

LPM_HOME=/srv/lpm lpm store path
LPM_HOME=/srv/lpm lpm store verify --deep

lpm.json has no store configuration. All projects that use the same LPM CLI home share its package data, security caches, and native-build artifacts. A different LPM home also has its own login and local env secrets; see Files LPM CLI creates.

lpm store path prints the path without creating the store or acquiring its lock.

Store versions

The three versions can exist together. Verification and cleaning always cover all three versions, regardless of LPM_STORE_VERSION.

To select a layout for an install, set LPM_STORE_VERSION for that command:

LPM_STORE_VERSION=v3 lpm install

The values v1, v2, and v3 select a version. The values 1, 2, and 3 are aliases.

An unset or empty value selects v2. An unknown value produces a warning and selects v2. LPM CLI never selects v3 automatically.

See Content-addressable store for the storage model.

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

Fast verification requires a nonempty, regular package.json file. It examines package directories, link metadata, object references, and v3 store metadata.

It rejects redirected store roots and package directories, including symbolic links and Windows junctions. It also rejects linked manifests.

Normal dependency links inside a package layout remain supported. Fast verification does not parse manifests or rehash package bytes.

Run a deep verification

Run this command from a project root:

lpm store verify --deep

Deep verification requires each package.json to contain a JSON object. If name or version is present, it must be a matching string.

Legacy manifests can omit those fields. Deep verification does not require them to exist.

Deep verification reads the applicable project lockfile, including a workspace member's view. It compares integrity through installed links and exact dependency relationships. It also rehashes v3 file blobs.

An unrelated store entry can share a package name and version but contain a different source. Verification does not compare that entry with another project's integrity.

Lockfile comparison requires installed project links that resolve to store entries. Legacy installs usually copy package files, so their comparison can remain partial. Missing integrity markers also leave records unexamined. Unreadable markers report an error.

If no applicable lpm.lock exists, LPM CLI skips the lockfile comparison. If an owning 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 with atomic replacement.

If a cache file is a symbolic link or hard link, replacement preserves the linked target. Redirected package directories fail verification before cache repair.

--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 verification finds corruption, it writes the JSON report and exits with status 1.

Errors that prevent enumeration, such as a redirected store root, return a command error before the detailed report.

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

For v1 and v2, deep verification compares saved integrity markers with the applicable lockfile. It does not recalculate integrity from extracted package bytes.

For v3, deep verification also rehashes stored file blobs. Oversized or unreadable source-integrity markers fail verification.

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,
  "lockfile_comparison": {
    "status": "complete",
    "packages": 12,
    "compared_packages": 12,
    "uncompared_packages": 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.

Lockfile comparison

Deep JSON includes lockfile_comparison:

complete describes coverage, not a successful result. Integrity mismatches still set success: false and exit with status 1.

partial does not mean that the unexamined packages are corrupt. For example, a lockfile-only export can lack the installed links needed for comparison.

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 MiB",
  "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 store directory and control files.

If a version root is a symbolic link or junction, cleaning removes the link and preserves its target. Dangling version-root links are also removed.

A redirected outer store root is rejected before LPM CLI creates a lock file or removes data.

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

If verification reports only security-cache differences, use lpm store verify --fix. These differences alone do not cause a failed exit status.

If package data is corrupt, inspect the reported paths. --fix cannot restore those files.

For corruption in unused data, preview lpm cache prune. For a complete reset, use the clean-and-install recipe above.

Concurrent operations

Verification and installs can overlap. Both hold a shared store lock, so a complete store clean waits for them. Verification is not a snapshot of concurrent package changes.

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