# How to Add a New Command to the Omarchy CLI Router > Easily add new commands to the Omarchy CLI router. Create executable files in bin/ and use metadata comments for auto-discovery and registration. Streamline your workflow today. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-13 --- **To add a new command to the Omarchy CLI router, create an executable file in the `bin/` directory following the `omarchy--` naming pattern, prepend metadata comments using the `# omarchy:key=value` format, and the router will auto-discover and register your command without any central registry updates.** The **Omarchy CLI** (from the `omacom/omarchy` repository) uses a file-based routing system that eliminates the need to manually register commands in a central configuration. By leveraging executable files with structured comment headers, the router dynamically builds its command tree at runtime, making it trivial to extend the CLI with new functionality. ## How the Omarchy CLI Router Auto-Discovers Commands The router logic resides in `bin/omarchy` and operates through a simple convention-based discovery process. When the CLI initializes, the `load_commands` function scans the `bin/` directory for any executable file prefixed with `omarchy-`. The registration workflow follows these steps: - **File Discovery**: The router identifies files matching `bin/omarchy-*` and treats each as a potential command. - **Metadata Parsing**: For each binary, the router reads the first 80 comment lines to extract metadata keys including `group`, `name`, `summary`, `args`, `aliases`, `hidden`, and `requires-sudo`. - **Route Registration**: The `register_route` function creates two entries for every command: the *canonical* route (derived from metadata or filename) and the *filename* route (where hyphens convert to spaces). - **Collision Detection**: The `omarchy commands --check` utility validates that no two commands register identical routes. This design means the filename itself—minus the `omarchy-` prefix and with hyphens replaced by spaces—determines the default command path (e.g., `bin/omarchy-theme-set` becomes `omarchy theme set`). ## Step-by-Step Guide to Adding a New Command ### 1. Create the Executable File Navigate to the `bin/` directory and create a new file following the naming convention `omarchy--`. For single-word group commands, use `omarchy-`. ```bash touch bin/omarchy-custom-deploy chmod +x bin/omarchy-custom-deploy ``` The hyphenated filename determines the default command structure. The router splits on hyphens to generate the command hierarchy. ### 2. Define Metadata Headers Open the file and add a comment block at the top using the `# omarchy:key=value` syntax. The router stops parsing metadata at the first non-comment line, so keep all definitions at the top. Available metadata keys include: - `group` – The command category (e.g., `theme`, `config`) - `name` – Overrides the filename-derived command name - `summary` – One-line description for help listings - `args` – Argument specification (e.g., `` or `[--force]`) - `aliases` – Space-separated alternative invocations - `hidden` – Set to `true` to hide from `omarchy commands` listings - `requires-sudo` – Set to `true` if the command needs elevated privileges ### 3. Implement Command Logic After the metadata block, write your implementation in any executable language. The router passes all remaining arguments directly to your script via `$@`. ```bash #!/usr/bin/env bash # omarchy:group=custom # omarchy:name=deploy # omarchy:summary=Deploy configuration to target # omarchy:args= set -e ENVIRONMENT="${1:?Environment required}" echo "Deploying to $ENVIRONMENT..." ``` ### 4. Register Group Descriptions (Optional) If your command introduces a new group that should appear in the top-level help output, edit `bin/omarchy` and add an entry to the `GROUP_DESCRIPTIONS` associative array: ```bash GROUP_DESCRIPTIONS[custom]="Custom deployment utilities" ``` Without this step, the command will still function, but the group will not appear in the main help listing. ### 5. Validate the Command Run the built-in checker to ensure your metadata includes a `summary` and does not collide with existing routes: ```bash omarchy commands --check ``` ## Practical Implementation Examples ### Example: Theme Management Command Create `bin/omarchy-theme-set` with the following content to implement a `theme set` subcommand: ```bash #!/usr/bin/env bash # omarchy:group=theme # omarchy:name=set # omarchy:summary=Apply a theme by name # omarchy:args= # omarchy:examples=omarchy theme set dark|omarchy theme set light THEME="${1:?Theme name required}" omarchy-theme-apply "$THEME" ``` After making the file executable, the command becomes available as `omarchy theme set `. ### Example: Hidden Plumbing Command For internal utilities that should not clutter the help listing: ```bash #!/usr/bin/env bash # omarchy:group=apply # omarchy:hidden=true # omarchy:summary=Apply hardware-specific tweaks (not listed) omarchy-hw-tweaks --apply-all ``` This command runs normally when invoked directly but remains hidden from `omarchy commands` output. ### Example: Creating a New Command Group To establish a new `experimental` group with a `test` command: 1. First, update `bin/omarchy` to register the group description: ```bash GROUP_DESCRIPTIONS[experimental]="Experimental feature utilities" ``` 2. Then create `bin/omarchy-experimental-test`: ```bash #!/usr/bin/env bash # omarchy:group=experimental # omarchy:name=test # omarchy:summary=Run experimental validation echo "Running experimental test suite with args: $@" ``` Now `omarchy experimental test` executes your script, and `omarchy help` lists the experimental group. ## Core Router Architecture Understanding the implementation in `bin/omarchy` helps explain why this convention-based approach works: - **Lazy Loading**: The router only parses metadata when necessary, caching route lookups for performance. - **Dual Route Registration**: Each command registers both a canonical route (potentially customized via metadata) and a literal filename route, ensuring predictable access patterns. - **Collision Resolution**: The `register_route` function detects conflicts during initialization and reports them via `omarchy commands --check`. The system requires zero compilation or central registry updates because the filesystem itself serves as the command registry. ## Summary - **Auto-Discovery**: The Omarchy CLI router automatically loads any executable `bin/omarchy-*` file as a command. - **Metadata Headers**: Use `# omarchy:key=value` comments in the first 80 lines to define `group`, `name`, `summary`, and other properties. - **Filename Convention**: Hyphens in filenames become spaces in commands (e.g., `omarchy-theme-set` → `omarchy theme set`). - **Group Registration**: Add new groups to the `GROUP_DESCRIPTIONS` array in `bin/omarchy` for top-level help visibility. - **Validation**: Always run `omarchy commands --check` after adding commands to verify metadata completeness and route uniqueness. ## Frequently Asked Questions ### What metadata keys does the Omarchy router support? The router recognizes `group`, `name`, `summary`, `args`, `aliases`, `hidden`, and `requires-sudo`. These are parsed from the first 80 comment lines of any `bin/omarchy-*` file using the format `# omarchy:key=value`. ### How do I hide a command from the help listing? Add `# omarchy:hidden=true` to the comment header of your command file. The command remains fully functional and routable, but it will not appear in the output of `omarchy commands` or help menus. ### What happens if two commands define the same route? The router detects collisions during the `register_route` phase. Running `omarchy commands --check` identifies any duplicate routes, allowing you to resolve conflicts by adjusting metadata `name` values or renaming files. ### Can I write commands in languages other than Bash? Yes. The Omarchy router treats any executable file matching `bin/omarchy-*` as a valid command, regardless of language. The shebang line determines the interpreter (e.g., `#!/usr/bin/env python3` for Python scripts). The router only cares that the file is executable and follows the naming convention.