Cli

CLI Reference

Complete reference for all burl command-line options

Complete documentation for all burl command-line options.

burl <url> [options]

Connection Options

Flag	Alias	Default	Description
`--connections`	`-c`	`10`	Number of concurrent connections
`--duration`	`-d`	`10s`	Test duration (e.g., `10s`, `1m`, `5m`)
`--requests`	`-n`	-	Total number of requests (alternative to duration)
`--qps`	`-q`	-	Rate limit in queries per second
`--timeout`	`-t`	`30s`	Request timeout
`--warmup`	`-w`	`0`	Number of warmup requests (excluded from stats)

Examples

# 50 connections for 30 seconds
burl https://api.example.com -c 50 -d 30s

# Exactly 1000 requests
burl https://api.example.com -n 1000

# Rate limited to 100 req/s
burl https://api.example.com -q 100

# With warmup
burl https://api.example.com -w 50 -d 60s

Request Options

Flag	Alias	Default	Description
`--method`	`-m`	`GET`	HTTP method
`--header`	`-H`	-	Custom header (repeatable)
`--body`	`-b`	-	Request body
`--body-file`	`-B`	-	Request body from file
`--content-type`	`-T`	-	Content-Type header shorthand

Examples

# POST with JSON
burl https://api.example.com -m POST -b '{"key":"value"}' -T application/json

# Multiple headers
burl https://api.example.com -H "X-Api-Key: secret" -H "Accept: application/json"

# Body from file
burl https://api.example.com -m POST -B payload.json -T application/json

HTTP Version

Flag	Default	Description
`--http1`	`false`	Force HTTP/1.1
`--http2`	`false`	Force HTTP/2
`--http3`	`false`	Force HTTP/3 (experimental)

HTTP/3 support is experimental and may not work with all servers.

Examples

# Force HTTP/1.1
burl https://api.example.com --http1

# Force HTTP/2
burl https://api.example.com --http2

Authentication

Flag	Alias	Description
`--auth`	`-a`	Authentication: `basic:user:pass` or `bearer:token`

Bearer Token

burl https://api.example.com -a bearer:eyJhbGciOiJIUzI1NiIs...

# Using environment variable
burl https://api.example.com -a bearer:$API_TOKEN

Basic Auth

burl https://api.example.com -a basic:username:password

# Using environment variables
burl https://api.example.com -a basic:$API_USER:$API_PASS

Output Options

Flag	Alias	Default	Description
`--format`	`-f`	`text`	Output format: `text`, `json`, `csv`, `markdown`
`--output`	`-o`	-	Write results to file
`--llm`	-	-	LLM-optimized output: `json` or `markdown`
`--no-tui`	-	`false`	Disable rich terminal UI
`--no-color`	-	`false`	Disable colored output
`--quiet`	-	`false`	Minimal output
`--verbose`	`-v`	`false`	Verbose output

Examples

# JSON output
burl https://api.example.com -f json

# Save to file
burl https://api.example.com -f json -o results.json

# LLM-optimized
burl https://api.example.com --llm json

# Quiet mode for scripts
burl https://api.example.com --quiet

TLS Options

Flag	Alias	Default	Description
`--insecure`	`-k`	`false`	Skip TLS certificate verification

Only use --insecure for testing with self-signed certificates. Never use in production.

burl https://self-signed.local -k

Advanced Options

Flag	Default	Description
`--latency-correction`	`false`	Enable coordinated omission correction

# More accurate tail latency measurements
burl https://api.example.com --latency-correction

Other Options

Flag	Alias	Description
`--version`	`-V`	Show version
`--help`	`-h`	Show help

Duration Format

Durations support human-readable formats:

Format	Example	Meaning
Seconds	`10s`	10 seconds
Minutes	`1m`	1 minute
Hours	`1h`	1 hour
Combined	`5m30s`	5 minutes and 30 seconds

Exit Codes

Code	Meaning
`0`	All requests successful (2xx responses)
`1`	One or more requests failed

Using in Scripts

#!/bin/bash
if burl https://api.example.com -n 100 --quiet; then
  echo "All requests succeeded"
else
  echo "Some requests failed"
  exit 1
fi

Environment Variables

burl respects standard environment variables:

Variable	Description
`NO_COLOR`	Disable colored output when set
`TERM`	Terminal type for TUI detection

Complete Example

burl https://api.example.com/v2/orders \
  -m POST \
  -H "X-API-Version: 2024-01" \
  -H "X-Request-ID: bench-$(date +%s)" \
  -a bearer:$API_TOKEN \
  -b '{"product_id": 123, "quantity": 1}' \
  -T application/json \
  -c 25 \
  -d 60s \
  -t 15s \
  -w 10 \
  -q 100 \
  --latency-correction \
  --llm json \
  -o results.json

This benchmark:

POSTs to the orders endpoint
Uses custom headers for API versioning and request tracing
Authenticates with a bearer token from environment
Sends a JSON order body
Uses 25 concurrent connections for 60 seconds
Has a 15 second timeout and 10 warmup requests
Rate limits to 100 requests/second
Enables latency correction for accurate tail latencies
Outputs LLM-optimized JSON to a file

Guide

CLI Reference