Exit codes

LPM CLI follows the conventional Unix exit-code convention: 0 for success, non-zero for failure. The CLI is intentionally narrow about which non-zero codes it produces — most failures exit 1. A few specific scenarios warrant a different code.

Subprocess passthrough

When a wrapped tool exits non-zero — your test suite fails, your script crashes, oxlint reports an error — LPM CLI forwards the exit code so CI gates see the right signal:

lpm test
echo "tests exit code: $?"     # whatever vitest / jest exited with

This is implemented via LpmError::ExitCode(code) flowing up to the top of main, which calls std::process::exit(code). No code mangling — lpm test exiting 1 from vitest looks identical to running vitest directly.

In --json mode

With --json, every error path also emits a structured JSON object on stdout before exiting:

{
  "schema_version": 1,
  "success": false,
  "error": "registry: not found",
  "error_code": "not_found"
}

The error_code field is the canonical short name for the error variant. Use it for programmatic dispatch in CI / agents (the error message text is human-facing and subject to change; error_code is the stable contract).

schema_version identifies the JSON document shape. On top-level error envelopes, version 1 is the shared error-envelope schema. Command success envelopes may also expose schema_version; those versions are command-specific.

When LPM CLI can suggest a concrete remediation command, the envelope includes next_steps:

{
  "schema_version": 1,
  "success": false,
  "error": "authentication required",
  "error_code": "auth_required",
  "next_steps": [
    {
      "description": "Authenticate with the LPM.dev Registry",
      "command": "lpm login"
    }
  ]
}

next_steps is optional and only appears when LPM CLI has a safe command to hand to a human, CI job, or agent.

Most errors put a human-facing string in error; rich diagnostics may use an object with a message field plus machine-readable context. Resolver failures use error_code: "resolution_failed" and include package, requested, required_by, kind, and candidate-summary fields; see Resolver failures.

Full error_code catalog

For single-package subprocess passthrough (lpm test, lpm bench, single-package lpm lint / fmt / check), --json preserves the wrapped command's own stdout — LPM CLI does not wrap it. This keeps the "single JSON result" contract for tools that already emit JSON. lpm run --json is different: it emits an LPM CLI task metadata envelope even for one script.

Workspace and multi-task aggregation DOES emit an LPM CLI envelope on stdout, but the envelope shape varies by command:

• lpm lint / fmt / check / test / bench workspace mode (--all / --filter / --affected) capture each member's subprocess stdout/stderr and surface them inside the envelope only on failure (truncated at 10 MB). Spawn / config / plugin / detection failures appear as exit_code: null paired with an error string, distinguishing "ran and exited non-zero" from "couldn't even launch." For test / bench, a member with no installed runner (no vitest/jest/mocha for test, no vitest or scripts.bench for bench) shows up as a per-member detection failure rather than aborting the entire run.
• lpm run emits a metadata-only envelope for single-script, multi-script, and workspace runs — each task/member's status, exit code, duration, cache hit, skip reason — but never the captured subprocess stdout/stderr. If a workspace filter matches no packages and --fail-if-no-match is not set, JSON mode emits a successful zero-package envelope. To debug a failing member, re-run that member without --json.

Common scenarios

CI gating idioms

- run: lpm install --offline --strict-integrity
- run: lpm audit --fail-on vuln
- run: lpm test
- run: lpm lint
- run: lpm fmt --check
- run: lpm check

Each step passes / fails on its own exit code. No special handling required.

See also

• lpm audit --fail-on — gate exit code by finding type
• lpm fmt --check — exit non-zero on unformatted files
• Global flags — --json for structured failure output