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_KEY

Connect 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_KEY

Benchmark with specific object size distribution:

warp put --obj.size 1MB,10MB,100MB --obj.randsize --access-key YOUR_ACCESS_KEY --secret-key YOUR_SECRET_KEY

Commands

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 and legal hold
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_TOKEN

Set --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