Skip to content
Tutorials Center
My learning

Topics

Linux Command Reference ยท Networking

Linux curl command

Reference for the Linux curl command: fetch URLs, send POST and JSON bodies, set headers, follow redirects, save files, show status codes, and use it in scripts.

curl transfers data to or from a server using a URL. It speaks HTTP and HTTPS first and foremost, but also FTP, SFTP, SMTP, IMAP and more. By default it writes the response body to standard output, which makes it a natural part of pipelines and shell scripts.

You will use it to call APIs, download files, check headers and status codes, and debug web servers.

Terminal
curl https://example.com
curl -fsSL -o file.tar.gz https://example.com/file.tar.gz
curl -X POST -H 'Content-Type: application/json' -d '{"a":1}' https://api.example.test/items

Try it

curl is not installed in our sandbox, and the sandbox has no network, so requests are read-only. The runnable example prepares the pieces a script needs: building a command in an array and reading a status code from a saved header.

Bash Build a curl command safely and read a status line

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Read-only: showing only the status code of a request and following redirects.

CONSOLE
$ curl -s -o /dev/null -w '%{http_code} %{url_effective}\n' -L http://example.com
200 https://www.example.com/

Syntax

Terminal
curl [OPTIONS] URL...
Option Description
-s, -S Silent (no progress meter); -S still shows errors. Use -sS together.
-f, --fail Exit with an error on HTTP 400 and above instead of printing the error page.
-L Follow redirects.
-o FILE, -O Save to FILE; -O uses the remote file name.
-X METHOD Set the request method. Often unnecessary: -d already implies POST.
-d DATA Send a body (application/x-www-form-urlencoded unless you set a header). @file reads from a file.
--data-urlencode Encode a form value for you.
-H "Name: value" Add a request header.
-I Send HEAD and show headers only.
-i Include response headers in the output.
-u user:pass Basic authentication.
-w FORMAT Print information after the transfer, such as %{http_code} or %{time_total}.
--max-time SEC Overall time limit.
--retry N Retry on transient errors.
-k Skip certificate verification (do not use in production).
-v Verbose: request and response headers on stderr.
-F name=@file Multipart form upload.
-C - Resume a download.

Returns: 0 on success. Common failures: 6 (cannot resolve host), 7 (connection refused), 22 (HTTP error with -f), 28 (timeout), 35 and 60 (TLS problems).

Usage notes

  • HTTP errors are not curl errors. A 404 or 500 still exits 0 unless you add -f or --fail-with-body. Scripts should check one of them, or print %{http_code}.
  • A good scripting default is curl -fsSL: fail on errors, silent but showing errors, follow redirects.
  • Quote URLs containing & or ?, or the shell will cut the command: curl 'https://x.test/?a=1&b=2'.
  • JSON bodies: -d alone sends the wrong content type, so add -H 'Content-Type: application/json'. Wrap the JSON in single quotes.
  • Secrets passed on the command line are visible in the process list. Use -K file, --netrc or read tokens from variables in a here-document.
  • curl URL | bash executes unreviewed code from the network. Download to a file, read it, then run it.
  • Timeouts: without --max-time (and --connect-timeout), a stalled server can hang a script forever.
  • Proxy and DNS testing: --resolve host:443:IP pins a name to an address; --proxy and the https_proxy variable choose a proxy.
  • Compared with wget: curl is stronger at APIs, headers and uploads; wget is stronger at recursive downloads.