curl --resolve: Override DNS for a Host
--resolve lets you point a hostname at a chosen IP for one command, TLS and all.
When you need to hit a specific backend or test before DNS cuts over, --resolve overrides resolution while keeping the right Host header and certificate name.
What it does
--resolve <host:port:addr> tells curl to use the given IP address for that hostname and port, bypassing DNS. Unlike editing /etc/hosts, it is scoped to the single command and lets you keep the real hostname so the Host header and TLS SNI/cert verification still use it. You can repeat it for multiple hosts, and use a wildcard port with *.
Common usage
curl --resolve api.example.com:443:10.0.0.5 https://api.example.com/health
curl --resolve api.example.com:443:10.0.0.5 \
--resolve api.example.com:80:10.0.0.5 https://api.example.com/x
curl --resolve '*:443:10.0.0.5' https://api.example.com/xFlags
| Flag | What it does |
|---|---|
| --resolve <host:port:ip> | Map a host:port to an IP, keep the real hostname |
| --resolve <host:port:-> | Clear a previous override for that host |
| --connect-to | Redirect connections without changing Host/SNI |
| -H 'Host: ...' | Set Host only (no TLS SNI, less safe) |
In CI
Use --resolve to smoke-test a new backend IP before flipping DNS, since TLS verification still validates the real certificate name. It is cleaner and safer than -H 'Host:' (which breaks SNI) or editing /etc/hosts (which is global and persists for other tools).
Common errors in CI
curl: (6) Could not resolve host means DNS failed and no --resolve covered it; add the mapping. curl: (7) Failed to connect after a --resolve means the IP is wrong or unreachable, not a DNS problem.