Configuration Guide

This guide provides comprehensive documentation for configuring fetch using a configuration file.

Configuration File Format

fetch uses an INI-like configuration file format that supports both global and host-specific settings.

File Locations

fetch searches for configuration files in the following order:

Specified path: The file location specified with the -c or --config flag
Default path candidates:
- $XDG_CONFIG_HOME/fetch/config (if XDG_CONFIG_HOME is set)
- $HOME/.config/fetch/config (if HOME is set)
- Windows only: %AppData%\fetch\config (fallback)

On Windows, fetch still checks XDG_CONFIG_HOME and HOME first when those environment variables are present, then falls back to %AppData%\fetch\config.

Configuration Precedence

Scalar settings are applied in the following order of precedence (highest to lowest):

Command line flags - Override all other settings
Domain-specific configuration - Host-specific settings in config file
Global configuration - Global settings in config file
Default values - Built-in application defaults

In summary, scalar options override other scalar options. List options merge in this order: global, host, and CLI. Repeatable options such as header, query, and ca-cert are applied in this order: global config first, then the matched host section, then command-line flags.

As a result, you can set global defaults and override scalar values for each domain or command. You can also add shared list values without removing more specific entries.

File Structure

Configuration files use a simple key-value format with optional sections:

# Global settings
option = value

# Host-specific settings
[example.com]
option = host_specific_value

Available Configuration Options

Auto-Update Options

`auto-update`

Type: Boolean or duration interval Default: false (disabled)

Enable or disable automatic updates, or set the minimum interval between update checks. See Updates for background update behavior, cache files, locking, verification, and timeout/proxy behavior.

# Enable auto-update with default 24-hour interval
auto-update = true

# Disable auto-update
auto-update = false

# Custom update interval
auto-update = 4h
auto-update = 1.5h
auto-update = 30m
auto-update = +30m
auto-update = 1d

Output Control Options

`copy`

Type: Boolean Default: false

Copy the response body to the system clipboard.

copy = true
copy = false

`color` / `colour`

Type: String Values: auto, off, on Default: auto

Control colored output in the terminal.

# Automatically detect terminal color support
color = auto

# Always disable colors
color = off

# Always enable colors
color = on

`format`

Type: String Values: auto, off, on Default: auto

Control automatic formatting of response bodies (JSON, XML, etc.).

# Automatically detect and format supported content types
format = auto

# Disable all formatting
format = off

# Always attempt formatting
format = on

`image`

Type: String Values: auto, external, off Default: auto

Control image rendering in the terminal.

# Try optimal terminal protocol with built-in decoders
image = auto

# Allow external adapters for additional formats
image = external

# Disable image rendering
image = off

`pager`

Type: String Values: auto, on, off Default: auto

Control piping response body output through a pager. auto uses the pager when stdout is a terminal, on forces pager use, and off disables the pager. When paging is enabled, fetch uses $PAGER if it is set. Set NO_PAGER to disable the default auto pager. If $PAGER is unset, fetch uses less -FIRX. If $LESS is set, fetch runs less without its default flags. Your LESS options still apply. $PAGER is split with POSIX shell-style quoting, but fetch launches the pager directly and does not interpret shell operators such as pipes or redirects.

# Disable pager
pager = off

# Force pager
pager = on

`silent`

Type: Boolean Default: false

Suppress verbose output. Only errors are written to stderr.

# Enable silent mode
silent = true

# Normal output (default)
silent = false

`timing`

Type: Boolean Default: false

Display a timing waterfall chart after the response, showing DNS, TCP, TLS, TTFB, and body download phases.

# Enable timing waterfall
timing = true

# Disable timing waterfall (default)
timing = false

`verbosity`

Type: Integer Values: 0 or greater Default: 0

Set the verbosity level for debug output.

# Normal output (default)
verbosity = 0

# Verbose - show response headers
verbosity = 1

# Extra verbose - show request and response headers with direction prefixes
verbosity = 2

# Debug - show DNS and TLS details with direction prefixes
verbosity = 3

`sort-headers`

Type: Boolean Default: false

Sort displayed request and response headers alphabetically by name. This only changes verbose output. fetch sends request headers in their normal order.

sort-headers = true

Network Options

`ca-cert`

Type: CA certificate path Repeatable: Yes Default: System default

Use a custom CA cert pool.

# Set to filepath to cert file
ca-cert = ca-cert.pem

# Multiple custom roots are appended in order
ca-cert = internal-root.pem
ca-cert = partner-root.pem

`dns-server`

Type: IP[:PORT], udp://IP[:PORT], tcp://IP[:PORT], tls://HOST[:PORT], dot://HOST[:PORT], quic://HOST[:PORT], doq://HOST[:PORT], or HTTPS URL Default: System default

Use a custom DNS server for hostname resolution.

DoH URLs use RFC 8484 wire-format requests, with Google-style JSON DoH retained as a compatibility fallback.

# Use Google DNS
dns-server = 8.8.8.8

# Use Cloudflare DNS with custom port
dns-server = 1.1.1.1:53

# Use IPv6 DNS server
dns-server = [2001:4860:4860::8888]:53

# DNS over TCP
dns-server = tcp://1.1.1.1

# DNS over TLS
dns-server = tls://dns.google

# DNS over QUIC
dns-server = doq://dns.adguard-dns.com

# Use DNS-over-HTTPS
dns-server = https://1.1.1.1/dns-query
dns-server = https://dns.google/dns-query

`proxy`

Type: URL Default: None

Route requests through the specified proxy server.

# HTTP proxy
proxy = http://proxy.example.com:8080

# HTTPS proxy
proxy = https://secure-proxy.example.com:8080

# SOCKS5 proxy
proxy = socks5://localhost:1080

`connect-timeout`

Type: Number (seconds) Default: None (no connect timeout)

Set a timeout for the connection phase (DNS resolution, TCP connect, TLS handshake). Independent of timeout, which covers the entire request. Accepts decimal values.

# 5 second connect timeout
connect-timeout = 5

# 2.5 second connect timeout
connect-timeout = 2.5

`timeout`

Type: Number (seconds) Default: None (no timeout)

Set a timeout for HTTP requests. Accepts decimal values. This timeout covers the full request, including streamed response bodies such as SSE, NDJSON, and gRPC streams.

# 30 second timeout
timeout = 30

# 2.5 second timeout
timeout = 2.5

`redirects`

Type: Integer Default: 10

Set the maximum number of automatic redirects to follow.

# Disable redirects
redirects = 0

# Allow up to 10 redirects
redirects = 10

`retry`

Type: Integer Default: 0 (no retries)

Maximum number of retries for transient failures. Retries occur on connection errors and retryable status codes (429, 502, 503, 504).

# Retry up to 3 times
retry = 3

# Disable retries (default)
retry = 0

`retry-delay`

Type: Number (seconds) Default: 1

Initial delay between retries in seconds. Uses exponential backoff with jitter. Accepts decimal values.

# 2 second initial delay
retry-delay = 2

# 500ms initial delay
retry-delay = 0.5

`http`

Type: String Values: 1, 2, 3

Force a specific HTTP protocol version.

When unset, direct HTTPS requests use DNS HTTPS/SVCB records to discover h3 endpoints. With dns-server, HTTPS-record discovery uses that custom UDP, TCP, DoT, DoQ, or DoH resolver. Without dns-server, it uses the platform resolver. On Linux, this uses systemd-resolved when available. The documented Unix resolver-file fallback cannot honor NSS or split-DNS policy. Discovery runs in parallel with normal A/AAAA lookup and TCP/TLS setup. fetch starts TCP/TLS as soon as normal DNS produces a usable address, while a usable h3 record discovered before TCP/TLS wins races QUIC setup against it. The request is sent once on the winning transport. System, UDP, TCP, and plaintext HTTP DNS can fall back after an HTTPS-record lookup failure. A transport, server, or malformed-response failure from certificate-verified DoH, DoT, or DoQ stops the connection to prevent protocol downgrade. Authenticated NODATA and NXDOMAIN results can use the normal ALPN path. Proxy and Unix socket requests also use the normal ALPN path.

Setting this option to 1, 2, or 3 forces that protocol. It does not set a version cap. Set http = 1 or http = 2 to opt out of automatic HTTP/3. Forced HTTP/2 with a plain http:// URL is only supported for gRPC requests, where fetch uses h2c (HTTP/2 over cleartext).

# Force HTTP/1.1
http = 1

# Force HTTP/2
http = 2

`tls`

Type: String Values: 1.2, 1.3 Default: 1.2

Specify the minimum TLS version to use. This is an alias for min-tls.

# Require TLS 1.2 or higher
tls = 1.2

# Require TLS 1.3 or higher
tls = 1.3

`min-tls`

Type: String Values: 1.2, 1.3 Default: 1.2

Specify the minimum TLS version to use.

min-tls = 1.2

`max-tls`

Type: String Values: 1.2, 1.3 Default: No maximum

Specify the maximum TLS version to use. Set min-tls and max-tls to the same value to require an exact TLS version.

# Require exactly TLS 1.2
min-tls = 1.2
max-tls = 1.2

`ech`

Type: String Values: auto, on, off Default: off

Enable Encrypted Client Hello (ECH). When set to auto, ECH is used if the server advertises it in DNS. When set to on, ECH is required.

See Encrypted Client Hello for details.

# Auto-detect ECH
ech = auto

# Require ECH
ech = on

`insecure`

Type: Boolean Default: false

Allow connections to servers with invalid TLS certificates.

# Allow invalid certificates (not recommended)
insecure = true

# Require valid certificates (default)
insecure = false

mTLS (Mutual TLS) Options

`cert`

Type: File path Default: None

Specify the path to a client certificate file for mTLS authentication. Use PEM format. If the file contains the certificate and private key, you do not need a separate key option.

# Client certificate for mTLS
cert = /path/to/client.crt

# Combined certificate and key file
cert = /path/to/client.pem

`key`

Type: File path Default: None

Specify the path to a client private key file for mTLS authentication. Use PEM format. This option is required if cert points to a certificate-only file.

# Client private key for mTLS
key = /path/to/client.key

mTLS Example Configuration:

# Global mTLS settings
cert = /path/to/default-client.crt
key = /path/to/default-client.key

# Host-specific mTLS for API server
[api.secure.example.com]
cert = /path/to/api-client.crt
key = /path/to/api-client.key
ca-cert = /path/to/api-ca.crt

Operation:

If you specify cert without key, fetch reads the private key from the certificate file.
If fetch does not find the private key, it reports an error.
TLS requests reject key without cert.
fetch does not support encrypted private keys.

`compress`

Type: String Default: auto

Control automatic compression negotiation and decompression.

# Request gzip, brotli, or zstd compression (default)
compress = auto

# Request one algorithm only
compress = br
# The brotli alias is also accepted:
compress = brotli
compress = gzip
compress = zstd

# Disable compression negotiation
compress = off

Output files receive decoded/decompressed bodies by default too. Use compress = off or --compress off for byte-for-byte downloads of .gz, .br, or .zst assets.

With compress = auto, fetch retries compressed SSE (text/event-stream) responses to GET and HEAD requests without Accept-Encoding. For other methods, it keeps the compressed response and gives a warning. For immediate SSE streaming with another method, set compress = off.

Session Options

`session`

Type: String Default: None

Set a named session to keep cookies for subsequent commands. fetch saves server cookies to disk. It sends the cookies in subsequent requests that use the same session name. Use only alphanumeric characters, hyphens, and underscores in the name.

# Global default session
session = default

# Per-host session names
[api.example.com]
session = api-prod

[staging.example.com]
session = api-staging

CLI --session flag overrides the config value. See CLI Reference for more details.

Request Options

`header`

Type: String (name:value format) Repeatable: Yes

Set custom HTTP headers. Repeat this option to set multiple headers.

# Single header
header = X-API-Key: your-api-key

# Multiple headers
header = X-Custom-Header: value1
header = Authorization: Bearer token
header = User-Agent: MyApp/1.0

`query`

Type: String (key=value format) Repeatable: Yes

Append query parameters to requests. Repeat this option to append multiple parameters.

# Single query parameter
query = api_version=2

# Multiple query parameters
query = page=1
query = limit=50
query = sort=name

`ignore-status`

Type: Boolean Default: false

HTTP 4xx/5xx responses exit nonzero by default. Set ignore-status = true to ignore HTTP status when choosing the exit code.

# Ignore HTTP status for exit code
ignore-status = true

# Use HTTP status for exit code (default)
ignore-status = false

Host-Specific Configuration

Use sections to configure different settings for specified hosts or domains:

# Global settings apply to all requests
timeout = 30
color = auto

# Settings for api.example.com
[api.example.com]
timeout = 10
header = X-API-Key: secret-key-for-api
query = version=2

# Settings for internal.company.com
[internal.company.com]
insecure = true
proxy = http://internal-proxy:8080
header = Authorization: Bearer internal-token

# Settings for slow.example.com
[slow.example.com]
timeout = 120
redirects = 0

Wildcard Subdomain Matching

Use the [*.domain.com] syntax to match all subdomains of a domain:

# Match any subdomain of example.com
[*.example.com]
header = X-API-Key: shared-key

# Match any subdomain of api.example.com (more specific)
[*.api.example.com]
header = X-API-Key: api-specific-key

# Exact match always takes priority
[admin.example.com]
header = X-API-Key: admin-key

Matching rules:

*.example.com matches api.example.com and a.b.example.com.
*.example.com does not match example.com itself
Exact matches always take priority over wildcard matches
When multiple wildcards match, the most specific (longest suffix) wins
Only one host config section is applied per request (no merging across sections)

Host Section Rules

Use the exact hostname, without the protocol or path, as the section name. Alternatively, use a wildcard pattern such as *.domain.com.
Duplicate host section names are rejected. Names are compared case-insensitively after trimming, so [API.example.com] and [api.example.com] are duplicates.
Scalar host-specific settings override global settings
Scalar command-line flags override both global and host-specific settings
List settings such as header, query, and ca-cert merge in order: global first, then the matched host section, then command-line flags

Configuration Examples

Basic Global Configuration

# Enable colored output and formatting
color = on
format = on

# Set reasonable timeouts
timeout = 30
redirects = 5

# Enable auto-update checks every 12 hours
auto-update = 12h

# Add common headers
header = User-Agent: fetch/1.0

API Development Configuration

# Global API settings
format = on
color = on
timeout = 10

# Development API
[api.dev.example.com]
header = X-API-Key: dev-key-here
header = X-Environment: development
query = debug=1

# Production API (more restrictive)
[api.example.com]
header = X-API-Key: prod-key-here
timeout = 30
redirects = 3

Enterprise/Corporate Configuration

# Corporate proxy settings
proxy = http://corporate-proxy.company.com:8080

# Internal services (allow self-signed certificates)
[internal.company.com]
insecure = true

# External APIs (strict security)
[external-api.vendor.com]
min-tls = 1.2
timeout = 60
header = X-Company-ID: company-identifier

Configuration File Validation

fetch validates configuration files when it loads them. It reports errors in this format:

config file '/home/user/.config/fetch/config': line 15: invalid option: 'invalid-option'

The tool reports these types of validation error:

Invalid option names
Invalid values for specified options, such as color = invalid
Malformed key=value pairs
Empty host section names []

Best Practices

Use host-specific sections for API keys and service-specific settings.
Set applicable timeouts to prevent requests from running too long.
Use global settings for common preferences such as color and formatting.
Keep configuration files secure. They can contain API keys.
Test configurations with dry-run mode: fetch --dry-run example.com.
Use comments to document complex configurations.
Enable automatic updates to get security and feature updates.

FilesExpand file tree

configuration.md

Latest commit

History

configuration.md

File metadata and controls

Configuration Guide

Configuration File Format

File Locations

Configuration Precedence

File Structure

Available Configuration Options

Auto-Update Options

auto-update

Output Control Options

copy

color / colour

format

image

pager

silent

timing

verbosity

sort-headers

Network Options

ca-cert

dns-server

proxy

connect-timeout

timeout

redirects

retry

retry-delay

http

tls

min-tls

max-tls

ech

insecure

mTLS (Mutual TLS) Options

cert

key

compress

Session Options

session

Request Options

header

query

ignore-status

Host-Specific Configuration

Wildcard Subdomain Matching

Host Section Rules

Configuration Examples

Basic Global Configuration

API Development Configuration

Enterprise/Corporate Configuration

Configuration File Validation

Best Practices

See Also

`auto-update`

`copy`

`color` / `colour`

`format`

`image`

`pager`

`silent`

`timing`

`verbosity`

`sort-headers`

`ca-cert`

`dns-server`

`proxy`

`connect-timeout`

`timeout`

`redirects`

`retry`

`retry-delay`

`http`

`tls`

`min-tls`

`max-tls`

`ech`

`insecure`

`cert`

`key`

`compress`

`session`

`header`

`query`

`ignore-status`