How Omarchy CLI Commands Are Organized into Groups: The Complete Guide

Omarchy CLI commands are organized into logical groups using a deterministic naming convention where each executable script follows the pattern omarchy-<group>-<verb>, with the central router managing group metadata and dispatching via the GROUP_DESCRIPTIONS associative array.

The Omarchy command-line interface implements a structured group-based architecture that simplifies system management through intuitive categorical organization. Understanding how Omarchy CLI commands are organized into groups reveals the deterministic routing mechanism that maps user inputs to specific Bash scripts. This guide examines the source code in basecamp/omarchy to explain the file naming conventions, routing logic, and group classification system.

The File Naming Convention That Defines Command Groups

Every user-facing Omarchy CLI command exists as a separate Bash script within the bin/ directory. The file naming convention strictly follows the pattern omarchy-<group>-<verb>, where the group represents a functional category and the verb specifies the action.

For example, the command omarchy toggle nightlight corresponds directly to the script bin/omarchy-toggle-nightlight. This places the command within the toggle group, which handles feature toggles throughout the system. Similarly, bin/omarchy-theme-list belongs to the theme group and implements the list verb for theme management.

This naming convention creates an implicit mapping between the command syntax and the filesystem. When users type omarchy <group> <verb>, the system locates the exact script by concatenating the components with hyphens.

How the Central Router Manages Group Descriptions

The bin/omarchy script serves as the central router that coordinates all Omarchy CLI commands. This script maintains the master list of valid groups and their descriptions through the associative array GROUP_DESCRIPTIONS defined at line 27.

The GROUP_DESCRIPTIONS Associative Array

The GROUP_DESCRIPTIONS array maps each group name to a human-readable description that appears in help text. According to the source code spanning lines 29-92, this array enumerates all functional categories including hardware control (hw), package management (pkg), theme handling (theme), system updates (update), and toggles (toggle). Each entry uses the syntax GROUP_DESCRIPTIONS[group_name]="Description text" to define the group's purpose.

When users invoke the help system or list available commands, the router references this array to display contextual information about what each group controls.

Routing Logic and Command Dispatch

The routing mechanism implemented at line 509 in bin/omarchy extracts the group identifier from the command arguments. The router validates the group against GROUP_DESCRIPTIONS, then constructs the target script name by combining omarchy, the group, and the verb with hyphen separators.

If the user executes omarchy update status, the router verifies that update exists as a valid group key, then dispatches execution to bin/omarchy-update-status. This deterministic approach ensures that every valid command maps to exactly one executable script.

Practical Examples of Group-Based Command Usage

The following examples demonstrate how Omarchy CLI commands map to specific groups and scripts:

# Toggle the screen night-light on/off (group: toggle)

omarchy toggle nightlight

# List all installed themes (group: theme)

omarchy theme list

# Install a missing optional package (group: install)

omarchy install pkg <package-name>

# Show a summary of the update status (group: update)

omarchy update status

# Refresh a user configuration file (group: refresh)

omarchy refresh config hypr/hyprland.lua

Each command above resolves to a specific script in the bin/ directory following the omarchy-<group>-<verb> pattern. The toggle group manages binary feature states, while the theme group handles visual customization. Package operations reside in install and pkg groups, and system maintenance commands populate the update and refresh groups.

Key Source Files Supporting the Group Architecture

Several critical files define and document the Omarchy CLI command group system:

• bin/omarchy – The central router script containing the GROUP_DESCRIPTIONS associative array (line 27) and the routing dispatch logic (line 509).
• docs/cli-router.md – Documentation explaining how the CLI routing mechanism processes group inputs and displays help text for command groups.
• docs/file-layout.md – Specification of the file naming conventions, confirming that user-facing commands follow the omarchy-<group>-<verb> pattern.
• bin/omarchy-<group>-<verb> – Individual command scripts implementing concrete behavior for each verb within their respective groups.

Summary

Omarchy CLI commands are organized into groups through a deterministic filesystem-based architecture:

• Script naming follows the strict pattern omarchy-<group>-<verb> in the bin/ directory.
• Group metadata is centralized in the GROUP_DESCRIPTIONS associative array within bin/omarchy.
• Routing logic at line 509 validates groups and dispatches to the appropriate script.
• Functional coverage includes groups for hardware (hw), packages (pkg, install), themes (theme), updates (update), toggles (toggle), and configuration (refresh).

Frequently Asked Questions

How does Omarchy determine which group a command belongs to?

Omarchy extracts the group identifier from the second positional argument in the command invocation. The router script bin/omarchy validates this identifier against the GROUP_DESCRIPTIONS associative array, then constructs the target script path by combining omarchy, the group name, and the verb with hyphens.

Can I create custom command groups in Omarchy?

Yes, custom groups require creating a new entry in the GROUP_DESCRIPTIONS array inside bin/omarchy and placing executable scripts named omarchy-<group>-<verb> in the bin/ directory. The router automatically recognizes new groups added to the associative array at lines 29-92.

Where are the human-readable descriptions for command groups defined?

The GROUP_DESCRIPTIONS associative array in bin/omarchy (starting at line 27) contains all group descriptions. This array maps group names like toggle, theme, and update to descriptive strings that appear in help output when users request assistance with specific command categories.

What happens if I run an Omarchy command with an invalid group name?

The router checks the requested group against the GROUP_DESCRIPTIONS array. If the group does not exist in this associative array, the routing logic at line 509 fails validation and displays an error message or help text rather than attempting to execute a non-existent script.

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