# How to Validate Omarchy CLI Metadata: 4 Essential Validation Rules

> Learn how to validate Omarchy CLI metadata using four essential rules. Ensure correct fields, data types, unique prefixes, and existing binaries for robust validation.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
[[ -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:

```bash
[[ -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:

```bash
[[ -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:

```bash
omarchy --metadata-check

```

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

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

```

**Automated validation:**

The test suite [`test/shell.d/runtime-smoke-test.sh`](https://github.com/basecamp/omarchy/blob/main/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:

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

```

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

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

```

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

```bash
omarchy --metadata-check

```

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

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/runtime-smoke-test.sh) provides automated regression testing for the metadata system.