# How the Omarchy CLI Router Dispatches Commands: Anatomy of the Entry Point > Discover how the Omarchy CLI router dispatches commands by parsing arguments, validating groups, and executing binaries. Understand the entry point's mechanism. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-28 --- **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--` 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`](https://github.com/basecamp/omarchy/blob/main/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 --help`, and developers add functionality simply by placing a new `omarchy--` script in the `bin/` directory. ## Practical Examples The following examples demonstrate the dispatch flow in action: ```bash # Example: List available themes $ omarchy theme list # Router parses: # group = "theme" # action = "list" # → Constructs and executes `omarchy-theme-list` ``` ```bash # Example: Toggle the touchpad $ omarchy toggle touchpad # Router builds `omarchy-toggle-touchpad` and executes it ``` ```bash # 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--`** 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--`. 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`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), prevents context isolation issues that could occur if such commands ran as independent subprocesses.