How to Validate Omarchy CLI Metadata: 4 Essential Validation Rules

You validate Omarchy CLI metadata by executing the validation routine in bin/omarchy that verifies the GROUP_DESCRIPTIONS associative array for required fields, correct data types, unique command prefixes, and existing binaries, a process automatically exercised by test/shell.d/runtime-smoke-test.sh.

The Omarchy command-line interface from the basecamp/omarchy repository uses a centralized metadata system to manage command groups. Validating this metadata ensures that every command group defined in the dispatcher correctly maps to executable binaries and maintains consistency across the CLI surface.

Understanding the Omarchy CLI Metadata Structure

All CLI metadata lives in the central dispatcher script bin/omarchy. The system defines an associative array called GROUP_DESCRIPTIONS that catalogs every available command group, storing properties such as human-readable descriptions, command prefixes, visibility flags, and aliases. When the CLI initializes, it parses this data structure to build the command tree and route user input to the appropriate binary under the bin/ directory.

The Four Core Validation Checks

The validation routine iterates over each entry in GROUP_DESCRIPTIONS and enforces strict consistency rules before the CLI becomes operational.

Required Field Verification

Every metadata entry must contain a description string and a commandPrefix string. The validator checks for non-empty values using conditional expressions:

[[ -n "${desc[description]}" ]] || fail "Missing description"

If either field is absent or empty, the dispatcher aborts with a clear error message preventing CLI startup.

Data Type Enforcement

The validator ensures that optional flags adhere to expected bash types. The hidden attribute must be a boolean value (true or false), while aliases must be defined as arrays. Type mismatches trigger immediate validation failures to prevent runtime parsing errors.

Prefix Uniqueness Constraints

Each commandPrefix within GROUP_DESCRIPTIONS must be unique across the entire CLI. The validation routine maintains a tracking array seen to detect duplicates:

[[ -z "${seen[$prefix]}" ]] || fail "Duplicate prefix $prefix"

This prevents command routing conflicts where two groups might claim the same namespace.

Binary Existence Verification

Metadata must remain synchronized with the filesystem. For every command listed in a group, the validator confirms that a corresponding executable binary exists in the bin/ directory:

[[ -x "$OMARCHY_PATH/bin/$cmd" ]] || fail "Missing binary $cmd"

Missing or non-executable binaries cause the validation to fail, ensuring that users never encounter broken command links.

How to Run Metadata Validation

You can trigger validation manually or rely on automated testing.

Manual validation:

Run the CLI with the metadata check flag to verify the current state without executing commands:

omarchy --metadata-check

A successful validation prints a confirmation message, while failures display specific errors such as:

Error: Invalid CLI metadata – missing description for group "foo"

Automated validation:

The test suite test/shell.d/runtime-smoke-test.sh exercises the validation routine automatically. This shell test invokes the CLI and asserts that the plugin metadata lists correctly, failing the build if any of the four core checks detect inconsistencies.

Example: Adding and Validating a New Command Group

Follow this workflow to safely extend the CLI while maintaining valid metadata:

1. Create the executable binary in the bin/ directory:

touch bin/omarchy-example
chmod +x bin/omarchy-example

2. Register the metadata in bin/omarchy by appending to GROUP_DESCRIPTIONS:

["example"]=(
  description="Demo command group for testing"
  commandPrefix="example"
  hidden=false
)

3. Run the validation check to confirm the new group is recognized:

omarchy --metadata-check

4. Execute the runtime smoke test to ensure full integration:

bash test/shell.d/runtime-smoke-test.sh

Summary

• Metadata lives in bin/omarchy within the GROUP_DESCRIPTIONS associative array.
• Four validation rules enforce required fields (description, commandPrefix), correct data types, unique prefixes, and existing binaries.
• Manual validation uses the --metadata-check flag for immediate feedback during development.
• Automated validation occurs through test/shell.d/runtime-smoke-test.sh in CI/CD pipelines.
• Binary consistency requires every metadata entry to map to an executable file in the bin/ directory.

Frequently Asked Questions

How do I know if my metadata changes broke the CLI?

Run omarchy --metadata-check immediately after editing bin/omarchy. This command parses GROUP_DESCRIPTIONS and reports specific validation errors, such as missing descriptions or duplicate prefixes, before you commit changes.

What error appears if a binary is missing?

The validator outputs Error: Missing binary [command-name] when a metadata entry references a command that does not exist as an executable file in the bin/ directory. You must create and chmod the binary or correct the metadata entry to resolve this.

Can I hide a command group from standard help output?

Yes. Set hidden=true in the group's metadata entry within GROUP_DESCRIPTIONS. The validation routine accepts boolean values for this field, and hidden groups remain functional but do not appear in standard CLI help listings.

Where is the validation logic implemented?

The validation logic resides directly in bin/omarchy, the central dispatcher script. It runs automatically during CLI initialization and can be invoked explicitly via the --metadata-check flag, while test/shell.d/runtime-smoke-test.sh provides automated regression testing for the metadata system.

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