How the Omarchy CLI Router Dispatches Commands: Anatomy of the Entry Point

The Omarchy CLI router dispatches commands by parsing the first argument as a command group, validating it against the GROUP_DESCRIPTIONS table, constructing a binary name following the omarchy-<group>-<action> convention, and executing the resulting binary if it exists on $PATH.

The Omarchy command-line interface, maintained in the basecamp/omarchy repository, implements a declarative routing mechanism that separates command resolution from execution. This architecture allows the system to remain self-documenting while delegating concrete operations to discrete, single-purpose binaries.

The Entry Point Architecture in bin/omarchy

At the heart of the system lies bin/omarchy, the single entry point script that acts as the command router. Unlike monolithic CLI tools that embed all logic internally, Omarchy adopts a dispatcher pattern where the main script only handles argument parsing and binary resolution. This design ensures that the omarchy script remains a stable, backward-compatible entry point while individual commands evolve independently.

The router maintains an internal lookup table called GROUP_DESCRIPTIONS (defined within bin/omarchy) that catalogs known command groups, their human-readable descriptions, and metadata such as visibility flags. This table serves as the source of truth for validation and help text generation.

The Five-Step Dispatch Flow

The routing logic follows a strict five-phase pipeline from user input to binary execution.

1. Argument Parsing and Group Resolution

The router reads the first positional argument as the command group (e.g., theme, toggle, update). All subsequent arguments are captured as the action and its parameters. For example, the invocation omarchy theme list parses theme as the group and list as the action.

2. Group Validation via GROUP_DESCRIPTIONS

Before attempting execution, the router validates the supplied group against the GROUP_DESCRIPTIONS table. This verification step ensures that only registered groups proceed to binary construction, while also enabling the generation of contextual help output for invalid or incomplete commands.

3. Binary Name Construction

For a validated group X and action Y, the router constructs the concrete binary name following the strict convention omarchy-X-Y. This naming convention creates a predictable mapping between CLI invocations and filesystem binaries, allowing the router to locate executables without maintaining a hardcoded command registry.

4. Execution and PATH Validation

The router checks whether the constructed binary exists on $PATH. If the binary is found, the router executes it via exec, passing all remaining arguments unchanged. If the binary is missing, the router emits an informative error message rather than failing silently. This PATH-based resolution enables system-wide command discovery without requiring manual registration.

5. Hyprland Safe Dispatch Mode

When commands require interaction with the Hyprland compositor (such as window management operations), the router employs a specialized dispatch path. Instead of invoking the binary directly, it forwards the request through hyprctl dispatch, Hyprland's official control interface. As documented in docs/cli-router.md, this "safe dispatch" path ensures that window manager commands execute within the compositor's context rather than as isolated subprocesses.

Hidden Commands and Self-Documentation

The Omarchy router supports hidden commands through metadata tags embedded in script headers (specifically omarchy:hidden=true). These commands remain dispatchable when referenced explicitly but are excluded from the GROUP_DESCRIPTIONS table and top-level help listings. This mechanism allows developers to implement administrative or experimental functions without cluttering the primary user interface.

Because the router delegates every operation to separate binaries, the CLI achieves self-documentation: users can explore available commands via omarchy <group> --help, and developers add functionality simply by placing a new omarchy-<group>-<action> script in the bin/ directory.

Practical Examples

The following examples demonstrate the dispatch flow in action:

# Example: List available themes

$ omarchy theme list

# Router parses:

#   group = "theme"

#   action = "list"

# → Constructs and executes `omarchy-theme-list`

# Example: Toggle the touchpad

$ omarchy toggle touchpad

# Router builds `omarchy-toggle-touchpad` and executes it

# Example: Dispatch a Hyprland command via the router

$ omarchy dsp exec_cmd "omarchy-launch-shell"

# Router forwards to Hyprland's dispatcher:

#   hyprctl dispatch 'hl.dsp.exec_cmd("omarchy-launch-shell")'

Summary

• bin/omarchy serves as the sole entry point and command router for the entire CLI.
• The GROUP_DESCRIPTIONS table validates command groups and drives help text generation.
• Binary resolution follows the omarchy-<group>-<action> naming convention and $PATH lookup.
• Missing binaries trigger explicit error messages rather than silent failures.
• Hyprland-specific operations route through hyprctl dispatch for compositor safety.
• Hidden commands (marked with omarchy:hidden=true) remain executable but invisible in help listings.
• New commands require no router modifications—only the addition of properly named binaries to bin/.

Frequently Asked Questions

What is the naming convention for Omarchy CLI binaries?

Omarchy binaries follow the strict pattern omarchy-<group>-<action>. The router in bin/omarchy constructs this name by concatenating omarchy- with the first argument (group), a hyphen, and the second argument (action). All concrete command implementations reside as individual scripts following this convention in the bin/ directory.

How does the router handle missing commands?

When the router constructs a binary name that does not exist on $PATH, it halts execution and prints an informative error message indicating that the command is unavailable. This validation occurs after group lookup but before any attempt to execute, ensuring users receive clear feedback rather than shell "command not found" errors.

What is the role of GROUP_DESCRIPTIONS in the Omarchy CLI?

The GROUP_DESCRIPTIONS table acts as the router's registry of valid command groups. Defined within bin/omarchy, this structure contains human-readable descriptions and metadata for each group, enabling the router to validate user input, generate help output, and distinguish between public and hidden functionality without parsing the filesystem.

How are Hyprland commands handled differently?

Commands targeting the Hyprland compositor bypass direct binary execution in favor of the Hyprland dispatcher. The router translates these requests into hyprctl dispatch calls, ensuring that window management operations execute within the compositor's context. This safe dispatch path, documented in docs/cli-router.md, prevents context isolation issues that could occur if such commands ran as independent subprocesses.

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