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

> Learn how to report a bug in the Omarchy CLI. Collect diagnostics, gather screenshots, and file a detailed issue on GitHub to help improve Omarchy.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-12

---

**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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md) (lines 19-26).

```bash
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:

```bash
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`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md) (lines 48-55):

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/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:

```bash
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`](https://github.com/omacom/omarchy/blob/main/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.