Omarchy CLI Command Groups: Complete Guide to the Router Architecture

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, 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 <group> <verb>, the router checks that <group> exists in the table, then executes the corresponding script named bin/omarchy-<group>-<verb>. 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 and documented in [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/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:

omarchy help

Toggle the night-light feature:

omarchy toggle nightlight

Capture a full-screen screenshot to the default location:

omarchy capture screenshot

Install a custom theme and refresh the UI:

omarchy theme set my-awesome-theme
omarchy theme refresh

Run the complete system update pipeline:

omarchy update

Switch audio output to a specific device:

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-<group>-<verb>.
• 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-<group>-<verb> and reside in the repository's bin/ directory. As noted in [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 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.

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