BenchBox CLI Reference

This section provides comprehensive documentation for all BenchBox command-line interface (CLI) commands and options.

Global Options

These options are available for all BenchBox commands:

• --version: Show version information and exit
• --help: Show help message and exit

Commands Overview

BenchBox provides the following commands:

Command	Purpose	Documentation
run	Execute benchmarks with full configuration control	run
convert	Convert data to Parquet, Vortex, Delta Lake, or Iceberg	convert
shell	Launch interactive SQL shell for database	shell
platforms	Manage database platform adapters	platforms
check-deps	Check dependency status and installation guidance	utilities
profile	Profile system resources	utilities
benchmarks	Manage benchmark suites	utilities
validate	Validate configuration files	utilities
tuning init	Generate sample tuning configurations	tuning
tuning (DataFrame)	DataFrame tuning via unified tuning commands	tuning
export	Export benchmark results to various formats	results
submit	Package results for PR contribution or hosted API upload	submit
auth	Manage hosted submission credentials	auth
results	Display exported benchmark results	results
compare	Compare benchmark results for regression detection	results
visualize	Generate ASCII charts from benchmark results	visualize
report	Historical analysis, rankings, and regressions	report
metrics	Calculate TPC Power@Size and Throughput@Size	metrics
aggregate	Aggregate results into CSV performance trends	aggregate
datagen	Generate benchmark data without running queries	datagen
setup	Interactive cloud platform credential setup	setup
show-plan	Display query plan as ASCII tree	query-plans
plan-history	Show query plan evolution across runs	query-plans
download-answers	Pre-download TPC answer files for validation	download-answers

Quick Start

--help-topic all shows all options including advanced ones, and --help-topic examples shows categorized usage examples.

benchbox run --platform duckdb --benchmark tpch --scale 0.01

benchbox run --help
benchbox run --help-topic all
benchbox run --help-topic examples

Documentation Sections

CLI Commands

• run - Run Benchmarks
• convert - Convert Data Formats
• shell - Interactive SQL Shell
• platforms - Platform Management
• Utility Commands
• Tuning Commands
• Results Commands
• submit - Submit Results
• auth - Hosted Submission Credentials
• visualize - Generate Charts
• report - Historical Analysis
• metrics - Performance Metrics
• aggregate - Aggregate Results
• datagen - Data Generation
• setup - Cloud Credentials
• show-plan / plan-history - Query Plans
• download-answers - Answer Files
• Configuration
• Common Workflows
• Troubleshooting