steamos-bootdebug

steamos-bootdebug command [image]

steamos-bootdebug is a small administration script that ships with SteamOS 3+ on the Steam Deck. It surfaces controls for the SteamOS chainloader — the small bootloader stub that decides which of the two A/B system images to load — and for the kernel command line baked into each image.The chainloader runs before GRUB and normally boots the active slot silently. steamos-bootdebug menu flips it into interactive mode so the user can edit GRUB entries (useful for adding systemd.unit=rescue.target, alternate root= parameters, and so on). verbose and quiet toggle whether chainloader log lines go to the console or are suppressed; log enable/disable/show capture those lines to a file in the EFI System Partition for post-mortem inspection.The kernel-debug/kernel-quiet family edits the kernel command line of one or both A/B images: enabling kernel debug removes the quiet parameter, enables verbose printk output, and is invaluable for diagnosing display, GPU, or storage init issues. kernel-debug-once is the safest option — it self-reverts after a single boot, so you cannot accidentally leave the system in a noisy state.

menu

Enable the chainloader boot menu, allowing GRUB editing and A/B slot selection at boot.

Send chainloader log output to the system console.

Disable both the menu and verbose console output.

Persist chainloader logs to a file on the EFI System Partition (/esp).

Stop persisting chainloader logs to the filesystem.

Print the contents of the chainloader log file.

Enable kernel debug output (no quiet parameter, debug messages on console) for the named slot image, or both if omitted.

Enable kernel debug for only the next boot, then automatically revert.

Restore the standard silent kernel boot.

Print the current debug configuration of both slots.

Read-only rootfs: SteamOS uses an immutable root, so steamos-bootdebug writes to the EFI System Partition rather than /etc. Boot menu output is rendered on whichever display the firmware picks; if you boot the Steam Deck while docked and undock during the menu, the menu may be lost on the internal panel and you must blindly navigate or reboot. The optional image argument selects the A or B slot — if omitted, both slots are modified.

steamos-bootdebug is shipped by Valve in SteamOS 3 (the Arch-based Linux distribution running on the Steam Deck since February 2022). It is part of the steamos-customizations family of scripts that adapt a stock Arch install to the read-only A/B image model used on the Deck.

grub(8), steamos-readonly(1), bootctl(1), efibootmgr(8)