docs/reference/commands/command-flags.md

---
title: Command Flags
parent: Command Reference
grand_parent: Reference
nav_order: 150
---

# Command Flags

Complete reference of all `solr-orbit` 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. |
| `--workload-params` | string | — | Comma-separated `key:value` Jinja2 parameter overrides |
| `--test-procedure` | string | workload default | Test procedure name to run |
| `--include-tasks` | string | — | 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-orbit` 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`) |

## info flags

| Flag | Description |
|------|-------------|
| `--workload` | Workload name |
| `--workload-path` | Local workload directory |
| `--workload-repository` | Git URL for the workloads repository |
| `--workload-revision` | Git revision of the workloads repository |
| `--workload-params` | Comma-separated `key:value` Jinja2 parameter overrides |
| `--test-procedure` | Specific test procedure to describe |
| `--include-tasks` | Comma-separated task names to display |
| `--exclude-tasks` | Comma-separated task names to hide |

## compare flags

| Flag | Description |
|------|-------------|
| `--baseline` | Test run ID of the baseline run (see `list test-runs`) |
| `--contender` | Test run ID of the contender run (see `list test-runs`) |
| `--results-format` | Output format: `markdown` (default) or `csv` |
| `--results-numbers-align` | Column alignment: `right` (default), `left`, `center`, or `decimal` |
| `--results-file` | Write the comparison table to a file |
| `--show-in-results` | Values to include: `available` (default), `all-percentiles`, or `all` |
| `--percentiles` | Comma-separated list of percentiles to include in the comparison |

## aggregate flags

| Flag | Description |
|------|-------------|
| `--test-runs` | Comma-separated test run IDs to aggregate |
| `--test-runs-id` | Custom ID for the aggregated result |
| `--results-file` | Path to write the aggregated results JSON |
| `--workload-repository` | Git URL for the workloads repository |

## download flags

Solr is pure Java — no OS- or architecture-specific variants exist.

| Flag | Description |
|------|-------------|
| `--distribution-version` | Solr version to download (e.g., `9.10.1`) |
| `--distribution-repository` | Source repository (default: `release`) |
| `--cluster-config` | Cluster configuration preset to apply |
| `--cluster-config-params` | Comma-separated `key:value` variable overrides for the cluster configuration |
| `--cluster-config-path` | Local path to a cluster configuration directory |
| `--cluster-config-repository` | Git URL for a cluster configuration repository |
| `--cluster-config-revision` | Git revision of the cluster-config repository to use |

## convert-workload flags

| Flag | Description |
|------|-------------|
| `--workload-path` | Path to the source (OpenSearch Benchmark format) workload directory |
| `--output-path` | Destination directory for the converted workload |
| `--force` | Overwrite the output directory if it already exists |