---
title: "mehen metrics"
description: "Analyze exactly one file and emit a metrics report as JSON, Markdown, YAML, or TOML."
keywords: ["mehen metrics", "single file", "static analysis", "cli"]
---

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

```text
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`. |
| `--config <PATH>` | discovered | Pin a [configuration file](/configuration) instead of discovering `mehen.toml` upward from the working directory. |

## Examples

<Tabs>
  <Tab title="JSON (default)">
    ```bash
    mehen metrics src/main.py
    ```
  </Tab>
  <Tab title="Pretty JSON">
    ```bash
    mehen metrics src/main.py --pretty
    ```
  </Tab>
  <Tab title="Markdown report">
    ```bash
    mehen metrics docs/architecture.md --format markdown
    ```
  </Tab>
  <Tab title="Forced language">
    ```bash
    mehen metrics app.tsx --language tsx --format json --pretty
    ```
  </Tab>
  <Tab title="CI profile">
    ```bash
    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. Also: a [configured metric threshold](/configuration) crossed, after the report is emitted. |
| 3 | Invalid serialization state — should not happen in production runs. |

## Configured thresholds

When a [`mehen.toml`](/configuration) is present, every configured threshold that matches a metric
this file publishes is evaluated against the report — the language's override table wins over the
global one. Crossed limits print a grouped violation report on stderr after the report lands on
stdout, and the command exits `1`. Files with blocking parse diagnostics exit `1` without
threshold evaluation: partial metrics are never gated.

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