Exit codes

An exit status of 0 means the command succeeded. Any nonzero status means the operation failed or its requested checks did not pass.

if lpm install --json > install.json 2> install.log; then
  echo "Dependencies are ready"
else
  status=$?
  cat install.log >&2
  echo "See install.json for the structured result" >&2
  exit "$status"
fi

Do not infer the cause from the number alone. A child process can return the same status as a CLI usage or registry error.

Status values

Running lpm without a command prints help and exits 2. Running lpm --json without a command emits a JSON usage error and exits 2. Explicit --help and version requests remain display output, even with --json.

Wrapped commands and signals

lpm exec, lpm dlx, source-file execution, and single-tool commands preserve the child's exit status. This includes lpm test, lpm bench, lpm lint, lpm fmt, and lpm check.

For lpm run, a single requested task without task dependencies preserves its child status, including pre/post hook failures. Multiple local tasks return their failed-task count, capped at 255. Workspace task runs return 1 on failure.

On Unix, a child terminated by a signal returns 128 + signal number. For example, SIGTERM produces 143. The child's numeric status is used directly on Windows.

Root install hooks preserve the failed hook's status. Their JSON error also includes phase and exit_code. Dependency rebuilds report an aggregate result; their status is not an individual hook's status.

JSON failures

CLI-owned failures normally produce an error envelope on stdout:

{
  "schema_version": 1,
  "success": false,
  "error": "authentication required",
  "error_code": "auth_required"
}

Use error_code for programmatic decisions. The human-readable error text can change. Some diagnostics use an object in error, with a message and additional context.

Version 1 identifies the shared error envelope. Success and aggregate results have their own command-specific schemas.

Usage errors

Argument errors use error_code: "usage" and exit 2. Their kind identifies the parser error. Additional fields can include argument, command, value, valid_values, usage, and hint.

lpm --json install --unknown-option > error.json

Suggested recovery

When a safe recovery command is available, 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. Check the suggested action before you run it. Resolver failures also carry dependency-specific context; see Resolver failures.

Command results and passthrough

A failed operation does not always emit the shared error envelope:

Tool results omit successful child logs and truncate included failed streams at 10 MiB each. An exit_code: null with an error means the member could not start or prepare its tool.

A command can complete its checks but report findings. For example, doctor can return a completed report with success: true and exit 1. Use the process status and the command's documented result fields together.

Error-code reference

These codes identify CLI-owned errors. Command reports can carry their own additional fields and finding codes.

Checks in CI

An unmatched workspace filter succeeds with zero packages unless --fail-if-no-match is set. Use it when an empty selection would hide missing CI coverage.

- run: lpm ci
- run: lpm audit --fail-on vuln
- run: lpm test
- run: lpm lint
- run: lpm fmt --check
- run: lpm check

Each step uses its own exit status. If you pipe output through another program, preserve the command's failure status with your shell's pipeline controls.

See also

• Terminal output
• CI/CD setup
• lpm run
• lpm audit
• lpm doctor