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:

CLI Flags (Highest) > YAML > 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)
Lua	lua (string / []string)	-lua (string / []string)	SARIN_LUA (string)	-	Lua script(s)
Js	js (string / []string)	-js (string / []string)	SARIN_JS (string)	-	JavaScript script(s)

---

Help

Show help message.

sarin -help

Version

Show version and build information.

sarin -version

Show Config

Show the final merged configuration before sending requests.

sarin -show-config

Config File

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

Priority Rules:

1. CLI flags (-f) have highest priority, processed left to right (rightmost wins)
2. Included files (via configFile property) are processed with lower priority than their parent
3. Environment variable (SARIN_CONFIG_FILE) has lowest priority

Example:

# config2.yaml
configFile: /config4.yaml
url: http://from-config2.com

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

Resolution order (lowest to highest priority):

Source	File	Priority
ENV (SARIN_CONFIG_FILE)	config1.yaml	Lowest
Included by config2.yaml	config4.yaml	↑
CLI -f (first)	config2.yaml	↑
CLI -f (second)	config3.yaml	Highest

Why this order?

• config1.yaml comes from ENV → lowest priority
• config2.yaml comes from CLI → higher than ENV
• config4.yaml is included BY config2.yaml → inherits position below its parent
• config3.yaml comes from CLI after config2.yaml → highest priority

If all four files define url, the value from config3.yaml wins.

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 in order, starting from a random index 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 in order, starting from a random index 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. Supports templating.

When the same key appears as separate entries (in CLI or config file), all values are sent in every request. When multiple values are specified as an array on a single key (config file only), Sarin cycles through them.

YAML example:

params:
  key1: value1
  key2: [value2, value3]  # cycles between value2 and value3

# OR

params:
  - key1: value1
  - key2: [value2, value3]  # cycles between value2 and value3

# To send both values in every request, use separate entries:
params:
  - key2: value2
  - key2: value3  # both sent in every request

CLI example:

-param "key1=value1" -param "key2=value2" -param "key2=value3"  # sends both value2 and value3

ENV example:

SARIN_PARAM="key1=value1"

Headers

HTTP headers. Supports templating.

When the same key appears as separate entries (in CLI or config file), all values are sent in every request. When multiple values are specified as an array on a single key (config file only), Sarin cycles through them.

YAML example:

headers:
  key1: value1
  key2: [value2, value3]  # cycles between value2 and value3

# OR

headers:
  - key1: value1
  - key2: [value2, value3]  # cycles between value2 and value3

# To send both values in every request, use separate entries:
headers:
  - key2: value2
  - key2: value3  # both sent in every request

CLI example:

-header "key1: value1" -header "key2: value2" -header "key2: value3"  # sends both value2 and value3

ENV example:

SARIN_HEADER="key1: value1"

Cookies

HTTP cookies. Supports templating.

When the same key appears as separate entries (in CLI or config file), all values are sent in every request. When multiple values are specified as an array on a single key (config file only), Sarin cycles through them.

YAML example:

cookies:
  key1: value1
  key2: [value2, value3]  # cycles between value2 and value3

# OR

cookies:
  - key1: value1
  - key2: [value2, value3]  # cycles between value2 and value3

# To send both values in every request, use separate entries:
cookies:
  - key2: value2
  - key2: value3  # both sent in every request

CLI example:

-cookie "key1=value1" -cookie "key2=value2" -cookie "key2=value3"  # sends both value2 and value3

ENV example:

SARIN_COOKIE="key1=value1"

Proxy

Proxy URL(s). If multiple values are provided, Sarin cycles through them in order, starting from a random index 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"

Lua

Lua script(s) for request transformation. Each script must define a global transform function that receives a request object and returns the modified request object. Scripts run after template rendering, before the request is sent.

If multiple Lua scripts are provided, they are chained in order—the output of one becomes the input to the next. When both Lua and JavaScript scripts are specified, all Lua scripts run first, then all JavaScript scripts.

Script sources:

Scripts can be provided as:

• Inline script: Direct script code
• File reference: @/path/to/script.lua or @./relative/path.lua
• URL reference: @http://... or @https://...
• Escaped @: @@... for inline scripts that start with a literal @

The transform function:

function transform(req)
    -- req.method   (string)                    - HTTP method (e.g. "GET", "POST")
    -- req.path     (string)                    - URL path (e.g. "/api/users")
    -- req.body     (string)                    - Request body
    -- req.headers  (table of string/arrays)    - HTTP headers (e.g. {["X-Key"] = "value"})
    -- req.params   (table of string/arrays)    - Query parameters (e.g. {["id"] = "123"})
    -- req.cookies  (table of string/arrays)    - Cookies (e.g. {["session"] = "abc"})

    req.headers["X-Custom"] = "my-value"
    return req
end

Note: Header, parameter, and cookie values can be a single string or a table (array) for multiple values per key (e.g. {"val1", "val2"}).

YAML example:

lua: |
    function transform(req)
        req.headers["X-Custom"] = "my-value"
        return req
    end

# OR

lua:
    - "@/path/to/script1.lua"
    - "@/path/to/script2.lua"

CLI example:

-lua 'function transform(req) req.headers["X-Custom"] = "my-value" return req end'

# OR

-lua @/path/to/script1.lua -lua @/path/to/script2.lua

ENV example:

SARIN_LUA='function transform(req) req.headers["X-Custom"] = "my-value" return req end'

Js

JavaScript script(s) for request transformation. Each script must define a global transform function that receives a request object and returns the modified request object. Scripts run after template rendering, before the request is sent.

If multiple JavaScript scripts are provided, they are chained in order—the output of one becomes the input to the next. When both Lua and JavaScript scripts are specified, all Lua scripts run first, then all JavaScript scripts.

Script sources:

Scripts can be provided as:

• Inline script: Direct script code
• File reference: @/path/to/script.js or @./relative/path.js
• URL reference: @http://... or @https://...
• Escaped @: @@... for inline scripts that start with a literal @

The transform function:

function transform(req) {
    // req.method   (string)                    - HTTP method (e.g. "GET", "POST")
    // req.path     (string)                    - URL path (e.g. "/api/users")
    // req.body     (string)                    - Request body
    // req.headers  (object of string/arrays)   - HTTP headers (e.g. {"X-Key": "value"})
    // req.params   (object of string/arrays)   - Query parameters (e.g. {"id": "123"})
    // req.cookies  (object of string/arrays)   - Cookies (e.g. {"session": "abc"})

    req.headers["X-Custom"] = "my-value";
    return req;
}

Note: Header, parameter, and cookie values can be a single string or an array for multiple values per key (e.g. ["val1", "val2"]).

YAML example:

js: |
    function transform(req) {
        req.headers["X-Custom"] = "my-value";
        return req;
    }

# OR

js:
    - "@/path/to/script1.js"
    - "@/path/to/script2.js"

CLI example:

-js 'function transform(req) { req.headers["X-Custom"] = "my-value"; return req; }'

# OR

-js @/path/to/script1.js -js @/path/to/script2.js

ENV example:

SARIN_JS='function transform(req) { req.headers["X-Custom"] = "my-value"; return req; }'