cURL Debugging, Performance, and Scripting

Tracing, DNS overrides, proxies, protocol selection, config files, timeouts, and script-friendly curl patterns.

View
StandardDetailedCompact
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all

Debugging and Diagnostics

Tracing, proxies, DNS overrides, timeouts, and connection tuning.

Limit connect time

Fail if the connection cannot be established quickly.

bashANYcurltimeoutnetwork
bash
curl --connect-timeout 5 https://example.com

Separate connect timeout from overall max time.

Limit total transfer time

Abort the request after a fixed total duration.

bashANYcurltimeoutautomation
bash
curl --max-time 20 https://example.com

Good for scripts that must not hang forever.

Override DNS resolution

Map a hostname and port to a specific IP address.

bashANYcurldnstesting
bash
curl --resolve example.com:443:127.0.0.1 https://example.com

Great for testing a site before DNS changes propagate.

Redirect one host:port to another

Change where curl connects without changing the URL's host name.

bashANYcurldnsrouting
bash
curl --connect-to example.com:443:staging.example.net:8443 https://example.com

Useful for staging, canaries, and origin testing.

Use an HTTP proxy

Send requests through an HTTP proxy.

bashANYcurlproxynetwork
bash
curl -x http://proxy.example.com:8080 https://example.com

Use `-x` / `--proxy` for HTTP, HTTPS, SOCKS, and related proxies.

Use a SOCKS5 proxy

Route a request through a SOCKS5 proxy.

bashANYcurlproxysocks5
bash
curl --socks5 localhost:1080 https://example.com

Useful for debugging network routes or tunneled access.

Force HTTP/2

Ask curl to use HTTP/2 where supported.

bashANYcurlhttp2protocol
bash
curl --http2 https://example.com

Useful when testing protocol behavior and ALPN negotiation.

Try HTTP/3

Attempt an HTTP/3 transfer when curl build and server support it.

bashANYcurlhttp3protocol
bash
curl --http3 https://example.com

HTTP/3 support depends on the curl build and backend support.

Force IPv4

Resolve and connect using IPv4 only.

bashANYcurlipv4network
bash
curl -4 https://example.com

Helpful for troubleshooting mixed IPv4/IPv6 environments.

Force IPv6

Resolve and connect using IPv6 only.

bashANYcurlipv6network
bash
curl -6 https://example.com

Useful when validating IPv6 reachability.

Config Files and Scripting

Reusable config files, shell integration, and script-safe patterns.

Use a curl config file

Load options from a config file.

bashANYcurlconfigscripting
bash
curl -K request.curl

Config files are useful for long commands and repeatable workflows.

Example curl config file

Store headers, auth, and URL in a reusable config file.

iniANYcurlconfigscripting
ini
url = 'https://api.example.com/v1/items'
header = 'Accept: application/json'
header = 'Authorization: Bearer TOKEN'
silent
show-error

A `.curlrc` or request-specific config file can keep complex commands readable.

Use --json shortcut

Send JSON body with curl's JSON convenience option.

bashANYcurljsonapi
bash
curl --json '{"name":"demo"}' https://api.example.com/v1/items

`--json` is a convenience option that sets JSON-related defaults.

Use output variables

Name outputs using transfer variables.

bashANYcurlglobbingoutput
bash
curl -o '#1-#2.txt' 'https://example.com/{dev,prod}/{a,b}'

Output templates pair nicely with URL globbing.

Script-safe status check

Capture HTTP status for shell scripts.

bashANYcurlscriptingstatus
bash
status=$(curl -s -o /tmp/resp.json -w '%{http_code}' https://api.example.com/health)
[ "$status" -eq 200 ] && echo ok || echo fail

A common automation pattern: body to file, status to shell variable.

Parse JSON with jq

Pipe JSON output to jq for filtering.

bashANYcurljqjson
bash
curl -s https://api.github.com/repos/curl/curl | jq '.stargazers_count'

curl focuses on transfer; pair it with `jq` for JSON processing.

Send request body from a file

Post the contents of a local file as the request body.

bashANYcurlpostfile
bash
curl -X POST -H 'Content-Type: application/json' --data @payload.json https://api.example.com/items

Prefix a filename with `@` for `--data` to read from file.

Bypass proxy for specific hosts

Skip proxy use for selected domains or hosts.

bashANYcurlproxynetwork
bash
curl --noproxy localhost,127.0.0.1 https://localhost:8443

Helpful in mixed environments where a proxy is configured globally.

Recommended next

No recommendations yet.