npm package: @knfrmd/kanmi
Description: Web performance CLI — audit, monitor, and guard your Core Web Vitals
Author: Kanmi Obasa
Latest version: 0.3.0

# kanmi

Web performance CLI powered by Lighthouse. Audit, monitor, and guard your site's performance from the terminal.

```bash
npx @knfrmd/kanmi audit https://your-site.com
```

```
  Kanmi Performance Audit
  https://your-site.com
  mobile · Slow 4G, 4x CPU · LH 12.0.0 · 14.2s
  ─────────────────────────────────────────────

  Performance      72
  Accessibility    95
  Best Practices   100
  SEO              91

  Lab Metrics
  ─────────────────────────────────────────────
  LCP      4,200ms    NEEDS IMPROVEMENT
  TBT        380ms    NEEDS IMPROVEMENT
  CLS       0.003     GOOD
  FCP      1,800ms    GOOD
  SI       3,400ms    GOOD
  TTI      5,100ms    NEEDS IMPROVEMENT

  Top Issues
  ─────────────────────────────────────────────
  * Reduce unused JavaScript (~1.2s savings)
  * Eliminate render-blocking resources (~800ms savings)
  * Properly size images (~450ms savings)
```

## Install

```bash
npm install -g @knfrmd/kanmi
```

Requires Node.js 18+ and Chrome/Chromium.

## Commands

### `kanmi audit <url>`

Run a Lighthouse audit and print results.

```bash
kanmi audit https://example.com
kanmi audit https://example.com --format json
kanmi audit https://example.com --runs 3
kanmi audit https://example.com --form-factor desktop
```

| Flag | Description | Default |
|------|-------------|---------|
| `--runs <n>` | Number of Lighthouse runs (median used for >1) | `1` |
| `--format <fmt>` | Output format: `terminal` or `json` | `terminal` |
| `--form-factor <f>` | Device emulation: `mobile` or `desktop` | `mobile` |
| `--save` | Save result to local history (`~/.kanmi/`) | `false` |

### `kanmi monitor <url>`

Audit a URL (3 runs, median), save to history, and detect regressions against your baseline.

```bash
kanmi monitor https://example.com
```

```
  Kanmi Monitor
  https://example.com
  Run #8 | 2026-02-28 | 3 runs (median)
  ─────────────────────────────────────────────

  Performance      92  unchanged

  Regressions
   CRIT  LCP: 2,100ms -> 2,600ms (+500ms)

  Regression Policy
  ─────────────────────────────────────────────
  Baseline     median of last 5 runs
  Rule         flag if delta >= max(abs, baseline x rel%)
  Fail         exit 1 on critical/high severity
```

### `kanmi history <url>`

Show past audit runs stored in `~/.kanmi/history/`.

```bash
kanmi history https://example.com
kanmi history https://example.com --limit 20
```

### `kanmi ci`

CI gate for GitHub Actions. Audit URLs, enforce thresholds, post PR comments.

```bash
kanmi ci --urls https://example.com --performance 90
```

Exits 1 if thresholds fail or critical/high regressions are detected. Add `--post-comment` to annotate PRs.

## JSON output

```bash
kanmi audit https://example.com --format json
```

```json
{
  "schemaVersion": 1,
  "tool": { "name": "@knfrmd/kanmi", "version": "0.3.0" },
  "url": "https://example.com",
  "urlNormalized": "example.com",
  "scores": {
    "performance": 0.92,
    "accessibility": 0.98,
    "bestPractices": 1.0,
    "seo": 0.91
  },
  "labMetrics": {
    "lcp": 2300,
    "tbt": 150,
    "cls": 0.05,
    "fcp": 1200,
    "speedIndex": 3100,
    "tti": 3800
  }
}
```

Scores in JSON are **0-1** (matches Lighthouse native). Terminal display shows 0-100.

## License

MIT