What Is the Purpose of the bin Directory in Omarchy? CLI Architecture Explained

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

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

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