Three commands answer nearly every "what is wrong with my machine" question.
maze-doctorA full health report of the system — 18 sections. This is the first thing to run when anything misbehaves, and the output to attach when reporting a bug.
sudo maze-doctor
It is read-only — it never changes anything — and every problem it finds
prints the command that fixes it. The last section sums up, e.g.
212 passed · 1 warnings · 0 failures · 4 skipped; a healthy system reports
0 failures. The exit code is 0 (all good), 2 (warnings only) or 1
(at least one failure).
This section answers the question people actually have: "was that Maze's fault, or my hardware?"
If your machine froze or shut itself down, maze-doctor shows the last line
the kernel wrote before the previous boot ended, and classifies the cause:
When the evidence is not conclusive it says inconclusive rather than guessing. That is deliberate: a confident wrong answer sends you looking in the wrong place for hours.
maze-boot-checkVerifies the boot chain end to end — 11 checks, each printing the command that
fixes it: a signed UKI for every installed kernel, that grubx64.efi matches a
kernel whose modules are still on disk, its MOK signature, shim, MOK enrolment
(when Secure Boot is on), the encrypt hook on a LUKS root, that the kernel
command line points at real devices, and enough free space on the ESP.
It runs automatically after every relevant update, 3 minutes after each boot and once a day, and warns you before you shut down if something is wrong. You can also run it by hand:
sudo maze-boot-check
sudo maze-boot-check --repair # fix what it finds
maze-boot-entriesIf you have installed Maze more than once, dead entries can pile up in the firmware boot menu. This tool clears them out:
sudo maze-boot-entries # show only
sudo maze-boot-entries --clean # clean up (asks for confirmation)
It never touches entries belonging to other operating systems, nor the entry you are currently booted from.
Attach the output of:
sudo maze-doctor > report.txt
It answers almost every follow-up question on its own.
See also: If the System Won't Boot · Hardware Kill Switches
maze-doctor --deep # also verify every installed file against the package database (pacman -Qkk, takes minutes)
maze-doctor --no-color # plain output, good for pasting into a report
maze-boot-check --quiet # exit code only
maze-boot-check --no-flag # check without writing the unsafe-boot flag
maze-boot-check writes /var/lib/maze/boot-unsafe, and maze-boot-guard
then holds a shutdown inhibitor — your machine will refuse to power off
cleanly while the boot chain looks broken.
This is intentional: it stops you rebooting into a system that will not come
back. Fix the boot chain (sudo maze-boot-check --repair) or see
Won't Boot?, then shut down normally.
The inhibitor blocks the normal routes (Plasma's power menu, systemctl reboot).
It deliberately does not block systemctl reboot -i or reboot -f — the
last word on your own machine stays yours.
| Command | Answers |
|---|---|
sudo maze-audit | "Did the installer leave this machine the way the Maze source intends?" (--deep for more) |
sudo maze-selftest | "Is every recent security fix installed and actually working?" Read-only. |
sudo maze-sandbox-check | "Can the sandboxed Maze daemons still do their jobs?" Read-only probes. |
sudo maze-exercise | Rehearses a kernel update and restarts the Maze daemons, then runs maze-audit. Changes state — for testing, not everyday use. |
maze-guard --doctor | Exercises every Maze Guard feature and prints PASS/WARN/FAIL with fixes. |