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. Useful in CI. |
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. Direct non-loopback HTTP also requires --insecure; that flag does not allow an HTTPS redirect to downgrade to HTTP. |
LPM_OIDC_TOKEN | Canonical pre-supplied OIDC token for registry-exchange surfaces — lpm setup ci npmrc --oidc, npm firewall checks in CI, the lpm publish auto-exchange path, and lpm env pull --oidc. The audience must be https://lpm.dev (the snippet emitted by lpm setup ci gitlab mints it correctly via the id_tokens block). When set, the bypass takes precedence over the GitHub Actions runtime fetch, so self-hosted runners can opt out of the runtime call. Does not affect lpm publish --provenance — Sigstore needs an audience-sigstore token instead. |
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 | Override the project's resolved vault-id when running lpm env operations. Useful in CI workflows that target a vault other than what the checked-out project's lpm.json > "vault" field would resolve to (e.g., the lpm setup ci github-actions snippet sets this on the lpm env pull --oidc step). Falls back to the project's vault-id when unset. 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). Moves the store, cache, global installs, and user config. Useful for hermetic CI runs and 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; in CI, LPM_TOKEN or stored auth is used first, and registry-audience OIDC is exchanged only when no bearer is already available. 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 lpm.json > runtime.node or lpm.json > runtime.bun is missing locally. |
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 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; switching relays changes who brokers tunnel connections. Useful for local development against a custom worker, staging, or future regional endpoints. Whitespace / empty values fall through. The TLS certificate is pinned per host under ~/.lpm/relay-pins/<host> — switching relays starts a fresh TOFU pin for that host. Persistent equivalent: tunnel.relay-url in ~/.lpm/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_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, v2 reusable-object validation, and v2 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.