Complete reference of all solr-benchmark command-line flags.
Global flags
Accepted by all subcommands.
Flag
Short
Description
--help
-h
Display help text for the current command and exit
--offline
—
Run without network access; disables workload repository fetching and update checks
--version
-v
Show version and exit
--quiet
—
Suppress console output (except errors)
run flags
Workload selection
Flag
Type
Default
Description
--workload
string
—
Named workload (fetched from workloads repository)
--workload-path
path
—
Local workload directory path
--workload-repository
string
"default"
Git URL for the workloads repository (the string "default" resolves to the URL configured in benchmark.ini)
--workload-revision
string
—
Git revision (branch, tag, or commit) of the workloads repository. If omitted, the branch is selected automatically based on --distribution-version (e.g., 10.0.0 → branch 10); falls back to main if no matching branch exists.
Comma-separated task names to run; all other tasks are skipped
--exclude-tasks
string
—
Comma-separated task names to skip
--enable-assertions
flag
off
Enable task-level assertions defined in the workload
Cluster and pipeline
Flag
Type
Default
Description
--pipeline
string
(dynamic)
Pipeline to use: benchmark-only, docker, from-distribution, or from-sources. Defaults to benchmark-only when no provisioning flags are given
--target-hosts
string
—
Comma-separated host:port list
--distribution-version
string
—
Solr version for provisioning pipelines
--cluster-config
string
defaults
Cluster config preset for provisioning pipelines
Distributed load generation
Flag
Type
Default
Description
--worker-ips
string
localhost
Comma-separated IP addresses of worker coordinator machines
Multiple-iteration aggregation
Flag
Type
Default
Description
--test-iterations
integer
1
Number of times to repeat the workload
--aggregate
boolean
true
Aggregate results from all iterations
--sleep-timer
integer
5
Seconds to wait between iterations
--cancel-on-error
boolean
false
Abort remaining iterations on first error
Telemetry
Flag
Type
Default
Description
--telemetry
string
—
Comma-separated telemetry device names
--telemetry-params
string
—
Telemetry device parameters
Result output
Flag
Type
Default
Description
--test-run-id
string
auto-generated
Custom ID for this run; used with compare and aggregate
--user-tag
string
—
A single key:value metadata pair attached to every metric record in this run (e.g., intention:baseline)
--results-format
string
markdown
Summary table format: markdown or csv
--results-numbers-align
string
right
Column alignment: right, left, center, or decimal
--results-file
path
—
Write the summary table to this file
--show-in-results
string
available
Values to include: available, all-percentiles, or all
--visualize
flag
off
Generate an interactive HTML visualization after the run
--visualize-output-path
path
—
Path to write the HTML visualization file (defaults to the test run directory)
General
Flag
Type
Default
Description
--test-mode
flag
off
Run with ≤1,000 documents for quick validation
--on-error
string
continue
Error strategy: continue or abort
--client-options
string
timeout:60
Comma-separated client options passed to the Solr client (short: -c)
--kill-running-processes
flag
off
Kill other running solr-benchmark processes before starting (short: -k)
--preserve-install
flag
off
Keep the Solr installation after the run (provisioned pipelines only)
Provisioning
Flag
Type
Default
Description
--revision
string
—
Source code revision for the from-sources pipeline
--runtime-jdk
integer
—
Major JDK version to use for provisioned Solr nodes (e.g., 21)
--solr-modules
string
—
Comma-separated Solr modules to enable (e.g., extraction)
--plugin-params
string
—
Comma-separated key:value pairs passed to all configured plugins
--cluster-config-params
string
—
Comma-separated key:value variable overrides for the cluster config
--cluster-config-repository
string
—
Git URL for a custom cluster-config repository
--cluster-config-revision
string
—
Git revision of the cluster-config repository
--distribution-repository
string
release
Repository to download Solr from
Advanced load generation
Flag
Type
Default
Description
--grpc-target-hosts
string
localhost:9400
gRPC endpoint(s) for worker coordinator communication
--enable-worker-coordinator-profiling
flag
off
Profile the worker coordinator process
--latency-percentiles
string
—
Comma-separated additional percentiles to report for latency (e.g., 50,90,99,99.9)
--throughput-percentiles
string
—
Comma-separated additional percentiles to report for throughput
Load testing
These flags enable automated load-ramp and redline testing to find a cluster’s performance limits.
Flag
Type
Default
Description
--load-test-qps
integer
—
Run a load test that ramps up to this target QPS value
--redline-test
integer?
0 (off)
Run a redline test to find the maximum sustainable throughput. Use as a bare flag (--redline-test, implicitly 1000 QPS) or with an explicit QPS target (e.g. --redline-test 5000)
--redline-scale-step
integer
—
Number of clients to add per scale step
--redline-scaledown-percentage
float
—
Percentage of clients to remove when the error threshold is exceeded
--redline-post-scaledown-sleep
integer
—
Seconds to wait after a scale-down event before resuming
--redline-max-clients
integer
—
Maximum number of concurrent clients during a redline test
--redline-max-cpu-usage
float
—
CPU usage percentage at which to begin scaling back
--redline-cpu-window-seconds
integer
30
Window in seconds over which average CPU load is measured
--redline-cpu-check-interval
integer
30
Seconds between CPU usage checks
list flags
Flag
Description
--workload
Workload name (used with list workloads to filter by workload)
--workload-path
Local workload directory
--workload-repository
Git URL for the workloads repository
--workload-revision
Git revision of the workloads repository
--limit
Maximum number of test-run results to show (default: 10; applies to list test-runs)