Environment variables
Environment variables LPM CLI reads for auth, routing, publishing, diagnostics, and CI.
LPM CLI reads a number of environment variables to override behavior, route auth, or expose diagnostic knobs. Most users never need to touch these — they exist for CI, debugging, recovery, and uncommon workflows.
Variables are grouped by purpose. Anything marked diagnostic is a debug-only escape hatch — not a stable, documented user knob.
| Variable | Effect |
|---|
LPM_TOKEN | Use this token instead of the OS-keychain-stored token. Equivalent to the global --token <T> flag and also the highest-priority credential for the LPM.dev Registry MCP server. Useful in CI or editor environments without keychain access. |
LPM_DISABLE_HOST_CLI_AUTH | Set to 1 or true to disable credentials from gh and glab. Environment tokens and fallback tokens stored by LPM CLI remain available. Useful in automation that must not inherit a local host CLI session. |
LPM_REGISTRY_URL | Override the registry URL. Equivalent to --registry <URL>. Use only trusted registry endpoints: this controls where package metadata requests and registry-scoped credentials are sent. When inherited by the editor, the MCP server uses an accepted HTTPS or HTTP-loopback URL for registry-scoped keychain lookup; it has no equivalent of the CLI's --insecure exception for remote HTTP. Direct non-loopback HTTP in the CLI requires --insecure, which does not allow an HTTPS redirect to downgrade to HTTP. |
LPM_OIDC_TOKEN | Canonical pre-supplied OIDC token for the lpm publish auto-exchange path and lpm env pull --oidc. The audience must be https://lpm.dev. When set, it takes precedence over the GitHub Actions runtime fetch, so self-hosted runners can opt out of that call. Does not affect lpm publish --provenance — Sigstore needs an audience-sigstore token instead. |
LPM_OIDC_POLICY_ID | Required server-issued policy selector for lpm env pull --oidc. Get the UUID from lpm env oidc allow or lpm env oidc list. --policy-id=<uuid> takes precedence. The value is not a bearer credential, but CI configuration must protect its integrity. It does not affect package publishing. |
LPM_GITLAB_OIDC_TOKEN | Legacy GitLab alias. Accepted on the registry-exchange and provenance surfaces for back-compat. New setups should mint LPM_OIDC_TOKEN (registry exchange) or SIGSTORE_ID_TOKEN (provenance). |
SIGSTORE_ID_TOKEN | GitLab CI OIDC token with audience sigstore, minted via the id_tokens block. Drives lpm publish --provenance on GitLab. Not used by registry-exchange surfaces (wrong audience). |
LPM_VAULT_ID | Vault ID for lpm env pull --oidc only. A non-empty, trimmed value takes precedence over lpm.json > "vault" and can bootstrap a checkout with no local vault field. An unset, empty, or whitespace-only value falls back to the local field; the pull fails if neither source is available. Other lpm env operations ignore it. See Secrets vault — Per-project identity. |
These npm-compatible variables are read by lpm publish and lpm stage publish. Provenance-file values attach only to npm-compatible targets; lpm publish rejects them when an lpm.dev target is active.
| Variable | Effect |
|---|
NPM_TOKEN | Token auth for the default npm registry when npm Trusted Publishing is not available. For non-default npm-compatible registries, store an exact registry-scoped token with lpm login --login-registry <URL> --token <T>. |
NPM_ID_TOKEN | Pre-supplied npm Trusted Publishing OIDC token. The audience must be npm:registry.npmjs.org. Used for lpm publish --npm and lpm stage publish against the default npm registry. |
NPM_CONFIG_PROVENANCE / npm_config_provenance | Truthy values (true, 1, yes, on) enable generated Sigstore provenance. Falsy values disable it unless a higher-precedence CLI flag or package.json > publishConfig.provenance overrides it. Mutually exclusive with NPM_CONFIG_PROVENANCE_FILE. |
NPM_CONFIG_PROVENANCE_FILE / npm_config_provenance_file | Path to a pre-generated Sigstore bundle to attach to npm-compatible publish targets. Relative paths are resolved from the project directory. Mutually exclusive with NPM_CONFIG_PROVENANCE. |
| Variable | Effect |
|---|
LPM_HOME | Override the LPM CLI root (~/.lpm by default). This path contains the store, cache, global installs, user config, and tunnel pins. Use it for hermetic CI runs or local development. It does not move the OS-managed policy used by lpm security protect. |
| Variable | Effect |
|---|
LPM_LINKER | node_modules layout for installs in this process. Accepts isolated (pnpm-style strict-deps) or hoisted (LPM CLI's v2 hoisted virtual-store layout). Useful for forcing a specific layout in CI without editing config or per-invocation flags; setting it also opts out of default peer-conflict auto-isolation. Equivalent to --linker=<value>. Sits below --linker and ~/.lpm/config.toml > linker in the precedence chain, and above package.json > lpm > linker. Unknown values fail loudly at install time — there is no silent fallback, even on the up-to-date cache fast path. Empty-string (LPM_LINKER="") is treated the same as unset, so an unset NAME || NAME="" automation pattern doesn't accidentally pin a layout. |
LPM_VERIFY_REGISTRY_SIGNATURES | Enables install-time npm registry package signature verification for this process. Accepts truthy values such as 1, true, yes, on, or enabled; otherwise falls back to ~/.lpm/config.toml > signatures. Persistent equivalent: lpm config signatures --set true. |
LPM_NPM_FIREWALL | Tighten LPM Firewall verdict checks for npm packages in this process. Accepts off, monitor, or enforce, but cannot weaken a stricter ~/.lpm/config.toml > [firewall].mode value. report remains accepted as a legacy alias for monitor. Active modes send LPM.dev Registry auth because the hosted verdict service is an LPM.dev Registry Pro/Org feature; use LPM_TOKEN in CI. Persistent equivalent: lpm config firewall --set monitor|enforce. |
LPM_V2_OBJECT_INTEGRITY | Override reused v2 store object validation for this process. source is the default fast source-identity check; tree rehashes expanded files before reuse to detect local store tampering/corruption. Legacy aliases sri and tarball mean source. Persistent equivalent: lpm config integrity --set source|tree. |
LPM_AUDIT_AFTER_INSTALL | Toggle audit after install for this process. Accepts 1 / true / yes / on (enable) and 0 / false / no / off (disable). Anything else falls through to ~/.lpm/config.toml > audit-after-install. Per-invocation overrides: --audit-after-install / --no-audit-after-install. Findings are informational — they never fail the install. |
LPM_CONCURRENT_DOWNLOADS | Cap the number of concurrent tarball downloads during install and lpm fetch. Integer in 1..=256; default 24. Out-of-range or unparseable values warn on stderr and fall back to the default — set this only when you have a measured reason. |
LPM_NO_AUTO_INSTALL | Set to true to disable automatic managed-runtime installation when a Node or Bun runtime selector is missing locally. It does not affect package.json > engines.node, which never installs a runtime. |
LPM_FORCE_TOOL_INSTALL | Set to 1 to force re-download a built-in tool even if the binary already exists in the cache. Useful when a downloaded binary has been corrupted. |
These variables are read by the shell installer, not by an installed lpm binary.
| Variable | Effect |
|---|
LPM_INSTALL_CHANNEL | Release channel to resolve when LPM_INSTALL_VERSION is unset. Accepts stable (default) or nightly. |
LPM_INSTALL_VERSION | Exact GitHub release tag to install, including the leading v. Accepts stable and prerelease tags and skips the moving-channel lookup. |
These are intentionally sharp controls. Use them only for recovery, local wrapper testing, or explicit security-policy exceptions.
| Variable | Scope | Effect |
|---|
LPM_PROVENANCE_ENFORCE | CLI runtime | Sigstore provenance posture for this process: deny (default), warn, or off. warn and off weaken verification, are surfaced by lpm security status, and are guarded by the security-approval layer on install/trust mutation paths. Unknown values fail at startup. |
LPM_ALLOW_UNVERIFIED_PLUGINS | Managed plugins | Set to 1 to install a plugin without checksum verification when neither a bundled nor an upstream <asset_url>.sha256 is available. The override is recorded on the plugin sidecar; reuse requires this variable on every subsequent invocation. See Built-in tools — Checksum verification. |
LPM_BINARY_PATH | npm wrapper | For the @lpm-registry/cli JavaScript launcher only: execute this exact native binary instead of the platform package resolved from optionalDependencies. Useful for local wrapper testing or emergency recovery, but a polluted environment can replace the executable behind lpm / lpx. |
LPM_INSTALL_INSECURE | Standalone installer | Set to 1 for the curl -fsSL https://cli.lpm.dev/install | sh installer to skip all download integrity checks. Emergency-recovery only; installed lpm binaries do not read this variable. |
LPM_INSTALL_MIN_VERSION_OVERRIDE | Standalone installer | Set to 1 to bypass the installer's minimum-version floor when intentionally installing an older release. SHA-256 verification against the downloaded manifest still runs unless LPM_INSTALL_INSECURE=1 is also set. When both cosign and the release bundle are available, the installer additionally authenticates the manifest through Sigstore and fails closed on rejection. |
| Variable | Effect |
|---|
LPM_REMOTE_CACHE | 1 / true enables hosted task cache for cache-enabled tasks even when lpm.json > remoteCache.enabled is absent. 0 / false disables it for this process. |
LPM_REMOTE_CACHE_TOKEN | Bearer token for hosted cache reads and writes. Falls back to LPM_TOKEN or the token from lpm login only when the cache endpoint shares the configured registry origin. Third-party cache hosts require this variable. |
LPM_REMOTE_CACHE_URL | Override the hosted cache endpoint. Defaults to the configured registry plus /v8. Direct HTTP is accepted only for localhost, and an automatically followed HTTPS redirect cannot downgrade to HTTP. Hosts outside the configured registry origin also require LPM_REMOTE_CACHE_SIGNATURE_KEY. |
LPM_REMOTE_CACHE_TEAM | Organization slug/team namespace. Falls back to lpm.json > remoteCache.team; unset means the authenticated personal namespace. |
LPM_REMOTE_CACHE_SIGNATURE_KEY | HMAC key for signed remote artifacts. Required when lpm.json > remoteCache.signature is true or the cache endpoint is outside the configured registry origin. |
LPM_REMOTE_CACHE_READ_ONLY | 1 / true reads hosted artifacts but skips uploads for this process. |
The Layer 5 LLM advisor persists verdicts at $LPM_HOME/cache/l4-verdicts.json so repeat installs of the same (name, version) skip the advisor round-trip.
| Variable | Effect |
|---|
LPM_L4_CACHE | Set to 0 to disable the verdict cache entirely (lookups miss, inserts are dropped). Default: enabled. Useful for measurement runs that need the cold-cache round-trip cost. |
LPM_L4_CACHE_PATH | Override the cache file location. Defaults to $LPM_HOME/cache/l4-verdicts.json. |
LPM_L4_CACHE_TTL_SECS | Override the verdict TTL in seconds. Default: 30 days. Expired entries are re-classified on next encounter. |
| Variable | Effect |
|---|
LPM_TUNNEL_RELAY | Override the tunnel relay WebSocket URL (default: wss://relay.lpm.fyi/connect). Use only trusted relay endpoints. A different relay changes the broker for tunnel connections. Use this variable for a custom worker, staging, or future regional endpoints. Empty or whitespace-only values use the next precedence level. LPM CLI stores each TLS pin at $LPM_HOME/relay-pins/<host>. A new relay host gets a new TOFU pin. Persistent equivalent: tunnel.relay-url in $LPM_HOME/config.toml. |
| Variable | Effect |
|---|
LPM_RESOLVER | pubgrub opts out of the default greedy-fusion resolver and uses the legacy PubGrub-with-split-retry resolver. Both speak npm-compatible semver. |
LPM_GREEDY_FUSION | 0 disables the fused dispatcher and falls back to the walker-arm orchestration for debugging. |
LPM_WALKER | Walker-dispatch picker. Diagnostic. |
LPM_NPM_FANOUT | Cap concurrent npm metadata fetches in the resolver. |
LPM_NPM_ROUTE | direct or proxy. Debug-only override of the npm package routing decision (default routes @lpm.dev/* through the LPM.dev Registry worker, everything else direct to registry.npmjs.org). Not a stable user knob. |
These exist for benchmarking and debugging. Don't depend on them in production.
| Variable | Effect |
|---|
LPM_HTTP | h1-pool forces an HTTP/1 connection pool instead of the default HTTP/2 path. |
LPM_STREAM_FETCH | Streaming-fetch mode toggle for the install pipeline. |
LPM_STORE_VERSION | Select the store layout for this process. Unset, empty, v2, or 2 uses the default v2 layout. v3 or 3 explicitly selects the experimental file-level CAS; LPM CLI never selects it automatically from the filesystem or CI environment. v1 or 1 is the legacy rollback path. Unknown values warn and fall back to v2. |
LPM_TIMING_DETAIL | Add env-gated install timing probes to lpm install --json. Set to any value for timing.detail; set to trace to also include slow package buckets and duplicate metadata rankings. Includes cache classification, reusable-object validation, v3 CAS validation, and virtual-store link-task timing. Diagnostic. |
LPM_SERIAL_LINK | Disable parallel linking — useful for reproducing race conditions. |
LPM_TYPOSQUAT_GUARD | Diagnostic typosquat analysis toggle. 0, false, off, or disabled skip suspicious-name analysis only when ~/.lpm/config.toml > typosquat-guard is absent, force-security-floor = true is not active, and managed policy does not own the typosquat floor. Persistent user-facing control: `lpm config typosquat --set default |
LPM_EXPERIMENT_NPM_FIREWALL | Legacy benchmark alias for LPM_NPM_FIREWALL. Prefer the config wizard or LPM_NPM_FIREWALL for new runs. |
LPM_EXPERIMENT_NPM_FIREWALL_LOOKUP | Diagnostic firewall lookup mode. Defaults to package-only; integrity, strict, or package-and-integrity enables the stricter integrity sidecar lookup for data-contract testing. |
LPM_EXPERIMENT_NPM_FIREWALL_CHUNK_SIZE | Diagnostic firewall verdict chunk size. Defaults to 64; non-positive or invalid values fall back to the default. |
LPM_MAX_BLOCKING_THREADS | Cap the tokio blocking-pool size. A/B benching hook for the install hot path. |
LPM_DEEP_FOLLOWUP | Resolver follow-up depth knob. |
| Variable | Effect |
|---|
LPM_FORCE_FILE_AUTH | Disable the OS keychain for token storage and force the encrypted-file fallback. Used by the test suite; also useful in sandboxed environments where the keychain isn't reachable. |
LPM_FORCE_FILE_VAULT | In debug/test builds, bypass native vault-key storage and force the encrypted-file fallback under ~/.lpm/vaults/ with ~/.lpm/.vault-fallback-key. Release builds ignore this override and use the platform default. See Secrets vault — Local storage. |
LPM_TEST_* | Reserved for the test suite; not user-facing. |
For settings that have both a CLI flag and an env var (--token / LPM_TOKEN, --registry / LPM_REGISTRY_URL, --linker / LPM_LINKER), the CLI flag wins.