sarin/docs/configuration.md

Configuration

Sarin supports environment variables, CLI flags, and YAML files. However, they are not exactly equivalent—YAML files have the most configuration options, followed by CLI flags, and then environment variables.

When the same option is specified in multiple sources, the following priority order applies:

YAML (Highest) > CLI Flags > Environment Variables (Lowest)

Use -s or --show-config to see the final merged configuration before sending requests.

Properties

Note: For CLI flags with string / []string type, the flag can be used once with a single value or multiple times to provide multiple values.

Name	YAML	CLI	ENV	Default	Description
Help	-	-help / -h	-	-	Show help message
Version	-	-version / -v	-	-	Show version and build info
Show Config	showConfig (boolean)	-show-config / -s (boolean)	SARIN_SHOW_CONFIG (boolean)	false	Show merged configuration
Config File	configFile (string / []string)	-config-file / -f (string / []string)	SARIN_CONFIG_FILE (string)	-	Path to config file(s)
URL	url (string)	-url / -U (string)	SARIN_URL (string)	-	Target URL (HTTP/HTTPS)
Method	method (string / []string)	-method / -M (string / []string)	SARIN_METHOD (string)	GET	HTTP method(s)
Timeout	timeout (duration)	-timeout / -T (duration)	SARIN_TIMEOUT (duration)	10s	Request timeout
Concurrency	concurrency (number)	-concurrency / -c (number)	SARIN_CONCURRENCY (number)	1	Number of concurrent workers
Requests	requests (number)	-requests / -r (number)	SARIN_REQUESTS (number)	-	Total requests to send
Duration	duration (duration)	-duration / -d (duration)	SARIN_DURATION (duration)	-	Test duration
Quiet	quiet (boolean)	-quiet / -q (boolean)	SARIN_QUIET (boolean)	false	Hide progress bar and logs
Output	output (string)	-output / -o (string)	SARIN_OUTPUT (string)	table	Output format for stats
Dry Run	dryRun (boolean)	-dry-run / -z (boolean)	SARIN_DRY_RUN (boolean)	false	Generate without sending
Insecure	insecure (boolean)	-insecure / -I (boolean)	SARIN_INSECURE (boolean)	false	Skip TLS verification
Body	body (string / []string)	-body / -B (string / []string)	SARIN_BODY (string)	-	Request body
Params	params (object)	-param / -P (string / []string)	SARIN_PARAM (string)	-	URL query parameters
Headers	headers (object)	-header / -H (string / []string)	SARIN_HEADER (string)	-	HTTP headers
Cookies	cookies (object)	-cookie / -C (string / []string)	SARIN_COOKIE (string)	-	HTTP cookies
Proxy	proxy (string / []string)	-proxy / -X (string / []string)	SARIN_PROXY (string)	-	Proxy URL(s)
Values	values (string / []string)	-values / -V (string / []string)	SARIN_VALUES (string)	-	Template values (key=value)

---

Help

Show help message.

Version

Show version and build information.

Show Config

Show the final merged configuration before sending requests.

Config File

Path to configuration file(s). Supports local paths and remote URLs.

If multiple config files are specified, they are merged in order. Later files override earlier ones.

Example:

# config2.yaml
configFile: /config4.yaml

SARIN_CONFIG_FILE=/config1.yaml sarin -f /config2.yaml -f https://example.com/config3.yaml

In this example, all 4 config files are read and merged with the following priority:

config3.yaml > config2.yaml > config4.yaml > config1.yaml

URL

Target URL. Must be HTTP or HTTPS. The URL path supports templating, allowing dynamic path generation per request.

Note: Templating is only supported in the URL path. Host and scheme must be static.

Example with dynamic path:

url: http://example.com/users/{{ fakeit_UUID }}/profile

CLI example with dynamic path:

sarin -U "http://example.com/users/{{ fakeit_UUID }}" -r 1000 -c 10

Method

HTTP method(s). If multiple values are provided, Sarin cycles through them randomly for each request. Supports templating.

YAML example:

method: GET

# OR

method:
  - GET
  - POST
  - PUT

CLI example:

-method GET -method POST -method PUT

ENV example:

SARIN_METHOD=GET

Timeout

Request timeout. Must be greater than 0.

Valid time units: ns, us (or µs), ms, s, m, h

Examples: 5s, 300ms, 1m20s

Concurrency

Number of concurrent workers. Must be between 1 and 100,000,000.

Requests

Total number of requests to send. At least one of requests or duration must be specified. If both are provided, the test stops when either limit is reached first.

Duration

Test duration. At least one of requests or duration must be specified. If both are provided, the test stops when either limit is reached first.

Valid time units: ns, us (or µs), ms, s, m, h

Examples: 1m30s, 25s, 1h

Quiet

Hide the progress bar and runtime logs.

Output

Output format for response statistics.

Valid formats: table, json, yaml, none

Using none disables output and reduces memory usage since response statistics are not stored.

Dry Run

Generate requests without sending them. Useful for testing templates.

Insecure

Skip TLS certificate verification.

Body

Request body. If multiple values are provided, Sarin cycles through them randomly for each request. Supports templating.

YAML example:

body: '{"product": "car"}'

# OR

body:
  - '{"product": "car"}'
  - '{"product": "phone"}'
  - '{"product": "watch"}'

CLI example:

-body '{"product": "car"}' -body '{"product": "phone"}' -body '{"product": "watch"}'

ENV example:

SARIN_BODY='{"product": "car"}'

Params

URL query parameters. If multiple values are provided for a key, Sarin cycles through them randomly for each request. Supports templating.

YAML example:

params:
  key1: value1
  key2: [value2, value3]

# OR

params:
  - key1: value1
  - key2: [value2, value3]

CLI example:

-param "key1=value1" -param "key2=value2" -param "key2=value3"

ENV example:

SARIN_PARAM="key1=value1"

Headers

HTTP headers. If multiple values are provided for a key, Sarin cycles through them randomly for each request. Supports templating.

YAML example:

headers:
  key1: value1
  key2: [value2, value3]

# OR

headers:
  - key1: value1
  - key2: [value2, value3]

CLI example:

-header "key1: value1" -header "key2: value2" -header "key2: value3"

ENV example:

SARIN_HEADER="key1: value1"

Cookies

HTTP cookies. If multiple values are provided for a key, Sarin cycles through them randomly for each request. Supports templating.

YAML example:

cookies:
  key1: value1
  key2: [value2, value3]

# OR

cookies:
  - key1: value1
  - key2: [value2, value3]

CLI example:

-cookie "key1=value1" -cookie "key2=value2" -cookie "key2=value3"

ENV example:

SARIN_COOKIE="key1=value1"

Proxy

Proxy URL(s). If multiple values are provided, Sarin cycles through them randomly for each request.

Supported protocols: http, https, socks5, socks5h

YAML example:

proxy: http://proxy1.com

# OR

proxy:
  - http://proxy1.com
  - socks5://proxy2.com
  - socks5h://proxy3.com

CLI example:

-proxy http://proxy1.com -proxy socks5://proxy2.com -proxy socks5h://proxy3.com

ENV example:

SARIN_PROXY="http://proxy1.com"

Values

Template values in key=value format. Supports templating. Multiple values can be specified and all are rendered for each request.

See the Templating Guide for more details on using values and available template functions.

YAML example:

values: "key=value"

# OR

values: |
  key1=value1
  key2=value2
  key3=value3

CLI example:

-values "key1=value1" -values "key2=value2" -values "key3=value3"

ENV example:

SARIN_VALUES="key1=value1"