# The Complete Guide to Omarchy Command Groups: 43 System-Level Categories Explained

> Discover the 43+ Omarchy command groups and understand how they are organized. This guide explains system-level categories following the omarchy-<group>-<verb> pattern. Learn more now.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-02

---

**Omarchy organizes all user-facing commands into 43+ hierarchical command groups defined in `bin/omarchy`, following the naming pattern `omarchy-<group>-<verb>`.**

The Omarchy Linux distribution uses a predictable command structure that groups related functionality under intuitive namespaces. This design, implemented in the central router script `bin/omarchy`, makes system administration discoverable and extensible. Understanding these command groups is essential for navigating Omarchy's CLI effectively.

## How Omarchy's Command Group System Works

### The Router Architecture

The command routing system in `bin/omarchy` uses three core mechanisms:

1. **`GROUP_DESCRIPTIONS` associative array** — maps each group name to a human-readable description (lines 27-95)
2. **Verb discovery** — scans `bin/omarchy-<group>-*` executables to expose available actions
3. **Dynamic help generation** — builds help output from the group description and discovered verbs

When you run `omarchy <group> --help`, the router prints the description from `GROUP_DESCRIPTIONS` and lists all matching verbs found in the `bin/` directory.

### Command Naming Convention

Every Omarchy command follows this strict structure:

```bash
omarchy <group> <verb>

```

Behind the scenes, this resolves to the executable:

```bash
bin/omarchy-<group>-<verb>

```

For example, `omarchy capture screenshot` executes `bin/omarchy-capture-screenshot`.

## Core System Command Groups

These groups handle fundamental Linux system administration tasks:

| Group | Description | Example Usage |
|-------|-------------|---------------|
| **system** | Power & session control | `omarchy system reboot` |
| **update** | Omarchy & system updates | `omarchy update self` |
| **config** | System configuration helpers | `omarchy config edit` |
| **refresh** | Reset config to defaults | `omarchy refresh config` |
| **restart** | Restart Omarchy components | `omarchy restart shell` |
| **debug** | Diagnostics & support logs | `omarchy debug dump` |
| **setup** | Interactive setup wizards | `omarchy setup wifi` |
| **version** | Version & channel information | `omarchy version show` |

The **system** group in `omarchy-system-*` scripts provides critical session management including poweroff, reboot, suspend, and lock operations.

## Hardware & Device Control Groups

### Display & Monitor Management

| Group | Description | Key Verbs |
|-------|-------------|-----------|
| **display** | Display scaling & layout | `mode`, `scale` |
| **monitor** | Monitor status helpers | `list`, `toggle` |
| **brightness** | Display & keyboard brightness | `set`, `get` |

### Audio & Input Devices

| Group | Description | Key Verbs |
|-------|-------------|-----------|
| **audio** | Audio input & output controls | `mute`, `volume`, `input` |
| **bluetooth** | Bluetooth device controls | `toggle`, `connect`, `list` |
| **battery** | Battery status helpers | `show`, `notify` |

### Storage & Drives

| Group | Description | Key Verbs |
|-------|-------------|-----------|
| **disk** | Disk performance helpers | `usage`, `speed` |
| **drive** | Drive selection & encryption | `mount`, `unlock` |

## Desktop Environment Groups (Hyprland)

Omarchy is built on Hyprland, and these groups expose window manager controls:

| Group | Description | Example Command |
|-------|-------------|---------------|
| **hyprland** | Window/monitor controls | `omarchy hyprland workspace 3` |
| **bar** | Shell bar layout & settings | `omarchy bar reload` |
| **theme** | Theme management | `omarchy theme apply dark` |
| **toggle** | Toggle Omarchy features | `omarchy toggle darkmode` |
| **notification** | Notification helpers | `omarchy notification send "Alert"` |

The **hyprland** group scripts in `bin/omarchy-hyprland-*` provide workspace navigation, window manipulation, and monitor configuration without manual `hyprctl` syntax.

## Development & Productivity Groups

### AI & Automation

| Group | Description | Key Verbs |
|-------|-------------|-----------|
| **agent** | AI coding-agent usage data | `status`, `log` |
| **voxtype** | Voice typing controls | (fewer common verbs) |

### Development Tools

| Group | Description | Example Command |
|-------|-------------|---------------|
| **dev** | Development tools | `omarchy dev watch` |
| **branch** | Git branch management | `omarchy branch list` |
| **install** | Optional software installers | `omarchy install node` |
| **pkg** | Package-management helpers | `omarchy pkg install neovim` |

The **install** group distinguishes itself from **pkg** by handling optional Omarchy-specific software installations rather than system package manager operations.

### Content Creation

| Group | Description | Key Verbs |
|-------|-------------|-----------|
| **capture** | Screenshots & screen recording | `screenshot`, `video`, `region` |
| **ascii** | Render text as ASCII art | `draw`, `banner` |
| **font** | Font management | `install`, `list` |

## Application & Interface Groups

| Group | Description | Example Command |
|-------|-------------|---------------|
| **launch** | Application launchers | `omarchy launch firefox` |
| **menu** | Omarchy menu commands | `omarchy menu show` |
| **cmd** | Command & shortcut helpers | `omarchy cmd find` |
| **clipboard** | Clipboard utilities | `omarchy clipboard copy` |
| **file** | File selection helpers | `omarchy file open` |
| **plugin** | Shell plugin & bar-widget management | `omarchy plugin list` |

The **launch** group provides consistent application spawning with environment-aware defaults, while **menu** controls Omarchy's dynamic menu system.

## Specialized & Niche Groups

| Group | Description | Notes |
|-------|-------------|-------|
| **games** | Game launchers & helpers | Steam, emulators, etc. |
| **windows** | Windows VM management | Virtual machine integration |
| **webapp** | Web application wrappers | Site-specific browsers |
| **weather** | Weather information display | Status bar integration |
| **network** | Network status helpers | Companion to **wifi** group |
| **wifi** | Wi-Fi connection helpers | `omarchy wifi connect` |

## Practical Command Examples

```bash

# Screenshot with automatic save to ~/Pictures

omarchy capture screenshot

# Launch browser with workspace assignment

omarchy launch firefox

# Check power status before travel

omarchy battery show

# Toggle hardware Bluetooth controller

omarchy bluetooth toggle

# Restore a config file to default

omarchy refresh config/hypr/hyprland.lua

# Install development tooling

omarchy install neovim

# Update Omarchy to latest release

omarchy update self

# Quick workspace switch via Hyprland

omarchy hyprland workspace 5

# Send system notification

omarchy notification send "Build complete"

# Mount encrypted external drive

omarchy drive mount /dev/sdb1

```

## How to Discover Available Commands

List all groups and their descriptions:

```bash
omarchy --help

```

Explore verbs within a specific group:

```bash
omarchy capture --help

# Output: "Screenshots & screen recording"

#         screenshot  video  region  window

```

## Key Source Files

| Path | Purpose |
|------|---------|
| `bin/omarchy` | Central router with `GROUP_DESCRIPTIONS` array (lines 27-95) |
| `bin/omarchy-*` | Individual command implementations per group-verb |
| [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) | Routing logic documentation |
| [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md) | Repository structure and script locations |

## Summary

- **43+ command groups** are defined in `bin/omarchy` via the `GROUP_DESCRIPTIONS` associative array
- **Predictable naming**: all commands follow `omarchy <group> <verb>` → `bin/omarchy-<group>-<verb>`
- **Self-documenting**: the router automatically generates help from group descriptions and discovered verbs
- **Extensible**: add new functionality by creating executable scripts in `bin/` and updating `GROUP_DESCRIPTIONS`
- **Core coverage**: system administration, Hyprland window management, hardware control, development tools, and desktop productivity

## Frequently Asked Questions

### How do I find all available commands in a specific Omarchy group?

Run `omarchy <group> --help` or simply `omarchy <group>`. The router reads the description from `GROUP_DESCRIPTIONS`, scans `bin/omarchy-<group>-*` executables, and lists available verbs. This dynamic discovery ensures the help output always matches installed functionality.

### What's the difference between `omarchy install` and `omarchy pkg`?

`omarchy install` (the **install** group) handles optional Omarchy-specific software installations with custom setup logic, while `omarchy pkg` (the **pkg** group) provides thin wrappers around the system package manager. Use `install` for Omarchy-curated tools like Node.js or Rust; use `pkg` for standard repository packages.

### Can I add custom command groups to Omarchy?

Yes. Create an executable script at `bin/omarchy-<mycustomgroup>-<myverb>`, then add your group to the `GROUP_DESCRIPTIONS` array in `bin/omarchy`. The router will automatically discover your verbs and include them in help output. No other router modifications are required.