Products › lamboot-tools › Appendix
Reference Appendix
Exit codes, JSON schema, versioning model, and finding IDs for lamboot-tools 0.9.1.
APPENDIX A
Exit code reference
Applies to all 10 shell CLIs and
lamboot-toolkit. The two bundled Rust binaries (lamboot-capcheck, lamboot-reader) use their own 0 through 3 contract.| Code | Constant | Meaning | summary.status | Automation guidance |
|---|---|---|---|---|
| 0 | EXIT_OK | All requested operations completed successfully. | pass | Continue pipeline. |
| 1 | EXIT_ERROR | Fatal error. Some state may have changed. | error | Log and alert. Inspect output. |
| 2 | EXIT_PARTIAL | Mixed success. Some operations succeeded; some failed. | fail or warn | Log. Re-run idempotent commands. |
| 3 | EXIT_NOOP | System already in requested state. Nothing to do. | noop | Idempotent-OK. Do not log as failure. |
| 4 | EXIT_UNSAFE | Refused by a safety check. No state changed. | unsafe | Inspect and fix, or --force if understood. |
| 5 | EXIT_ABORT | User declined interactive confirmation. No change. | abort | Expected when user aborts. Not a failure. |
| 6 | EXIT_NOT_APPLICABLE | Operation does not apply to this system. | noop | Skip silently. Not a failure. |
| 7 | EXIT_PREREQUISITE | Required tool or capability missing. | error | Install missing dependency and retry. |
Bundled Rust binary exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error |
| 2 | Partial success |
| 3 | Prerequisite missing |
APPENDIX B
JSON envelope quick reference
The complete contract is on the CLI Contract page. This table is a portable cheat sheet.
| Field | Type | Notes |
|---|---|---|
| schema_version | string | "v1". Pin on this to guard against breaking changes. |
| tool | string | Executable name. |
| version / toolkit_version | string | Per-tool semver / release bundle version. |
| timestamp | string | ISO-8601 UTC, Z suffix, no fractional seconds. |
| run_id | string | Unique per invocation. Correlates log lines. |
| exit_code | integer | The process exit code, set at emit time. |
| summary.status | string | pass, warn, fail, noop, error, unsafe, abort. |
| findings[].id | string | Dotted-path stable ID, e.g. esp.free_space. |
| findings[].severity | string | critical, error, warning, info. "How bad if unaddressed?" |
| findings[].status | string | pass, warn, fail, skip. "What did this check report?" |
| findings[].remediation.command | string | Executable command that fixes this finding. |
| actions_taken | array | Empty for read-only tools. One object per mutation. |
| backup_dir | string or null | Path to backup created before mutation; null for read-only. |
APPENDIX C
Versioning model
lamboot-tools uses semantic versioning with a dual-track model:
Toolkit version
The release bundle version (currently 0.9.1). Appears in lamboot-toolkit status and the toolkit_version JSON field. Major version bumps break the --json schema (and bump schema_version in lockstep).
Per-tool version
Each tool carries its own semver in --version output and the version JSON field. In 0.9.1, all tools share the same version. In future toolkit releases, individual tools may advance independently.
Stability promises
- Additive within major version: New fields in JSON output, new subcommands, new finding IDs. These are never breaking.
- Breaking in major version: Renamed fields, removed fields, changed exit code semantics, renamed finding IDs. These all bump the major version.
- Bug fixes in patch: Fixes to incorrect output, wrong exit codes, crashes. Never remove features.
APPENDIX D
Finding ID catalog
Dotted-path finding IDs are stable within a toolkit major version. These are the most actionable finding categories in 0.9.1.
| Category | Example IDs | Tool |
|---|---|---|
| esp.* | esp.free_space, esp.mount, esp.size, esp.filesystem | lamboot-diagnose, lamboot-esp |
| bootloader.* | bootloader.grub.pe_format, bootloader.grub.cfg, bootloader.systemd.present | lamboot-diagnose, lamboot-repair |
| nvram.* | nvram.boot_order, nvram.stale_entries, nvram.missing_entry | lamboot-diagnose, lamboot-nvram |
| secureboot.* | secureboot.state, secureboot.pk, secureboot.signature.bootloader | lamboot-diagnose, lamboot-signing-keys |
| vm.* | vm.lamboot_state, vm.ovmf_version, vm.boot_mode | lamboot-diagnose (VM subcommand) |
| prereq.* | prereq.efibootmgr, prereq.parted, prereq.sbsign | All tools |
The complete finding catalog with severity classifications and remediation commands for all IDs is available in the --json-schema output of each tool, which includes per-tool finding ID definitions as part of the JSON Schema draft 2020-12 document.
APPENDIX E
Quick reference: canonical facts
| Attribute | Value |
|---|---|
| Current version | 0.9.1 |
| Supported architectures | x86_64, aarch64 |
| Shell requirement | bash 4.0+ |
| Core tool count | 11 |
| Bundled Rust binaries | lamboot-capcheck 0.1.0 (12 domains), lamboot-reader 0.1.0 |
| Shell exit codes | 0 through 7 (see Appendix A) |
| Rust binary exit codes | 0 through 3 |
| JSON schema version | v1 |
| GPG signing subkey | 405CB1E36258DA1DA406A852A236DDB84E0EC96E |
| License | MIT OR Apache-2.0 |
| Distribution channel | GitHub Releases only |
| Proxmox companion | lamboot-toolkit-pve (5 tools: setup, fleet, migrate, monitor, ovmf-vars) |