How to Check Omarchy CLI Command Metadata for Errors

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:

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:

omarchy commands --json --check

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

{
  "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:

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 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:

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

- 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 – Human‑readable documentation explaining the CLI routing logic and metadata linting purpose.

• 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.

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