Omarchy CLI Commands: Complete Guide to 70+ Command Groups

The Omarchy CLI exposes over 70 command groups through a single driver script at bin/omarchy, using a Bash associative array GROUP_DESCRIPTIONS (lines 27‑97) to route omarchy <group> [sub-command] patterns to specialized sub‑scripts in bin/omarchy-<group>.

The omacom/omarchy repository centralizes Linux desktop environment control through this unified interface. Instead of managing disparate utilities, users interact with one consistent syntax that delegates to modular implementations based on the first argument parsed from $1.

CLI Architecture and Routing

The command system relies on a central driver pattern. When you run omarchy theme list, the main bin/omarchy script:

1. Parses $1 to identify the group (theme)
2. Looks up the description in the GROUP_DESCRIPTIONS associative array
3. Delegates execution to bin/omarchy-theme
4. Passes remaining arguments to the sub‑script’s argument handler

This design keeps the core driver lightweight while allowing each functional area to maintain its own sub‑command logic. The GROUP_DESCRIPTIONS array defined at lines 27‑97 maps short names to human‑readable descriptions used for help text and auto‑completion generation.

Core Command Categories

Omarchy organizes its 70+ command groups into functional domains. Each group supports multiple sub‑commands accessible via omarchy <group> --help.

System and Power Management

Control system states, updates, and hardware monitoring:

• system – Reboot, shutdown, logout, lock, and status reporting
• update – Omarchy and system package updates (omarchy update check)
• snapshot – System snapshot creation and management
• hibernation – Hibernate setup and removal workflows
• power – Power supply detection and status
• powerprofiles – Power profile switching (omarchy powerprofiles list)
• battery – Battery status helpers and reporting
• refresh – Reset configurations to defaults (omarchy refresh hyprland)
• reinstall – Component reinstallation workflows

Display, Audio, and Peripherals

Manage monitors, sound, and input devices:

• hyprland – Window manager controls for workspaces, monitors, and toggles
• display – Display scaling and resolution settings
• brightness – Display and keyboard backlight adjustment
• monitor – Monitor status and configuration helpers
• bar – Shell bar layout and widget settings (omarchy bar reload)
• audio – Input/output controls and muting
• bluetooth – Device pairing and connection management
• wifi – Wi‑Fi scanning and connection helpers
• osd – On‑screen display status overlays

Development and AI Tools

Software installation, coding agents, and development workflows:

• install – Optional software installers (omarchy install docker)
• installed – Verification checks for optional services
• remove – Package and component removal workflows
• pkg – Package management helpers
• dev – Development tools and linting (omarchy dev lint)
• agent – AI coding agent usage and status
• openclaw – OpenClaw agent platform initialization
• voxtype – Voice dictation system controls
• mise – Mise version manager wrappers (omarchy mise install node)

Configuration and Theming

Customize appearance, defaults, and system behavior:

• theme – Theme management and listing (omarchy theme list)
• toggle – Feature toggles like nightlight (omarchy toggle nightlight)
• config – System configuration editing
• default – Default application selection (omarchy default set browser)
• font – Font installation and management
• plugin – Shell plugin and bar widget management (omarchy plugin add battery)
• menu – Omarchy menu customization
• setup – Interactive setup wizards
• finalize – User setup completion runner
• migrate – Configuration migration tools

File Operations and Applications

File handling, launching, and clipboard management:

• file – File selection dialogs and helpers
• launch – Application launchers (omarchy launch terminal)
• clipboard – Clipboard copy/paste utilities
• webapp – Web application shortcuts (omarchy webapp open reddit)
• games – Game launcher integration (omarchy games launch steam)
• tui – Terminal UI application launchers

Hardware and Storage

Disk management and hardware detection:

• disk – Performance benchmarking helpers
• drive – Drive selection and encryption workflows (omarchy drive encrypt /dev/sda)
• hw – Hardware detection and control listing

Networking and Security

Network configuration and system security:

• network – Connectivity testing and status (omarchy network ping google.com)
• dns – DNS resolver configuration (omarchy dns set 1.1.1.1)
• tailscale – Tailscale VPN integration helpers
• sudo – Sudo configuration management
• windows – Windows VM management (omarchy windows start)

Utilities and Interface Extras

Specialized helpers for branding, notifications, and media:

• branding – Screensaver and about‑dialog branding
• screensaver – Screensaver animation controls
• notification – Desktop notification sending
• reminder – Scheduled reminder notifications
• capture – Screenshots and screen recording
• transcode – Image and video format conversion
• weather – Weather status reporting
• ascii – ASCII art text generation (omarchy ascii draw "Hello")
• version – Channel and version information
• debug – Diagnostic log collection (omarchy debug dump)
• crash – Crash notification controls
• hook – User hook script execution (omarchy hook run myhook)
• cmd – Command and shortcut helper listings
• channel – Release channel management (omarchy channel set stable)
• restart – Component restart utilities (omarchy restart bar)
• shell – Shell IPC communication helpers

Common Usage Patterns

The CLI follows a consistent three‑tier syntax:

# Check system status

omarchy system status

# Toggle a desktop feature

omarchy toggle nightlight

# Install development dependencies

omarchy mise install node

# Change the active release channel

omarchy channel set stable

# Generate hardware report

omarchy debug dump

Each group script accepts --help to display available sub‑commands and flags specific to that domain.

Implementation Details

Key source files define and implement the CLI ecosystem:

• bin/omarchy – Central driver defining GROUP_DESCRIPTIONS and dispatch logic at lines 27‑97
• bin/omarchy-<group> – Individual group implementations (e.g., bin/omarchy-theme, bin/omarchy-toggle)
• agents/skills/command-metadata.md – Documentation for adding new command groups
• docs/testing.md – Testing framework for CLI routing validation

The modular structure allows contributors to add new command groups by creating a bin/omarchy-<group> script and registering the group name in the driver’s associative array.

Summary

• Single entry point: All commands route through bin/omarchy which parses the first argument as a group name
• Associative array routing: The GROUP_DESCRIPTIONS Bash array at lines 27‑97 maps groups to descriptions for help generation
• Modular implementation: Each group has a dedicated script at bin/omarchy-<group> handling its specific sub‑commands
• 70+ command groups: Coverage spans system management, Hyprland window controls, AI agents, development tools, and hardware configuration
• Consistent syntax: Pattern remains omarchy <group> <sub-command> [options] across all functionality

Frequently Asked Questions

How do I view available sub‑commands for a specific Omarchy CLI group?

Run omarchy <group> --help where <group> is any valid command group such as theme, system, or toggle. The help output displays available sub‑commands, options, and examples specific to that group’s implementation in bin/omarchy-<group>.

Where are new Omarchy CLI command groups registered?

New groups must be added to the GROUP_DESCRIPTIONS associative array in bin/omarchy at lines 27‑97, mapping the group name to a description string. Additionally, you must create a corresponding executable script at bin/omarchy-<group> that implements the sub‑command logic and argument parsing.

Can Omarchy CLI commands be used outside the Omarchy desktop environment?

While the CLI ships with omacom/omarchy, individual group scripts may function independently if their dependencies are satisfied. However, groups like hyprland, bar, and osd require the full Omarchy/Hyprland session to operate correctly, whereas utilities like ascii, transcode, or dns may run in standard Linux environments.

How does the Omarchy CLI handle command completion?

The driver script uses the GROUP_DESCRIPTIONS array to generate completion data for the shell. When you type omarchy <TAB>, the shell reads the registered group names from the driver script to suggest valid completions, delegating further completion logic to the specific group scripts when available.

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