How to Report a Bug in the Omarchy CLI: A Complete Guide

To report a bug in the Omarchy CLI, run omarchy version and omarchy debug --no-sudo --print to collect system diagnostics, optionally capture screenshots with omarchy capture screenshot, then file a structured issue on the omacom/omarchy GitHub repository.

The Omarchy CLI provides the command-line interface for the Omarchy operating system. When you encounter unexpected behavior, following the verified-bug workflow ensures maintainers can reproduce and resolve issues efficiently. This guide walks through the exact process defined in the official contributing documentation and the diagnostic tooling located in bin/omarchy-debug.

Confirm It Is a Bug Before Reporting

Before opening a GitHub issue, verify that the behavior is an actual bug rather than a configuration error or user mistake. According to default/agents/skills/omarchy/contributing.md (lines 13-15), uncertain reports should first go to the Discord community at omarchy.org/discord. This prevents the issue tracker from being overwhelmed with support questions that are not actionable code defects.

Collect Diagnostic Information

The Omarchy project requires specific diagnostic data to triage CLI bugs effectively. The workflow documented in manual/14-omarchy-cli.md and implemented in the repository's diagnostic scripts involves gathering version details, system logs, and optional visual evidence.

Check Version and System Details

Start by capturing your environment baseline. The omarchy version command outputs the Omarchy release and hardware summary, as documented in manual/14-omarchy-cli.md (lines 19-26).

omarchy version

Generate a Diagnostic Log

The bin/omarchy-debug script creates a comprehensive log file containing system information, dmesg output, journalctl logs, and the full package list (see script header lines 31-37). Execute the following to generate diagnostics without requiring sudo privileges:

omarchy debug --no-sudo --print

This command writes the complete diagnostic output to /tmp/omarchy-debug.log. The script can automatically upload this file and return a shareable URL, or you can manually attach the raw log to your issue. If uploading manually, copy the file from /tmp/omarchy-debug.log to your working directory.

Capture Visual Evidence (Optional)

For UI-related bugs, visual proof significantly accelerates triage. The CLI includes capture utilities referenced in manual/14-omarchy-cli.md (lines 48-55):

# Take a screenshot of the current screen

omarchy capture screenshot

# Record a screen video with microphone audio

omarchy capture screenrecording --with-microphone-audio --stop-recording

These commands are implemented in the bin/omarchy-capture* scripts within the repository. Include the resulting files as attachments to your GitHub issue.

Submit the Bug Report on GitHub

Once you have compiled the diagnostics, create an issue in the omacom/omarchy repository. According to default/agents/skills/omarchy/contributing.md (lines 19-31), your report must include:

• A clear, descriptive title summarizing the defect
• Exact steps to reproduce the issue
• Output from omarchy version
• The diagnostic log (either the auto-uploaded URL or the contents of /tmp/omarchy-debug.log)
• Any relevant screenshots or screen recordings

You can streamline issue creation using the GitHub CLI with a template:

gh issue create \
  --repo omacom/omarchy \
  --title "omarchy capture screenshot crashes on external monitors" \
  --body "## Steps to reproduce

1. Connect an external monitor via HDMI
2. Run \`omarchy capture screenshot\`
3. Observe the crash

## System details

$(omarchy version)

## Diagnostic log

$(omarchy debug --no-sudo --print)

## Attachments

- screenshot-error.png
"

Summary

• Verify first: Use the Discord channel at omarchy.org/discord if you are unsure whether the behavior constitutes a bug
• Gather diagnostics: Run omarchy version and omarchy debug --no-sudo --print to collect system data; logs are stored at /tmp/omarchy-debug.log
• Add visuals: Use omarchy capture screenshot or omarchy capture screenrecording for interface-related issues
• Report: File structured issues on GitHub at omacom/omarchy including reproduction steps, version output, and diagnostic logs

Frequently Asked Questions

Where is the diagnostic log saved after running the debug command?

The omarchy debug command writes the complete system diagnostic to /tmp/omarchy-debug.log as implemented in bin/omarchy-debug. You can copy this file using cp /tmp/omarchy-debug.log ~/Desktop/omarchy-debug.log or allow the script to automatically upload it and provide a shareable URL for your issue report.

Can I report a bug without using the diagnostic script?

While manual reports are accepted, the bin/omarchy-debug output is required for efficient triage according to default/agents/skills/omarchy/contributing.md. Issues lacking diagnostic data may be closed or delayed until the information is provided, as the logs contain essential dmesg, journalctl, and package information needed to reproduce your environment.

What should I do if the debug command itself is broken?

If omarchy debug fails to execute, first verify your installation by running omarchy version. Report the tool failure on Discord at omarchy.org/discord first to check if it is a known issue, or file a GitHub issue manually with the error message output and your version details, citing the failure of the bin/omarchy-debug script itself.

Are there special procedures for reporting security vulnerabilities?

The standard omarchy debug output may contain sensitive system information such as hardware IDs and network details. For security-related bugs, review the repository's security policy in the contributing documentation before posting logs publicly. Sanitize /tmp/omarchy-debug.log before attachment or request a private disclosure channel through Discord if the vulnerability involves sensitive system access.

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