lpm install

lpm install [packages...]   # alias: lpm i

With no arguments, installs every dependency declared in package.json against the lockfile. At a workspace root, the same no-argument command installs every member and then the root. With one or more package names, resolves and adds them to package.json and installs them.

The typosquat guard is off by default. Enable it with lpm config typosquat --set on to check new direct dependency names before resolution. See Typosquat guard for interactive choices and project exceptions.

Project discovery

lpm install (and lpm i) discovers the project root the same way npm, pnpm, yarn, and bun do: it walks up from the current directory looking for the nearest ancestor package.json and treats that directory as the project root. All install side-effects — manifest edits, lpm.lock, lpm.lockb when representable, node_modules/ — land at the discovered root, not in the subdirectory you happened to run the command from.

In a workspace, bare lpm install from the workspace root recurses by default. Running it from a member remains local to that member. Use lpm install --recursive from a member when you want to widen the operation to its owning workspace.

If lpm i <pkg> runs in a directory with no package.json anywhere up the tree, LPM CLI auto-creates a minimal {"dependencies": {}} manifest in the current directory before installing — matching npm i <pkg>'s fresh-dir behavior. Bare lpm install (no package args) still errors when nothing can be found, since it has nothing to install against.

Examples

lpm install                   # install everything in package.json
lpm install zod               # add latest, save as ^x.y.z
lpm install zod@4.3.6         # add exact, save as 4.3.6
lpm install zod@^4.3.0        # add with explicit range
lpm install -D vitest         # save under devDependencies
lpm install --prod            # install production deps only
lpm install --omit=optional   # skip optionalDependencies
lpm install --catalog react   # save as "catalog:" when the default catalog matches
lpm install --catalog=ui react # save as "catalog:ui" when the named catalog matches
lpm install -g typescript     # install into ~/.lpm/global/
lpm install --offline         # never touch the network
lpm install --frozen-lockfile # fail if package.json and lpm.lock differ
lpm fetch                     # warm the store from lpm.lock, no node_modules
lpm tidy                      # find unused deps and undeclared imports
lpm install --force           # full re-install, bypass every fast path
lpm install --recursive       # install the owning workspace explicitly
lpm install --no-recursive    # install only the root project
lpm install --strict-peer-dependencies # fail on peer warnings/conflicts
lpm install --no-skills        # skip @lpm.dev package skills for this run
lpm install --verbose         # append per-phase timings + lockfile size
lpm install --json --timing   # include JSON timing diagnostics

Publication review

If an @lpm.dev package has published versions but no available latest version, the install stops before it changes project files. LPM CLI reports pending review, manual review, or processing when the registry provides that status. For pending review or processing, wait and retry the install. For manual review, open the package page to see its publication status. If the registry does not provide a status, LPM CLI reports that no latest version is available without guessing the cause.

With --json, this failure returns success: false and error_code: "publication_unavailable". See lpm publish for publication status and --wait.

Cached package access

During an online install, LPM CLI checks current access to every resolved @lpm.dev dependency, including transitive dependencies. This check also applies to cached packages and projects that are already up to date.

If a version is quarantined, unpublished, or unavailable, the install fails before it links packages or commits project changes. A revoked license or organization membership also prevents a cached install. With --json, a denied version returns error_code: "package_install_denied" and identifies the package and reason.

If access is denied, check the package page, license, and organization membership before you retry. If the registry cannot complete the check, the online install fails. --offline cannot detect registry changes and uses the existing offline behavior. Existing files remain on disk; access changes do not erase downloaded copies.

For an allowed deprecated version, LPM CLI shows the registry's deprecation message. With --json, the message appears in warnings, including when the project is already up to date. Lockfiles continue to pin the original package content.

--verbose footer

The global --verbose flag (no short form — -v is --version, matching npm / pnpm / yarn) appends a per-phase timing breakdown and the lockfile size beneath the ✓ Done line. Useful for profiling install runs without dropping to JSON.

✓ Done · installed 247 packages in 1.31s
  resolve: 383ms  fetch: 165ms  link: 2ms
  lpm.lock (247 packages) + lpm.lockb (4.2 KB)
  120 linked, 127 symlinked

Without --verbose, only the ✓ Done line is shown — keeps the slim output focused on what changed (+ pkg@version entries) and the success terminus.

JSON timing diagnostics

lpm install --json keeps the default success envelope lean and omits the timing object. Opt in when a tool or benchmark needs install timing diagnostics:

lpm install --json --timing
LPM_TIMING=1 lpm install --json
LPM_TIMING_DETAIL=1 lpm install --json
LPM_TIMING_DETAIL=trace lpm install --json

--timing and LPM_TIMING=1 include the coarse timing.waterfall object for setup, resolve, fetch, link, and tail attribution without the heavier detail tree. commit_wait_ms reports time a recursively installed workspace target spent waiting for its deterministic importer-commit turn. post_resolve_work_ms reports the remaining work between resolution and fetch; pre_fetch_ms remains as a compatibility alias for that value.

Timing objects declare their measurement scope. A standalone or per-workspace-target object uses scope: "target", phase_aggregation: "target_wall_clock", and work_is_cumulative: false. The recursive command root uses scope: "recursive_command" and reports summed target phase work under timing.work, serialized-importer waiting under timing.wait, and process-wide registry and resolver-policy metrics once under timing.process.

Install JSON also includes an explicit counts object that distinguishes resolved package rows, authoritative fetch candidates, store-reuse observations, newly created and reused linker entries, project-root symlinks, and bin links. Recursive roots mark these as aggregation: "sum_of_target_observations" because the same package can be observed by more than one workspace target.

LPM_TIMING_DETAIL=1 adds timing.detail with metadata request attribution by purpose, resolver wall/metadata/scheduler/CPU/policy counters, fetch-stage plan/cache/download attribution, cache-classification branch timing, v2 reusable-object validation counters, registry-signature/provenance timing, v2 link-task timing, link finalize substages, and tail writes such as lockfile and build-state persistence. LPM_TIMING_DETAIL=trace also adds timing.detail.trace.slow_packages buckets for the slowest tarball HTTP, extract, security, finalize, v2 link task, and provenance verification work, plus per-purpose duplicate metadata request rankings.

Resolver concurrency appears under timing.resolve.metadata_dispatcher and, in detail mode, timing.detail.resolve.scheduler.metadata_dispatcher; dispatcher remains as a compatibility alias. These objects describe metadata scheduling only and set tarball_downloads_included: false. configured_fanout is the metadata-fetch permit limit, active_fetch_high_water is the peak number of direct jobs holding permits, and pending_high_water is the peak number of canonical requests pending in the resolver dispatcher, including direct jobs waiting for permits and Worker root or tail batch candidates. semaphore_wait_count and semaphore_wait_ms show direct-route permit contention. The compatibility field inflight_high_water has the same value as active_fetch_high_water. Tarball dispatch and overlap counters are reported separately by the fetch timing objects.

LPM_TIMING_DETAIL=1 and LPM_TIMING_DETAIL=trace imply timing, so they work without also passing --timing. Use detail mode for local performance investigations and cold/warm install comparisons, not as a stable production API.

Swift packages

Use lpm install for Swift dependencies hosted by LPM.dev Registry:

lpm install @lpm.dev/owner.swift-pkg
lpm install -y @lpm.dev/owner.swift-pkg

LPM CLI performs the required Swift Registry setup, updates Package.swift, and runs swift package resolve. If the package has one eligible non-test target, LPM CLI selects it automatically. With multiple eligible targets, a normal install opens the target selector; -y / --yes skips it and selects the first eligible target, matching the selector's default.

Swift manifest changes are transactional. If resolution fails—or a later JavaScript package in the same mixed install fails—LPM CLI restores the selected package's original Package.swift and Package.resolved; a Package.resolved created during the failed run is removed.

For a fresh Swift dependency, --json includes the automatic setup disposition:

{
  "registry_setup": {
    "scope": "repaired",
    "signing_certificate": "retained",
    "signing_trust": "retained"
  }
}

Each value is "repaired" when LPM CLI changed that part of the setup or "retained" when the existing state already matched. registry_setup is omitted when the dependency already existed and no automatic setup ran.

Use lpm swift-registry --force only to repair stale or corrupt Registry configuration or refresh the signing certificate. It is not a prerequisite for the normal install flow. lpm add remains the legacy Swift source-copy path.

How it works

1. Resolve. LPM CLI walks package.json, applies the lockfile, and fetches whatever metadata is missing from the appropriate registry (see Registries for routing).
2. Download. Tarballs go into the global content-addressable store at ~/.lpm/store/. Anything already present is reused. Package extraction uses the archive safety limits. Canonical store bytes and project-writable package files use independent inodes: APFS and reflink-capable Linux filesystems preserve physical sharing through copy-on-write, while ext4 and other non-reflink filesystems use independent copies. Automatically followed redirects are checked at every hop and cannot return to HTTP after the chain has used HTTPS; see Redirect transport policy.
3. Link. node_modules/<pkg> is created as a symlink into the selected virtual store's links/<graph-key>/ directory. The default is v2; experimental v3 is used only when explicitly selected with LPM_STORE_VERSION=v3. Single packages start hoisted: root direct dependencies are surfaced at the project root, while package-local dependency links live inside shared link entries. Workspaces auto-default to isolated (strict dependency visibility). If resolution detects incompatible peer requirements and no explicit linker was set, LPM CLI switches that install to isolated and records the decision in lpm.lock so warm installs keep the same layout. Override per-invocation with --linker=isolated or --linker=hoisted.
4. Run root lifecycle, gate dependency scripts. Bare installs run the root project's install lifecycle (pnpm:devPreinstall before dependency work, then preinstall / install / postinstall / preprepare / prepare / postprepare after a successful install). Dependency package scripts stay blocked by default; when policy permits them to run (--policy=allow / --yolo, or a triage-green tier), only dependency preinstall, install, and postinstall fire. Other recognized dependency phase names (prepare, prepublishOnly, preuninstall / uninstall / postuninstall) are surfaced in detection but never executed by install. See lifecycle scripts below.
5. Summarize cached security results. LPM CLI reads the local behavioral-analysis cache for every installed package and reports actionable findings. LPM.dev Registry packages can also receive registry-side enrichment.

Source identity is preserved during linking. A registry package, tarball, Git package, file: package, and link: package may share the same name@version; each dependency edge points at the source declared by that edge instead of guessing from name and version alone. Local file: and link: source snapshots refresh when you run lpm install again.

Project node_modules path

The project-level node_modules path must be a real directory. Do not replace this path with a symlink or directory junction.

LPM CLI checks the project root before it accesses the registry. A recursive install checks the root and each selected workspace member before it starts install work.

Give each worktree its own node_modules directory. LPM CLI still shares canonical package data and graph link entries through ~/.lpm/store/.

If LPM CLI reports Project layout error, run:

lpm doctor --fix
lpm install

The doctor command removes only the project link entry. It does not remove the target or its contents.

lpm cache prune and lpm store clean do not repair this project layout.

GitHub dependencies

package.json can declare public GitHub repositories with GitHub shorthand or a public git+https URL:

{
  "dependencies": {
    "wa-sqlite": "github:rhashimoto/wa-sqlite#779219540f66cecaa159da32b3b8936697ba10a7",
    "ci-info": "git+https://github.com/watson/ci-info.git#main"
  }
}

An exact 40-character commit is used directly. A branch, tag, or omitted ref is resolved through GitHub's public API, then lpm.lock records the exact commit. Package bytes are downloaded directly from GitHub's codeload origin, assigned SHA-512 integrity, securely extracted, and passed through the same install-time source analysis as registry packages. Public GitHub traffic does not pass through LPM.dev Registry services.

GitHub URLs must use public git+https://github.com/<owner>/<repository>.git form. Credentials, custom ports, query parameters, redirects, non-GitHub hosts, and non-HTTPS Git transports are rejected. Private/authenticated Git repositories are not currently supported.

Frozen and offline installs replay the commit and integrity from lpm.lock without contacting GitHub when the package is already in the global store. lpm fetch can populate that store from the lockfile. A frozen offline install fails if the required Git object is missing instead of resolving or downloading a replacement.

Direct GitHub dependencies work at a project root and in recursive workspace members. Registry dependencies declared by the Git package remain part of its locked graph; nested non-registry dependencies inside that package are rejected.

Post-install security summary

When install-time source analysis is enabled, LPM CLI analyzes package source locally as extracted bytes enter the store. The scanner records behavioral, supply-chain, and manifest signals in .lpm-security.json next to the stored package bytes. This applies to npm, custom-registry, and @lpm.dev/* packages; it does not depend on an LPM.dev Registry package being present.

Install-time source analysis is disabled by default. Manage it with lpm config source-analysis:

lpm config source-analysis --set true   # enable analysis
lpm config source-analysis --set false  # default; approval required after an approved opt-in

The disabled setting skips new install-time scans and cache creation without deleting existing caches. lpm audit still scans installed package source when no usable cache exists and stores its fallback result in the project audit cache. Re-enabling source analysis makes the next install backfill any missing, malformed, or outdated store cache from the already-extracted package bytes; it does not need to download the tarball again.

At the end of an install, LPM CLI reads those cached results for every installed package. It does not upload package source during this summary step. For installs larger than 50 packages, progress is reported as Checking cached security results for N packages / Checked cached security results for N packages, reflecting that this phase reads analysis already produced during extraction rather than rescanning source.

A normal install keeps Security summary compact. It shows the total number of Critical, High, and Medium findings, then shows package details only for Critical findings. Run lpm audit for the complete report, or use lpm --verbose install to include High and Medium details plus exact query selectors.

Info results describe common package capabilities or artifact traits. Examples include environment-variable access, URL literals, cryptography, and minified source. LPM CLI still detects and caches these signals, but a normal install does not show them as security findings.

Use one of these commands to inspect Info signals:

lpm --verbose install  # show all finding details and Behavioral metadata
lpm audit              # include Info signals in the complete audit
lpm query :info        # select packages with any Info tag

Verbose install output uses the heading Behavioral metadata. Its query hint contains the tags that were found. For example, environment access plus URL literals produces lpm query ":env,:url-strings", not a generic :critical hint.

If the same name@version has findings from multiple sources, the summary distinguishes registry packages by credential-free origin and uses an opaque source ID for tarball, directory, link, and git packages. Registry credentials, paths, queries, and fragments are never included in these labels.

For @lpm.dev/* packages only, LPM CLI makes one batch metadata request to the configured LPM.dev Registry. The normal summary uses registry behavioral tags and lifecycle-script metadata.

The normal summary does not use registry vulnerabilities or AI security findings. For JavaScript packages, lpm audit and audit-after-install add those findings.

For a Swift package named in lpm install, audit-after-install adds findings from the Registry metadata that LPM CLI already fetched. lpm audit does not currently discover Swift dependencies from Package.resolved.

The request contains package names. It does not contain source bytes, local findings, versions, or filesystem paths.

This best-effort enrichment is enabled by default and is independent of the local scanner:

lpm config lpm-insights --set false  # keep local findings; skip enrichment
lpm config lpm-insights --set true

The combined lpm config lpm-dev editor manages this setting alongside automatic LPM.dev package skills. npm-only installs still receive local analysis and actionable summaries. They do not trigger this LPM.dev Registry enrichment request. The separately configured LPM Firewall can make its own verdict requests for npm packages.

--no-security-summary skips the post-install cache aggregation and human report. It does not change the install-time source-analysis setting or remove existing .lpm-security.json cache files.

With --json --timing, source analysis from the authoritative fetch path appears under timing.fetch_breakdown.source_scan as sum_ns and max_ns. Fused overlap-prefetch tasks report the same counters under timing.detail.fetch.overlap.breakdown.source_scan, so use detail mode when measuring the complete cold-install scan attribution. Both paths scan while extraction is running: the work is already included in cold install wall time and extract_ms, and the counters must not be added to the total again.

Package-published LPM.dev skills

Installed @lpm.dev/* packages can publish package-specific agent guidance. LPM CLI reconciles that content into .lpm/skills/<package>/ by default. This automatic step is specific to LPM.dev Registry packages; npm and custom-registry packages do not use it.

lpm install @lpm.dev/owner.package --no-skills # skip once
lpm config lpm-skills --set false              # persist the opt-out
lpm install @lpm.dev/owner.package --skills    # override config once

The persistent setting does not delete existing package skill files. Use lpm skills clean to remove them. Explicit lpm skills add @lpm.dev/owner.package commands remain available regardless of the setting. See AI agent skills.

For registry packages, any tarball URL recorded in lpm.lock is only a cache hint. Before fetching it, LPM CLI checks the registry metadata for that exact name@version and refuses the install if the hint does not match dist.tarball. Explicit tarball, file:, link:, and git sources keep their own source identity and are not rebound to registry metadata.

JSR dependencies

package.json can declare JSR packages with the jsr: protocol:

{
  "dependencies": {
    "@std/path": "jsr:@std/path@^1.1.0",
    "@std/fs": "jsr:^1.0.0"
  }
}

LPM CLI installs those dependencies under the JSR import name (node_modules/@std/path) and fetches the folded npm package (@jsr/std__path) from https://npm.jsr.io. Version-only specs such as "jsr:^1.0.0" borrow the package name from the dependency key. Malformed JSR package names are rejected before any registry request.

Use .npmrc to point JSR fetches at a mirror:

@jsr:registry=https://npm-jsr-mirror.example.com

See Registries for the routing details.

Peer dependency strict mode

By default, LPM CLI follows pnpm's non-strict install posture: missing required peers, peer version mismatches, and cross-consumer peer conflicts print warnings, then install continues.

When those warnings include a cross-consumer peer conflict, the default linker auto-switches to isolated for that project. Explicit linker choices (--linker, ~/.lpm/config.toml > linker, LPM_LINKER, or package.json > lpm.linker) are respected and do not auto-switch.

Use strict mode when peer diagnostics should gate CI:

lpm install --strict-peer-dependencies

Strict mode fails after resolution if a required peer is missing, an installed peer does not satisfy the declared range, or the resolver found incompatible peer requirements across consumers. Optional peers that are absent still do not fail.

Precedence: --strict-peer-dependencies / --no-strict-peer-dependencies > package.json > lpm.strictPeerDependencies > ~/.lpm/config.toml > strict-peer-dependencies > default (false). On -g, the package.json tier is not present, so CLI flags override ~/.lpm/config.toml.

Under --json, peer diagnostics are always attached to the success envelope as peer_issues. Missing required peers land in missing, installed peers that do not satisfy the declared range land in bad, and cross-consumer resolver conflicts land in conflicts. Each list has a matching *_count, and total_count is the combined issue count. The legacy peer_conflicts array is still emitted and matches peer_issues.conflicts.

{
  "success": true,
  "peer_issues": {
    "missing": [
      {
        "type": "missing",
        "package": "required-peer-host",
        "version": "1.0.0",
        "peer": "missing-peer",
        "required_range": "^1.0.0",
        "resolved_version": null
      }
    ],
    "bad": [
      {
        "type": "bad",
        "package": "peer-consumer-a",
        "version": "1.0.0",
        "peer": "shared-peer",
        "required_range": "^1.0.0",
        "resolved_version": "2.0.0"
      }
    ],
    "conflicts": [
      {
        "canonical": "shared-peer",
        "chosen_version": "2.0.0",
        "unsatisfied_consumers": [{ "consumer": "peer-consumer-a", "range": "^1.0.0" }]
      }
    ],
    "intersections": [],
    "missing_count": 1,
    "bad_count": 1,
    "conflicts_count": 1,
    "intersections_count": 0,
    "total_count": 3
  }
}

Save policy

When you run lpm install <pkg> without an explicit version, LPM CLI saves ^resolvedVersion to package.json. If you typed an explicit version or range, LPM CLI preserves what you typed. Prereleases are saved exact for safety.

Override per-invocation with --exact, --tilde, or --save-prefix '<p>'. Set persistent defaults in ./lpm.toml (project) or ~/.lpm/config.toml (global):

save-prefix = "^"   # one of "^", "~", or "" (exact, no prefix)
save-exact = false  # bool; true forces exact regardless of prefix

Re-installing an existing dep without a version or override flag refreshes the lockfile and store but does not rewrite the existing range — "zod": "~4.3.6" stays put.

Interrupted installs

If a JavaScript package install fails or receives Ctrl+C, LPM CLI restores its staged manifest changes and invalidates the install cache.

After a forced stop, the next install restores staged package.json changes before it proceeds. This also covers selected workspace members. An intentional "*" range remains unchanged.

Repeat the original command to complete the interrupted operation:

lpm install zod

A bare lpm install instead installs the dependencies from the restored manifest. The retry also repairs incomplete node_modules state.

If you edit a staged manifest after interruption, automatic recovery stops and preserves your edits. The error identifies the backup directory under .lpm/install-recovery.

Save your current edits separately. Restore the matching backup record's original text to its package.json path. Repeat the install, then reapply your edits. Keep the backup until recovery succeeds.

Typosquat guard

The guard is off by default. Enable it for this machine:

lpm config typosquat --set on

When enabled, lpm install <pkg> and bare lpm install guard new direct dependency names before resolution. The detector covers low-noise cases such as adjacent transpositions (axois → axios), delimiter variants (crossenv → cross-env). Flag-shaped package names after -- (--legacy-peer-deps) remain invalid even when the guard is off. Transitive dependencies are not blocked by this guard.

In interactive terminals, a single suspicious CLI package can be replaced with the suggested package or committed to the project allow-list. In CI, --json, non-TTY, and --yes runs, LPM CLI exits 1 with error_code: "typosquat_suspected" and leaves the manifest untouched.

Intentional names belong in lpm.toml:

[[policy.typosquat.allow]]
package = "axois"
similar-to = "axios"
reason = "Intentional internal compatibility package"

The guard only fires when a name is newly entering the project. If lpm.lock already records the direct dependency, CI=true lpm install and lpm install --frozen-lockfile replay the lockfile normally.

Machine-wide guard mode lives in ~/.lpm/config.toml > typosquat-guard and is managed by lpm config typosquat --set default|on|off. default removes the explicit override and keeps the current product default (disabled); on keeps the guard enabled even if the diagnostic env toggle is set; off always disables the guard. Switching an approved guard from on to off or default requires security approval. The diagnostic env toggle is also ignored when managed policy owns the typosquat floor. Use project allow-list entries for legitimate false positives instead of turning the guard off globally.

npm firewall

When ~/.lpm/config.toml > [firewall] mode is set to monitor or enforce, LPM CLI sends selected public npm package versions to LPM Firewall at firewall.lpm.dev in batches. Metadata and tarballs still use the direct npm route; the firewall request only asks for block/warn verdicts. LPM Firewall is an LPM.dev Registry Pro/Org feature, so active modes send LPM.dev Registry auth; run lpm login locally or set LPM_TOKEN in CI.

When human output is active and the install includes public npm packages that need verdict checks, the install phase line shows 🔥 LPM Firewall active.

monitor prints would-block and warning verdicts and lets the install continue. If LPM Firewall denies entitlement or is unreachable, monitor mode warns and continues. enforce blocks packages whose effective firewall action is block before their tarballs are allowed through, and fails before package bytes are materialized when entitlement is denied. Configure it with:

lpm config firewall --set monitor
lpm config firewall --set enforce

The legacy string report is still accepted as an alias for monitor. Disabling or downshifting the firewall after it becomes part of the approved machine posture is guarded by lpm security. See the Firewall for npm guide for custom policy groups.

Policy extensions

Install can run local policy extensions from ~/.lpm/config.toml > [policy.extensions.<name>]. Extensions receive the resolved package candidates as JSON on stdin and return verdicts as JSON on stdout. LPM CLI spawns the configured command directly; it does not use sh -c or interpolate package data into a command string. The command's first entry must be an absolute path or a program name found on an absolute PATH directory; relative executable paths are rejected.

Policy extensions run after resolution, platform filtering, and --omit filtering, but before registry tarballs are fetched or packages are linked. Warm lockfile and offline installs run the same check before linking. When an extension is active, install-time registry tarball prefetch waits until policy verdicts pass. Direct remote tarball URL dependencies are rejected while policy extensions are active because V1 cannot identify the package candidate without downloading the tarball first.

[policy.extensions.local-feed]
command = ["/usr/local/bin/lpm-policy-feed", "--deny-list", "/etc/lpm/deny.json"]
mode = "enforce"       # report | enforce
on-error = "block"     # warn | block
timeout-ms = 5000
events = ["package.candidate"]

report mode warns and continues. enforce mode fails the install when the extension returns a block decision. With --json --timing, the success envelope includes timing.policy_extensions and security.policy_extensions counters.

Use lpm policy to inspect and test configured extensions:

lpm policy list
lpm policy status
lpm policy doctor
lpm policy test local-feed --package react@19.0.0

Full request/response schema: ~/.lpm/config.toml policy extensions.

Use --catalog to force a catalog reference for this invocation. --catalog <pkg> writes "catalog:"; --catalog=<name> <pkg> writes "catalog:<name>". The entry must already exist in the selected root catalog and the resolved version must satisfy that catalog range, otherwise the install fails before committing package.json. This flag is mutually exclusive with --exact, --tilde, and --save-prefix.

Catalogs can override the saved spec for packages that exist in the root default catalog. Set package.json > lpm > catalogMode:

Set package.json > lpm.cleanupUnusedCatalogs = true or pnpm-workspace.yaml > cleanupUnusedCatalogs: true to prune unused root catalog entries after successful installs. The default is to preserve catalog entries exactly as written.

Full details in Save policy.

Production and omitted deps

Use --prod (alias: --production) to install the production dependency closure only. It omits devDependencies from node_modules while keeping the lockfile graph reproducible.

lpm install --prod
lpm install --omit=dev          # same dev-dep omission
lpm install --omit=optional     # skip optionalDependencies
lpm install --omit=dev,optional # compose both

--omit accepts dev and optional, comma-separated or repeated. Production filtering keeps peer packages needed by retained production packages, so production installs do not accidentally drop a peer that a kept package can resolve.

Lifecycle scripts

Bare lpm install runs the root project's install lifecycle:

This root lifecycle applies to bare installs only. lpm install <pkg> adds the requested packages and does not auto-run the root prepare lifecycle.

Dependency package lifecycle scripts are separate and deny-by-default. To run dependency scripts, choose a policy:

Triage auto-runs only when every unbuilt scripted package classifies green. If any amber or red remains, scripts defer to lpm approve-scripts review unless an explicit auto-build signal is set: --auto-build on the command line, or — on project installs — package.json > lpm > scripts.autoBuild = true. Global installs (-g) only honor --auto-build; the synthesized package.json doesn't project per-project script knobs.

Auto-build runs after dependency resolution/linking. The same build tail is used for fresh resolution, lpm install <pkg>, and lockfile/offline replays when the effective policy permits dependency scripts. If any trusted lifecycle script exits non-zero, lpm install exits non-zero and surfaces the failing package/script instead of treating the install as successful.

Set per-invocation:

lpm install --policy=allow      # equivalent to --yolo
lpm install --yolo              # alias for --policy=allow
lpm install --triage            # alias for --policy=triage

Or pin in package.json:

{ "lpm": { "scriptPolicy": "allow" } }

Or globally in ~/.lpm/config.toml:

script-policy = "deny"

Precedence: CLI flag > package.json > ~/.lpm/config.toml > default (deny). On -g the package.json tier is N/A; the chain collapses to CLI > ~/.lpm/config.toml > default.

Optional LLM advisor (under triage)

If you have a local LLM available — Claude CLI, Codex, or Ollama — the triage gate can ask it to review Amber-tier scripts during install. If the advisor returns Approve for every amber phase a package presents, that package's scripts run via an ephemeral trust path for the current install only — verdicts are never persisted. See security overview for the full contract.

lpm config triage --set claude-cli          # one-time setup

Or in package.json: { "lpm": { "triageAdvisor": "claude-cli" } } · or ~/.lpm/config.toml: triage-advisor = "claude-cli". The advisor is opt-in — triage-advisor: "none" is the default, and script-policy: "triage" alone gives you the portable layers 1-4.

Override per-invocation with --advisor:

lpm install --triage --advisor=claude-cli   # one-off uplift
lpm install --triage --advisor=none         # one-off opt-out

Precedence: --advisor flag > package.json > lpm > triageAdvisor > ~/.lpm/config.toml > triage-advisor > default (none). The flag is only consulted when the effective script-policy is triage; under deny / allow the advisor never runs.

See lpm rebuild and lpm approve-scripts for the manual-approval flow.

Sandbox

When a dependency lifecycle script does run (greens under triage, or anything under allow), it executes inside the filesystem sandbox by default — Seatbelt on macOS, landlock on Linux, AppContainer on Windows. Default mode allows the project read, the package's own directory write, and outbound network. Strict mode adds env scrubbing and denies outbound network.

Linux masks conventional project-secret files through a private namespace overlay. If protected files exist and the host blocks any required namespace, ID-map, propagation, or bind-mount step, LPM CLI refuses to execute the lifecycle script. Projects with no protected files, or only files explicitly authorized through sandboxReadAllow / script-read-allow, continue without that overlay. See Project secret files for the exact policy and remaining limits.

lpm install --strict-sandbox          # engage strict mode for this install
lpm install --paranoid                # alias for --strict-sandbox
lpm install --no-sandbox              # drop ALL containment for this install (single flag — drops env scrubbing too)

Persistent strict mode: ~/.lpm/config.toml > [sandbox] mode = "strict" (or LPM_STRICT_SANDBOX=1). Persistent off: lpm config sandbox --set none. Per-invocation flags override the persistent mode.

--no-sandbox is reserved for debugging a sandbox false-positive — scripts run with full host access including credential-bearing env (LPM_TOKEN, NPM_TOKEN, GITHUB_TOKEN, etc.). The three flags are mutually exclusive. See the filesystem sandbox reference for declaring extra write directories per-package.

Guarded weakeners and approvals

Some install-time weakeners are approval-gated:

• --yolo / --policy=allow
• --triage when it weakens the current approved machine floor
• --allow-new or a lower --min-release-age
• --no-sandbox
• LPM_PROVENANCE_ENFORCE=warn|off for the current install run
• raw ~/.lpm/config.toml > [sigstore].verify = "warn"|"off"
• --unverified-provenance* and --ignore-provenance-drift*

Interactive TTY behavior:

lpm install --no-sandbox

In an interactive shell, LPM CLI can ask inline for confirmation and continue the install if you approve.

Automation behavior:

lpm install --no-sandbox --json

With --json, in CI, or in any non-TTY shell, LPM CLI does not prompt. It fails with error_code: "security_approval_required" and includes a suggested_command, for example:

lpm security unlock sandbox-none --project . --ttl 10m

Package-scoped unlocks only cover the package names listed with --package. A package-scoped unlock does not authorize blanket all-package provenance flags such as --unverified-provenance-all or --ignore-provenance-drift-all.

Repo-file weakeners are treated differently. If a repo asks for a weaker posture through:

• package.json > lpm.scriptPolicy
• package.json > lpm.minimumReleaseAge
• package.json > lpm.minimumReleaseAgePolicy
• lpm.toml > [sandbox]

install or rebuild does not prompt inline. LPM CLI treats those file values as proposals, fails the command, and points you at lpm security unlock ... for a temporary project exception.

Use lpm security to create the unlock explicitly or to inspect the current floor with lpm security status.

Dependency overrides

Use package.json > lpm.overrides, top-level overrides, or top-level resolutions to replace direct or transitive dependency versions.

{
  "lpm": {
    "overrides": {
      "ms": "2.1.3"
    }
  }
}

An override target replaces the declared range of each matching consumer. An exact target pins that version, even when the consumer declares another range.

This behavior changed from older LPM CLI releases. Older releases intersected the override target with each consumer range. Current releases replace the consumer range, so an existing lockfile can select different versions after an upgrade.

A range target selects the newest eligible published version in the override range. Security and platform policies still apply to the selected version.

Workspace-root overrides apply to the root and all members. A member can add overrides or replace a root selector in the same field.

Field precedence is lpm.overrides, then overrides, then resolutions. LPM CLI lists an override as applied only when it changes the selected version.

If an override target is unavailable or blocked by policy, LPM CLI warns and keeps the natural version. See package.json > lpm.overrides for selector forms.

Workspaces

At a workspace root, no-argument install is recursive by default:

lpm install                   # every member in dependency order, root last
lpm install --no-recursive    # root project only

LPM CLI shares workspace discovery across member installs and refreshes the root configuration once before installing the root, so lifecycle edits and merged pnpm-workspace.yaml settings stay current. On a cold install, eligible importers share one union resolution, with shared expansion passes as needed, and receive isolated projections of the resulting graph; an importer that cannot be projected safely falls back independently. Each selected project still runs through the normal materialization, engine, lifecycle, and security pipeline. Member project lifecycles run in dependency order; the root lifecycle runs last. A failure stops later targets. Cyclic graphs fall back to stable path order.

Recursive installs write one schema-v10 lpm.lock at the workspace root. The file stores distinct package rows once under workspace-packages and records each member's package closure and root state under importers. It is committed only after every selected target succeeds. Member-local commands read and update their own projection in that root file; workspace unions are TOML-only and do not write lpm.lockb.

When a successful recursive install finds legacy member lockfiles, it absorbs them into the root union and then removes the obsolete member lpm.lock / lpm.lockb files. A failed recursive install does not commit the new root union or remove the legacy lockfiles. Targets that already changed node_modules remain provisional; their install hashes force a later install to converge them with the authoritative lockfile.

lpm install --recursive and lpm -r install request the same behavior explicitly. From inside a member, the explicit form widens to the owning workspace. --recursive is a manifest refresh operation and cannot be combined with package specs.

Filter a recursive refresh when only part of the workspace needs work:

lpm install --filter web              # web plus all workspace dependencies
lpm install --filter-prod web         # production dependency closure only
lpm install --filter web --fail-if-no-match

A filtered refresh omits unrelated members and the workspace root. Required workspace dependencies are included automatically, even when the filter only names the consuming member.

workspace: references resolve by declared package name against both discovered members and a named workspace root. A selected project's own devDependencies are installed normally unless production filtering omits them. When another workspace package is consumed as a dependency, its dependencies, peerDependencies, and optionalDependencies can extend the local dependency closure; its devDependencies do not become transitives.

When adding a package, target a specific member or the workspace root:

lpm install react --filter web    # add react to packages/web/
lpm install -w typescript -D      # add to the root package.json
lpm install react --filter './apps/*' # any glob the workspace filter accepts
lpm install react --filter-prod ...web # production closure only

--filter / --filter-prod and -w are mutually exclusive. --filter-prod uses the same grammar but ignores devDependencies during closure expansion. --changed-files-ignore-pattern <glob> and --test-pattern <glob> apply when a filter contains a [git-ref] atom. --fail-if-no-match makes a typo'd filter exit non-zero (recommended in CI). When a filtered install would mutate more than one member's package.json, LPM CLI prompts for confirmation; pass -y to skip the prompt.

With --json, a recursive install emits one aggregate envelope with recursive: true, workspace_root, a targets array, and success counts under summary. Per-target install envelopes are suppressed, so stdout remains one JSON document.

Workspace selection is ecosystem-aware. An @lpm.dev/* version whose Registry metadata says ecosystem: "swift" is routed through the SE-0292 installer for each selected member that owns a direct Package.swift; it is never staged into package.json. Root (-w), member-cwd, and filtered installs mutate and resolve from that same selected Swift package directory. Mixed requests keep JavaScript packages on the existing package.json path. One eligible Swift target is automatic; multiple targets prompt unless -y selects the first, and zero eligible targets fail without mutating an unrelated manifest.

See Workspaces for filter grammar.

Frozen Lockfile And CI

lpm ci --offline --strict-integrity

• lpm ci — frozen install. Requires lpm.lock, validates that the lockfile's importer snapshot matches package.json, and never rewrites lpm.lock or lpm.lockb.
• --offline — never touches the network. Replays entirely from the lockfile + global store. Errors out if anything is missing.
• --strict-integrity — fail on tarball-URL deps that don't declare an inline SRI hash. Disables trust-on-first-use for fresh installs.
• --no-skills and --no-security-summary skip optional work to shave CI time. Persist the package-skill opt-out with lpm config lpm-skills --set false; use --skills to override it for one CI run. --no-editor-setup remains accepted but has no effect; package skills never create editor links or configuration.

For reused expanded-store object validation, use lpm config integrity. integrity = "tree" rehashes expanded files before reuse; --strict-integrity only controls whether tarball URL dependencies must declare SRI before first use.

lpm install --frozen-lockfile gives the same frozen behavior on the regular install command. On CI providers that set CI=true (or a provider-specific CI env var), plain lpm install automatically becomes frozen when lpm.lock exists. Pass --no-frozen-lockfile only when you intentionally want a mutable install in CI.

Frozen means frozen: package specs are rejected, --force is rejected, missing lockfiles fail, stale manifest ranges or dependency sections fail, and drift in overrides, catalogs, patches, peer rules, or autoInstallPeers fails before install work proceeds.

Artifact availability does not weaken that contract. If a registry no longer serves an artifact pinned by an existing lockfile, mutable lpm install, lpm install --frozen-lockfile, and lpm ci all fail without deleting, truncating, rewriting, or replacing lpm.lock or lpm.lockb. A mutable install does not silently select a newer version or a different source.

When the unavailable package is a direct dependency, the error reports an upgrade command using its package.json key:

lpm upgrade <manifest-key>

For an npm alias such as "local": "npm:canonical@1.0.0", that command is lpm upgrade local, not lpm upgrade canonical. When the unavailable package is transitive, LPM CLI does not emit an unusable command action. Restore the artifact, or update the owning direct dependency or an override in a mutable development environment.

Review the result and commit the updated lockfiles before retrying a frozen or CI install.

Artifact-unavailable errors identify the pinned package and version but show only a sanitized registry/source identity. Registry URL credentials, paths, query strings, and fragments are not printed. Authentication, rate-limit, timeout, transport, and registry 5xx failures keep their own error classifications instead of being reported as unavailable pinned artifacts.

For Docker layers keyed only by the lockfile, warm the store before copying the rest of the project:

COPY lpm.lock ./
RUN lpm fetch --platform linux/x64/glibc

COPY package.json ./
RUN lpm install --offline --frozen-lockfile

For full image patterns, see Docker deploys.

Recently published packages

The minimum release age is off by default (0 seconds). Enable a one-day cooldown for this machine:

lpm config release-age --set 1d

When enabled, the default scope checks direct/root dependencies: the package specs declared by the project, plus packages you pass to lpm install <pkg>. For ranges on checked packages, the resolver skips candidates that are still inside the cooldown window and picks the newest older candidate that still satisfies the range. When the request is latest, fallback candidates are also capped at the registry's authoritative dist-tags.latest target. A maintainer rollback to a lower SemVer therefore cannot select an older-by-date but SemVer-greater release. Exact pins to a too-new version still fail, because there is no older version that can satisfy the exact request.

Transitive dependencies of an allowed direct package are not separately halted by the default policy. That keeps a mature direct package on its normal dependency graph instead of downgrading it only because one of its children was published recently.

For stricter supply-chain posture, opt into transitive enforcement:

{ "lpm": { "minimumReleaseAge": 86400, "minimumReleaseAgePolicy": "strict" } }

minimum-release-age-secs = 86400
release-age-policy = "strict"

Strict mode applies the cooldown to direct and transitive dependencies. Lockfile replays are revalidated from the registry-published-at timestamps persisted in lpm.lock, so a frozen replay cannot silently reintroduce a package that is still inside the configured cooldown window.

lpm install foo --allow-new                # bypass the cooldown for this command
lpm install foo --min-release-age=1h       # tighten or loosen the window
lpm install foo --min-release-age=0        # disable the cooldown for this command
lpm install foo --min-release-age-exclude foo

Set persistent defaults in package.json or ~/.lpm/config.toml. Exclusions accept package names, exact versions, and @scope/* selectors.

For "local": "npm:real-pkg@1.0.0", use the canonical target name real-pkg. Do not use the alias name local.

Manage project exclusions with lpm trust release-age-exclude. Manage user exclusions with lpm config release-age-exclude.

CLI, project, and user exclusion lists merge in that order. LPM CLI removes duplicate selectors.

See the lpm trust storage contract for persistent locations and workspace-member behavior.

Set cooldown scope via package.json > lpm.minimumReleaseAgePolicy or ~/.lpm/config.toml > release-age-policy. Use lpm config release-age-policy --set strict for the global wizard, or lpm config set release-age-policy strict for the generic setter.

--allow-new and --min-release-age-exclude <pkg> skip the install cooldown only — the provenance-drift check still applies unless you also pass --ignore-provenance-drift <pkg> or --ignore-provenance-drift-all. Under --policy=triage, the identity-match widening is also gated by the cooldown — bypassing the install halt does not make a recent-publish package's scripts trusted. Use --policy=allow to opt out of the script-tier review as well, or set minimum-release-age=0 to disable cooldown universally.

Registry signatures and trust policy

Registry package signatures are off on the install path by default so the hot path stays lean. Audit them on demand:

lpm audit signatures
lpm audit signatures --json

Enable install-time verification when you want the install itself to fail closed on unsigned or unverifiable npm registry packages:

lpm config signatures --set true
# or, for one process:
LPM_VERIFY_REGISTRY_SIGNATURES=1 lpm install

The verifier checks npm-compatible dist.signatures against registry signing keys and the package integrity hash. @lpm.dev/* packages and non-registry sources are skipped by this specific check; they still pass through the normal integrity, provenance, script, and behavioral layers.

trust-policy = "no-downgrade" is a separate verified-history policy:

lpm config trust-policy --set no-downgrade

When enabled, LPM CLI first rejects releases whose npm trusted-publisher or staged-publish evidence is weaker than an earlier published release. It also remembers verified provenance in lpm.lock: after any locked version of a package has verified evidence, a later version without verified evidence fails with the trust-policy reason. verify=warn, verify=off, per-package verification skips, and best-effort availability cannot bypass the lockfile-history floor; disable trust-policy itself to permit an intentional downgrade. Registry attestation pointers alone are not treated as evidence. The default is off.

Sigstore verification has two additional opt-in axes:

lpm config sigstore --set scope=all
lpm config sigstore --set availability=strict

scope=all verifies every resolved package and locks successful evidence; the default approved scope checks packages with previously approved provenance identities. availability=strict requires evidence; the default best-effort mode keeps attestation absence or transient unavailability non-blocking. Invalid supplied bundles still fail under the default verify=deny posture. See Security audit for artifact binding, cache, and frozen-replay details.

Audit after install

After a successful install, LPM CLI can add a compact audit summary. This feature is optional.

✓ Done · installed 247 packages in 1.31s
! Audited 247 packages, 2 vulnerabilities, 67 suspicious, 3 critical in 412ms — run `lpm audit`
  Critical
    @lpm.dev/acme.tool@2.0.0 LPM-ADV-101 — remote code execution [registry/vulnerability]

The audit is informational only. Its findings never fail the install. Run lpm audit --fail-on=all for a gating audit. The feature is disabled by default.

Without this option, a normal install does not query OSV. It also does not report LPM.dev Registry advisories or AI security findings.

For JavaScript packages, audit-after-install uses the same discovery, scan, and severity policy as lpm audit. It counts each advisory separately and preserves Critical Registry security findings.

For a Swift package named in lpm install, audit-after-install uses the same Registry issue collection and severity policy. It uses the metadata fetched for that package. It does not query OSV, scan Swift source, or discover transitive Swift dependencies.

The summary prints every Critical finding below the first line. For JavaScript packages, findings with lower severity remain available through lpm audit. lpm audit does not currently discover Swift dependencies.

For JavaScript packages, the vulnerability count includes OSV.dev findings and exact-version LPM.dev Registry advisories. If either lookup cannot complete, LPM CLI suppresses the ! Audited line and the JSON audit_summary. The install still succeeds, and logs contain the audit failure.

For an explicit Swift package, the vulnerability count includes its exact-version LPM.dev Registry advisories. The Swift summary does not include OSV findings.

Enable per-invocation:

lpm install --audit-after-install        # opt in for this run
lpm install --no-audit-after-install     # opt out for this run (beats env + config)

Or persistently:

• LPM_AUDIT_AFTER_INSTALL=1 env (accepts 1/true/yes/on and 0/false/no/off)
• ~/.lpm/config.toml > audit-after-install = true

Precedence: --audit-after-install / --no-audit-after-install > LPM_AUDIT_AFTER_INSTALL > ~/.lpm/config.toml > default (false).

Under --json, the human line is suppressed and the same counts are attached to the install envelope as audit_summary:

{
  "success": true,
  "audit_summary": {
    "packages_audited": 247,
    "vulnerabilities": 2,
    "suspicious": 67,
    "severity_counts": {
      "critical": 3,
      "high": 4,
      "moderate": 12,
      "low": 0,
      "info": 51
    },
    "critical_findings": [
      {
        "package": "@lpm.dev/acme.tool",
        "version": "2.0.0",
        "message": "LPM-ADV-101 — remote code execution",
        "category": "vulnerability",
        "source": "registry"
      }
    ],
    "elapsed_ms": 412
  }
}

The ! Audited advisory is hidden when the install short-circuits on the up-to-date fast path — re-auditing an unchanged tree on every lpm install would be noise. Run lpm audit directly if you want to scan without re-installing.

Global installs

lpm install -g shares the project install pipeline. The same security gates fire end-to-end on -g:

Two things differ from project installs:

• Globals don't write to package.json. lpm install -g resolves a single package into ~/.lpm/global/installs/<pkg>@<ver>/ and tracks it in ~/.lpm/global/manifest.toml. The project's package.json is never read or mutated. Approvals from lpm approve-scripts --global land in ~/.lpm/global/trusted-dependencies.json instead of any project's package.json.
• Project config is skipped. With no project-level package.json > lpm block to read, the script-policy and strict-peer-dependency chains on -g collapse to CLI flag > ~/.lpm/config.toml > default. The ~/.lpm/config.toml > minimum-release-age-secs and release-age-policy chains work the same way.

A global install commits only after LPM CLI has materialized at least one safe, executable bin shim for the package. If the package exposes no usable bins, declares unsafe bin names, or the install cannot write its ready marker, LPM CLI rolls the pending global entry back instead of leaving a half-installed package in ~/.lpm/global/.

Re-running scripts after lpm approve-scripts --global requires lpm uninstall -g <pkg> && lpm install -g <pkg> for each affected top-level global. lpm rebuild --global is a planned follow-up.

Engines enforcement

lpm install enforces engine compatibility at two boundaries:

• Project preflight: reads the workspace root package.json > engines block before install work begins.
• Resolved dependencies: checks every selected package version's engines.node constraint before materialization. The constraint is persisted in lpm.lock, so warm, frozen, and offline installs revalidate it without relying on cached registry metadata.

The workspace-root keys are:

$ lpm install
Error: lpm::engine_mismatch
  × lpm version 0.32.0 does not satisfy required >=0.40.0 (from package.json
  │ > engines.lpm)

For dependencies, an incompatible required package aborts with engine_mismatch. An incompatible package reachable only through optional dependency edges is skipped. When the same package is also reachable through a required path, the required path wins and the mismatch remains fatal. Optional reachability is computed from the resolver's final selected graph, so dependency traversal order and discarded backtracking candidates do not change that result.

Workspace members may omit version. LPM CLI keeps the workspace discovery fallback of 0.0.0 for those members and reads engines.node independently, so enabling dependency engine enforcement does not make version mandatory.

Other workspace-root engines.<pm> keys (npm, pnpm, yarn, bun) are recognized and surfaced as a one-line warning that LPM CLI doesn't enforce them. Use engines.lpm for the LPM CLI version, and use lpm.json > runtime.bun when scripts need a managed Bun binary on PATH.

Workspace-root failures exit during preflight. Dependency constraints are evaluated after resolution identifies exact versions. If no effective Node version can be determined, a declared Node constraint fails and suggests selecting one explicitly with lpm use node@<version>; LPM CLI never installs a runtime from the engine range.

lpm install --no-engine-strict            # warning-only for this invocation

Persistent opt-out:

• package.json > lpm > engineStrict = false (per-project)
• ~/.lpm/config.toml > engine-strict = false (per-user)

Precedence: CLI flag > package.json > lpm.engineStrict > ~/.lpm/config.toml > default (true). The same resolved policy applies to the workspace root and dependencies. Under engineStrict = false, incompatible dependencies remain installed and mismatches print as stderr warnings (suppressed under --json).

The workspace-root preflight also runs for lpm rebuild and lpm add. Add runs it before manifest mutation, then applies dependency checks during its install phase.

Flags

Plus the global flags: --token, --registry, --json, --verbose, --insecure.

Pool install reports

After a successful install, LPM CLI reports the resolved graph for @lpm.dev/* packages to the LPM.dev Registry. The report follows actual dependency and peer targets, including overrides and npm aliases. Downloads from a failed install do not create Pool credit.

Older LPM CLI versions that send only package roots remain compatible. Their reports credit eligible roots, but can omit credit for transitive packages. Access checks still apply.

If the registry cannot confirm the report, the command returns pool_attribution_unconfirmed. Retry the same command to reuse cached packages and resend the report.

See Pool weighting and limits.

See also

• lpm uninstall — remove a dependency
• lpm tidy — find unused dependency declarations and phantom imports
• lpm upgrade — bump eligible LPM.dev Registry and npm deps to their latest matching range
• lpm rebuild — run dependency lifecycle scripts after install
• lpm approve-scripts — approve packages to run scripts
• Save policy — full details of the save-prefix system
• Resolver — how versions are picked
• Lockfile — lpm.lock and lpm.lockb