curl --resolve: Usage, Options & Common CI Errors
curl --resolve forces a hostname to a specific IP so you can test before DNS changes.
curl --resolve is how you smoke-test a host with the correct SNI and Host header but a hand-picked IP - invaluable for validating a new server before flipping DNS, or routing around a broken resolver in CI.
What it does
curl --resolve HOST:PORT:ADDR injects a fake DNS entry for a single request, so curl connects to ADDR while still sending the real Host header and TLS SNI for HOST. This lets a pipeline test a specific backend (e.g. a green deployment) before public DNS points at it.
Common usage
curl --resolve example.com:443:10.0.0.5 https://example.com/health
curl --resolve api.example.com:443:203.0.113.9 -fsS https://api.example.com/
# Equivalent for multiple ports / simpler syntax:
curl --connect-to example.com:443:10.0.0.5:443 https://example.com/
curl --resolve example.com:80:127.0.0.1 http://example.com/Options
| Flag | What it does |
|---|---|
| --resolve <host>:<port>:<addr> | Pin host:port to a specific IP |
| --connect-to <h1>:<p1>:<h2>:<p2> | Redirect connection to another host:port |
| -H "Host: ..." | Override the Host header (lower-level alternative) |
| --resolve <host>:<port>:[ipv6] | IPv6 target in brackets |
Common errors in CI
The port in --resolve must match the request port exactly - --resolve example.com:443:IP for an https:// URL; pinning :80 for an https request does nothing and curl falls back to real DNS. The address is literal (no second DNS lookup) so a hostname there is invalid - use an IP. Unlike -H "Host:", --resolve keeps the correct SNI, so it is the right tool for TLS hosts (a bare Host header override breaks certificate matching). Combine with -f so an HTTP error from the pinned backend fails the check.