lpm doctor / lpm health

Use lpm doctor to find project and environment problems. Use lpm health to examine one registry.

lpm doctor [OPTIONS] [COMMAND]
lpm doctor list [--code <CODE>] [--category <CATEGORY>] [--json]
lpm doctor sandbox-setup [--project <PATH>] [--metadata-dir <PATH>]... [--tool-dir <PATH>]... [--user-sid <SID>] [--apply | --remove] [-y|--yes] [--json]
lpm health [--registry <URL>] [--json]

Quickstart

Run the fast checks from the project directory or any directory inside it:

lpm doctor

The command examines the nearest directory at or above the current one that has a package.json or an lpm.json. The search stops before your home directory. When that project is not the current directory, doctor prints which directory it uses. Without such a directory, doctor examines the current directory.

Doctor reports failures and warnings, then returns a summary.

Choose a command or mode

lpm.json behavior

If lpm.json exists, doctor reads it automatically. You do not need a separate option.

For example:

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

The fast mode checks the JSON structure and every top-level field in the canonical lpm.json schema. It reports unknown fields as warnings.

It also checks value types and the details of runtime, task, tool, and service fields. Unreadable runtime pin files and invalid linker values appear as failed checks. The remaining checks still run.

The fast mode also checks the configured Node.js or Bun version.

The full mode uses tools pins for installed lint and format tools. A workspace member can inherit these pins from the project root. Doctor reports an unavailable pinned tool without downloading another version.

There is no doctor configuration block or flag to ignore lpm.json for one run. Use --all to extend the check set and --yes to apply available fixes without a prompt.

The full mode checks the configured tunnel domain. If authentication is available, it also checks ownership and reachability.

Read lpm tunnel for the complete tunnel configuration.

Fast and full checks

lpm doctor runs the fast mode by default. This mode reads local project and LPM CLI state.

The fast mode examines:

• Local storage and install state
• package.json, node_modules, and lockfiles
• Dependency synchronization and local dependency paths
• lpm.json structure and runtime pins
• Node.js and Bun readiness
• Workspace cycles
• Policy extensions
• Local authentication and secret storage
• Sigstore settings

Without repairs, fast mode does not contact a registry or tunnel service. It does not start background update requests or run lint or format checks.

Use --all to add:

• Registry and authentication requests
• Tunnel ownership and reachability
• Lint and format checks
• TypeScript readiness and plugin updates
• Global-install health
• Sandbox and script-policy checks
• Manifest compatibility checks
• Tracked .lpm/ state and store-orphan checks

lpm doctor --all

The full mode can take more time because it runs tools and sends network requests.

Recipes

Diagnose the current project

Run doctor from the project root or one of its subdirectories:

cd /path/to/project
lpm doctor

The fast output usually hides passing rows. It keeps the resolved linker mode and active policy extensions for context.

Run a complete environment check

lpm doctor --all

Use this command after a machine change, a toolchain change, or a difficult install failure.

Use doctor as a CI gate

lpm doctor --json > doctor-report.json

Add --all for tool, machine, and connected-service checks. Full mode requires registry credentials for a passing authentication result.

If a check fails, doctor exits with code 1. Warnings keep exit code 0.

The JSON report contains both the summary and every emitted check. Match automation on the stable code field.

Apply supported fixes

Save your project changes before you use --fix. Some fixes can change project files or installed dependencies. Repairs can download packages and runtimes, even without --all.

lpm doctor --fix

--fix shows the available actions and asks once before it changes anything. Doctor then reruns the selected checks and reports the resulting state.

Use --all --fix to include fixes from the full check set:

CAUTION: --all --fix can prune the shared store, update installed plugins, and claim a tunnel domain.

lpm doctor --all --fix

The full fix mode can also format the project.

Find one check in the catalog

lpm doctor list --code node_modules_symlinked

The result explains when the check appears and how to resolve it. The --code value is an exact match.

Find checks by category

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

The category filter is not case-sensitive. It matches any category that contains the supplied text.

Examine a specific registry

lpm health --registry https://registry.example.com

The command reports the registry URL, its health state, and one response-time measurement.

Automatic fixes

Doctor can apply fixes for selected results. The available fix depends on the emitted check code.

Supported fixes include:

• Install the pinned Node.js version
• Install the pinned Bun version
• Run lpm install for missing or inconsistent project state
• Run lpm fmt for formatting failures
• Reconcile lpm.lockb with lpm.lock
• Replace a linked project node_modules path with a real directory
• Prune unreachable entries from the shared store during a full run
• Claim an available tunnel domain during a full run
• Update an installed plugin during a full run

lpm doctor list --json shows the supported action before a fix run. For each code, auto_fix identifies the action or is null.

The JSON field fixes_applied lists completed fixes. fixes_failed lists unsuccessful actions and their errors. Targeted actions include the plugin name, tunnel domain, or runtime version selector. After repairs, doctor reloads root and member manifests before it reruns the same check set. A failed repair appears in the final terminal summary and keeps the exit code at 1.

Repairs apply once to the initial report. The final report can show remaining or newly discovered problems.

lpm doctor --fix runs the selected checks before it changes the project. If automatic fixes exist, doctor shows the planned actions and asks once.

The default response is No. If you decline, doctor makes no changes.

-y and --yes imply --fix and skip the confirmation. Use either flag for CI, scripts, or JSON output:

lpm doctor --yes
lpm --json doctor --yes

Without --yes, --fix returns an error when standard input is not a terminal. It also returns an error with --json.

Doctor makes no changes in both cases. If no automatic fix exists, doctor returns the normal result without a prompt.

Windows sandbox permission setup

Windows may block Node.js scripts from reading metadata for protected parent directories. System-installed tools can also need explicit read and execute permissions. This affects publishing hooks and sandboxed dependency scripts.

Preview the required permissions from your normal PowerShell terminal:

lpm doctor sandbox-setup --project 'C:\work\my-package' --tool-dir 'C:\Program Files\nodejs'

The preview changes nothing and runs no package scripts. It shows your Windows user SID, each directory, and the requested access. It includes the ancestors of your project and temporary directory. Use --metadata-dir <path> for an additional temporary, cache, or build directory.

The two permission types have different scope:

Select only the tool directories that your scripts need. The command does not approve every directory on PATH automatically. Tool setup skips links and junctions, and refuses files with multiple hard links. The selected tool path must not contain a link or junction in any component. Use a separate tool copy if its installation contains hard-linked files. A drive root cannot be selected as a tool directory.

Apply the preview

1. Review the permissions in the preview.
2. Open PowerShell with Run as administrator.
3. Run the administrator command printed by the preview.
4. Confirm the changes.
5. Return to your normal terminal and retry publishing.

The printed command includes --user-sid and the original directory paths. Keep those arguments when another administrator performs setup for you. On a managed machine, give the preview to your IT administrator.

Setup does not elevate later installs or publishes. Package scripts continue to run in the sandbox as your normal user. Project-secret restrictions remain active. Explicitly approved tool directories avoid repeated permission walks when scripts run. Other directories on PATH can still add preparation time.

For automation, review a JSON preview first:

lpm doctor sandbox-setup --project 'C:\work\my-package' --tool-dir 'C:\Program Files\nodejs' --json

Run the printed apply_args with lpm in an administrator terminal. Add --yes --json for a non-interactive apply. The JSON output includes success, operation, user_sid, grants, count, and apply_args.

Repeat or remove setup

Grants belong to a Windows user and the selected directory identities. Repeat setup after moving or replacing a tool directory, or when a new protected path is reported. A new project may reuse existing ancestor grants. Adding another protected tool requires selecting its directory explicitly.

To remove selected grants, repeat the administrator command with --remove instead of --apply. Use the same project, additional directories, tool directories, and user SID. Removal preserves unrelated permissions. Shared ancestor grants can affect other projects for that user. Stop active installs and publishes before removal.

If setup fails partway through, some permissions may have changed. Preview the same selection again, then retry the same operation. A tool grant becomes active only after its permission walk completes. Neither --apply nor --remove runs on non-Windows platforms.

Setup flags

Check catalog

This catalog explains every check that lpm doctor can report. The tables group related codes so that you can find a result quickly.

Match automation on the code value. Human-readable descriptions can change.

Run lpm doctor list for the same catalog in the terminal. Use lpm doctor list --json for the complete machine-readable metadata.

In the JSON catalog, auto_fix identifies the action that --fix supports for each code. A null value means that no automatic fix exists.

Paths under ~/.lpm refer to the LPM home. When LPM_HOME is set, they are under that directory instead.

pass is a healthy or informational result. warn needs attention but keeps exit code 0. fail causes exit code 1.

Infrastructure

Auth

Policy extensions

Project state

lpm.json

Runtime

Tunnel

Code quality

TypeScript

Plugin

| plugin_pin_unavailable | warn | The pinned tool is unavailable or lacks a valid verification receipt. Run the tool command to install that version. |

Workspace

Global installs

Sandbox + scripts

Sigstore provenance

Manifest compat

Incomplete probes

JSON output and exit codes

Use --json for CI and scripts:

lpm doctor --json

{
  "success": true,
  "mode": "fast",
  "no_failures": false,
  "clean": false,
  "has_warnings": false,
  "passed": 0,
  "failed": 1,
  "warnings": 0,
  "fixes_applied": [],
  "fixes_failed": [],
  "checks": [
    {
      "code": "node_modules_missing",
      "check": "node_modules",
      "passed": false,
      "severity": "fail",
      "detail": "not found — run: lpm install"
    }
  ]
}

In doctor JSON, success: true means that LPM CLI created the report. It does not mean that every check passed.

Use these fields for automation:

Match on checks[].code. The check and detail text can change.

Doctor uses these exit codes:

Registry health

lpm health sends one health request to the selected registry. It does not check the current project.

lpm health
lpm health --json

{
  "success": true,
  "healthy": true,
  "registry_url": "https://lpm.dev",
  "response_time_ms": 87
}

The command does not collect repeated measurements. The response_time_ms value is the time for one request.

Both output modes return a nonzero exit code for an unhealthy response or a failed request:

A successful JSON response has success: true and healthy: true. The health request has a five-second deadline and does not retry.

Recovery

Repair project install state

If doctor reports a missing install or dependency drift, run lpm install. Then run doctor again.

lpm install
lpm doctor

Repair a linked project node_modules

The node_modules_symlinked check reports a project-level symlink or directory junction. LPM CLI does not install through this path.

lpm doctor --fix
lpm install
lpm doctor

The fix removes only the link entry. It creates a real node_modules directory and does not change the linked target.

Do not run lpm cache prune or lpm store clean for this error. The global store is not the cause.

Resolve registry or authentication failures

Run the registry check first:

lpm health

If the registry responds, view the current account:

lpm whoami

If the account is not correct, sign in again:

lpm login

Read lpm login for authentication options.

Read the remediation for a check

Use checks[].code from lpm doctor --json:

lpm doctor list --code <CODE>

Flags

lpm doctor

--all and --fix apply only to the diagnostic run, not to its subcommands. The catalog also ignores --yes. Sandbox setup uses --yes to approve an explicit --apply or --remove.

lpm doctor list

lpm health

See also

• Install packages
• Sign in to a registry
• Configure tunnel domains
• Manage the package store
• Manage policy extensions
• Update LPM CLI
• Review global flags