lpm.toml reference

lpm.toml is an optional TOML file that sits next to package.json. It pins per-project defaults for behaviors that aren't part of publishable package metadata — most notably the save policy and the project sandbox posture.

LPM CLI reads this file with a 16 MiB limit enforced before TOML parsing. Missing remains equivalent to no project-level config; an oversized file fails with its path and byte limit instead of falling through to user defaults. See local configuration size limits for the complete scope and exclusions.

The file is intentionally separate from package.json > lpm because these keys are tool behavior, not publishable metadata. Mixing them into the manifest creates avoidable diff churn whenever someone tweaks a personal preference. Keeping them in lpm.toml lets each team decide whether to commit the file or .gitignore it.

Today's keys

lpm.toml

save-prefix = "^"     # one of "^", "~", or "" (empty for exact, no prefix)
save-exact  = false   # bool; true forces exact regardless of save-prefix

[workspace]
concurrency = 4       # positive integer; caps workspace run/test/bench fan-out
changed-files-ignore-pattern = ["**/README.md", "docs/**"]
test-pattern = ["**/*.test.js", "**/*.spec.ts"]

[sandbox]
mode = "default"      # "default" | "strict" | "none"
allow-degraded = false

[tidy]
ignore-unused = ["eslint-config-next"]
ignore-phantom = ["virtual:*"]
ignore-paths = ["generated/**"]

[[policy.typosquat.allow]]
package = "axois"
similar-to = "axios"
reason = "Intentional internal compatibility package"

Key	Type	Default	Notes
`save-prefix`	`"^"` \| `"~"` \| `""`	`"^"`	Prefix applied when `lpm install <pkg>` saves to `package.json`. `` is not* accepted.
`save-exact`	bool	`false`	Force exact saves regardless of `save-prefix`.
`workspace.concurrency`	positive integer	available parallelism	Project default for concurrent workspace members in `lpm run`, `lpm test`, and `lpm bench` workspace mode.
`workspace.changed-files-ignore-pattern`	string or string array	`[]`	Project default for git-diff paths to ignore before `[git-ref]` filters or `--affected` map changed files to members. CLI `--changed-files-ignore-pattern` entries append to this list.
`workspace.test-pattern`	string or string array	`[]`	Project default for changed files treated as test-only. Test-only packages stay selected, but they do not seed dependent fan-out for `[git-ref]` reverse closures or `--affected`. CLI `--test-pattern` entries append to this list.
`sandbox.mode`	`"default"` \| `"strict"` \| `"none"`	`"default"`	Project-default lifecycle-script sandbox posture. CLI flags still win per invocation.
`sandbox.allow-degraded`	bool	`false`	Allow degraded sandbox fallback for this repo on hosts that cannot provide the full posture.
`tidy.ignore-unused`	string or string array	`[]`	Suppress `lpm tidy` unused-dependency findings by package-name glob.
`tidy.ignore-phantom`	string or string array	`[]`	Suppress `lpm tidy` phantom-import findings by package-name glob.
`tidy.ignore-paths`	string or string array	`[]`	Ignore source imports from matching project-relative path globs during `lpm tidy`.
`policy.typosquat.allow[]`	table array	`[]`	Reviewable exceptions for intentional suspicious direct package names. Each entry needs `package`, `reason`, and optionally `similar-to`.

Invalid values (save-prefix = "*", save-prefix = ">=", etc.) are rejected at load time with a clear error pointing at the offending file. Unknown keys are accepted silently for forward compatibility.

Precedence

Save policy

Save policy resolves in this order, highest first:

CLI flag — --exact, --tilde, or --save-prefix '<p>' on the install command
./lpm.toml — this file
~/.lpm/config.toml — user-level fallback
Built-in default — save-prefix = "^", save-exact = false

See Save policy for the full table of how each combination flows into package.json.

Workspace concurrency

Workspace package fan-out for lpm run, lpm test, and lpm bench resolves in this order, highest first:

CLI flag — --workspace-concurrency <N>
./lpm.toml > [workspace].concurrency — this file
~/.lpm/config.toml > workspace-concurrency — user-level fallback
Built-in default — available host parallelism

Git-diff workspace filters

changed-files-ignore-pattern and test-pattern under [workspace] are project defaults for workspace selections that read git changes: [git-ref] filter atoms and --affected. CLI flags append to the project lists for the current invocation.

Sandbox

Sandbox mode resolves in this order, highest first:

CLI flag — --no-sandbox, --strict-sandbox, or --paranoid
LPM_STRICT_SANDBOX — strict-mode env override
./lpm.toml > [sandbox] — this file
~/.lpm/config.toml > [sandbox] — user-level fallback
Built-in default — mode = "default", allow-degraded = false

If this repo asks for a weaker sandbox than the machine currently allows, install or rebuild does not silently obey the file. It fails with error_code: "security_approval_required" and points you at lpm security unlock instead.

Tidy ignores

[tidy] keys are project-local only. They affect lpm tidy report and fix mode; ignore-unused and ignore-phantom match package names, while ignore-paths matches project-relative source paths before imports are analyzed.

Typosquat policy

policy.typosquat.allow is the committed exception list for suspicious direct package names. It is consulted by lpm install and lpm add before network access or manifest mutation.

lpm.toml

[[policy.typosquat.allow]]
package = "crossenv"
similar-to = "cross-env"
reason = "Internal migration package kept for compatibility"

package is the exact direct dependency name to allow. similar-to narrows the exception to the popular package LPM CLI detected; omit it only when the same local name may intentionally resemble more than one popular package. reason is required so the exception is reviewable in code review.

lpm.toml

Today's keys

Precedence

Save policy

Workspace concurrency

Git-diff workspace filters

Sandbox

Tidy ignores

Typosquat policy

See also

On this page