CLI Reference: benchbox visualize

Tags intermediate reference visualization cli

Generate ASCII charts directly from benchmark result JSON files.

Synopsis

benchbox visualize [SOURCES...] [OPTIONS]

Description

The visualize command transforms BenchBox result JSON files into ASCII charts rendered directly in the terminal. It supports multiple chart types, templates for common workflows, and display customization options.

Auto-detection: When no sources are specified, automatically finds the latest results in benchmark_runs/results/.

Arguments

SOURCES (optional) : One or more result JSON files or glob patterns. If omitted, uses the latest result files.

benchbox visualize                              # Auto-detect latest
benchbox visualize results.json                 # Single file
benchbox visualize results/*.json               # Glob pattern
benchbox visualize run1.json run2.json          # Multiple files

Options

Template Selection

--template {default,flagship,head_to_head,trends,cost_optimization,comparison,latency_deep_dive,regression_triage,executive_summary} : Use a predefined chart template. Overrides --chart-type.

benchbox visualize results/*.json --template flagship

Chart Type Selection

--chart-type {auto,all,performance_bar,power_bar,distribution_box,query_heatmap,query_histogram,cost_scatter,time_series,...} : Specify chart types to generate. Repeatable for multiple types. Run benchbox visualize --help for the full list.

benchbox visualize results/*.json --chart-type performance_bar --chart-type distribution_box

Value

Description

auto

Render all applicable chart types (default)

all

Same as auto

performance_bar

Platform comparison bar chart (total execution time, lower is better)

power_bar

TPC Power@Size comparison bar chart (higher is better; TPC benchmarks only)

distribution_box

Latency distribution box plot

query_heatmap

Query x platform variance heatmap

query_histogram

Per-query latency vertical bars (auto-splits for >33 queries)

cost_scatter

Cost-performance scatter plot

time_series

Performance trend line chart

comparison_bar

Per-query paired bars with % change (requires 2 results)

diverging_bar

Percentage change centered on zero (requires 2 results)

summary_box

Key aggregate statistics panel

percentile_ladder

P50/P90/P95/P99 ladder across platforms

normalized_speedup

Log₂-scaled speedup relative to a baseline

stacked_phase

Stacked phase breakdown by benchmark phase

sparkline_table

Compact metric table with sparklines

cdf_chart

Cumulative distribution of query latency

rank_table

Per-query platform rankings (1st = fastest)

Appearance

--theme {light,dark} : Color theme for charts.

benchbox visualize results/*.json --theme dark

Default: light

--no-color : Disable ANSI colors in output. Useful for piping to files or plain terminals.

benchbox visualize results/*.json --no-color > charts.txt

--no-unicode : Use ASCII-only characters instead of Unicode block characters. For terminals without Unicode support.

benchbox visualize results/*.json --no-unicode

Examples

Basic Usage

# Generate charts from latest result (auto-detected)
benchbox visualize

# Generate from specific file
benchbox visualize benchmark_runs/results/tpch_duckdb_sf1.json

# Generate from multiple files for comparison
benchbox visualize duckdb.json snowflake.json bigquery.json

Using Templates

# Flagship comparison (4-chart set)
benchbox visualize results/*.json --template flagship

# Head-to-head comparison
benchbox visualize platform_a.json platform_b.json --template head_to_head

# Performance trends over time
benchbox visualize runs/2024/*.json runs/2025/*.json --template trends

# Cost optimization analysis
benchbox visualize cloud_results/*.json --template cost_optimization

Display Options

# Dark theme
benchbox visualize results/*.json --theme dark

# Specific chart types only
benchbox visualize results/*.json --chart-type performance_bar --chart-type cost_scatter

# Pipe-friendly output (no ANSI codes)
benchbox visualize results/*.json --no-color > comparison.txt

# ASCII-only for basic terminals
benchbox visualize results/*.json --no-unicode

# Combine options
benchbox visualize results/*.json --theme dark --no-color --no-unicode

Query Latency Histogram

# Per-query latency histogram (ideal for identifying slow queries)
benchbox visualize results/*.json --chart-type query_histogram

# TPC-DS results auto-split into 3 charts (99 queries / 33 per chart)
benchbox visualize tpcds_results.json --chart-type query_histogram

Output

Charts render directly to the terminal (stdout). All output is text-based with optional ANSI color codes.

To save output to a file:

# With ANSI codes preserved (viewable in terminals that support ANSI)
benchbox visualize results/*.json > charts.ansi

# Plain text (no color codes)
benchbox visualize results/*.json --no-color > charts.txt

Exit Codes

Code

Meaning

0

Success

1

Error (invalid input, no results found, etc.)

Dependencies

No additional dependencies required. Visualization is built into BenchBox core.

See Also