lpm catalog

lpm catalog list
lpm catalog list --unused
lpm catalog show --resolved

lpm catalog inspects the version catalogs declared by the workspace root. Use it to find unused catalog pins before cleanup, or to verify which catalog references were resolved into lpm.lock.

Catalogs are declared in root package.json > catalogs or in pnpm-style pnpm-workspace.yaml > catalog / catalogs. Root and workspace-member manifests reference them with "catalog:" for the default catalog or "catalog:<name>" for a named catalog.

Examples

lpm catalog list                 # every declared catalog entry
lpm catalog list --unused        # only entries no manifest references
lpm catalog show --resolved      # resolved catalog snapshots from lpm.lock
lpm catalog show --resolved --json

List Declared Entries

lpm catalog list

list reads the root catalog declarations and scans the root package plus every workspace member for catalog: references in dependency sections. Human output prints one row per entry:

default react ^18.2.0 used
default react-dom ^18.2.0 used
testing vitest ^1.0.0 unused

Use --unused before enabling catalog cleanup:

lpm catalog list --unused

--unused filters out entries that are still referenced. If none remain, LPM prints No unused catalog entries.

Show Resolved Snapshots

lpm catalog show --resolved

show --resolved reads catalog snapshots from lpm.lock. These snapshots record the catalog entry, the saved catalog reference, the resolved version, and the original catalog range:

default react catalog: -> 18.2.0 (^18.2.0)
testing vitest catalog:testing -> 1.6.1 (^1.0.0)

lpm catalog show currently requires --resolved. If a manifest references a catalog entry that is missing from lpm.lock, LPM exits non-zero and asks you to run lpm install so the lockfile snapshot cannot look falsely clean.

JSON Output

Pass the global --json flag for automation:

lpm catalog list --unused --json

{
  "success": true,
  "mode": "unused",
  "count": 1,
  "used_count": 2,
  "unused_count": 1,
  "entries": [
    {
      "catalog": "testing",
      "package": "vitest",
      "specifier": "^1.0.0",
      "used": false
    }
  ]
}

lpm catalog show --resolved --json

{
  "success": true,
  "count": 1,
  "entries": [
    {
      "catalog": "default",
      "package": "react",
      "specifier": "^18.2.0",
      "version": "18.2.0",
      "reference": "catalog:"
    }
  ]
}

Cleanup Policy

By default, LPM preserves unused catalog entries exactly as written. Set package.json > lpm.cleanupUnusedCatalogs = true to prune unreferenced root package.json > catalogs entries after successful installs. In pnpm-style workspaces, pnpm-workspace.yaml > cleanupUnusedCatalogs: true does the same for pnpm-workspace.yaml > catalog / catalogs, unless package.json > lpm.cleanupUnusedCatalogs explicitly overrides it.

Run lpm catalog list --unused first when you want a dry inspection before the next install mutates catalog declarations.

Flags

Plus the global flags. --json emits structured envelopes for both subcommands.

See also

• Workspaces - catalog declarations and member references
• Save policy - saving dependencies as catalog: references
• lpm install --catalog - force a catalog save for one invocation
• package.json > lpm - catalog fields and cleanup policy