CLI Reference
Command-line interface reference for poly-bench
Loading...
Command-line interface reference for poly-bench
poly-bench includes commands for validation, compilation, execution, project setup, dependency management, cache management, formatting, and editor integration.
| Command | Description |
|---|---|
poly-bench check <file> | Parse and validate a .bench file |
poly-bench compile [file] | Compile-check benchmarks without running |
poly-bench cache <stats|clear|clean> | Inspect or manage compile cache/workspace |
poly-bench run [file] | Execute benchmarks |
poly-bench plot <from-file|bar-chart|line-chart|speedup-chart|table> | Generate charts from results.json without running |
poly-bench codegen <file> | Generate runtime code without running |
poly-bench fmt [files...] | Format .bench files |
poly-bench init [name] | Initialize a new project |
poly-bench new <name> | Create a new benchmark template |
poly-bench add | Add language dependencies |
poly-bench add-runtime <RUNTIME> | Add a runtime (go, ts, rust, python, c, csharp, zig) to the project |
poly-bench remove | Remove language dependencies |
poly-bench install | Install dependencies from polybench.toml |
poly-bench build | Build/regenerate runtime environment |
poly-bench upgrade | Upgrade to latest binary |
poly-bench lsp | Start the language server |
poly-bench runExecute benchmarks from a .bench file, or run all files in benchmarks/ when no file is provided.
$poly-bench run [OPTIONS] [FILE]| Option | Description |
|---|---|
--lang <LANG> | Restrict language: go, ts/typescript, rust/rs, python/py, c, csharp/cs, zig |
--iterations <N> | Override iteration count |
--report <FORMAT> | console (default), markdown, json |
--output <DIR> / -o <DIR> | Output directory for reports/charts |
--project-dir <LANG:DIR> | Explicit project root per language (e.g. go:./my-mod, ts:./frontend). Repeatable. |
$poly-bench run benchmarks/hash.bench \$--lang go \$--report json \$--output out/out/results.json after each run.poly-bench plotGenerate charts from existing out/results.json without re-running benchmarks.
$poly-bench plot <SUBCOMMAND> [OPTIONS]| Subcommand | Description |
|---|---|
from-file [FILE] | Plot using chart directives from a .bench file's after block |
bar-chart | Generate a bar chart (requires --output-file) |
line-chart | Generate a line chart (requires --output-file) |
speedup-chart | Generate a speedup chart (requires --output-file) |
table | Generate a results table (requires --output-file) |
| Option | Description |
|---|---|
--results <PATH> | Path to results JSON (default: out/results.json) |
--output <DIR> / -o <DIR> | Output directory for charts (default: out/) |
| Option | Description |
|---|---|
--output-file <FILE> | Output filename (required for direct charts) |
--title <TITLE> | Chart title |
--suite <NAME> | Filter to a specific suite |
--y-scale <SCALE> | Y-axis scale: linear, log10, symlog, split |
--sort-by <KEY> | Sort by: speedup, name, time, ops |
--theme <THEME> | Color theme: dark or light |
$poly-bench plot from-file benchmarks/bubble.benchpoly-bench checkParse and validate a benchmark DSL file.
$poly-bench check <FILE> [--show-ast]poly-bench compileCompile-check benchmarks without running them.
$poly-bench compile [FILE] [--lang <LANG>] [--no-cache] [--clear-cache]| Option | Description |
|---|---|
--lang <LANG> | Compile-check only one language (go, ts, typescript, rust, rs, python, py, c, csharp, cs, zig) |
--no-cache | Disable compile-result cache for this run |
--clear-cache | Clear cache before compiling |
compile in CI to catch embedded-language errors before benchmark execution.poly-bench cacheManage compile cache and workspace state.
$poly-bench cache stats$poly-bench cache clear$poly-bench cache clean| Subcommand | Description |
|---|---|
stats | Show cache statistics and workspace size |
clear | Clear compile cache entries |
clean | Clean entire .polybench/ workspace |
poly-bench codegenGenerate code from DSL without running.
$poly-bench codegen <FILE> --lang <LANG> --output <DIR>LANG supports go, ts/typescript, rust/rs only. Python, C, C#, and Zig do not support codegen output.
poly-bench fmtFormat benchmark files.
$poly-bench fmt [FILES...] [--write]| Option | Description |
|---|---|
--write / -w | Write formatted content back to files (otherwise prints to stdout) |
poly-bench init$poly-bench init [NAME] [--languages go,ts,rust] [--no-example]poly-bench new$poly-bench new <NAME>poly-bench addAdd language dependencies to the project. Updates polybench.toml and installs into .polybench/runtime-env/<lang>/.
$poly-bench add --go <PKG>$poly-bench add --ts <PKG>$poly-bench add --rs <CRATE> [--features <F1,F2,...>]$poly-bench add --py <PKG>$poly-bench add --c <PKG>@<version>$poly-bench add --cs <PKG>@<version>$poly-bench add --zig <PKG>poly-bench add-runtimeAdd a runtime to an existing project. Creates the runtime config in polybench.toml and the .polybench/runtime-env/<lang>/ directory. Supported runtimes: go, ts, rust, python, c, csharp, zig.
$poly-bench add-runtime go$poly-bench add-runtime ts$poly-bench add-runtime rust$poly-bench add-runtime python$poly-bench add-runtime c$poly-bench add-runtime csharp$poly-bench add-runtime zigpoly-bench remove$poly-bench remove --go <PKG>$poly-bench remove --ts <PKG>$poly-bench remove --rs <CRATE>$poly-bench remove --py <PKG>poly-bench install$poly-bench installpoly-bench build$poly-bench build [--force] [--skip-install]poly-bench lsp$poly-bench lsppoly-bench upgrade$poly-bench upgrade| Option | Description |
|---|---|
--version, -V, -v | Print version and exit |
--color <WHEN> | Color mode: auto, always, never |
--quiet, -q | Reduce log output |
--help, -h | Show help |