Exit codes

LPM 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 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:

{
  "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).

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 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 task metadata envelope even for one script.

Workspace and multi-task aggregation DOES emit an LPM 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