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

# mehen metrics

> Analyze exactly one file and emit a metrics report as JSON, Markdown, YAML, or TOML.

`mehen metrics` is the single-file analysis command. It takes one path, auto-detects the language, and
emits a complete metrics report.

```text theme={null}
mehen metrics [OPTIONS] <PATH>
```

| Argument | Description                                                           |
| -------- | --------------------------------------------------------------------- |
| `<PATH>` | Path to the file to analyze. `mehen metrics` never walks directories. |

| Flag                    | Default       | Description                                                                                                           |
| ----------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--language <LANGUAGE>` | auto-detected | Override language detection. Accepts canonical names or aliases (e.g. `python`, `py`, `ts`, `tsx`, `markdown`, `md`). |
| `--format <FORMAT>`     | `json`        | One of `json`, `markdown`, `yaml`, `toml`.                                                                            |
| `--pretty`              | off           | Pretty-print JSON output.                                                                                             |
| `--profile <PROFILE>`   | `default`     | One of `default`, `ci`, `strict`.                                                                                     |

## Examples

<Tabs>
  <Tab title="JSON (default)">
    ```bash theme={null}
    mehen metrics src/main.py
    ```
  </Tab>

  <Tab title="Pretty JSON">
    ```bash theme={null}
    mehen metrics src/main.py --pretty
    ```
  </Tab>

  <Tab title="Markdown report">
    ```bash theme={null}
    mehen metrics docs/architecture.md --format markdown
    ```
  </Tab>

  <Tab title="Forced language">
    ```bash theme={null}
    mehen metrics app.tsx --language tsx --format json --pretty
    ```
  </Tab>

  <Tab title="CI profile">
    ```bash theme={null}
    mehen metrics src/main.py --profile ci --pretty
    ```
  </Tab>
</Tabs>

## Exit codes

| Code | Meaning                                                                    |
| ---- | -------------------------------------------------------------------------- |
| 0    | Success.                                                                   |
| 1    | IO error, unsupported language, or analyzer-fatal diagnostic on this file. |
| 3    | Invalid serialization state — should not happen in production runs.        |

## What gets reported

Source-code files yield the
[code metric family](/metrics/code/overview) (cyclomatic, cognitive, Halstead, MI, ABC, LOC family,
NOM, NPA, NPM, NARGS, NEXITS, WMC).

Markdown files yield the [Markdown metric suite](/metrics/markdown/overview) — DMI, MRPC, MCC,
Markdown Halstead, link debt, table burden, visual scaffold, artifact debt, repository grounding,
evidence coverage, filler/lazy risk, review criticality, section balance, good scaffold. The opt-in
[prose layer](/metrics/markdown/prose/overview) ships behind Cargo features.

When an analyzer supports source-resolved evidence, the default profile also emits a
`contributions` array. Each entry identifies the metric, weighted amount, stable reason code, and
byte/line span responsible for that amount. SQL change risk is the first supported metric:
`sql.change_risk_score` explains destructive DDL/DML and distinct object-touch terms. The
`ci`/`strict` profiles skip this optional evidence to keep automated payloads lean.

## Profiles

`--profile` selects a built-in preset for what gets reported and how thresholds are interpreted:

| Profile   | Use case                                                                                                    |
| --------- | ----------------------------------------------------------------------------------------------------------- |
| `default` | Local developer output, including supported contribution evidence. No implicit failure policy.              |
| `ci`      | GitHub Action-friendly defaults without contribution evidence. Stable tables, standard metric selector set. |
| `strict`  | Same evidence behavior as `ci`, with tighter built-in threshold suggestions.                                |

Explicit CLI flags always override profile defaults.

## Inspecting contribution evidence

Maintainers can print only the contribution array for a file through the developer task:

```bash theme={null}
cargo xtask metric-contributions migrations/2026-07-10.sql
```

The task runs the production analyzer through the real `mehen metrics` path, so language detection,
profile behavior, reason codes, and spans match the public CLI report.

## See also

* [`mehen diff`](/commands/diff) — compare metrics between revisions.
* [`mehen top-offenders`](/commands/top-offenders) — rank files by metric.
* [Concepts → Output formats](/concepts/output-formats) — schema details.