CLI Recipes

$# 1. Create a new project
$poly-bench init my-benchmarks
$cd my-benchmarks

$# 2. Add dependencies for each language you'll use
$poly-bench add --go golang.org/x/crypto
$poly-bench add --ts viem
$poly-bench add --rs tiny-keccak

$# 3. Install all dependencies
$poly-bench install

$# 4. Create a benchmark file
$poly-bench new keccak

$# 5. Run it
$poly-bench run benchmarks/keccak.bench --output results/

1my-benchmarks/
2├── polybench.toml           # Project config and dependencies
3├── benchmarks/
4│   └── example.bench        # Template benchmark
5└── .polybench/
6  └── runtime-env/         # Installed dependencies (gitignore this)

$poly-bench run benchmarks/keccak.bench

$poly-bench run

$# Save charts and reports to results/
$poly-bench run benchmarks/keccak.bench --output results/

$# Save markdown report
$poly-bench run benchmarks/keccak.bench --report markdown --output results/

$# Save JSON (for programmatic processing)
$poly-bench run benchmarks/keccak.bench --report json --output results/

$# Save markdown then JSON (run twice)
$poly-bench run benchmarks/keccak.bench --report markdown --output results/
$poly-bench run benchmarks/keccak.bench --report json --output results/

$# Run all languages (default)
$poly-bench run benchmarks/keccak.bench

$# Run only Go
$poly-bench run benchmarks/keccak.bench --lang go

$# Run only TypeScript
$poly-bench run benchmarks/keccak.bench --lang ts

$# Run only Rust
$poly-bench run benchmarks/keccak.bench --lang rust

$# Run Go and TypeScript, skip Rust
$poly-bench run benchmarks/keccak.bench --lang go --lang ts

$# Run Go and Rust, skip TypeScript
$poly-bench run benchmarks/keccak.bench --lang go --lang rust

$# Run exactly 100 iterations per benchmark (fast smoke test)
$poly-bench run benchmarks/keccak.bench --iterations 100

$# Combine with language filter for maximum speed
$poly-bench run benchmarks/keccak.bench --iterations 100 --lang go

$# Validate a single file
$poly-bench check benchmarks/keccak.bench

$# Success output
$✓ benchmarks/keccak.bench is valid

$# Error output
$error: undefined fixture 'data' at line 42
$--> benchmarks/keccak.bench:42:9
$ |
$42 |     go: keccak256(data)
$ |         ^^^^^^^^^^^^^^
$ = help: define a fixture named 'data' before using it

$#!/bin/sh
$# Validate all .bench files before committing
$for f in benchmarks/*.bench; do
$  poly-bench check "$f" || exit 1
$done

$# Print formatted output for a single file
$poly-bench fmt benchmarks/keccak.bench

$# Format all .bench files in benchmarks/ (print to stdout)
$poly-bench fmt

$# Write formatted output back to file(s)
$poly-bench fmt benchmarks/keccak.bench --write
$poly-bench fmt --write

1- name: Format benchmark files
2run: poly-bench fmt --write

$# Generate Go harness
$poly-bench codegen benchmarks/keccak.bench --lang go --output generated/

$# Generate TypeScript harness
$poly-bench codegen benchmarks/keccak.bench --lang ts --output generated/

$# Generate Rust harness
$poly-bench codegen benchmarks/keccak.bench --lang rust --output generated/

$# Inspect the output
$cat generated/benchmark_plugin.go

$# Compile-check all benchmark files (uses cache by default)
$poly-bench compile

$# Compile-check a single file/language
$poly-bench compile benchmarks/keccak.bench --lang go

$# Force cold compile-check
$poly-bench compile benchmarks/keccak.bench --no-cache --clear-cache

1poly-bench cache stats
2poly-bench cache clear
3poly-bench cache clean

1name: Benchmarks
2
3on:
4push:
5  branches: [main]
6pull_request:
7  branches: [main]
8
9jobs:
10bench:
11  runs-on: ubuntu-latest
12
13  steps:
14    - uses: actions/checkout@v4
15
16    - name: Install Go
17      uses: actions/setup-go@v5
18      with:
19        go-version: "1.22"
20
21    - name: Install Node.js
22      uses: actions/setup-node@v4
23      with:
24        node-version: "20"
25
26    - name: Install Rust
27      uses: dtolnay/rust-toolchain@stable
28
29    - name: Install poly-bench
30      run: curl -L https://install.evm-tooling.tools | bash
31
32    - name: Install benchmark dependencies
33      run: poly-bench install
34
35    - name: Format benchmark files
36      run: poly-bench fmt --write
37
38    - name: Compile-check benchmark files
39      run: poly-bench compile
40
41    - name: Validate benchmark files
42      run: |
43        for f in benchmarks/*.bench; do
44          poly-bench check "$f"
45        done
46
47    - name: Run benchmarks (markdown + json)
48      run: |
49        poly-bench run --report markdown --output results/
50        poly-bench run --report json --output results/
51
52    - name: Upload results
53      uses: actions/upload-artifact@v4
54      with:
55        name: benchmark-results
56        path: results/

1name: Benchmark Comparison
2
3on:
4pull_request:
5  branches: [main]
6
7jobs:
8bench-pr:
9  runs-on: ubuntu-latest
10  steps:
11    - uses: actions/checkout@v4
12
13    - name: Install poly-bench
14      run: curl -L https://install.evm-tooling.tools | bash
15
16    - name: Install dependencies
17      run: poly-bench install
18
19    - name: Run benchmarks (PR)
20      run: poly-bench run --report json --output results-pr/
21
22    - name: Upload PR results
23      uses: actions/upload-artifact@v4
24      with:
25        name: bench-pr
26        path: results-pr/
27
28bench-base:
29  runs-on: ubuntu-latest
30  steps:
31    - uses: actions/checkout@v4
32      with:
33        ref: ${{ github.base_ref }}
34
35    - name: Install poly-bench
36      run: curl -L https://install.evm-tooling.tools | bash
37
38    - name: Install dependencies
39      run: poly-bench install
40
41    - name: Run benchmarks (base)
42      run: poly-bench run --report json --output results-base/
43
44    - name: Upload base results
45      uses: actions/upload-artifact@v4
46      with:
47        name: bench-base
48        path: results-base/