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.
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.
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.
$ curl -s -o /dev/null -w '%{http_code} %{url_effective}\n' -L http://example.com 200 https://www.example.com/
Syntax
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
-for--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:
-dalone 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,--netrcor read tokens from variables in a here-document. curl URL | bashexecutes 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:IPpins a name to an address;--proxyand thehttps_proxyvariable choose a proxy. - Compared with wget:
curlis stronger at APIs, headers and uploads;wgetis stronger at recursive downloads.
Related
wget,ssh,openssl,nc,ping- Lessons: Network Troubleshooting, Web Server Setup