lpm catalog

Use lpm catalog to inspect shared dependency versions before cleanup or to read the versions that an install selected.

lpm catalog <COMMAND>
lpm catalog list [--unused]
lpm catalog show --resolved

Quickstart

# List declared catalog entries and their usage
lpm catalog list

# Inspect entries that no current manifest references
lpm catalog list --unused

# Read the saved catalog resolutions
lpm catalog show --resolved

These commands do not install packages, contact registries, or change the project. From a workspace member, they inspect the workspace root and its members. Outside a workspace, they inspect the current directory.

Declare catalogs

Put shared ranges in the root package.json. Reference each range from a dependency section:

{
  "catalogs": {
    "default": {
      "react": "^19.0.0"
    },
    "testing": {
      "vitest": "^3.0.0"
    }
  },
  "dependencies": {
    "react": "catalog:"
  },
  "devDependencies": {
    "vitest": "catalog:testing"
  }
}

catalog: and catalog:default refer to the default catalog. catalog:<name> selects a named catalog. Workspace members use the root declarations. Member-level catalog declarations do not replace them.

pnpm-style workspaces can declare the same ranges in pnpm-workspace.yaml:

packages:
  - packages/*
catalog:
  react: ^19.0.0
catalogs:
  testing:
    vitest: ^3.0.0

For duplicate entries, root package.json > catalogs takes precedence over the YAML declarations. Catalogs select version ranges. Registry routing still comes from registry configuration.

Add an inspection task

lpm.json has no catalog configuration block. Use a task for repeatable inspection:

{
  "tasks": {
    "catalog-unused": {
      "command": "lpm catalog list --unused",
      "cache": false
    }
  }
}

lpm run catalog-unused
lpm run catalog-unused -- --json

The task reads current manifests on every run. An explicit task command takes precedence over a package script with the same name. See Tasks for task configuration.

Inspect usage

lpm catalog list
lpm catalog list --unused --json

Usage includes references in regular, development, optional, and peer dependencies. It also includes supported catalog targets in overrides, resolutions, and lpm.overrides. An entry counts as used even when an install does not select it.

Human output contains the catalog, package, range, and usage:

default react ^19.0.0 used
testing vitest ^3.0.0 used

With --json, entries contains the selected rows. count is their number. used_count and unused_count count all declared entries, even with --unused. An empty result succeeds. The command does not fail a CI job merely because unused entries exist.

Read saved versions

lpm catalog show --resolved
lpm catalog show --resolved --json

Each result contains catalog, package, specifier, version, and reference:

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

The command requires snapshots for effective direct catalog dependencies in each project recorded by the lockfile. Optional declarations require a snapshot only when the lockfile records a selected dependency. A missing optional package, a peer-only declaration, or an unused override does not require a snapshot. Applied override snapshots remain visible.

For duplicate dependency names, optional dependencies take precedence over regular dependencies, which take precedence over development dependencies. Workspace inspection checks each recorded member separately, then combines equal entries. Members outside a filtered lockfile's saved scope do not require snapshots.

Different saved ranges or versions for the same catalog entry cause an error. Equivalent default references combine as catalog:. This normalization does not change the lockfile.

This command reports saved resolutions. It does not resolve newer versions or compare every saved range with current catalog declarations. A selected optional package can remain in the lockfile even when the current platform cannot install it.

Recover from a missing snapshot

If the lockfile is missing, unreadable, or lacks a required snapshot, refresh it:

lpm install
lpm catalog show --resolved

lpm install can also reconcile conflicting workspace snapshots. lpm catalog show requires --resolved. Both inspection commands support non-interactive use without --yes.

Remove unused declarations

By default, installs preserve unused catalog entries. Inspect them before you enable automatic cleanup:

lpm catalog list --unused

{
  "lpm": {
    "cleanupUnusedCatalogs": true
  }
}

After a successful install, this policy removes unreferenced root catalog entries. In pnpm-style workspaces, cleanupUnusedCatalogs: true in pnpm-workspace.yaml also enables cleanup. An explicit package.json > lpm.cleanupUnusedCatalogs value takes precedence. Set it to false to disable cleanup. There is no catalog command flag for a one-run cleanup override.

Flags

See Global flags for shared options.

See also

• lpm install
• Workspaces
• Save policy
• package.json configuration
• Lockfile