# Environment variables (/docs/reference/env-vars) 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. ## Auth and routing [#auth-and-routing] | Variable | Effect | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LPM_TOKEN` | Use this token instead of the OS-keychain-stored token. Equivalent to the global `--token ` flag. Useful in CI. | | `LPM_REGISTRY_URL` | Override the registry URL. Equivalent to `--registry `. 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](/docs/infra/secrets-vault#per-project-identity). | ## npm publish and provenance [#npm-publish-and-provenance] These npm-compatible variables are read by [`lpm publish`](/docs/packages/publish#provenance) 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 --token `. | | `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`. | ## Filesystem layout [#filesystem-layout] | 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`. | ## Install pipeline [#install-pipeline] | 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=`. Sits below `--linker` and `~/.lpm/config.toml > linker` in the [precedence chain](/docs/reference/config-toml#exception-linker), 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](/docs/packages/install#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. | ## Security and recovery overrides [#security-and-recovery-overrides] 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`](/docs/infra/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 `.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](/docs/dev/builtin-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. | ## Remote task cache [#remote-task-cache] | 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. | ## Triage advisor cache [#triage-advisor-cache] The Layer 5 [LLM advisor](/docs/packages/security-audit#verdict-cache) 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. | ## Tunnel [#tunnel] | 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/` — switching relays starts a fresh TOFU pin for that host. Persistent equivalent: `tunnel.relay-url` in `~/.lpm/config.toml`. | ## Resolver (advanced) [#resolver-advanced] | 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. | ## Diagnostic / experimental [#diagnostic--experimental] 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 | on | off\`. | | `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. | | | ## Test-only / sandboxed environments [#test-only--sandboxed-environments] | 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](/docs/infra/secrets-vault#local-storage). | | `LPM_TEST_*` | Reserved for the test suite; not user-facing. | ## Precedence reminder [#precedence-reminder] 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**. ## See also [#see-also] * [Global flags](/docs/commands#global-flags) — CLI flags equivalent to several of these vars * [`lpm config`](/docs/infra/config) — for persistent CLI defaults instead of env vars * [`~/.lpm/config.toml`](/docs/reference/config-toml) — file-backed config alternative