# Omarchy CLI Command Groups: Complete Guide to the Router Architecture > Explore Omarchy CLI command groups like toggle capture theme and system. Understand the router architecture and how commands map to verb implementations in this complete guide. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-21 --- **The Omarchy CLI organizes all functionality into logical command groups—such as `toggle`, `capture`, `theme`, and `system`—that route through a central `bin/omarchy` script using a `GROUP_DESCRIPTIONS` associative array to map prefixes to specific verb implementations.** The Omarchy project from basecamp/omarchy implements a strictly modular command-line interface where every operation follows a `group-verb` naming convention. This architecture, defined in the main router script and documented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), categorizes system operations into distinct command groups that correspond directly to executable files located in the `bin/` directory. ## How the Omarchy CLI Router Works The entry point `bin/omarchy` functions as a dispatcher that validates group prefixes against the `GROUP_DESCRIPTIONS` table. When you invoke `omarchy `, the router checks that `` exists in the table, then executes the corresponding script named `bin/omarchy--`. This design enforces a flat, predictable filesystem structure while providing organized help text through the `GROUP_DESCRIPTIONS` metadata as implemented in the quattro branch. ## Complete Reference of Omarchy CLI Command Groups The following groups are defined in the `GROUP_DESCRIPTIONS` array within [`bin/omarchy`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy) and documented in [[`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md)](https://github.com/basecamp/omarchy/blob/quattro/docs/cli-router.md): - **cmd**: General utilities and sanity checks. Examples: `omarchy-cmd-present`, `omarchy-cmd-missing` - **capture**: Screen-capture, webcam, and QR utilities. Examples: `omarchy-capture-screenshot`, `omarchy-capture-webcam-list` - **pkg**: Package-management helpers for adding or removing software. Examples: `omarchy-pkg-add`, `omarchy-pkg-drop` - **hw**: Hardware detection and configuration tools. Examples: `omarchy-hw-asus-rog`, `omarchy-hw-display` - **refresh**: Copies default configuration files to the user’s `$HOME`. Example: `omarchy-refresh-config` - **restart**: Restarts specific components or services. Example: `omarchy-restart-omarchy` - **launch**: Opens applications or URLs via dedicated launchers. Examples: `omarchy-launch-browser`, `omarchy-launch-floating-terminal-with-presentation` - **install**: Optional software installers for development environments. Examples: `omarchy-install-node`, `omarchy-install-fonts` - **setup**: Interactive setup wizards for initial system configuration. Examples: `omarchy-setup-dev`, `omarchy-setup-wifi` - **toggle**: Switches features on or off dynamically. Examples: `omarchy-toggle-nightlight`, `omarchy-toggle-screensaver` - **theme**: Theme selection, installation, and manipulation utilities. Examples: `omarchy-theme-set`, `omarchy-theme-list`, `omarchy-theme-refresh` - **update**: System-wide update pipeline and lock management. Examples: `omarchy-update`, `omarchy-update-available`, `omarchy-update-lock` - **agent**: AI-agent interfaces including Claude and Codex integrations. Examples: `omarchy-agent-prompt`, `omarchy-agent-usage-claude` - **dev**: Development helpers, benchmarking, and test scaffolding. Examples: `omarchy-dev-benchmark-cli`, `omarchy-dev-add-migration` - **system**: Power-control, sleep, and shutdown helpers. Examples: `omarchy-system-reboot`, `omarchy-system-sleep-monitor` - **weather**: Weather-service configuration and status checks. Examples: `omarchy-weather-location`, `omarchy-weather-status` - **voxtype**: Voice-type (speech-to-text) model management. Examples: `omarchy-voxtype-install`, `omarchy-voxtype-model` - **windows**: Windows VM integration and key-mapping utilities. Examples: `omarchy-windows-vm`, `omarchy-windows-key` - **bar**: Status-bar customization and text-color controls. Examples: `omarchy-bar`, `omarchy-bar-text-color` - **audio**: Audio output/input selection and volume control. Examples: `omarchy-audio-output-switch`, `omarchy-audio-input-mute` - **branding**: Branding-related UI elements and screensavers. Examples: `omarchy-branding-about`, `omarchy-branding-screensaver` - **brightness**: Screen-brightness control for DDC, Apple displays, and keyboard backlights. Examples: `omarchy-brightness-display`, `omarchy-brightness-keyboard-mute` - **clipboard**: Clipboard interaction helpers for text and data. Examples: `omarchy-clipboard-paste-text`, `omarchy-clipboard-open` - **channel**: Update-channel selection for release management. Examples: `omarchy-channel-set`, `omarchy-channel-current` - **dots** *(planned)*: Reserved for constrained dotfiles commands. - **backup** *(planned)*: Reserved for future backup-related operations. - **server** *(planned)*: Reserved for server-edition specific commands. ## Routing and File Naming Conventions Each command group acts as a strict prefix in the executable filename. According to [[`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md)](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md), the router constructs the target script path by joining three components: `bin/omarchy-`, the group prefix, a hyphen, and the verb. For instance, invoking `omarchy toggle nightlight` causes the router to execute `bin/omarchy-toggle-nightlight`, while `omarchy capture screenshot` maps to `bin/omarchy-capture-screenshot`. This convention ensures that adding new functionality requires only dropping a correctly named executable into the `bin/` directory without modifying the router logic. ## Practical Usage Examples List available groups and their descriptions: ```bash omarchy help ``` Toggle the night-light feature: ```bash omarchy toggle nightlight ``` Capture a full-screen screenshot to the default location: ```bash omarchy capture screenshot ``` Install a custom theme and refresh the UI: ```bash omarchy theme set my-awesome-theme omarchy theme refresh ``` Run the complete system update pipeline: ```bash omarchy update ``` Switch audio output to a specific device: ```bash omarchy audio output-switch ``` ## Summary - The Omarchy CLI uses a **group-verb architecture** where every command belongs to a logical group defined in `GROUP_DESCRIPTIONS`. - The central router at **`bin/omarchy`** dispatches invocations to executables named **`bin/omarchy--`**. - Groups range from system control (**`system`**, **`update`**) and hardware management (**`hw`**, **`brightness`**, **`audio`**) to development tools (**`dev`**, **`agent`**, **`install`**). - Future expansion is handled through reserved groups like **`dots`**, **`backup`**, and **`server`**. - Command discovery is self-documenting via the **`GROUP_DESCRIPTIONS`** table, which the router exposes through the help interface. ## Frequently Asked Questions ### How does the Omarchy router validate command groups? The router references the **`GROUP_DESCRIPTIONS`** associative array defined at the top of `bin/omarchy`. If the provided group prefix exists as a key in this table, the router proceeds to locate the specific verb script; otherwise, it returns an error and displays the help text listing valid groups. ### What is the difference between the `refresh` and `update` command groups? The **`refresh`** group handles configuration synchronization—copying default dotfiles and templates to the user’s home directory without installing new software. The **`update`** group manages the system-wide software update pipeline, including package upgrades, lock files, and maintenance tasks. According to the source, `refresh` is idempotent and safe to run frequently, while `update` performs network operations and system modifications. ### Where should new command scripts be placed to integrate with existing groups? New scripts must follow the naming convention `omarchy--` and reside in the repository's **`bin/`** directory. As noted in [[`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md)](https://github.com/basecamp/omarchy/blob/quattro/AGENTS.md), when adding a new group, you must also register it in the `GROUP_DESCRIPTIONS` array within `bin/omarchy` and document the description in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) to maintain consistency with the router's help system. ### Can users create custom command groups? While the router supports any group name listed in `GROUP_DESCRIPTIONS`, adding custom groups requires modifying the **`GROUP_DESCRIPTIONS`** table in `bin/omarchy` and creating the corresponding executable files. The system does not dynamically load unknown groups from the filesystem alone; explicit registration in the router's description table is mandatory for the help system to recognize and route the commands correctly.