lpm global

Use lpm global to manage command-line packages outside a project and expose local tools on PATH.

lpm global [OPTIONS] <COMMAND>

Quickstart

Install a command-line package with lpm install, then inspect it:

lpm install -g eslint
lpm global list
lpm global list --outdated
lpm global update eslint --dry-run
lpm global update eslint

LPM CLI supports npm, LPM.dev Registry, and private registries. Only @lpm.dev/* packages always use LPM.dev Registry. See registry configuration.

Commands

Global installation uses lpm install -g. A package needs at least one usable executable command before LPM CLI records the installation.

Configuration and PATH

lpm.json has no global-package configuration block. Its tools field configures managed development tools, which use a separate workflow.

Global packages use the LPM CLI home directory, which defaults to ~/.lpm. LPM_HOME changes this location. The default command directory is ~/.lpm/bin.

For Bash or Zsh, add the directory to PATH in your shell configuration:

export PATH="$(lpm global bin):$PATH"

For the current PowerShell session:

$env:Path = "$(lpm global bin);$env:Path"

Windows installations provide launchers for Command Prompt, PowerShell, and Git Bash. They forward arguments and the exit code to the package command.

Global comparisons and updates read registry routing from the global environment, including the user .npmrc. A project-local .npmrc in your current directory does not configure these operations.

Global packages do not inherit the current project's package.json > lpm configuration. The user configuration supplies persistent release-age and security policy.

Inspect packages

lpm global list
lpm global list --verbose
lpm global path eslint
lpm global list --outdated --json

Ordinary list --verbose adds installation dates, disk usage, and installation paths. For a local link, path prints the source checkout.

With --outdated, the table contains these columns:

A newer Wanted or Latest produces an outdated row. A new major release remains visible even if the saved range excludes it. A registry rollback alone does not mark a package outdated.

Local links are skipped because their files come from your checkout. With --outdated --verbose, output adds saved specifications and details about current packages and skipped links. It does not add the ordinary verbose date and size columns.

If a package cannot be compared, the command returns a nonzero exit status. JSON retains successful comparisons and reports the unresolved packages.

Update packages

Preview updates before applying them:

lpm global update --dry-run
lpm global update

Update one package without changing its saved specification:

lpm global update eslint --dry-run
lpm global update eslint

Without an explicit specification, updates select only newer matching versions. Bulk updates skip local links. An explicit local-link target returns an error.

To change the saved specification, include it in the argument:

lpm global update 'eslint@^9' --dry-run
lpm global update 'eslint@^9'

An explicit specification can select an older version. It can also change the saved specification without reinstalling an unchanged version. The save policy explains how specifications become saved values.

Update preserves existing command aliases. If a new version removes an aliased command or introduces a command collision, that package's update fails.

Preview and automation

lpm global update --dry-run --json > global-update-plan.json
lpm global update --json > global-update-result.json

These commands do not prompt for package selection. A preview leaves installations, command launchers, and global recovery state unchanged. It can contact registries and refresh metadata caches.

Update revalidates registry metadata before installation and uses the metadata from its plan. Bulk updates can apply successful packages even if another package fails. A failed package produces a nonzero exit status for the command.

Release age and scripts

Global updates use the minimum release age in the user configuration. The default is 0, which disables the cooldown. The same policy applies to previews and outdated comparisons.

lpm config release-age --set 1d
lpm global update --dry-run

The update command has no one-run release-age override. For an explicit installation with an override, see lpm install.

Global update does not reuse the global script-approval set or enable automatic rebuilds. If the tool needs approved dependency scripts, reinstall it through lpm install -g with the appropriate policy.

lpm approve-scripts -g
lpm install -g my-cli --auto-build

See lpm approve-scripts for approval scope and script policy for execution rules.

Link a local checkout

Use a global link to run a command from a checkout while you develop it:

lpm global link ../my-cli
lpm global path my-cli
my-cli --help
lpm global unlink my-cli

The checkout's package.json needs name, version, and at least one valid bin entry:

{
  "name": "my-cli",
  "version": "1.0.0",
  "bin": {
    "my-cli": "bin/cli.js"
  }
}

Each target must be a file inside the checkout. On Unix, targets must already be executable:

chmod +x bin/cli.js
lpm global link

Link does not install dependencies or build the package. Prepare the checkout before linking it. Changes to the target's contents are immediately available through the global command. If you change the package's name or bin mapping, unlink the old package and link it again.

Link rejects occupied command paths, invalid names, overlapping Windows launcher names, and a pending registry installation for the same package. On macOS and Windows, command-name comparisons also reject case collisions.

Unlink removes the recorded command files and global registration. It leaves the source checkout intact. It also works if the checkout or its global wrapper directory is gone.

If a command file differs from the recorded original, unlink stops and preserves it. Older links lack an original-file record, so unlink retains their wrapper directory and reports its path. Additional unrecorded files also remain in the wrapper directory.

Command collisions

A local link cannot take over an existing command. Unlink the local owner or remove the registry owner before linking the replacement.

For registry installations, lpm install -g supports deliberate replacement and aliases:

lpm install -g foo --replace-bin serve
lpm install -g foo --alias serve=foo-serve

Replacement transfers the command name. The previous package remains installed. An alias exposes the new package's command under a different name. The global link and global update commands do not accept these installation flags.

Remove a package

lpm global remove eslint
lpm global unlink my-cli

Use remove for registry packages and unlink for local checkouts. Registry removal also removes the package's aliases. Files held open by another process can delay directory cleanup. After you stop that process, lpm cache prune --apply can retry cleanup.

Recover an interrupted operation

Ordinary global commands attempt recovery before they proceed. A preview refuses pending recovery instead of changing that state.

lpm global list
lpm global update --dry-run

An interrupted local link removes unfinished command files unless its registration already committed. An interrupted unlink completes cleanup after its registration is removed.

Recovery preserves changed files, conflicting ownership records, and unexpected recovery files. If it reports a conflict, save the identified files separately and restore the expected state before retrying. Do not delete recovery state to bypass a conflict.

A missing or policy-blocked registry version also causes comparisons or update plans to fail. Inspect the package's saved specification and the release-age configuration before changing either.

Flags and JSON output

See the global flags for registry, authentication, color, and diagnostic controls.

An empty update set returns empty updated and skipped arrays instead of plans or results. retained_wrapper is null when unlink leaves no wrapper directory. Check success and the process exit status before treating a comparison or update as complete.

See also

• lpm install — install global executables and select security policy
• lpm uninstall — remove project or global dependencies
• lpm approve-scripts — review dependency script approvals
• lpm cache — retry deferred cleanup
• lpm config — configure user policy
• Registries — configure npm, LPM.dev Registry, and private registries