ScreenshotNeo

BlogHow-to

How to Use cURL to Show Response Headers

Learn when to use curl -I, -i, -D, -v and -w to inspect, save and automate HTTP response headers.

By the ScreenshotNeo team30 September 20268 min read

How to Use cURL to Show Response Headers

Use curl -I https://example.com when you want response headers without downloading the response body. Use curl -i https://example.com when you want headers and the normal response body together. Use curl -D headers.txt https://example.com to save headers separately, and use curl -v when you need the complete request, response and connection trace.

The right command depends on whether you need a HEAD or GET request, where output should go, and how much diagnostic detail you need. This guide explains every practical method, shows copy-and-run examples, covers redirects and scripts, and explains common failures.

Quick reference

Goal Command Request Body returned?
Headers only curl -I https://example.com HEAD No
Headers plus body curl -i https://example.com GET Yes
Save headers to a file curl -D headers.txt https://example.com GET by default Yes
Headers on screen, body in a file curl -D - https://example.com -o body.html GET Saved to file
Protocol diagnostics curl -v https://example.com GET by default Yes, unless redirected
Status or selected headers in automation curl -sS -o /dev/null -w '%{http_code}\n' https://example.com GET by default Discarded

The curl manual defines -I as --head, -i as --show-headers, and -D as --dump-header. See the official curl man page and the curl project’s response-header guide.

Choose HEAD for headers only, or GET when you need the response body too.
Choose HEAD for headers only, or GET when you need the response body too.

1. Show headers only with -I or --head

-I makes curl issue an HTTP HEAD request and print the response headers without the response body:

curl -I https://example.com

# Long option
curl --head https://example.com

This is useful for checking status codes, redirects, content type, cache directives, server dates, entity tags and content length before downloading a large resource. A typical response might include lines such as HTTP/2 200, content-type and cache-control.

Follow redirects

Many sites redirect HTTP to HTTPS or redirect one URL to another path. Add -L to inspect the final response:

curl -I -L https://example.com

With redirects enabled, curl can print a header block for each hop. That is useful when you need to see where a redirect chain starts and ends. If you only care about the final destination, inspect the last block.

When HEAD is not supported

Some servers deny HEAD even though GET works. The curl documentation calls this a server-side annoyance rather than a curl parsing problem. Retry with a normal GET and include its headers:

curl -i https://example.com

If you want to avoid writing the body to your terminal, discard it while retaining headers:

curl -i -o /dev/null https://example.com

On Windows Command Prompt, use NUL instead of /dev/null. In PowerShell, $null is commonly used as the destination for commands that support it, although curl’s native options remain the most portable choice.

2. Show headers and body with -i

Use -i, also written --show-headers, when you want the regular response body preceded by the response headers:

curl -i https://example.com
curl --show-headers https://example.com

This sends a normal GET unless you select another method. The headers and body share the output stream, so the result is convenient for a quick terminal inspection but inconvenient for HTML or JSON processing.

Keep the body out of the terminal

Send the body to a file and leave the headers in standard output:

curl -i https://example.com -o body.html

That command still displays headers and writes the body to body.html. If you need headers in a separate file as well, use -D.

3. Save response headers with -D

-D (or --dump-header) writes received headers to a file while curl handles the body normally:

curl -D headers.txt https://example.com -o body.html

Now headers.txt contains the HTTP status line and response fields, while body.html contains only the body. This separation is the safest pattern for scripts that must parse a document independently from transport metadata.

Use a hyphen as the filename to write dumped headers to standard output:

curl -D - https://example.com -o body.html

When redirects are followed with -L, the dump can contain multiple header blocks. Preserve the file if you need to audit every hop.

Append or overwrite?

Each transfer writes the dump file according to curl’s normal file-output behavior. If you are collecting multiple samples, choose unique filenames or explicitly combine files after each command. Do not assume a dump file represents only the final response when redirects or authentication handshakes occur.

4. Use verbose mode for full diagnostics

-v is for protocol debugging rather than simple header viewing:

curl -v https://example.com

Verbose output marks sent headers with >, received headers with <, and other connection diagnostics with *. It can reveal DNS resolution, TCP or TLS negotiation, proxy use, request headers, redirects and connection reuse.

Because verbose output can include credentials or cookies that you supplied, review it before sharing logs. For routine header capture, prefer -i or -D.

5. Extract status and headers for scripts

Use -sS for quiet operation with errors preserved, -o to control the body destination, and -w (also called --write-out) to print structured values after the transfer:

# Status code only
curl -sS -o /dev/null -w '%{http_code}\n' https://example.com

# Status, content type and total time
curl -sS -o /dev/null -w 'status=%{http_code} type=%{content_type} time=%{time_total}\n' https://example.com

Current curl manuals document %{header{name}} for a selected response header and header_json for a JSON object containing response headers from the most recent transfer:

curl -sS -o /dev/null -w 'server=%{header{server}}\n' https://example.com
curl -sS -o /dev/null -w '%{header_json}\n' https://example.com

Header names are case-insensitive. A missing header may produce an empty value, so scripts should handle that case. Keep the -w format on standard output and send the body elsewhere to avoid mixing machine-readable output with HTML or binary data.

6. Request headers versus response headers

Response headers come from the server. Request headers are the fields curl sends. To inspect both, use verbose mode:

curl -v -H 'Accept: application/json' https://api.example.com/data

The > lines show the request, including your custom Accept field; the < lines show the server response. The -i option does not show the request headers.

7. Practical combinations

Check a URL without following redirects

curl -I https://example.com

Inspect every redirect

curl -I -L https://example.com

Capture headers and a binary file

curl -D image.headers https://example.com/image.png -o image.png

Inspect a JSON API response

curl -i -H 'Accept: application/json' https://api.example.com/items

Send authentication without exposing it in a shared command history

curl -sS -D response.headers -H 'Authorization: Bearer YOUR_TOKEN' https://api.example.com/items -o response.json

Use environment variables or a credential helper in production. Never paste real bearer tokens into tickets or verbose logs.

8. Common errors and fixes

Symptom Likely cause Fix
curl: (6) Could not resolve host DNS failure or a malformed URL. Check spelling, scheme and DNS configuration. Quote URLs containing shell characters.
curl: (7) Failed to connect Host, port, firewall or proxy is unreachable. Verify the port, proxy variables and network route. Use -v for connection details.
TLS certificate error The certificate is expired, mismatched or untrusted locally. Fix the certificate chain or local trust store. Avoid -k except for controlled debugging.
-I returns 405 or 403 The server rejects HEAD. Use curl -i or curl -i -o /dev/null with GET.
Only the final redirect is visible Redirect following was enabled and earlier blocks were overlooked. Use -I -L and inspect each status block, or remove -L to inspect the first response.
Headers are mixed with JSON or HTML -i writes both streams together. Use -D headers.txt -o body.json for separate files.
Script receives unexpected progress text Progress output was not suppressed. Use -sS and reserve -w for the values your script needs.
Header value appears empty The field is absent, duplicated, or generated only on another redirect hop. Use -v or -D to inspect all blocks and handle missing values.

9. Performance, reliability and security notes

  • Choose HEAD carefully: HEAD usually avoids transferring a body, but server behavior and middleware can differ from GET. Use GET when you need to validate the actual representation.
  • Do not download large bodies accidentally: combine -D with -o, or use -I where the server supports it.
  • Set time limits in automation: add options such as --connect-timeout 10 and --max-time 90 so a stalled endpoint does not block a job indefinitely.
  • Make retries deliberate: --retry 3 --retry-all-errors can help transient failures, but retries are not automatically safe for every non-idempotent request. For header checks and GET requests, retries are generally easier to reason about.
  • Preserve evidence: save -D output with a timestamp and URL when debugging cache or redirect behavior.
  • Protect secrets: verbose traces can expose authorization headers, cookies and query-string tokens. Restrict log permissions and redact before sharing.
  • Interpret cache fields carefully: etag, last-modified, age and cache-control describe caching policy; they do not prove that every intermediary used the same cache.
A rendered-page capture can remove consent banners and overlays before the image is returned.
A rendered-page capture can remove consent banners and overlays before the image is returned.

10. A repeatable header-inspection checklist

  1. Start with curl -I URL for a fast HEAD check.
  2. If HEAD fails or you need the real response, retry with curl -i URL.
  3. Add -L when redirects matter.
  4. Use -D headers.txt -o body.file when output must be processed.
  5. Use -v only when request, TLS or connection details are needed.
  6. Use -w for stable values consumed by scripts.
  7. Set timeouts and redact secrets in automated logs.

Or skip the browser setup

If your next step is capturing a rendered webpage rather than inspecting a raw HTTP response, ScreenshotNeo provides a single screenshot API request. The API returns PNG, JPEG, WebP or PDF, and its response includes X-Page-Verdict and X-Billed headers so a caller can see whether the page was cleanly captured and billed.

For a runnable request, see the ScreenshotNeo documentation:

curl -G 'https://api.screenshotneo.com/v1/shot' -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get('https://api.screenshotneo.com/v1/shot', params={'access_key': 'YOUR_API_KEY', 'url': 'https://stripe.com'}, timeout=90)
open('shot.webp', 'wb').write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Before capture, ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and the response identifies the result. It also provides an MCP server with take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients.

The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.

FAQ

What is the difference between curl -I and curl -i?

-I sends HEAD and prints headers only. -i performs the normal transfer and places response headers before the body.

How do I save only headers?

Use curl -D headers.txt URL -o /dev/null. The dump file receives headers and the body is discarded.

Can curl print one response header?

Use -w '%{header{name}}\n' with a current curl version, or save headers with -D and parse them in your script.

Why are there several status lines?

Redirects, proxy responses or authentication handshakes can create multiple response blocks. Inspect with -v or -D, and identify the block relevant to your request.

Should I use verbose output in production?

Usually no. Prefer -sS, -D and -w because verbose logs can contain credentials, cookies and other sensitive request details.