How to Use omarchy-debug and omarchy-upload-log for Omarchy Diagnostics

omarchy-debug and omarchy-upload-log are companion Bash utilities that collect comprehensive system snapshots and installation logs, then upload them to logs.omarchy.org for streamlined troubleshooting.

When troubleshooting Omarchy—an opinionated Arch Linux-based distribution—these built-in diagnostic tools eliminate guesswork by automatically gathering the exact data maintainers need. Written in pure Bash and relying only on standard Linux tools like inxi, journalctl, and pacman, these scripts run without additional dependencies on any system where Omarchy is installed.

What omarchy-debug Collects

The primary diagnostic script located at bin/omarchy-debug generates a comprehensive snapshot of your current system state.

System Information Gathered

The utility aggregates critical host data into a single log file at /tmp/omarchy-debug.log:

• Basic host details including hostname and date stamps
• Hardware inventory via inxi
• Kernel ring buffer messages from dmesg
• Systemd journal warnings and errors via journalctl
• Installed package manifests using pacman and expac

Interactive Workflow Options

After collection, the script presents three interactive choices: view the log immediately, save it to the current directory as ./omarchy-debug.log, or upload it directly to the public log hosting service at logs.omarchy.org.

How omarchy-upload-log Works

The secondary utility at bin/omarchy-upload-log functions as both a hidden helper and a standalone tool for specific diagnostic scenarios.

Log Concatenation and Augmentation

When invoked, the script assembles a comprehensive payload by:

1. Concatenating the debug log with installation-specific logs (e.g., the Arch-install log and Omarchy installation log)
2. Appending a succinct system-info section generated by fastfetch when available
3. Posting the assembled bundle to logs.omarchy.org

Direct Invocation Modes

Unlike the interactive omarchy-debug, you can call this helper directly with specific arguments: omarchy-upload-log install uploads combined installation logs, while omarchy-upload-log this-boot uploads logs from the current boot session.

Practical Command Examples

Generate a debug log and display it immediately without saving:

omarchy-debug --print

Create a local copy for offline inspection:

omarchy-debug

# Select "Save in current directory" when prompted

less ./omarchy-debug.log

Upload logs non-interactively using curl:

omarchy-debug --no-sudo --print | curl -sf -F "file=@-" -F expires=24 https://logs.omarchy.org/

Upload installation logs after a fresh system setup:

omarchy-upload-log install

Capture only the current boot session for recent issues:

omarchy-upload-log this-boot

Source Code Architecture

According to the Omarchy source code and documentation, these utilities are organized as follows:

• bin/omarchy-debug – The main diagnostic collector implementing the interactive menu and data gathering logic
• bin/omarchy-upload-log – The formatting and upload helper that handles HTTP POST operations to the log server
• docs/file-layout.md – Lists these utilities as required diagnostic tools in the file architecture documentation
• manual/45-troubleshooting.md – Provides end-user guidance on employing omarchy-debug when seeking community help

Both scripts reference system tools directly without external dependencies, ensuring compatibility across Arch-based systems where Omarchy is deployed.

Summary

• omarchy-debug generates comprehensive system snapshots including hardware, kernel messages, systemd logs, and package lists at /tmp/omarchy-debug.log
• omarchy-upload-log formats and uploads installation logs or boot-specific diagnostics to logs.omarchy.org
• Both utilities are pure Bash scripts located in the bin/ directory of the Omarchy repository
• Use --print for immediate terminal output or pipe directly to curl for non-interactive uploads
• The tools integrate with standard Linux utilities like inxi, fastfetch, journalctl, and pacman

Frequently Asked Questions

What information does omarchy-debug collect?

The script gathers basic host details, hardware specifications via inxi, recent kernel messages from dmesg, systemd journal warnings and errors, and a complete list of installed packages using pacman and expac. This data is written to /tmp/omarchy-debug.log before any upload or display actions occur.

How do I upload logs without the interactive prompt?

Pipe the output of omarchy-debug --no-sudo --print directly to curl with the command: omarchy-debug --no-sudo --print | curl -sf -F "file=@-" -F expires=24 https://logs.omarchy.org/. This bypasses the interactive menu and returns a temporary URL immediately.

Can I use omarchy-upload-log independently?

Yes, while omarchy-upload-log is typically invoked by omarchy-debug during the upload process, you can run it directly with arguments like install (for installation logs) or this-boot (for current session logs). This is useful when you need to share specific diagnostic subsets without regenerating the full system snapshot.

Where are these diagnostic scripts located?

The utilities reside in the bin/ directory of the Omarchy repository: bin/omarchy-debug contains the main collector logic, and bin/omarchy-upload-log handles the formatting and HTTP upload functionality. These paths are documented in docs/file-layout.md and referenced in the troubleshooting guide at manual/45-troubleshooting.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}