Introducing lamboot-tools: The Linux UEFI boot toolkit that tells you how to fix it

When a Linux machine won't boot, the tools to fix it have always existed, and not one of them tells you what's actually wrong. efibootmgr, sgdisk, dosfstools, sbsign: Each does its one small job and assumes you already know which one to reach for, in what order, and why. So boot troubleshooting has stayed what it always was, a hunt through forum threads while you guess at the cause. Today I'm releasing lamboot-tools, the Linux UEFI boot toolkit I wanted to exist: A suite of command-line tools that scans your UEFI boot chain, tells you exactly what's broken, and prints the command that fixes it. It works on any UEFI Linux system, whatever bootloader is installed.

Product page: lamco.ai/products/lamboot-tools. Source and releases: github.com/lamco-admin/lamboot-tools.

Here's what that looks like on a machine with a real problem. The scan is read-only, so running it changes nothing:

$ sudo lamboot-diagnose
lamboot-diagnose 0.7.3

boot_mode:
  ✓ Booted in UEFI mode

partition_table:
  ✓ Partition table is GPT

esp:
  ✓ ESP mounted at /boot/efi
  ⚠ Fallback loader EFI/BOOT/BOOTX64.EFI missing
      Firmware will not boot from removable media without an explicit NVRAM entry.

bootloader:
  ✗ No bootloader binaries found on ESP
      ESP contains no recognized bootloader; system may not boot.

Result: 1 critical, 1 warning, 17 passed (19 checks)

That's the whole idea in one screen: A read-only scan that names every problem in the boot chain and, for anything at warning or above, hands you the command that resolves it.

When a machine actually won't boot, the recovery walkthrough follows this exact kind of finding from an offline scan through a snapshot, a guided fix, and a verified result.

Why this didn't already exist

The standard utilities each operate on one piece of the boot chain, blind to the rest. efibootmgr writes NVRAM boot entries, but it won't notice that the ESP they point at has no loader on it. sgdisk rewrites partition tables with no idea what a healthy boot configuration looks like. dosfstools checks a FAT filesystem. sbsign signs a binary. Neither knows the other exists, or that there's a boot chain they're both part of.

The knowledge of how the pieces fit, and which one to reach for when a machine goes dark, has always lived in an operator's head and a dozen open browser tabs. lamboot-tools is that knowledge, turned into software. It treats the boot chain as one system: Firmware mode, partition table, ESP, bootloader, NVRAM entries, kernel images, and trust state, checked together and reported with the fix attached.

Eleven tools, one grammar

lamboot-tools is eleven standalone command-line tools that share one interface. Ten do the work, and lamboot-toolkit dispatches across them, reporting status and running any tool in the suite:

• lamboot-diagnose scans the boot chain across eleven categories and reports every finding by severity.
• lamboot-doctor chains diagnose to repair to verify, so you type sudo once and let it walk the loop.
• lamboot-repair runs the plan, confirm, execute, verify flow on a live system or an offline disk.
• lamboot-esp checks ESP health, inventories what's on it, and clears stale loaders and orphaned kernels.
• lamboot-nvram inventories UEFI boot entries and deletes the dead ones left behind by reinstalls.
• lamboot-backup snapshots NVRAM, boot order, and Secure Boot state, and restores any of them.
• lamboot-migrate converts BIOS installs to UEFI, moves between bootloaders, and rolls back on failure.
• lamboot-uki-build builds, inspects, signs, and verifies Unified Kernel Images.
• lamboot-signing-keys runs the Secure Boot key lifecycle: Generate, rotate, MOK-enroll, and sign binaries.
• lamboot-inspect reads LamBoot's own boot.json and trust-log artifacts for deep introspection.

None of this is bound to a bootloader. GRUB, systemd-boot, rEFInd, Limine, and LamBoot, the memory-safe UEFI bootloader, are all first-class: If a system boots through UEFI, the tools work on it. And because every tool speaks the same flags (--json, --dry-run, --offline, --suggest-next-command), returns the same exit codes, and emits the same JSON, learning one teaches you the shape of all of them.

A fix on every finding, in text or JSON

Two design decisions separate this from a pile of shell scripts.

The first: Every finding at warning severity or above carries a remediation. It's not a description of the problem. It's a command you can run, sitting right next to the thing it fixes. A missing fallback loader comes with the command to write one. An ESP that's nearly full comes with sudo lamboot-esp clean. You're never left turning a diagnosis into an action on your own.

The second: Every tool emits the same structured JSON, under a versioned schema (schema_version v1) that stays stable within the toolkit's major version. The finding a person reads in the terminal is the one a script parses:

{
  "id": "esp.free_space",
  "category": "esp",
  "severity": "warning",
  "title": "ESP is 89% full",
  "message": "ESP at /boot/efi has 54 MB free of 512 MB (10.1% free)",
  "remediation": {
    "summary": "Remove stale kernel images to free space",
    "command": "sudo lamboot-esp clean --dry-run",
    "doc_url": "https://lamco.ai/products/lamboot-tools/"
  }
}

A human gets color and severity ordering. A script gets a stable finding id, a machine-readable remediation, and an exit code from 0 to 7 it can branch on. One answer serves both readers, so there's no second code path that drifts out of sync with the first.

Nothing irreversible happens by accident

Diagnose and the other read paths change nothing, so the first thing you run is always safe. The moment a tool would modify your system, the model changes. A mutating operation takes a backup first, shows you the plan, asks before it executes, and verifies the result afterward. lamboot-backup captures NVRAM, boot order, and Secure Boot state before a repair touches anything, so a change you don't like is one restore away. You always know what a tool did, and you can always undo it.

How far it reaches

Diagnosis is the front door. Behind it, the suite covers most of what goes wrong, or needs doing, at the boot layer:

• BIOS-to-UEFI migration is automated end to end, with rollback: lamboot-migrate takes a Linux install all the way from BIOS firmware to UEFI, a ten-phase pipeline whose seven preflight guardrails refuse to start on a hybrid MBR, a Windows dual-boot, an LVM or dm-crypt root, or a disk too full to convert safely.
• ESP health and hygiene, through lamboot-esp, finds the stale loaders and orphaned kernel images that fill a 512 MB partition and clears them before they wedge an update.
• Secure Boot, end to end spans lamboot-signing-keys and lamboot-uki-build: Generate and rotate signing keys, enroll them through MOK, build and sign Unified Kernel Images, and produce an OVMF_VARS image with your certificate pre-enrolled for VMs.
• Offline diagnosis works from outside the machine, because every tool but the migrator takes --offline DISK, so you can scan or repair an unmounted disk image, including a Proxmox guest's disk, from the host without booting it. It auto-detects raw versus qcow2, sets up the loopback or qemu-nbd, mounts read-only, runs the scan, and cleans up on exit.
• Firmware capability auditing comes from lamboot-capcheck, bundled in the release, which probes what a machine's firmware claims to support across twelve domains, verifies which of those claims actually hold, and reports the result for a human or a pipeline.

There's also a Proxmox companion package on top of all this: Five host-side tools that manage guest boot across a fleet, including reading a guest's boot health from the host with nothing running inside the guest. That breadth is a post of its own.

It runs the same on every distribution

The shell tools depend on almost nothing: Bash 4, coreutils, util-linux, and efibootmgr, all already on a Linux box. The two pieces written in Rust, the GRUB config reader and the firmware auditor, ship as prebuilt static binaries linked against musl, one per architecture for x86_64 and aarch64. There's no glibc version to match and nothing to compile at install time. The same release tarball that runs on a current Fedora runs on a decade-old enterprise box and on an aarch64 board, unchanged.

Try it

lamboot-tools is available now from GitHub Releases as a signed tarball. Each release is GPG-signed, so verify the .asc and then sudo make install. More packaging channels are being prepared; the release is the install path today. It's free and dual-licensed under MIT or Apache-2.0, and it's built by Lamco Development LLC.

If you do one thing with it, run sudo lamboot-diagnose on a machine you care about. It only reads and never writes, so the first run costs nothing but a few seconds. You'll see your whole boot chain the way the toolkit does: Every check, its severity, and the exact command for anything it flags.

Product page: lamco.ai/products/lamboot-tools. Source and releases: github.com/lamco-admin/lamboot-tools.