lpm self-update

Use lpm self-update to update LPM CLI or switch release channels. The command detects the installation method and uses its update process.

lpm self-update [--channel <stable|nightly>] [--refresh] [--json]

Quickstart

Update LPM CLI on its current release channel:

lpm self-update

Choose a task

This command manages the LPM CLI installation on your computer. lpm.json does not control or run CLI updates.

Release channels

Without --channel, LPM CLI uses the channel of the installed version. Stable versions continue on stable, and nightly versions continue on nightly.

A version such as 0.71.0-nightly.20260728.42.d82ceea selects nightly. A version without the nightly prerelease identifier selects stable.

An explicit --channel value changes the channel. A switch from nightly to stable can install a lower semantic version.

Homebrew and Cargo installations return an error for --channel nightly. Use npm or a standalone installation for nightly releases.

How the update runs

LPM CLI identifies the installation method from the current executable. Normal output and JSON output have different update behavior.

CAUTION: --json is not a universal preview. It applies the update for a standalone installation.

If the installed version is current, the command makes no change. If the installed version is newer, the command also makes no change.

Recipes

Update on the installed channel

lpm self-update

Use this command for normal updates. Stable and nightly installations remain on their current channels.

Switch to nightly

lpm self-update --channel nightly

Use nightly for early access to unreleased changes. Nightly releases can change more frequently than stable releases.

Return to stable

lpm self-update --channel stable

This command can replace a newer nightly version with a lower stable version. The channel change is intentional.

Retry a version lookup

lpm self-update --refresh

Use --refresh after a lookup failure, or after a release appears during the 10-minute cache period.

The flag also bypasses the one-hour cooldown after a failed lookup. It does not change the verification or installation process.

Get an external update plan

CAUTION: Use this recipe only for npm, Homebrew, or Cargo installations. A standalone installation applies the update.

lpm self-update --json

For an external installation method, read install_method and update_command. Then run the returned command in your normal update environment.

There is no universal dry-run flag for lpm self-update.

Run the update command manually

For npm, you can also follow a channel tag:

npm install -g @lpm-registry/cli@latest   # newest stable
npm install -g @lpm-registry/cli@nightly  # newest nightly

Cargo source verification

For a Cargo installation, LPM CLI verifies the signed release manifest before it starts Cargo.

The signature identifies the exact release workflow, Git reference, and source commit. LPM CLI then uses that commit with cargo install --rev.

The --locked flag makes Cargo use the dependency versions in the release lockfile. A moved Git tag cannot change the selected source commit.

lpm self-update --json applies the same verification. It returns the verified --rev command without running Cargo.

Update source trust

LPM CLI uses a different trust model for each installation method.

LPM CLI resolves each external manager from a filtered PATH. The manager must use an absolute, non-project path with trusted ownership.

LPM CLI verifies the manager file before it runs the update. It also verifies the installed LPM CLI version after the update.

These checks do not add independent artifact attestation to registry managers or Homebrew. Their configured repositories remain part of the trust boundary.

Cargo ownership detection reads the local Cargo install metadata. Stale metadata does not prove the build provenance of the current executable.

LPM CLI rejects intermediate manager and configuration symlinks. It accepts a leaf manager symlink only for a target that passes the same checks.

For manager ownership detection, XDG_CONFIG_HOME must resolve inside the account home. LPM CLI ignores an external configuration root.

Version lookup and cache

LPM CLI reads the npm latest or nightly tag first. If that lookup fails, it uses the corresponding GitHub Releases data.

Successful lpm self-update lookups remain cached for 10 minutes. Stable and nightly use separate cache state in ~/.lpm/update-check.json.

A failed lookup starts a one-hour cooldown for that channel. During the cooldown, the command returns the previous error state without a network request.

Use --refresh to bypass the successful-result cache and the failure cooldown.

Background update notices

Normal LPM CLI commands can print a cached update notice after their command output. JSON commands do not print this notice.

LPM CLI refreshes the update information in a detached process. The command does not wait for this network request.

After a successful background lookup, LPM CLI waits 24 hours before another lookup. A failed lookup has a one-hour cooldown.

Disable background lookups and cached update notices for a command with this environment variable:

LPM_NO_UPDATE_CHECK=1 lpm install

LPM_NO_UPDATE_CHECK does not disable an explicit lpm self-update.

Standalone update verification

For a standalone installation, LPM CLI downloads the release files and completes these steps before it replaces the binary:

1. It verifies that the signed manifest comes from the expected LPM CLI release workflow.
2. It verifies that the signed Git reference and source commit match the requested version.
3. It verifies that the signature time matches the GitHub release time.
4. It verifies the checksum of the manifest.
5. It verifies the downloaded binary against the manifest.

If any verification step fails, LPM CLI refuses the update and retains the current binary.

The updater attempts to copy the current binary to <binary>.previous. This backup is best-effort and can be absent after a permission error.

Supported standalone targets

There is no standalone Linux ARM64 musl asset. On that platform, install from source.

macOS app bundle compatibility

The updater accepts signed app bundles with and without the optional application icon. It still checks required files, code signatures, notarization, and the signing identity. Removing a resource covered by the app signature causes verification to fail.

The standalone updater shipped in 0.76.5 cannot read newer app bundles. If it reports an unexpected Contents/Resources/ entry, rerun the installer once:

curl -fsSL https://cli.lpm.dev/install | sh

To recover onto the latest nightly:

curl -fsSL https://cli.lpm.dev/install | LPM_INSTALL_CHANNEL=nightly sh

The installer preserves saved credentials and configuration. It retains the installer verification checks. Do not disable verification or delete your credentials. For npm and Homebrew installations, use the package manager.

Recover from a standalone update error

If verification fails, do not replace the current binary manually with the rejected download. Retry later or install a trusted exact version.

If the new binary cannot start, look for <binary>.previous beside it. Restore that backup manually, or reinstall an exact release.

The standalone updater does not provide an automatic rollback command. See Installation for exact-version and source installations.

Do not replace the binary with a raw curl or Invoke-WebRequest download. Those commands do not apply the verification steps on this page.

Filesystem and process limits

The update lock prevents concurrent LPM CLI updates on local filesystems. Advisory lock behavior on NFS and SMB depends on the filesystem.

On Unix, the update lock is account-specific. The package manager must coordinate updates across accounts that share one installation.

CAUTION: If the LPM CLI installation is on a shared filesystem, run updates from one host at a time.

A process with the same account permissions can replace parent directories, manager paths, or staged files after the final check.

The updater does not protect against a compromised user account or an administrator. Operating-system access controls provide this protection.

On Windows, trusted write access includes the current account, Administrators, SYSTEM, and TrustedInstaller. LPM CLI accepts an OWNER RIGHTS entry only when it trusts the file or directory owner. LPM CLI rejects reparse points in checked paths.

The Windows installation lock uses a global operating-system name. Another local account can block updates by reserving that name.

Homebrew can use user-owned, group-writable directories. LPM CLI accepts this layout only for directories owned by the current account.

LPM CLI terminates the manager process group after errors and timeouts. On Unix, a child that creates a new session can survive cleanup.

JSON output

CAUTION: On a standalone installation, lpm self-update --json verifies and applies the update.

Already current

{
  "success": true,
  "current": "0.71.0",
  "latest": "0.71.0",
  "up_to_date": true,
  "cache_hit": false,
  "channel": "stable",
  "target_channel": "stable",
  "channel_changed": false
}

External update plan

For npm, Homebrew, and Cargo, JSON output reports the update command but does not run it:

{
  "success": true,
  "current": "0.71.0",
  "latest": "0.72.0",
  "up_to_date": false,
  "install_method": "npm",
  "update_command": "npm install -g @lpm-registry/cli@0.72.0",
  "cache_hit": false,
  "channel": "stable",
  "target_channel": "stable",
  "channel_changed": false
}

success: true means that version discovery and plan creation succeeded. It does not mean that the external update was applied.

Applied standalone update

For a standalone installation, JSON output applies the update and includes its verification record:

{
  "success": true,
  "current": "0.71.0",
  "latest": "0.72.0",
  "up_to_date": false,
  "install_method": "standalone",
  "cache_hit": false,
  "channel": "stable",
  "target_channel": "stable",
  "channel_changed": false,
  "verified": true,
  "attestation": {
    "publisher": "<verified publisher>",
    "workflow_path": ".github/workflows/release.yml",
    "workflow_ref": "<verified workflow reference>",
    "integrated_time": "2026-08-05T12:00:00+00:00",
    "log_index": 123456789,
    "log_id": "<transparency log ID>",
    "leaf_cert_sha256": "<certificate SHA-256>",
    "manifest_sha256": "<manifest SHA-256>",
    "asset_sha256": "<binary SHA-256>",
    "asset_name": "lpm-darwin-arm64",
    "source_commit": "<verified source commit>"
  }
}

Common fields

Outcome fields

attestation fields

GitHub fallback limits

GitHub permits 60 unauthenticated API requests each hour for one IP address. This limit matters only after the npm lookup fails.

Set GITHUB_TOKEN or GH_TOKEN to use the authenticated limit of 5,000 requests each hour. Public repository metadata access is sufficient.

If the fallback reaches its limit, LPM CLI reports the reset time. Wait for that time, or supply a token.

CI

Do not run lpm self-update during a CI job. An update changes the toolchain during the job and makes the build less reproducible.

Pin an exact npm package version or standalone release instead. Change that pin in a reviewed project update.

Use lpm health for a registry connectivity test.

Flags

See the global flags.

See also

• Installation — install or reinstall LPM CLI
• lpm doctor — inspect the project and local environment
• lpm health — verify registry connectivity
• LPM CLI releases — read release notes and download exact versions