> ## Documentation Index
> Fetch the complete documentation index at: https://mehen.ophi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands overview

> The mehen CLI exposes three commands: metrics, diff, and top-offenders.

The mehen CLI has a small, focused command surface designed for CI runs, pre-PR hooks, and pull
request automation.

## Commands

| Page                                             | What it does                                                         |
| ------------------------------------------------ | -------------------------------------------------------------------- |
| [`mehen metrics`](/commands/metrics)             | Analyze exactly one file and emit a metrics report.                  |
| [`mehen diff`](/commands/diff)                   | Compare metrics between two git revisions and emit JSON or Markdown. |
| [`mehen top-offenders`](/commands/top-offenders) | Walk one or more paths and rank the worst-offending files.           |

`mehen --version --json` is the fourth supported invocation — it emits a machine-readable shape that the
[GitHub Action](/guides/github-action) reads to stamp its sticky comment footer.

## Why three commands

Each command matches one consumption pattern:

* **`metrics`** → "tell me about this one file" — single-file IDE/CI hooks, code-review screencasts.
* **`diff`** → "what changed on this PR" — the engine behind the GitHub Action sticky comment.
* **`top-offenders`** → "where are the hottest files?" — repository scans for prioritization dashboards.

AST inspection for maintainers lives in `cargo xtask` rather than the public CLI — see
[Developers → Add a new language](/developers/new-language).

## Output formats

All three commands accept a small format set. See
[Concepts → Output formats](/concepts/output-formats) for the schema of each.

| Format         | Available on                                                                    |
| -------------- | ------------------------------------------------------------------------------- |
| `json`         | every command                                                                   |
| `markdown`     | every command (default for `top-offenders`; `github-markdown` style for `diff`) |
| `yaml`, `toml` | `metrics` only                                                                  |

## Profiles

`mehen metrics` accepts a built-in `--profile` flag: `default`, `ci`, or `strict`. Profiles tune the
metric selector set and the threshold suggestions.

## See also

* [GitHub Action](/guides/github-action) — production consumer of `mehen diff`.
* [Concepts → Architecture](/concepts/architecture) — how each command flows through the engine.
* [Concepts → Thresholds and diffs](/concepts/thresholds-and-diffs) — `--fail-on` and threshold inputs.