CLI reference¶
Auto-generated from the cyclopts app. For an introduction and examples, see Command-line interface.
mew¶
$ mew --help
Usage: mew COMMAND
Microbenchmarking for Python via Google Benchmark.
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ compare Compare benchmark result files; the first file is the baseline. │
│ list, ls List discovered benchmarks without running them. │
│ profile Profile benchmarks out-of-process, capturing native C frames. │
│ run Discover and run benchmarks. │
│ -h, --help Display this message and exit. │
│ --version Display application version. │
╰──────────────────────────────────────────────────────────────────────────────╯
mew ls¶
$ mew list --help
Usage: mew list [OPTIONS] [PATHS]
List discovered benchmarks without running them.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ PATHS Files, directories, or <path>::<filter> selectors to discover │
│ benchmarks from. Defaults to [tool.mew] benchpaths. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ -k, --pattern List benchmarks whose name matches this regex (re.search, │
│ unanchored). A plain word still works as a substring. │
│ Parametrize case labels are not part of the name and won't │
│ match. │
│ -t, --tag Filter benchmarks by tag. Can be repeated, uses OR semantics. │
│ --show-tags Show associated tags alongside each benchmark name. │
╰──────────────────────────────────────────────────────────────────────────────╯
mew run¶
$ mew run --help
Usage: mew run [OPTIONS] [PATHS]
Discover and run benchmarks.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ PATHS Files, directories, or <path>::<filter> selectors to discover │
│ benchmarks from. Defaults to [tool.mew] benchpaths. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ -k, --pattern Only run benchmarks whose name matches this regex │
│ (re.search, unanchored; a plain word works as a │
│ substring). Matches the registered name │
│ (file.py::func); parametrize case labels like n=10000 │
│ are not part of the name and won't match. │
│ -t, --tag Filter benchmarks by tag. Can be repeated, uses OR │
│ semantics. │
│ -o, --output Output sink, repeatable: - for a rich terminal table, │
│ <path>.{json,jsonl,parquet} for a JSON / │
│ streaming-JSONL / Parquet file. Default: -. │
│ --min-time The minimum amount of time that each benchmark should │
│ run, in seconds (float, e.g. 0.5) or number of │
│ iterations (e.g. 100x). │
│ --repetitions Repeat each benchmark N times. │
│ --session-tag Label this run's output as a session (e.g. before), │
│ persisted next to the generated session id. Defaults to │
│ git describe --always --dirty inside a checkout; │
│ disable the fallback with [tool.mew] auto_session_tag = │
│ false. Unrelated to -t/--tag, which selects which │
│ benchmarks run. │
│ --append Append this run as a new session to existing .jsonl / │
│ .parquet sinks instead of overwriting. Pair with │
│ --session-tag and select sessions later via mew compare │
│ file@<tag>. │
│ --variant Run a name=path variant in its own subprocess, │
│ repeatable. For suites that can't share an interpreter │
│ (rival engines, GIL vs free-threaded, …). Rows are │
│ tagged with the variant name; compare with mew compare │
│ <file> --by variant. Mutually exclusive with positional │
│ paths. │
│ --benchmark-option raw arguments forwarded to Google Benchmark │
│ --profile-memory Profile memory allocations with memray before the │
│ timing run. │
│ --flamegraph Write an HTML flame graph containing allocation data to │
│ this path. Implies --profile-memory. │
│ --sample Sample CPU time in-process with pyinstrument before the │
│ timing run. Python frames only — for native/C frames │
│ use mew profile. │
│ --sample-interval pyinstrument sampling interval in seconds (default │
│ 1e-4). │
│ --sample-iterations Iterations of the body per benchmark under the sampler │
│ (default 1000). │
│ --sample-html Write a pyinstrument HTML report to this path. Implies │
│ --sample. │
╰──────────────────────────────────────────────────────────────────────────────╯
mew compare¶
$ mew compare --help
Usage: mew compare [OPTIONS] FILES
Compare benchmark result files; the first file is the baseline.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ FILES │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ -m, --metric metric to compare: real_time, cpu_time, iterations, or │
│ (for --profile-memory results) memory.peak_bytes, │
│ memory.total_bytes, memory.total_allocations │
│ --key how benchmarks are matched across files: name (full │
│ registered name) or func (strip the file.py:: prefix, │
│ for A/B suites in different files with matching │
│ function names) │
│ -k, --pattern regex filter (re.search) │
│ --stddev show stddev columns if present in the result files │
│ --by pivot dimension: variant compares the variants within │
│ one mew run --variant result file (one column each) │
│ instead of files │
│ --baseline with --by variant, the baseline variant (default: │
│ first written) │
│ --fail-on-regression exit 2 if any benchmark is slower than baseline by │
│ more than this percent │
│ --regressions-config TOML file with [tool.mew.regressions] (default: │
│ ./pyproject.toml) │
│ --allow inline allowlist entry PATTERN (ignore) or PATTERN:PCT │
│ (per-rule threshold) │
╰──────────────────────────────────────────────────────────────────────────────╯