ScreenshotNeo

BlogHow-to

Using the cURL Command: A Practical Example

Learn how to use curl for GET, POST, JSON, headers, redirects, files, debugging, and website screenshots with runnable examples.

By the ScreenshotNeo team30 September 20269 min read

Using the cURL Command: A Practical Example

How do you use the cURL command? Start with a URL:

curl https://example.com

That command transfers the server response to your terminal. curl is a command-line tool for transferring data to or from a server using URLs, with options for request methods, headers, bodies, redirects, authentication, files, diagnostics, and more. This guide explains the most useful patterns, shows complete runnable examples, and covers the details that commonly cause confusing results.

The examples use the official curl syntax documented in the curl manual. Check your installed version before copying newer options:

curl --version
curl --help

1. The basic curl command

The general form is:

curl [options] URL

Arguments that are not recognized as options or option arguments are treated as URLs. You can request more than one URL in one command:

curl https://example.com https://example.org

By default, curl writes each response body to standard output. That is convenient for a short text response, but binary data such as an image should be written to a file.

curl -o page.html https://example.com
curl --output page.html https://example.com

The short and long forms are interchangeable. Long forms are often clearer in scripts; short forms are convenient interactively.

2. GET requests, redirects, and query parameters

Follow redirects

HTTP redirects are not followed automatically. Add -L (or --location) when a URL may redirect:

curl combines a URL with options, sends the request, and writes the response where you choose.
curl combines a URL with options, sends the request, and writes the response where you choose.
curl -L https://example.com/old-path

curl repeats the request when the server returns a Location header with a 3xx response. When following a redirect to a different origin, curl does not forward authorization and cookie credentials by default. That behavior limits accidental credential disclosure.

Add query parameters safely

For a GET request, use --get with one or more --data-urlencode options:

curl --get 'https://api.example.com/search' \
  --data-urlencode 'q=blue shoes' \
  --data-urlencode 'page=2'

This produces a URL similar to https://api.example.com/search?q=blue%20shoes&page=2. Quoting prevents the shell from interpreting spaces or the ampersand.

Without --get, -d normally changes an HTTP request to POST. This distinction matters:

# POST body
curl -d 'q=blue shoes' https://api.example.com/search

# GET query string
curl --get -d 'q=blue shoes' https://api.example.com/search

Inspect only response headers

Use -I (or --head) for a proper HEAD request:

curl -I https://example.com

Do not assume that -X HEAD configures every behavior needed for HEAD; the dedicated option is preferable.

3. Headers, form data, and JSON

Add request headers

-H (or --header) adds a header and can be repeated:

curl \
  -H 'Accept: application/json' \
  -H 'X-Request-ID: demo-123' \
  https://api.example.com/status

Header names are case-insensitive. Quote the whole argument when values contain spaces, punctuation, or shell metacharacters.

Submit form-style data

-d (or --data) sends data as an HTTP POST for HTTP(S), using application/x-www-form-urlencoded by default:

curl -d 'name=curl&purpose=example' https://example.com/form

Repeated data options are joined with an ampersand:

curl \
  -d 'name=curl' \
  -d 'purpose=example' \
  https://example.com/form

When data comes from a file, --data removes carriage returns, newlines, and null bytes. Use --data-binary when the exact bytes must be preserved:

curl --data-binary @payload.bin https://api.example.com/upload

Send JSON

On curl 7.82.0 and newer, --json is a shortcut that sends a body and sets JSON content negotiation headers:

curl --json '{"name":"curl","enabled":true}' \
  https://api.example.com/items

--json is equivalent to using binary data with Content-Type: application/json and Accept: application/json. It does not validate that the supplied text is valid JSON. On older versions, write the headers explicitly:

curl \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary '{"name":"curl","enabled":true}' \
  https://api.example.com/items

For a JSON file:

curl \
  -H 'Content-Type: application/json' \
  --data-binary @request.json \
  https://api.example.com/items

4. Authentication and sensitive values

Basic authentication can be supplied with -u:

curl -u "$API_USER:$API_PASSWORD" https://api.example.com/private

Bearer tokens are usually sent as an authorization header:

curl \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.example.com/private

Environment variables keep secrets out of shell history and source files. Avoid putting keys directly in commands copied into tickets or logs. When using -v, inspect output carefully because request headers can contain credentials.

5. Output files, status codes, and diagnostics

Save response bodies

curl -o response.json https://api.example.com/data
curl -O https://example.com/archive.zip

-o chooses an explicit filename. -O uses the filename from the URL path.

Show the HTTP status with the body

curl -sS -w '\nHTTP %{http_code}\n' \
  -o response.json \
  https://api.example.com/data

-sS hides the progress meter while retaining errors; -w prints transfer variables after completion.

Fail on HTTP errors

A completed transfer is not the same as a successful HTTP response. Without an error option, a 404 response body can still produce a zero exit status. Use --fail (or --fail-with-body when supported) in scripts:

curl --fail --silent --show-error \
  -o response.json \
  https://api.example.com/data

Check the process exit code in shell automation:

if curl --fail --silent --show-error -o response.json https://api.example.com/data; then
  echo "download succeeded"
else
  echo "download failed" >&2
  exit 1
fi

Debug a request

curl -v https://example.com

-v prints connection details, request headers, response headers, and TLS information. For a complete wire trace, use --trace trace.log; treat trace files as sensitive because they can include credentials and cookies.

6. A complete API request example

This script sends JSON, follows redirects, saves the response, prints the status, and fails on HTTP errors:

#!/usr/bin/env sh
set -eu

API_URL='https://api.example.com/v1/items'

curl --fail-with-body --silent --show-error --location \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${API_TOKEN:?set API_TOKEN first}" \
  --data-binary @item.json \
  --output response.json \
  --write-out '\nHTTP %{http_code}\n' \
  "$API_URL"

The dedicated options communicate intent: --location follows redirects, --data-binary preserves the request file, --output stores the body, and --write-out reports the status.

7. Shell quoting and URL edge cases

Quote URLs whenever they contain query strings, fragments, spaces, braces, brackets, or shell punctuation:

curl 'https://example.com/search?q=one&sort=recent'

The shell treats an unquoted & as a background operator. curl also supports URL globbing with braces and brackets. Disable it when those characters are literal:

curl --globoff 'https://example.com/files/[draft].txt'

For multiple unrelated URLs, list them separately. For a literal URL containing a newline or unusual byte, place it in a file and use a script that reads it safely rather than relying on shell expansion.

8. Website screenshots from the command line

curl can download any HTTP response, including an image generated by a screenshot service. A screenshot API is useful when a browser installation, rendering code, waiting logic, and cleanup rules would otherwise become part of your script.

A screenshot workflow can remove consent banners and other overlays before capture.
A screenshot workflow can remove consent banners and other overlays before capture.

Or skip the browser setup

ScreenshotNeo returns a clean PNG, JPEG, WebP, or PDF from one GET request. Its capture process accepts cookie and consent banners like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and lets you turn each step off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; the response identifies the result with X-Page-Verdict and X-Billed headers.

Here is a complete cURL request (see the ScreenshotNeo API documentation for all options):

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

The same request in Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

And in Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo includes full-page capture with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets plus custom viewports, retina scale, PDF paper sizes and margins, page ranges, custom CSS and JavaScript, clicks before capture, selector waits, delay or network-idle waits, ad and tracker blocking, custom headers, cookies, user agents and authorization, timezone and geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work, which helps when migrating.

An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. You get 1,000 screenshots per month free without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

9. Performance, reliability, and cost considerations

  • Keep requests explicit. Use timeouts in automation and save output to a known path. For screenshot calls, the service example uses a 90-second client timeout because page rendering can involve redirects and asynchronous assets.
  • Reduce unnecessary transfers. Use -I for header checks, request only required fields, and write binary responses directly to files.
  • Reuse cacheable results. ScreenshotNeo lets you choose a cache TTL. Cache hits are identified and cost nothing.
  • Separate diagnostics from output. Send progress and verbose information to a log while keeping the response body in a file.
  • Plan for failures. Combine --fail, bounded retries where appropriate, and an idempotent request design. Do not blindly retry non-idempotent POST operations.
  • Control screenshot scope. Full-page capture, lazy-image loading, custom waits, and PDF rendering can require more page work than a viewport image. Capture one CSS-selected element when that is all you need.
  • Understand billing. ScreenshotNeo bills only clean shots. Bot checks, blank pages, timeouts, failed loads, and cache hits are free, and each response reports whether it was billed.

10. Troubleshooting common curl errors

Symptom Likely cause Fix
URL appears truncated at & The shell interpreted the ampersand. Quote the URL or use --data-urlencode.
301/302 response instead of final content Redirects are not followed by default. Add -L; review credential behavior across hosts.
JSON endpoint returns 415 Missing or incorrect content type. Use --json, or add Content-Type: application/json.
Script succeeds on a 404 HTTP errors are being treated as ordinary bodies. Add --fail or --fail-with-body and check the exit code.
unknown option --json The installed curl is older than 7.82.0. Use explicit headers and --data-binary, or upgrade curl.
Binary output corrupts the terminal An image or archive was written to standard output. Use -o file or -O.
Credentials leak in logs -v or tracing printed authorization headers. Redact logs, use environment variables, and remove trace files after diagnosis.
Screenshot response is not an image The API returned an error or a page verdict. Inspect HTTP status and X-Page-Verdict/X-Billed; do not assume every body is an image.
Screenshot is incomplete Lazy assets or client-side rendering had not finished. Use full-page capture and a selector, delay, or network-idle wait; block problematic third-party resources if needed.

11. A practical checklist

  1. Run curl --version and confirm that your options exist.
  2. Quote URLs and data containing shell punctuation.
  3. Choose the request body deliberately: form data, JSON, or binary data.
  4. Add -L when redirects are expected.
  5. Use -I for HEAD, rather than only changing the method with -X.
  6. Use --fail in scripts and record the HTTP status.
  7. Save binary responses with -o or -O.
  8. Use -v temporarily, and protect trace output.
  9. For screenshots, verify verdict and billing headers before processing the file.

12. FAQ

Is curl only for GET requests?

No. It supports GET, POST, PUT, PATCH, DELETE, HEAD, uploads, downloads, and many protocol options. Prefer purpose-built options such as --data and --head when they express the operation directly.

What is the difference between -d and --data-binary?

Both send a request body. --data may strip newlines, carriage returns, and null bytes when reading a file; --data-binary preserves the bytes exactly.

Does --json validate JSON?

No. It sets convenient headers and sends the supplied text. Validate JSON separately if malformed input would be costly.

Why did curl return exit code zero for an HTTP error?

Transport completion and HTTP success are separate. Add --fail and inspect the status code.

Can curl render JavaScript?

curl transfers HTTP responses; it does not execute a browser page. For rendered screenshots, use a browser-based service such as ScreenshotNeo or maintain your own browser automation.

Where should I start with ScreenshotNeo?

Use the one-call endpoint shown above, then add viewport, full-page, wait, selector, PDF, or delivery options from the documentation. The free plan includes 1,000 shots each month without a card.