curl: HTTP from the Shell

The universal HTTP/{,S}, FTP, ... client

curl sends one HTTP request and prints the response. It is the cli tool every API doc shows examples in. curl https://example.com dumps the HTML.

Daily flags

-L — follow redirects.
-sS — silent but show errors. Pipe-friendly default.
-o file — write to file. -O uses the URL's filename.
-X POST / -X PUT — change method.
-H 'Header: Value' — add a header. Repeat for many.
-d 'data' — POST body (form-encoded).
--data-urlencode 'key=value with spaces' — URL-encode the body.
--data @body.json — read body from a file.
-u user:pass — basic auth.
-i / -I — include / only response headers.
-w '%{http_code}\n' — print custom output (status, time, etc.).

POST a JSON body

curl -sS https://api.example.com/items \
  -H 'Authorization: Bearer ${TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{"name":"pippa","qty":3}'

GET with auth, parse with jq

curl -sS -H 'Authorization: token ghp_xxx' \
  https://api.github.com/user/repos | jq '.[].name'

Download a big file with progress

curl -L -o ubuntu.iso --progress-bar https://...

Health check one-liner

curl -sS -o /dev/null -w '%{http_code} %{time_total}s\n' https://api

Don't paste curl from random tutorials

Pipe-to-shell installers (curl ... | bash) execute everything the server sends. If the server is compromised, you ran their code. Save to a file, read it, then run.

Code

Real API call patterns·bash

# GitHub user repos (no auth, public)
curl -sS https://api.github.com/users/cli/repos | jq '.[].full_name' | head
# Health check
curl -sS -o /dev/null -w 'http=%{http_code} dns=%{time_namelookup}s total=%{time_total}s\n' \
  https://api.openai.com
# POST JSON from file
curl -sS -X POST https://example/api \
  -H 'Content-Type: application/json' \
  --data @body.json