Project setup

LPM CLI splits project configuration across three files. Each owns a different kind of setting, by design:

The split is deliberate: anything that ships to consumers of your package lives in package.json. Anything that's about running the project locally lives in lpm.json. Anything that's about which way you personally (or the team) prefer the CLI to behave lives in lpm.toml.

package.json

Most LPM CLI behavior keys live under the "lpm" block — committed alongside dependencies so every contributor picks them up:

{
  "name": "my-app",
  "version": "1.0.0",
  "engines": { "node": ">=22.0.0", "lpm": ">=0.40.0" },
  "workspaces": ["packages/*"],

  "dependencies": { "react": "^19.0.0" },

  "lpm": {
    "linker": "isolated",
    "scriptPolicy": "deny",
    "trustedDependencies": ["esbuild", "sharp"],
    "scripts": {
      "autoBuild": false,
      "sandboxWriteDirs": ["build/"]
    }
  }
}

Full field reference: package.json "lpm" key.

lpm.json

Optional. Sits next to package.json and configures runtime / dev infrastructure:

{
  "$schema": "https://cli.lpm.dev/schemas/lpm.json",
  "runtime": { "node": ">=22.0.0", "bun": "1.3.14" },
  "tools": { "oxlint": "1.57.0", "biome": "2.4.8" },

  "env": {
    "dev":  ".env.development",
    "prod": ".env.production"
  },
  "envSchema": {
    "vars": {
      "DATABASE_URL": { "required": true, "format": "url" }
    }
  },

  "tasks": {
    "build": {
      "command": "tsup",
      "dependsOn": ["^build"],
      "cache": true,
      "outputs": ["dist/**"]
    }
  },

  "services": {
    "db":  { "command": "docker compose up postgres", "readyPort": 5432 },
    "web": { "command": "next dev", "port": 3000, "primary": true }
  },

  "publish": {
    "registries": ["lpm", "npm"]
  }
}

Full field reference: lpm.json.

The $schema line is optional but enables inline validation and field completion in any JSON-schema-aware editor.

lpm.toml

Optional. Sits next to package.json and pins per-project CLI defaults. It owns the save policy, workspace/test defaults, tidy ignores, sandbox defaults, and reviewable local policy exceptions:

save-prefix = "~"     # team prefers tilde over caret
save-exact  = false

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

Commit it for team-shared CLI defaults; .gitignore it if save policy should stay per-developer. The keys here override ~/.lpm/config.toml (user-level) but lose to CLI flags.

Full field reference: lpm.toml.

Local configuration size limits

LPM CLI bounds local configuration before UTF-8 decoding or parsing. The limit applies to the bytes read from the opened file, including the target of a supported symlink.

A missing optional file keeps its normal default or fallback behavior. A file that exists but exceeds its limit is not treated as missing: LPM CLI returns an error naming the path and byte limit. Install-time configuration fails before dependency resolution or registry access, and run-time configuration fails before a script or child process is spawned. This prevents an oversized higher-precedence file from silently changing registry, source, or security-policy selection.

Malformed or semantically invalid lpm.json fails before any project-bound environment operation can mutate local or remote state. That includes local secret operations, named --env resolution, validation, aliases, inheritance, schema operations, OIDC policy environment resolution, and lpm env push, which needs the complete alias, inheritance, and schema metadata to preserve environment boundaries. lpm env pull and lpm env rotate-key validate before network access or local vault replacement; lpm env share validates before sharing-key classification or registration. Only account-level operations that do not consult project configuration, such as browser pairing and sharing-key rotation, are unaffected by an unrelated malformed file. Oversized or unreadable configuration remains a hard error whenever the command needs it.

These small-file limits do not apply to lpm.lock / lpm.lockb, package tarballs and downloaded archives, package source or build outputs, patch and skill source payloads, README content, growing task/audit/webhook logs, or operating-system pseudo-files such as /proc. Those inputs retain their own streaming, integrity, rotation, or format-specific controls.

Safe atomic rewrites

LPM-managed atomic rewrites of project manifests, configuration, and state use an exclusively created, collision-resistant file in the destination directory. They do not follow an attacker-preplanted temporary symlink, hardlink, junction, or reparse entry. The final destination is replaced as a path entry rather than dereferenced, while existing regular-file modes and restricted 0600 outputs retain their intended Unix permissions.

The boundary is the audited atomic-rewrite paths. This does not provide arbitrary parent-directory confinement, cover every file written by LPM CLI or a package script, or imply crash durability unless a particular operation also synchronizes its file and parent directory.

Which file owns what

Quick decision table when you're not sure where a setting belongs:

.gitignore essentials

lpm init creates a .gitattributes entry for the binary lockfile automatically:

lpm.lockb binary

You probably want to ignore a few LPM CLI artifacts:

node_modules/
.lpm/                  # local install hash, security caches, skills, tunnel state
.env*.local            # local-only env overrides

.lpm/ holds project-local install state (install-hash, captured tunnel webhooks, agent skill markdown, etc.). The global store lives in ~/.lpm/, completely separate — nothing project-specific belongs there.

See also

• package.json "lpm" key — every field under the "lpm" block
• lpm.json — runtime / task / publish config
• lpm.toml — project-level CLI defaults
• ~/.lpm/config.toml — user-level CLI defaults
• Save policy — full precedence chain across these files