# How to Customize Omarchy CLI Commands: A Complete Guide > Customize Omarchy CLI commands by creating scripts in bin/ and adding metadata headers. Discover how to easily extend Omarchy's functionality without extra config files. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-12 --- **Yes, you can customize Omarchy CLI commands by creating executable scripts in the `bin/` directory and annotating them with `# omarchy:` metadata headers that the router automatically discovers without requiring additional configuration files.** The **omac/omarchy** repository implements a lightweight command-line interface built entirely within a single Bash script. Because the routing logic relies solely on executable files and their embedded comment metadata, you can extend or modify the CLI instantly by adding or editing scripts. This architecture eliminates complex plugin systems—any executable matching the `omarchy-*` pattern becomes a discoverable command. ## How the Command Router Discovers Scripts The core routing mechanism lives in **`bin/omarchy`**, which implements a dynamic discovery system. When the `omarchy` binary executes, the function **`load_commands`** iterates over all files matching `"$OMARCHY_BIN_DIR"/omarchy-*` (see lines 15‑22). For each executable file found, it invokes **`register_command`** to parse metadata. Inside **`register_command`** (lines 90‑115), the script reads the first 80 lines of the target file, searching for comment headers formatted as `# omarchy:=`. Valid keys include `group`, `name`, `summary`, `args`, `examples`, `aliases`, `requires-sudo`, and `hidden`. A `case` block beginning at line 112 extracts these values into associative arrays. After parsing, **`register_route`** constructs route mappings. The system generates a fallback route from the filename (e.g., `omarchy-capture-screenshot` becomes `omarchy capture screenshot`) and registers both explicit and fallback routes (lines 65‑73 and 98‑101). When a user executes a command, **`resolve_route`** (lines 191‑216) iteratively shortens the provided token list until it finds a match in the `ROUTE_TO_KEY` array, then executes the associated binary. ## Three Methods to Customize Omarchy CLI Commands Because the router depends only on filesystem presence and comment metadata, you have three primary ways to customize the CLI: - **Add new commands**: Drop an executable script named `omarchy--` (or simply `omarchy-`) into the `bin/` directory with the required `# omarchy:` headers. The router will discover it automatically on the next invocation. - **Extend existing commands**: Edit any existing `bin/omarchy-*` script to modify its `group`, `name`, `summary`, `args`, `examples`, or metadata. Changes take effect immediately without restarting any service. - **Create command aliases**: Add an `# omarchy:aliases=` line to any script, using pipe-separated values (e.g., `omarchy upd | omarchy up`). The router registers each alias as a distinct route pointing to the same binary. ## Practical Implementation Examples ### Creating a Custom Hello Command To add a new command that greets users, create a script at **`bin/omarchy-demo-hello`** with the following content: ```bash #!/usr/bin/env bash # omarchy:group=demo # omarchy:name=hello # omarchy:summary=Print a greeting from Omarchy # omarchy:args=[name] # omarchy:examples=omarchy demo hello Alice | omarchy demo hello name="${1:-World}" echo "Hello, $name! 👋" ``` Make the file executable with `chmod +x bin/omarchy-demo-hello`. The command now responds to `omarchy demo hello` (or `omarchy hello` via fallback routing), and `omarchy demo hello --help` automatically displays the metadata-driven help text. ### Adding Aliases to Existing Commands To create shortcuts for frequently used commands, edit the target script’s headers. For example, to alias the update command, modify **`bin/omarchy-update`** to include: ```bash # omarchy:aliases=omarchy upd | omarchy up ``` After saving, both `omarchy upd` and `omarchy up` resolve to the same binary as `omarchy update`. The router parses this metadata during the next CLI invocation. ### Hiding Commands and Enforcing Sudo Privileges For experimental or administrative commands, use the `hidden` and `requires-sudo` metadata flags. To hide a command from the default `omarchy commands` list (visible only with `--all`), add: ```bash # omarchy:hidden=true ``` To force automatic sudo elevation when the command runs, add: ```bash # omarchy:requires-sudo=true ``` These headers work in any `bin/omarchy-*` script and take effect immediately. ## Core Router Functions and Source Code Understanding the internal functions helps when debugging custom commands: 1. **`load_commands`** (lines 15‑22): Scans `bin/` for executables matching `omarchy-*` and initializes registration. 2. **`register_command`** (lines 90‑115): Parses the first 80 lines for `# omarchy:` metadata using a `case` block (starting line 112) to populate routing tables. 3. **`register_route`** (lines 65‑73, 98‑101): Maps human-readable routes to binary paths, handling both explicit metadata and filename fallbacks. 4. **`resolve_route`** (lines 191‑216): Resolves user input tokens to executable binaries by traversing the route hierarchy. Key files to reference when customizing: - **`bin/omarchy`**: The core router script containing all discovery and dispatch logic. - **`bin/omarchy-update`**: Reference implementation showing metadata usage. - **[`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md)**: Documentation explaining CLI usage and discovery conventions. ## Summary - The Omarchy CLI uses a file-based router in `bin/omarchy` that scans for executable `omarchy-*` scripts on every invocation. - Custom commands require only an executable file with `# omarchy:` comment headers specifying `group`, `name`, and `summary`. - The router automatically generates help text, handles argument parsing, and manages command aliases through metadata. - Changes to scripts take effect immediately—no compilation or service restart is necessary. - Advanced features like sudo enforcement and command hiding are controlled via `requires-sudo` and `hidden` metadata flags. ## Frequently Asked Questions ### Do I need to restart Omarchy after adding a custom command? No. The router reloads all commands on every invocation of the `omarchy` binary. Simply save your executable script in the `bin/` directory and run any `omarchy` command—the new command will be available immediately. ### What metadata headers are required for a custom command? At minimum, you should include `# omarchy:group=`, `# omarchy:name=`, and `# omarchy:summary=`. While the router can generate a fallback route from the filename (e.g., `omarchy-demo-hello`), explicit metadata ensures proper categorization in help listings and enables features like custom argument descriptions and examples. ### Can I override existing Omarchy commands with custom scripts? Yes. If you create a script with the same effective route as an existing command, the router will resolve to the binary based on the standard discovery order. However, be cautious when overriding core commands, as updates to the repository may conflict with your custom implementations. ### How do I make a custom command require administrator privileges? Add the header `# omarchy:requires-sudo=true` to your script. When users invoke the command, the CLI automatically detects this flag and prepends `sudo` to the execution context, ensuring the script runs with elevated privileges without users needing to manually type `sudo` before the command.