How Omarchy CLI Commands Are Organized: Directory Structure and Routing

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-<group>-<verb>, 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 <group>, 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, 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-<service>: 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-<group>-<verb> 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.

# 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.

Frequently Asked Questions

How do I add a custom command to Omarchy?

Create an executable script in the bin/ directory following the omarchy-<group>-<verb> 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 <group>. 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, 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.

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