warp CLI
This section provides comprehensive reference documentation for the warp command-line interface.
Warp is MinIO’s S3 benchmarking tool designed to measure and analyze object storage performance. The tool generates realistic workloads and provides detailed performance metrics for S3-compatible storage systems.
Use this reference to understand all available flags and commands. For installation instructions, see the Installation section. For practical guidance on running benchmarks, see the Administration section. Each command listed below has its own detailed documentation page with examples and use cases.
Command structure
warp COMMAND [FLAGS] [COMMAND FLAGS]The warp command accepts a command name, followed by global flags, followed by command-specific flags.
Most flags can be set via environment variables for convenience in scripted environments.
Basic examples
Run a simple PUT benchmark against an S3-compatible storage system:
warp put --host myaistor.example.com:9000 --access-key YOUR_ACCESS_KEY --secret-key YOUR_SECRET_KEYConnect to multiple Warp clients for distributed load generation:
warp mixed --warp-client client1:7761,client2:7761,client3:7761 --access-key YOUR_ACCESS_KEY --secret-key YOUR_SECRET_KEYBenchmark with specific object size distribution:
warp put --obj.size 1MB,10MB,100MB --obj.randsize --access-key YOUR_ACCESS_KEY --secret-key YOUR_SECRET_KEYCommands
Benchmark commands
| Command | Tests |
|---|---|
| append | S3 Express append operations |
| delete | Delete operations |
| fanout | Single object to multiple copies |
| get | Download performance |
| list | List operations |
| mixed | Mixed operations (GET, PUT, DELETE, STAT) |
| multipart | Multipart upload and download |
| multipart-put | Multipart upload only |
| put | Upload performance |
| retention | Object retention |
| snowball | TAR file extraction |
| stat | Stat operations |
| versioned | Versioned object operations |
| zip | ZIP file operations (MinIO s3zip extension) |
Utility commands
| Command | Purpose |
|---|---|
| analyze | Analyze existing benchmark data |
| client | Start warp client for distributed benchmarking |
| cmp | Compare two benchmark runs |
| merge | Merge multiple benchmark runs |
| run | Execute benchmark from YAML configuration |
Common flags
These flags apply to most warp commands. Command-specific flags are documented on individual command pages.
Global flags
| Flag | Description |
|---|---|
--autocompletion | Install shell auto-completion |
--debug | Enable debug output |
--help, -h | Show help |
--insecure | Disable TLS certificate verification |
--no-color | Disable colored output |
--version, -v | Print the version |
Connection flags
| Flag | Description | Environment Variable |
|---|---|---|
--access-key | S3 access key | WARP_ACCESS_KEY |
--bucket | Bucket for benchmark data (all data will be deleted) (default: “warp-benchmark-bucket”) | |
--host | S3 endpoint to connect to (supports multiple as comma-separated list) (default: “127.0.0.1:9000”) | WARP_HOST |
--host-select | Host selection algorithm: “weighed” or “roundrobin” (default: “weighed”) | |
--ktls | Use Kernel TLS (HTTPS) if available | WARP_KTLS |
--lookup | Force ‘host’ for host-style or ‘path’ for path-style lookup (autodetect by default) | |
--region | S3 region | WARP_REGION |
--secret-key | S3 secret key | WARP_SECRET_KEY |
--session-token | Session token for temporary credentials | WARP_SESSION_TOKEN |
--sts-web-token | Token Warp presents when it authenticates with STS (Security Token Service) web identity credentials (prefix the value with ‘file:’ to load the token from a file). Requires --signature STS_WEB_TOKEN | WARP_STS_WEB_TOKEN |
--tls | Use TLS (HTTPS) for transport | WARP_TLS |
Warp signs requests with AWS Signature Version 4 unless you tell it otherwise, so --sts-web-token has no effect on its own.
To authenticate with an STS web identity token, pass both flags:
warp get --sts-web-token file:/path/to/token --signature STS_WEB_TOKENSet --signature to one of S3V2, S3V4, IAM, or STS_WEB_TOKEN.
For complete environment variable documentation including usage examples, see the Environment Variables Reference.
Performance and concurrency flags
| Flag | Description |
|---|---|
--concurrent | Concurrent operations per warp client (default: 20) |
--rps-limit | Rate limit per instance in requests per second (0 to disable) (default: 0) |
Object and data flags
| Flag | Description |
|---|---|
--noprefix | Do not use separate prefix for each thread |
--obj.generator | Data generator to use (default: “random”) |
--obj.randsize | Randomize object sizes up to specified size |
--obj.size | Size of generated objects (number or 10KiB/MiB/GiB, base 2 binary) |
--prefix | Custom prefix for each thread |
Upload and encryption flags
| Flag | Description |
|---|---|
--checksum | Add checksum to uploaded objects: CRC64NVME, CRC32[-FO], CRC32C[-FO], SHA1, or SHA256 (requires server trailing headers) |
--disable-multipart | Disable multipart uploads |
--disable-sha256-payload | Disable calculating sha256 on client side |
--encrypt | Server-side encrypt/decrypt objects using random keys |
--md5 | Add MD5 sum to uploads |
--sse-s3-encrypt | Server-side SSE-S3 encrypt/decrypt objects |
--storage-class | Custom storage class (for example, ‘STANDARD’ or ‘REDUCED_REDUNDANCY’) |
Benchmark control flags
| Flag | Description |
|---|---|
--autoterm | Automatically terminate when benchmark stabilizes |
--autoterm.dur | Minimum stable duration before auto-termination (default: 15s) |
--autoterm.pct | Percentage threshold for stability detection (default: 7.5) |
--benchdata | Output file for benchmark and profile data (generates unique filename by default) |
--duration | Benchmark duration (use ’s’ and ’m’ for seconds and minutes) (default: 5m0s) |
--noclear | Do not clear bucket before or after benchmarks (use for multiple clients) |
--serverprof | MinIO server profiling type: ‘cpu’, ‘mem’, ‘block’, ‘mutex’, or ’trace’ |
--stress | Stress test mode (discard output) |
--syncstart | Benchmark start time in ‘hh:mm’ format (24h, server timezone) |
--warp-client | Connect to warp clients for distributed benchmarking |
Analysis flags
| Flag | Description |
|---|---|
--analyze.dur | Split analysis into durations (for example, ‘1s’, ‘5s’, ‘1m’) |
--analyze.host | Filter output by host |
--analyze.op | Filter output by operation type (GET, PUT, DELETE, etc.) |
--analyze.out | Output aggregated data to file |
--analyze.skip | Additional duration to skip when analyzing (default: 0s) |
--analyze.v | Display additional analysis data |
--full | Record full analysis data with every request (default aggregates) |
Monitoring and output flags
| Flag | Description | Environment Variable |
|---|---|---|
--influxdb | Send operations to InfluxDB: ‘http://@://’ | WARP_INFLUXDB_CONNECT |
--serve | Open webserver to fetch results remotely (for example, localhost:7762) | |
--web | Open a web UI on the local machine to visualize results |