Where Are Omarchy Runtime Binaries and Scripts Located?

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:

omarchy commands --all

To inspect a specific command's metadata as JSON:

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 – Clipboard capture helper used by the clipboard plugin
• 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:

/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. These are distinct from the CLI binaries in bin/ and are typically invoked by Quickshell QML components rather than user commands.

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