# Where Are Omarchy Runtime Binaries and Scripts Located? > Find Omarchy runtime binaries and scripts easily. Discover the bin/omarchy and bin/omarchy-* locations for core functions and shell/ for UI scripts in the basecamp/omarchy repository. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-22 --- **Omarchy's runtime binaries are located in the `bin/` directory, with the dispatcher at `bin/omarchy` and individual commands following the `bin/omarchy-*` naming convention, while auxiliary UI and plugin scripts reside under the `shell/` tree.** Omarchy organizes its command-line interface through a modular binary architecture that separates command dispatch from implementation. Understanding the exact file locations and loading mechanisms is essential for debugging, extending, or customizing the system. This guide maps every runtime component based on the basecamp/omarchy source code. ## The Dispatcher: `bin/omarchy` The single entry point for all Omarchy CLI operations is **`bin/omarchy`**. This dispatcher script serves as the orchestration layer that discovers, registers, and executes runtime binaries. When invoked, the dispatcher scans its own directory (`bin/`) for any executable files whose names begin with `omarchy-`. It then parses the metadata embedded in the top-comment block of each binary to build the command registry. The core registration logic lives in the `register_command` function (lines 66–94 of the dispatcher), which extracts routing information, groups, aliases, and help text from specially formatted comments (e.g., `# omarchy:group=update`). ## Runtime Binaries in `bin/` All **runtime binaries** implementing specific Omarchy commands reside in the `bin/` directory alongside the dispatcher. These are standard Bash scripts (shebang `#!/usr/bin/env bash`) that expose capabilities through embedded metadata comments. ### Command Discovery and Registration The dispatcher uses the `load_commands` and `load_group_commands` functions to build the execution environment at startup. It automatically discovers binaries matching the `bin/omarchy-*` pattern and maps them to command routes based on their filenames and metadata. For example, the binary `bin/omarchy-theme-list` automatically registers under the route `omarchy theme list`, while `bin/omarchy-update` maps to the update command group. ### Notable Runtime Binaries The `bin/` directory contains specialized binaries for system management, theming, and feature toggles: - **`omarchy-update`** – Handles system and Omarchy package updates - **`omarchy-theme-list`** and **`omarchy-theme-set`** – Manage desktop theme switching - **`omarchy-toggle-screensaver`** and **`omarchy-toggle-nightlight`** – Control desktop environment features - **`omarchy-windows-vm`** and **`omarchy-windows-key`** – Provide Windows virtual machine integration helpers - **`omarchy-weather-status`** and **`omarchy-weather-location`** – Support weather widget functionality You can list all available commands (including hidden ones) using: ```bash omarchy commands --all ``` To inspect a specific command's metadata as JSON: ```bash omarchy commands --json | jq '.commands[] | select(.binary=="omarchy-update")' ``` ## Auxiliary Scripts in `shell/` Beyond the CLI binaries, **supporting scripts** for the Quickshell-based UI and individual plugins live in the `shell/` directory. These components are not invoked directly from the command line but provide runtime services and widget logic. ### UI Components and Services The top-level QML files establish the graphical runtime environment: - **`shell/shell.qml`** – The primary UI entry point that initializes the desktop shell - **`shell/services/PluginRegistry.qml`** – Loads and manages shell plugins at runtime These QML components orchestrate the desktop environment and delegate specific tasks to helper scripts. ### Plugin Helper Scripts Many plugins ship small Bash scripts that perform specialized functions invoked by their parent QML components: - **[`shell/plugins/clipboard/capture.sh`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/clipboard/capture.sh)** – Clipboard capture helper used by the clipboard plugin - **[`shell/plugins/image-picker/list.sh`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/image-picker/list.sh)** – Generates image lists for the image picker widget - **`shell/plugins/bar/widgets/Tray.qml`** – Contains tray widget logic (QML-based but part of the runtime script architecture) While designed for internal use, you can invoke these scripts directly for debugging: ```bash /path/to/omarchy/quattro/shell/plugins/clipboard/capture.sh ``` ## How the Dispatcher Loads Commands When you execute a command like `omarchy theme list`, the dispatcher performs the following sequence: 1. **Scanning**: Reads the `bin/` directory to find `bin/omarchy-theme-list` 2. **Parsing**: Extracts metadata from the binary's comment block using `register_command` 3. **Routing**: Maps the CLI arguments to the discovered binary 4. **Execution**: Spawns the binary with any additional arguments This architecture allows new commands to be added simply by dropping an executable `omarchy-*` file into the `bin/` directory with appropriate metadata headers. ## Summary - **Dispatcher location**: `bin/omarchy` serves as the single entry point that orchestrates all commands - **Runtime binaries**: All command implementations reside in `bin/` following the `omarchy-*` naming convention - **Metadata parsing**: The `register_command` function (lines 66–94) extracts command metadata from comment blocks - **Support scripts**: UI helpers and plugin logic live under `shell/`, including QML services and Bash helper scripts - **Extensibility**: New commands are automatically discovered when placed in `bin/` with executable permissions and proper metadata ## Frequently Asked Questions ### What is the entry point for Omarchy commands? The entry point is **`bin/omarchy`** in the repository root. This dispatcher binary handles all CLI invocations and routes them to the appropriate runtime binary in the `bin/` directory. You should never need to call the individual `omarchy-*` binaries directly; instead, use the dispatcher which provides unified help, routing, and error handling. ### How does Omarchy discover available commands? Omarchy uses filesystem scanning and metadata parsing. The dispatcher executes `load_commands` at startup to scan the `bin/` directory for files matching `omarchy-*`, then uses `register_command` (lines 66–94) to parse metadata from comment headers like `# omarchy:group=update` or `# omarchy:alias=up`. This allows commands to self-describe their capabilities without requiring a central registry file. ### Can I run individual Omarchy binaries directly? While technically possible, **direct execution is not recommended**. The binaries in `bin/omarchy-*` expect specific environment variables and argument formats set by the dispatcher. If you must run a script directly for debugging, use the full path (e.g., `./bin/omarchy-update`), but be aware that help text, grouping, and aliases will not function outside the dispatcher context. ### Where are Omarchy's UI-related scripts stored? UI-related scripts and components reside in the **`shell/` directory**. This includes the main `shell/shell.qml` UI entry point, `shell/services/PluginRegistry.qml` for plugin management, and helper scripts like [`shell/plugins/clipboard/capture.sh`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/clipboard/capture.sh). These are distinct from the CLI binaries in `bin/` and are typically invoked by Quickshell QML components rather than user commands.