How to Add a New Command to the Omarchy CLI Router

To add a new command to the Omarchy CLI router, create an executable file in the bin/ directory following the omarchy-<group>-<name> 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-<group>-<command>. For single-word group commands, use omarchy-<group>.

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., <theme> 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 $@.

#!/usr/bin/env bash

# omarchy:group=custom

# omarchy:name=deploy

# omarchy:summary=Deploy configuration to target

# omarchy:args=<environment>

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:

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:

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:

#!/usr/bin/env bash

# omarchy:group=theme

# omarchy:name=set

# omarchy:summary=Apply a theme by name

# omarchy:args=<theme>

# 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 <theme>.

Example: Hidden Plumbing Command

For internal utilities that should not clutter the help listing:

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

GROUP_DESCRIPTIONS[experimental]="Experimental feature utilities"

2. Then create bin/omarchy-experimental-test:

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

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