perfgate-cli 0.17.0

CLI for perfgate performance budgets and baseline diffs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

# perfgate

**One tool to run benchmarks, detect regressions, and gate CI.**

You ship code daily. Performance regressions slip through because measuring,
comparing, and enforcing budgets are three separate problems. perfgate solves
all three in a single binary that fits into any CI pipeline.

## Install

```bash
# Pre-built binary (via cargo-binstall)
cargo binstall perfgate-cli

# From crates.io
cargo install perfgate-cli

# From source
cargo install --path crates/perfgate-cli
```

Check the local install and project setup:

```bash
perfgate doctor
```

## Quick Start

```bash
# 1. Measure
perfgate run --name my-bench --out run.json -- ./my-benchmark

# 2. Compare against a baseline
perfgate compare --baseline baseline.json --current run.json --out cmp.json

# 3. Gate CI (exit 2 on regression)
perfgate report --compare cmp.json --out report.json
```

Or use `check` for the full workflow in one command:

```bash
perfgate check --config perfgate.toml --bench my-bench
```

## Commands

Commands are organized by workflow stage.

### Measure

| Command   | Purpose |
|-----------|---------|
| `run`     | Execute a command N times, emit a `perfgate.run.v1` receipt |
| `paired`  | Interleaved A/B benchmarking to cancel out environmental noise |

### Analyze

| Command   | Purpose |
|-----------|---------|
| `compare` | Diff current vs baseline, emit a `perfgate.compare.v1` receipt |
| `probe compare` | Compare named probe receipts, emit a `perfgate.probe_compare.v1` receipt |
| `blame`   | Identify which Cargo.lock dependency changes caused a regression |
| `explain` | Generate AI-ready diagnostic prompts for regressions |

### Report

| Command              | Purpose |
|----------------------|---------|
| `md`                 | Render Markdown from a compare receipt |
| `report`             | Generate a `perfgate.report.v1` envelope |
| `summary`            | Print a terminal table from one or more compare receipts |
| `github-annotations` | Emit `::error::`/`::warning::` lines for GitHub Actions |
| `export`             | Export to CSV, JSONL, HTML, Prometheus, or JUnit |
| `decision bundle`    | Export indexed decision evidence as a portable JSON bundle |

### Manage

| Command     | Purpose |
|-------------|---------|
| `promote`   | Copy a run receipt into baseline storage |
| `baseline`  | Manage baselines on a centralized server (list, upload, download, delete, history, verdicts, migrate) |
| `decision`  | Manage decision ledger records (upload, history, latest, export, prune, debt) |
| `serve`     | Start or preflight a local SQLite-backed dashboard server |
| `aggregate` | Merge multiple run receipts (e.g. from a fleet) into one |
| `fleet`     | Fleet-wide dependency regression alerts and impact analysis |

### Automate

| Command  | Purpose |
|----------|---------|
| `check`  | Config-driven end-to-end workflow: run, compare, report, gate |
| `doctor` | Diagnose config, benchmark commands, baselines, artifacts, CI, and server reachability |
| `bisect` | Binary-search for the commit that introduced a regression |

## Exit Codes

Every command follows the same contract:

| Code | Meaning |
|------|---------|
| `0`  | Success (or warn without `--fail-on-warn`) |
| `1`  | Runtime error (I/O, parse, spawn failure) |
| `2`  | Policy fail (budget violated) |
| `3`  | Warn treated as failure (`--fail-on-warn`) |

## Examples

```bash
# Paired A/B benchmarking (interleaved to reduce noise)
perfgate paired --name my-bench \
  --baseline-cmd "./old" --current-cmd "./new" --repeat 30 --out cmp.json

# Export metrics for Prometheus
perfgate export --run run.json --format prometheus --out metrics.prom

# Find the commit that introduced a regression
perfgate bisect --good v1.0.0 --bad HEAD --executable ./target/release/my-bench

# Cockpit mode: always emit a sensor report, exit 0 for dashboard ingestion
perfgate check --config perfgate.toml --bench my-bench --mode cockpit
```

## More

- Workspace overview and CI examples: [README.md](../../README.md)
- Testing strategy: [TESTING.md](../../TESTING.md)
- API docs: [docs.rs/perfgate-cli](https://docs.rs/perfgate-cli)

## License

Licensed under either Apache-2.0 or MIT.