# What Is the Purpose of the bin Directory in Omarchy? CLI Architecture Explained > Discover the purpose of the bin directory in Omarchy. Learn how this CLI architecture uses executable Bash scripts to translate commands into binary operations. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: architecture - Published: 2026-09-12 --- **The `bin` directory serves as the runtime command ecosystem for Omarchy, containing executable Bash scripts that the top-level router discovers and invokes to translate spaced CLI syntax into concrete binary operations.** The Omarchy project implements a modular command-line interface where every user-facing operation maps to a specific executable within the repository’s `bin` folder. Understanding the purpose of the bin directory in Omarchy reveals how the system achieves zero-configuration command registration through file naming conventions and a flat, self-describing script architecture. ## Automatic Command Discovery and Registration The `bin` directory operates as a self-registering command surface. Any file located under `bin/` that begins with the `omarchy-` prefix is automatically recognized as a routable command by the central dispatcher. This design eliminates the need for a separate registry or configuration file. In `bin/omarchy`, the router script implements this discovery mechanism by scanning the directory at runtime and building an internal command map. When you invoke `omarchy theme set dark`, the router parses this spaced syntax and locates the corresponding `bin/omarchy-theme-set` executable. The router then uses `exec` to replace its own process with the target binary, ensuring that exit codes propagate correctly to the shell. ## Routing Logic: Mapping Commands to Binaries Omarchy's CLI design translates human-readable spaced commands into flat binary invocations through a consistent naming convention. According to the router implementation documented in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md), the system converts command groupings and verbs into hyphen-separated filenames. For example: - `omarchy toggle touchpad` → executes `bin/omarchy-toggle-touchpad` - `omarchy theme set solarized-dark` → executes `bin/omarchy-theme-set` This pattern allows the router to remain agnostic about specific command implementations while maintaining a clean, namespaced user interface. ```bash # Display all available commands and groups omarchy commands # Execute a specific theme command (maps to bin/omarchy-theme-set) omarchy theme set dark # Toggle hardware features (maps to bin/omarchy-toggle-touchpad) omarchy toggle touchpad ``` ## Command Grouping and Metadata Beyond simple execution, the `bin/omarchy` router provides structured help output through the **GROUP_DESCRIPTIONS** associative array defined within the script. This Bash associative array maps command group prefixes (such as `theme`, `toggle`, or `update`) to human-readable titles that appear in help listings. When users run `omarchy commands`, the router references `GROUP_DESCRIPTIONS` to categorize discovered binaries, providing context for each command family without requiring metadata headers within the individual script files. ## Installation Layout and PATH Resolution The `bin` directory serves dual purposes across development and production environments. In a production installation, the individual binaries are typically placed in `/usr/bin/omarchy-*` or `/usr/share/omarchy/bin/`, making them available system-wide. During local development, the repository’s `bin/` directory is added directly to the `$PATH`, allowing developers to test commands immediately after creating new scripts. This layout is documented in [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md), which specifies that the router searches for executables first in the system path and falls back to relative resolution within the development tree. ## Extending the CLI: Adding New Commands Extending Omarchy’s functionality requires only filesystem operations. To add a new command, create a new script following the `bin/omarchy--` naming pattern and optionally add its group description to the `GROUP_DESCRIPTIONS` array in `bin/omarchy`. No compilation, registration, or dispatcher modification is necessary. The router discovers the new binary automatically on the next invocation, reflecting Omarchy’s philosophy of flat, file-based command architecture. ## Summary - The **bin directory** contains all Omarchy executables prefixed with `omarchy-`, creating a self-describing command surface. - The **router script** (`bin/omarchy`) discovers binaries at runtime and maps spaced CLI syntax to flat binary names. - **Command grouping** is implemented via the `GROUP_DESCRIPTIONS` associative array in the router, providing categorized help output. - **Installation layouts** vary between development (repository `bin/` on `$PATH`) and production (`/usr/bin/omarchy-*`). - **Extensibility** is file-based; adding commands requires only creating properly named scripts in the `bin` directory. ## Frequently Asked Questions ### What naming convention do Omarchy commands follow? Omarchy commands follow the `omarchy--` naming convention. The router script in `bin/omarchy` automatically discovers any executable in the `bin` directory starting with this prefix, converting spaced user input like `omarchy theme set` into the corresponding binary `omarchy-theme-set`. ### How does Omarchy map spaced commands to specific binaries? The router parses the user’s spaced command input and translates it into a hyphen-separated filename. It then searches for this file in the `bin` directory (or system PATH) and executes it using `exec`, replacing the router process entirely so that exit codes and signals propagate correctly to the calling shell. ### Where are Omarchy binaries installed in production systems? In production environments, Omarchy binaries are installed to `/usr/bin/omarchy-*` or `/usr/share/omarchy/bin/` according to [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md). The router locates these executables through standard `$PATH` resolution, while development environments use the repository’s local `bin/` directory. ### How do I add a custom command to Omarchy? Create a new Bash script in the `bin` directory using the format `omarchy--`, make it executable, and optionally add a description for its group to the `GROUP_DESCRIPTIONS` array in `bin/omarchy`. The router will automatically discover and make the command available without requiring additional registration steps.