perfgate-cli-0.17.0 is not a library.

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

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

perfgate doctor

Quick Start

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

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

# 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

Workspace overview and CI examples: README.md
Testing strategy: TESTING.md
API docs: docs.rs/perfgate-cli

License

Licensed under either Apache-2.0 or MIT.

perfgate-cli 0.17.0