OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
omarchy-core low common DISPUTE

Collect a debug log when 'omarchy debug' says Unknown Omarchy command

omarchyomarchy-4
CORRECTED An auditor found the fix wrong or incomplete and rewrote it. · checked against Omarchy omarchy 4.0.4-1 on 2026-10-05
AUDIT NOTE

Re-confirmed: /usr/bin/omarchy-debug is owned by omarchy-settings 4.0.4-1 and is absent from /usr/share/omarchy/bin. /usr/share/omarchy/bin/omarchy is a symlink to /usr/bin/omarchy, and the router derives OMARCHY_BIN_DIR from the unresolved BASH_SOURCE path, so the directory scanned depends on which path launched it. envs.lua prepends /usr/share/omarchy/bin to the session PATH, and env-bootstrap prepends nothing on a production install, so ssh and TTY shells resolve /usr/bin/omarchy. Here, /usr/share/omarchy/bin/omarchy commands --all lists no debug route and /usr/bin/omarchy commands --all lists both debug routes. The fix and its flags match the script's argument parser. One correction: the danger overstated the network exposure. omarchy-debug runs inxi -Farz, and inxi's -z filter masks IP and MAC addresses and serial numbers in its own section. The log also writes the hostname, the current boot's warning-and-error journal (which can name networks, addresses and usernames), dmesg unless --no-sudo, and the full installed package list. It also always writes /tmp/omarchy-debug.log. Danger rewritten. Cited issues #14014, #13702, #7185, #12374 and #12629 all describe this defect.

The cause above was rewritten on 2026-10-04 to match this note; the fix was corrected by the audit itself.
RISK

The log contains your hostname, the full list of installed packages, the current boot's warnings and errors from the journal, and kernel messages unless you pass --no-sudo. The inxi section masks IP and MAC addresses and serial numbers, but journal lines can still contain network names, IP and MAC addresses and usernames. The script also always leaves a copy at /tmp/omarchy-debug.log. Read the log before uploading it or pasting it into a public issue.

Symptom

In a terminal opened from the desktop, omarchy --help lists omarchy debug under Common commands, and the bug-report instructions say to attach its output, but it fails:


$ omarchy debug
Unknown Omarchy command: omarchy debug
Run 'omarchy commands --all' to discover available commands.

omarchy commands --all | grep debug shows nothing. The same command can work over ssh or on a TTY.

Cause

The omarchy router only scans the directory it was started from (OMARCHY_BIN_DIR is derived from BASH_SOURCE) for omarchy-* scripts. On 4.0.4-1, omarchy-debug is shipped by omarchy-settings as a real file at /usr/bin/omarchy-debug and is absent from /usr/share/omarchy/bin, while the help text hardcodes the route. /usr/share/omarchy/default/hypr/envs.lua puts /usr/share/omarchy/bin first on the Hyprland session PATH, so every terminal opened from the desktop runs /usr/share/omarchy/bin/omarchy, which cannot see it. An ssh or TTY login runs /usr/bin/omarchy, which scans /usr/bin and does find it. Confirmed on this workstation with pacman -Qo /usr/bin/omarchy-debug and by comparing commands --all from both routers. The bundled agent skill documentation repeats the broken form.

Fix

Call the script directly. It is on PATH:


omarchy-debug --no-sudo --print > ~/omarchy-debug.txt
less ~/omarchy-debug.txt

Without --print it writes the log and offers to upload it. Without --no-sudo it asks for your password to include privileged sections.

Verify

omarchy-debug --no-sudo --print | head prints system information instead of Unknown Omarchy command.

Sources

omarchy-debug-unknown-command