# What Is the Main CLI Router for Omarchy Commands? Understanding bin/omarchy

> Discover bin/omarchy, the main CLI router for Omarchy commands. Learn how it parses input and directs execution to sub-commands for efficient management.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-05

---

**The main CLI router for Omarchy commands is the `bin/omarchy` script, which parses user input and dispatches execution to specialized sub-command scripts under the `bin/` directory.**

The **Omarchy** open-source project implements a clean, modular command-line interface through a single entry-point router. Rather than a monolithic binary, Omarchy uses a dispatch pattern where `bin/omarchy` handles argument parsing and delegates actual work to purpose-built executable scripts. This architecture keeps the core router simple while enabling extensible, group-based command organization.

## How bin/omarchy Routes Commands

The router script operates through a predictable parsing sequence. When you run `omarchy <group> [action] [args]`, the script performs several key operations in order.

### Argument Parsing and Group Lookup

`bin/omarchy` treats the first positional argument as a **command group**. It validates this group against an internal `GROUP_DESCRIPTIONS` associative array defined within the same file. This array maps group names to human-readable descriptions for help output.

```bash

# Group descriptions are defined directly in bin/omarchy

# Example groups: theme, toggle, update

```

### Sub-Command Discovery and Execution

After identifying the group, the router searches for an executable matching the pattern `omarchy-<group>-<action>` in the `bin/` directory. If found, it validates executability and delegates control. The script also handles **hidden groups** — those marked with `omarchy:hidden=true` — which remain functional but are excluded from help summaries.

### Environment Setup

Before handing off to sub-commands, `bin/omarchy` establishes critical environment variables including `$OMARCHY_PATH`. This ensures all downstream scripts operate within a consistent runtime context.

## CLI Router Usage Examples

Understanding the routing pattern helps predict which underlying script executes for any given command.

```bash

# Display top-level help showing all visible groups

omarchy help

# Route to theme group scripts (bin/omarchy-theme-*)

omarchy theme set dark

# Route to toggle group scripts (bin/omarchy-toggle-*)

omarchy toggle screensaver

# Hidden groups work when explicitly invoked

omarchy hidden-group some-action

```

Each invocation flows through `bin/omarchy` before reaching the actual implementation at `bin/omarchy-<group>-<action>`.

## Core Files in the Routing Architecture

The Omarchy CLI system spans several coordinated files across the repository:

- **`bin/omarchy`** — The central router; handles parsing, group validation, hidden group filtering, environment setup, and sub-command dispatch.
- **`bin/omarchy-<group>-<action>`** — Individual command implementations (e.g., `bin/omarchy-theme-set`, `bin/omarchy-toggle-screensaver`).
- **[`docs/testing.md`](https://github.com/omacom/omarchy/blob/main/docs/testing.md)** — Documents how CLI routing behavior is validated through automated tests.
- **[`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md)** — Lists task-specific agents; explicitly includes the CLI router as a core system agent.

## Summary

- **`bin/omarchy`** serves as the sole entry point and router for all Omarchy CLI commands.
- The script parses arguments into **groups** and **actions**, then dispatches to matching executables under `bin/`.
- **Hidden groups** remain functional but are excluded from help output via `omarchy:hidden=true` markers.
- Environment variables like `$OMARCHY_PATH` are initialized before sub-command execution.
- The modular design enables clean extension by adding new `bin/omarchy-<group>-<action>` scripts.

## Frequently Asked Questions

### How does Omarchy handle unknown or misspelled commands?

The `bin/omarchy` router validates groups against its internal `GROUP_DESCRIPTIONS` array. Unrecognized groups trigger appropriate error handling rather than silent failure, directing users toward valid commands via the help system.

### Can I add custom command groups to Omarchy?

Yes. Create a new executable following the `bin/omarchy-<group>-<action>` naming convention and optionally add the group to `GROUP_DESCRIPTIONS` in `bin/omarchy` for visibility in help output. The router automatically discovers any executable matching its dispatch pattern.

### What distinguishes visible from hidden groups in Omarchy?

Visible groups appear in standard help output and are listed in `GROUP_DESCRIPTIONS`. Hidden groups carry the `omarchy:hidden=true` marker and remain operational but unadvertised — useful for internal tooling, experimental features, or power-user functionality.