How to Contribute to Omarchy CLI Development: A Complete Guide

To contribute to Omarchy CLI development, create an executable script in bin/omarchy-<group>-<name> with # omarchy: metadata comments, implement your logic, and add corresponding tests in test/shell.d/.

The Omarchy CLI framework provides a lightweight, metadata-driven command dispatcher that automatically discovers and routes subcommands. Whether you are adding utilities to the omacom/omarchy repository or extending the toolkit for your own infrastructure, understanding how the dispatcher discovers commands and validates metadata ensures your contributions integrate seamlessly. This guide covers the architecture of bin/omarchy, the metadata system, and the testing framework required to contribute to Omarchy CLI development effectively.

Understanding the Omarchy CLI Architecture

Omarchy’s command-line interface is built around a single dispatcher script that handles discovery, registration, and routing for every omarchy-* executable in the distribution.

The Dispatcher Script (bin/omarchy)

At the heart of the system lies bin/omarchy, the central router script. When invoked, it scans the directory defined by $OMARCHY_BIN_DIR (typically /usr/share/omarchy/bin) for all executables prefixed with omarchy-. This scanner feeds each discovered binary into the register_command function, which parses the script’s metadata to build the command tree.

Command Discovery and Registration

During startup, register_command reads the first approximately 80 comment lines of each executable, searching for metadata prefixed with # omarchy:. Valid metadata fields include:

• group= – Defines the top-level category (e.g., network, system)
• name= – Specifies the subcommand name
• summary= – Provides a brief description for help output
• args= – Documents positional arguments and optional parameters
• examples= – Shows usage examples
• requires-sudo= – Boolean flag for privilege requirements
• hidden= – Boolean flag to hide from default help listings

The metadata determines the routing path (omarchy <group> <name>), fallback routes derived from filenames, and any command aliases.

Routing Logic and Route Resolution

When a user executes omarchy …, the dispatcher invokes resolve_direct_route and resolve_route to match the longest possible prefix against registered routes. If a binary matches, the dispatcher executes it directly via exec with the remaining arguments. For help requests (--help or -h), the system generates documentation from stored metadata using show_group_help or show_prefix_help, including usage syntax, argument descriptions, and examples.

Adding a New CLI Command

Contributing a new command requires creating a properly annotated executable and ensuring it follows the project’s metadata conventions.

Step 1: Create the Executable Script

Place your script in the bin/ directory following the naming convention omarchy-<group>-<name> or omarchy-<group> for group-level commands. The file must be executable and include a proper shebang:

#!/bin/bash

Step 2: Define Command Metadata

Add a block of # omarchy: comments immediately after the shebang. The dispatcher parses these lines to generate help text and determine routing:

# omarchy:group=network

# omarchy:name=ping

# omarchy:summary=Ping a host and show latency statistics

# omarchy:args=[HOST] [COUNT=5]

# omarchy:examples=omarchy network ping example.com 10

Step 3: Implement Command Logic

Following the metadata, implement the command functionality. Here is a complete example for a network ping command:

#!/bin/bash

# omarchy:group=network

# omarchy:name=ping

# omarchy:summary=Ping a host and show latency statistics

# omarchy:args=[HOST] [COUNT=5]

# omarchy:examples=omarchy network ping example.com 10

host="${1:-}"
count="${2:-5}"

[[ -z $host ]] && { echo "Usage: $0 <host> [count]"; exit 1; }

ping -c "$count" "$host"

Save this as bin/omarchy-network-ping. The dispatcher automatically discovers the command on the next run. Running omarchy network ping --help displays the formatted help derived from your metadata, including arguments and examples.

When introducing new groups, update the GROUP_DESCRIPTIONS associative array inside bin/omarchy to include a description for your category.

Testing Your CLI Contributions

All non-graphical tests reside in test/shell.d/ and follow the base-test.sh contract. Every new command should include corresponding test coverage.

The Shell Test Framework

Test files must end with -test.sh and source the base test utilities. The framework provides sandboxed environments with temporary directories and PATH manipulation for stubbing external binaries.

Writing Tests with Base-Test.sh

Create a test file like test/shell.d/network-ping-test.sh:

#!/bin/bash
set -euo pipefail
source "$(dirname "${BASH_SOURCE[0]}")/base-test.sh"

# Stub the ping binary

cat >"$test_tmp/bin/ping" <<'SH'
#!/bin/bash
printf 'ping to %s (%s)\n' "$1" "$2" >"$test_tmp/ping.log"
SH
chmod +x "$test_tmp/bin/ping"

HOME="$test_tmp" PATH="$test_tmp/bin:$PATH" \
  omarchy network ping example.com 3 >"$out"

# Assert that our stub was called

grep -q 'ping to example.com' "$test_tmp/ping.log"

Execute the test suite using ./test/shell or the aggregated runner ./test/all. The framework validates that your command executes correctly and interacts with dependencies as expected.

Validating Command Metadata

Before submitting contributions, run omarchy commands --check to validate your metadata. This command executes the show_commands_check function within bin/omarchy, ensuring:

• Every binary has a required summary
• Boolean flags like requires-sudo and hidden contain valid values
• All registered routes are unique
• No collisions exist in the command namespace

CI pipelines typically invoke this check automatically to catch regressions early.

Documentation and Style Guidelines

Reference the canonical style guide at agents/skills/command-metadata.md when documenting new commands. This guide defines the expected format for metadata comments and provides templates for consistent documentation across the Omarchy CLI. For working examples of properly documented commands, examine bin/omarchy-version, which demonstrates standard metadata practices.

Summary

• Create executable scripts in bin/omarchy-<group>-<name> with #!/bin/bash shebangs to contribute to omarchy cli development.

• Annotate metadata using # omarchy: comments to define group, name, summary, args, and examples for automatic discovery.

• Update GROUP_DESCRIPTIONS in bin/omarchy when adding new command categories.

• Write shell tests in test/shell.d/ using the base-test.sh framework, stubbing external dependencies as needed.

• Validate changes with omarchy commands --check to ensure metadata integrity before submission.

• Follow the style guide at agents/skills/command-metadata.md for consistent documentation standards.

Frequently Asked Questions

Where do I place new scripts when contributing to Omarchy CLI development?

Place executable scripts in the bin/ directory using the naming convention omarchy-<group>-<name> or omarchy-<group> for group-level commands. The dispatcher scans $OMARCHY_BIN_DIR (typically /usr/share/omarchy/bin) for these prefixes and automatically registers them on the next execution via the register_command function.

How does the Omarchy CLI handle command routing and help generation?

The dispatcher in bin/omarchy uses register_command to parse metadata from the first 80 lines of each script, then routes commands using resolve_direct_route and resolve_route. For help requests, it generates formatted output from the stored summary, args, and examples metadata without executing the binary.

What testing framework should I use for Omarchy CLI contributions?

Use the shell testing framework in test/shell.d/. Each test file must end with -test.sh and source base-test.sh for sandboxing utilities. The framework supports stubbing external binaries by prepending temporary directories to $PATH, allowing isolated testing of command logic without affecting the host system.

How do I validate that my command metadata is correct before submitting?

Run omarchy commands --check to execute the show_commands_check validation function. This verifies that all binaries have summaries, boolean flags are valid, routes are unique, and no metadata regressions exist. Include this check in your development workflow to ensure CI pipeline compatibility.

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