# How Omarchy CLI Commands Are Organized: Directory Structure and Routing > Discover how Omarchy CLI commands are organized using a hierarchical naming convention and centralized routing in bin/omarchy. Understand the directory structure and command patterns for efficient use. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-23 --- **Omarchy CLI commands follow a hierarchical naming convention in the `bin/` directory, using the prefix `omarchy-` followed by a group and verb pattern, with routing logic centralized in `bin/omarchy` through a `GROUP_DESCRIPTIONS` associative array.** Omarchy is an opinionated Arch Linux distribution developed by Basecamp that manages system configuration through a structured command-line interface. Understanding how Omarchy CLI commands are organized reveals a clean, file-based architecture where command discovery, grouping, and execution rely on consistent naming conventions and a central dispatcher. This design makes the system both self-documenting and easily extensible without complex registration steps. ## Command Storage and Naming Convention All user-facing executable commands reside in the repository’s `bin/` directory. Each command follows a strict filename pattern: `omarchy--`, where the segment after the prefix identifies the functional category and the final segment describes the action. This convention produces intuitive filenames such as: - `omarchy-toggle-touchscreen` – Toggles hardware features - `omarchy-update-system-pkgs` – Handles package updates - `omarchy-theme-set` – Manages visual themes The full inventory of available commands is visible directly in the filesystem under `bin/`, making the CLI surface area transparent to both users and developers. ## The Central Router and Group Descriptions The file `bin/omarchy` serves as the main entry point and implements the routing logic that connects user input to the appropriate executable. Inside this dispatcher script, a Bash associative array named `GROUP_DESCRIPTIONS` maps each command group (the segment between `omarchy-` and the final hyphen) to a human-readable description. When a user runs `omarchy `, the script parses the argument, consults `GROUP_DESCRIPTIONS` to validate the group exists, and displays the relevant help text. This centralization ensures that group definitions and metadata remain consistent across the entire CLI. ## Hidden Commands and Special Routing The routing system supports hidden commands that remain executable but are excluded from automatic help listings. Developers mark these by adding the comment `# omarchy:hidden=true` within the command script. Despite being hidden from the `omarchy help` output, these scripts remain fully routable when invoked directly via the dispatcher. Detailed documentation for this routing mechanism is maintained in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), which specifies how arguments are parsed and dispatched to the underlying `bin/` scripts. ## Common Command Groups The naming pattern encodes functionality across several standard domains: **`omarchy-toggle-*`**: Commands that switch binary states for hardware or system features, including touchscreen, touchpad, and nightlight controls. **`omarchy-update-*`**: Update pipeline steps such as `omarchy-update-system-pkgs`, `omarchy-update-aur-pkgs`, and `omarchy-update-status`. **`omarchy-theme-*`**: Theme management utilities like `omarchy-theme-install`, `omarchy-theme-set`, and `omarchy-theme-refresh`. **`omarchy-`**: Standalone service utilities including `omarchy-weather`, `omarchy-voxtype`, and `omarchy-tailscale` that do not require a secondary verb. ## Extending the CLI Adding a new command requires no registration boilerplate. Create a new executable script in `bin/` that follows the `omarchy--` naming convention. Optionally, add an entry to the `GROUP_DESCRIPTIONS` array in `bin/omarchy` to provide a description for the new group. The router automatically recognizes and dispatches to any executable matching the pattern. ```bash # List all available command groups with descriptions omarchy help # Toggle the touchscreen on or off omarchy-toggle-touchscreen # Update system packages (part of the full update pipeline) omarchy-update-system-pkgs # Switch to a different theme omarchy-theme-set solstice ``` ## Summary - **Omarchy CLI commands are organized** as executable scripts in the `bin/` directory, prefixed with `omarchy-` and following a `group-verb` naming pattern. - The `bin/omarchy` file acts as the central dispatcher, using the `GROUP_DESCRIPTIONS` associative array to map command groups to human-readable help text. - Hidden commands are supported via the `# omarchy:hidden=true` comment marker, keeping advanced utilities out of default listings while maintaining routability. - New commands require only a properly named executable in `bin/` and an optional entry in `GROUP_DESCRIPTIONS`, making the CLI highly extensible. - Documentation for the routing logic is available in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md). ## Frequently Asked Questions ### How do I add a custom command to Omarchy? Create an executable script in the `bin/` directory following the `omarchy--` naming convention. If your command introduces a new group, add the group and description to the `GROUP_DESCRIPTIONS` associative array in `bin/omarchy`. The router automatically picks up the command without additional registration. ### What is the purpose of the `GROUP_DESCRIPTIONS` array? The `GROUP_DESCRIPTIONS` array in `bin/omarchy` maps command group names to descriptive strings displayed when users run `omarchy help` or `omarchy `. This centralizes metadata management and ensures consistent help text across the CLI. ### How can I hide a command from the automatic help listing? Add the comment `# omarchy:hidden=true` anywhere in your command script. The router will exclude this command from help outputs and group listings, but users can still invoke it directly if they know the full command name. ### Where is the CLI routing logic documented? The routing architecture is documented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), which explains how arguments are parsed, how the dispatcher resolves commands against `bin/` scripts, and how the `GROUP_DESCRIPTIONS` system integrates with the help interface.