# How to Check Omarchy CLI Command Metadata for Errors

> Validate Omarchy CLI command metadata for errors with `omarchy commands --check`. Ensure correct formatting, routing, and required fields for robust command execution.

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

---

**Run `omarchy commands --check` to validate all CLI command metadata, ensuring boolean fields are correctly formatted, routing groups match filenames, and required summary fields are present.**

Omarchy is Basecamp’s open-source CLI framework that discovers commands by scanning the `bin/` directory and parsing metadata comments embedded in each file. Checking this metadata for errors prevents routing failures and malformed help text. The validation system is built into the main router and inspects every discovered command for structural integrity.

## Running the Metadata Validation Command

The primary interface for metadata validation is the `omarchy commands --check` subcommand. When executed, this invokes the `show_commands_check` function located at **line 732** in `bin/omarchy`. The routine iterates through `COMMAND_KEYS`—the internal list of discovered commands—and validates each record against the schema requirements.

To verify your CLI metadata manually, run:

```bash
omarchy commands --check

```

A successful validation outputs a confirmation line with the total command count, such as `Command metadata check passed (237 commands)`. If any check fails, the routine aborts immediately and prints an error message identifying the offending command.

## Validation Rules and Metadata Constraints

The linter in `show_commands_check` enforces three categories of constraints to ensure runtime reliability.

### Boolean Field Requirements

The metadata fields `hidden` and `requires-sudo` must contain literal boolean values (`true` or `false`). String representations like `"true"` or `1` trigger validation failures. These values control whether a command appears in help listings and whether the router requests elevated privileges before execution.

### Route Consistency Checks

Every command file must declare a `group` in its metadata that matches the group derived from its filename. For example, a file named `omarchy-theme-set` must declare `omarchy:group=theme` (or inherit it consistently). Mismatches between the filesystem-derived group and the metadata group cause the check to fail, preventing routing table corruption.

### Required Metadata Fields

Every command must define a `summary` field using the `omarchy:summary=` comment marker. While optional fields like `description`, `args`, and `example` enhance the help output, the absence of a summary triggers a validation error. The `parse_metadata` function, called from `load_child_commands_by_binary`, extracts these markers during command discovery.

## Output Formats and Debugging

For programmatic inspection or detailed debugging, combine the `--check` flag with `--json` as documented in the option list at lines 532‑544 of `bin/omarchy`.

### JSON Output Structure

Passing `--json` invokes the JSON emitter located at **lines 696‑700** in `bin/omarchy`, outputting a complete validation report:

```bash
omarchy commands --json --check

```

This produces a structured object containing an `ok` boolean and a `commands` array with full metadata records:

```json
{
  "ok": true,
  "commands": [
    {
      "name": "omarchy-theme-set",
      "summary": "Set the current theme",
      "group": "theme",
      "hidden": false,
      "requires-sudo": false
    }
  ]
}

```

### Inspecting Individual Commands

Pipe the JSON output to `jq` to filter specific commands during debugging:

```bash
omarchy commands --json --check | jq '.commands[] | select(.name=="omarchy-theme-set")'

```

## Metadata Format in Source Files

Metadata is defined via comment markers at the top of each executable in the `bin/` directory. According to the [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md) style guide and the parsing logic in `bin/omarchy`, the `parse_metadata` function scans for lines beginning with `# omarchy:` and converts them into JSON records.

A valid metadata block follows this pattern:

```bash

# omarchy:summary=Toggle the night-light

# omarchy:requires-sudo=true

# omarchy:args=[on|off]

```

These comments are parsed when `load_child_commands_by_binary` runs during CLI initialization. Errors in this format—such as missing equals signs or invalid keys—are caught during the `--check` validation phase.

## Automating Metadata Checks in CI/CD

The Omarchy repository includes an automated test suite in `test/cli` that executes `omarchy commands --check` and asserts a zero exit status. This guarantees that no commit ships with broken metadata.

Integrate the same check into your pipeline:

```yaml
- name: Verify CLI metadata
  run: |
    omarchy commands --check || { echo "Metadata error!"; exit 1; }

```

According to the Basecamp Omarchy source code, this test runs automatically when executing `./test/cli`, ensuring that boolean format violations, missing summaries, or group mismatches block deployment.

## Key Source Files and Documentation

Understanding the metadata system requires familiarity with these specific files:

- **`bin/omarchy`** – The core router script containing `show_commands_check` (line 732), the option parser for `--check` (lines 532‑544), usage help (line 523), and the JSON emitter (lines 696‑700).
- **[`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md)** – Human‑readable documentation explaining the CLI routing logic and metadata linting purpose.
- **[`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md)** – Style guide defining the required comment markers (`# omarchy:summary=`, etc.) that the router parses.

- **`test/cli`** – Automated test suite that runs the metadata validation and fails on any violation.

## Summary

- Run **`omarchy commands --check`** to execute the `show_commands_check` function and validate all discovered commands.
- The linter enforces **boolean literals** for `hidden` and `requires-sudo`, **route consistency** between filenames and group metadata, and the **presence of summary fields**.
- Use **`--json --check`** to output machine‑readable validation reports generated by the emitter at lines 696‑700 in `bin/omarchy`.
- Metadata is parsed from **`# omarchy:`** comment markers by the `parse_metadata` function during command loading.

- The **`test/cli`** suite automatically runs metadata checks to prevent shipping broken CLI definitions.

## Frequently Asked Questions

### What happens if a command fails the metadata check?

The validation routine aborts immediately with a non‑zero exit status and prints an error message identifying the specific command and the validation rule that failed. The check does not produce a partial list of failures; it stops at the first violation to prevent execution with corrupted metadata.

### Can I validate metadata for a single command instead of the entire suite?

The built‑in `omarchy commands --check` validates the complete `COMMAND_KEYS` array discovered at runtime. To inspect a single command, use the JSON output combined with `jq` filtering: `omarchy commands --json --check | jq '.commands[] | select(.name=="command-name")'`. This allows targeted debugging without modifying the core validation logic in `bin/omarchy`.

### How do I fix a "route consistency" error?

Ensure the `group` declared in the metadata comments matches the group derived from the filename. For example, if the file is named `omarchy-theme-set`, the metadata must include `# omarchy:group=theme` (or the parser must derive the same group). Edit the comment markers at the top of the binary file and rerun `omarchy commands --check` to verify the fix.

### Is the metadata check run automatically during development?

Yes. The **`test/cli`** test suite, which runs when you execute `./test/cli` in the repository root, automatically invokes `omarchy commands --check` and fails the build if any metadata violations exist. This ensures that all commits in the Basecamp Omarchy repository maintain valid CLI definitions before merging.