How to Customize Omarchy CLI Commands: A Complete Guide

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:<key>=<value>. 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-<group>-<name> (or simply omarchy-<name>) 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:

#!/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:

# 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:

# omarchy:hidden=true

To force automatic sudo elevation when the command runs, add:

# 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: 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=<name>, # omarchy:name=<name>, and # omarchy:summary=<description>. 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.

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