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

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:

omarchy <group> <verb>

Behind the scenes, this resolves to the executable:

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

# 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:

omarchy --help

Explore verbs within a specific group:

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	Routing logic documentation
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.

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