Project health

Understand what LPM CLI examines, how health results affect automation, and which automatic fixes change a project.

Project health combines the state of your manifest, installed packages, runtimes, security posture, tools, and connected services.

lpm doctor turns these areas into named results. Use the report to find the cause of an install or environment problem.

# Inspect local project state
lpm doctor

# Include tools, machine state, and connected services
lpm doctor --all

# Explain a result from either report
lpm doctor list --code <CODE>

The command reference contains the complete syntax, result catalog, and flags.

Understand the health layers

LPM CLI separates core project state from broader machine and service state.

Health layer	Default mode	Full mode adds
Project and install	Shared-store access, manifest, linker mode, `node_modules`, lockfiles, dependency synchronization, local sources, and workspace cycles	Store orphans, tracked `.lpm/` state, and manifest compatibility
Runtime and security	Node.js, Bun, policy extensions, auth storage, local secret storage, an `LPM_HOME` that leaves login or env data unused, and Sigstore posture	Sandbox and lifecycle-script policy
Project configuration	`lpm.json` structure, runtime pins, tasks, tools, and services	Tunnel ownership and reachability
Tools and machine	None	Lint, format, TypeScript readiness, plugin versions, global installs, PATH, and shims
Connected services	None	Registry health, registry authentication, and tunnel requests

Some tool results apply only to configured or installed tools. Full mode always examines registry authentication and reports a failure when credentials are missing.

Secret-storage results describe the selected backend or available local keys. A passing result does not prove that LPM CLI can decrypt every secret.

The Sigstore result reports the verification mode. Verification scope and fetch availability remain separate controls. See security controls.

Choose fast or full health

Run the default health report from the project root or one of its subdirectories:

lpm doctor

Doctor examines the nearest directory at or above the current one that has a package.json or an lpm.json, stopping before your home directory. It prints the directory when that is not the current one.

Without repairs, the default mode reads local project and LPM CLI state. It does not contact a registry or tunnel service.

Runtime detection can run node --version or bun --version. Each process has a two-second limit. The default mode does not run lint or format tools.

Run the full report for machine, tool, and service health:

lpm doctor --all

Mode	Use case	Cost
Default	An install, runtime, lockfile, or local project state looks incorrect	Local file access and runtime detection
`--all`	You need a complete environment report, including registry authentication	Tool processes, machine inspection, and network requests

The full mode includes every default result. Tool timeouts and network conditions can make it take longer.

Use project configuration

LPM CLI reads lpm.json automatically. You do not need a separate doctor flag.

For example:

lpm.json

{
  "runtime": {
    "node": "22"
  },
  "tunnel": {
    "domain": "my-api.lpm.fyi"
  }
}

The default mode examines the runtime pin and relevant project fields. The full mode also examines the configured tunnel domain.

Doctor reports invalid JSON, unrecognized fields, and a vaultSync block, which is one checkout's env sync state and belongs in .lpm/. It also reports runtime or workspace problems that the project configuration creates.

See the lpm.json reference for the complete project configuration.

Interpret health results

Each result has a severity, a short name, and current details. JSON output also includes its stable code.

Severity	Meaning	Exit code effect
`pass`	The examined state is healthy or informational	None
`warn`	The state needs attention but does not block the command	None
`fail`	The state is broken or required state is unavailable	Exit code `1`

Warnings keep exit code 0. A report with warnings is not clean, but it has no failures.

The default terminal output hides most passing results. It keeps failures, warnings, linker mode, and active policy extensions visible.

The full terminal output includes passing results. If you need every emitted result from either mode, use JSON.

Find the meaning of a result

Use checks[].code from JSON output to find the catalog entry:

lpm doctor list --code <CODE>

The catalog describes the result, its possible severities, and the recommended action.

List results by category:

lpm doctor list --category "project state"
lpm doctor list --category runtime --json

Match automation on code. Human-readable names and details can change.

Repair supported problems

CAUTION: Save your project changes before a repair. Automatic fixes can change project files and installed dependencies.

lpm doctor --fix

LPM CLI shows the planned actions and asks for confirmation. After the fixes, it reloads the root and member manifests. Then it runs the selected diagnostics again. The final report describes the resulting state. Repairs apply to the initial report. The final report can show remaining or newly discovered problems.

Repairs can install dependencies or download runtimes, even without --all.

-y and --yes enable fixes and skip confirmation. Non-interactive and JSON repair runs require --yes when applicable fixes exist:

lpm doctor --fix --yes --json > doctor-repair.json

The report separates completed actions in fixes_applied from failed actions in fixes_failed. Failed actions also appear in the final terminal summary. A failed action keeps the exit status unsuccessful, even if later checks pass.

The full mode can also prune shared store entries, update plugins, and claim a configured tunnel domain:

lpm doctor --all --fix

Current automatic fixes

Problem	Automatic action
Missing, mixed, legacy, or unmanaged `node_modules` state	Run lpm install
Missing lockfile or dependency drift	Run lpm install
Missing, stale, or corrupt `lpm.lockb`	Reconcile it with `lpm.lock`. Remove it when the graph requires TOML-only metadata
Missing managed Node.js version	Install the selected Node.js version. If Node.js is missing and no version is pinned, install Node.js 22
Missing managed Bun version	Install the selected Bun version
Project-level `node_modules` link	Replace only the link with a real directory
Format result from the full mode	Run `lpm fmt`
Store orphans from the full mode	Prune unreachable store entries
Unclaimed configured tunnel from the full mode	Claim the domain for the current account
Plugin update from the full mode	Update the installed plugin

Some failures require a user decision. For example, doctor does not add TypeScript or change a tunnel domain that another account owns.

In lpm doctor list --json, a non-null auto_fix value identifies the supported action for that code. A null value means no automatic fix exists.

Use auto_fix to identify available repairs. After repair, read both action lists and the fresh diagnostic results.

Use health results in CI

Create a local diagnostic report without repairs:

lpm doctor --json > doctor-report.json

For a complete report, add --all. This mode requires registry credentials for a passing authentication result.

If the CI job must not repair the workspace, omit --fix, --yes, and -y.

Use these fields for automation:

Field	Meaning
`success`	LPM CLI created the diagnostic report
`no_failures`	No result has `fail` severity
`clean`	No result has `warn` or `fail` severity
`has_warnings`	At least one result has `warn` severity
`checks[].code`	Stable identifier for one result
`fixes_applied`	Actions that completed during this run
`fixes_failed`	Actions that failed during this run

success: true does not mean that the project is healthy. Read clean for a warning-sensitive policy. Otherwise, read no_failures.

Diagnostic failures and failed repair actions cause exit code 1. Warnings alone keep exit code 0.

For a warning-sensitive CI gate, require a clean report and no failed repairs:

if lpm doctor --json > doctor-report.json; then
  jq -e '.success and .clean and ((.fixes_failed | length) == 0)' doctor-report.json
else
  cat doctor-report.json
  exit 1
fi

For a policy that allows warnings, replace .clean with .no_failures. Keep the command's exit status and failed-action check.

Compare project and registry health

Use lpm doctor for project and environment health. Use lpm health for one registry request.

lpm doctor
lpm health --registry https://lpm.dev

Command	Scope	Project files	Network
`lpm doctor` without repairs	Fast project and local environment health	Yes	No
`lpm doctor --all`	Complete project, machine, tool, and service health	Yes	Yes
`lpm health`	One selected registry	No	Yes

lpm health sends one anonymous GET request to <registry>/api/registry/health. Any HTTP 2xx response counts as healthy.

The request has a five-second deadline and no retries. Other responses and request failures return an unsuccessful exit status.

A custom registry must implement this endpoint. It is not a standard npm registry health check.

A healthy JSON result includes healthy: true. Handle an error response through the command exit status and JSON error fields.

Know what doctor does not examine

Project health is a diagnostic layer. It does not replace these focused commands:

Need	Command
Run project tests and type checks	`lpm check`
Examine local certificate trust and expiry	`lpm cert status`
Examine package-store content integrity	`lpm store verify`
Examine dependency vulnerabilities	`lpm audit`
Examine one registry only	`lpm health`

Doctor examines TypeScript readiness in full mode. It does not run the complete project type check.