Reference

CLI · doug-backtest

Available

Replay a repository’s merged-PR history and print the full scoreboard. Harvests are cached and checkpointed — kill it and relaunch any time; it resumes.

repo positional · required: owner/repo, e.g. astral-sh/ruff
--limit int · default 300: Merged PRs to harvest, newest-first within the window.
--before YYYY-MM-DD: Only harvest PRs created before this date — the right-censoring guard.
--labels git | api | both · default git: Defect label source. See Defect labels.
--token string: GitHub token. Default: environment, then the gh CLI.
--cache-dir path · default .backtest-cache: Harvest cache location. Safe to reuse across runs; seeds bigger runs from smaller ones.
--output path: Write the full JSON report here as well as printing tables.
--backfill-details flag: Fetch per-file stats + patch text for cached PRs missing them (~1 request/PR; checkpointed, resumable).

# quick look, 300 PRs $ doug-backtest astral-sh/ruff # serious run: deep window, censoring guard, # patch-level detail, JSON report $ doug-backtest grafana/grafana \ --limit 12000 \ --before 2026-06-15 \ --labels git \ --backfill-details \ --output report.json # resume after a kill — same command, cache does the rest $ doug-backtest grafana/grafana --limit 12000 \ --before 2026-06-15