Curl Command Guide: Syntax, Options & Examples

This guide explains the curl command, a tool for transferring data to or from a server using URLs, and shows you how to use its most common options. You will learn the basic syntax, see practical examples for HTTP requests, and understand how to handle output, headers, and errors. By the end, you will be able to read and write curl commands for everyday tasks like testing APIs and downloading files.

What Is curl?

curl (short for “client URL”) is a command-line utility that uses URL syntax to transfer data. It supports many protocols, including HTTP, HTTPS, FTP, SFTP, SCP, and more. Developed by Daniel Stenberg, it has been around since 1997 and is now installed by default on most Linux distributions, macOS, and Windows 10 and later. Its name is often written as cURL, but the official project spells it curl.

curl is not a programming language or a web browser; it is a tool that sends requests and receives responses. You can use it to download files, test REST APIs, upload data, check headers, and debug network connections. Because it is scriptable, it is a favorite among developers and system administrators.

Basic Syntax

The simplest form of a curl command is:

curl [options] [URL]

For example, to fetch the homepage of example.com and print it to the terminal:

curl https://example.com

By default, curl writes the response body to standard output. If you want to save it to a file, use the -o option (lowercase) followed by a filename, or -O (uppercase) to save with the same name as the remote file:

curl -o homepage.html https://example.com
curl -O https://example.com/file.zip

To see the HTTP headers along with the body, use -i (include). To see only the headers, use -I (head request) or --head:

curl -I https://example.com

Common Options and Their Uses

Here are the most frequently used curl options, grouped by purpose:

Output control: -o (write to file), -O (use remote filename), -s (silent, hides progress and errors), -S (show errors even with -s), -v (verbose, shows request and response details).
HTTP methods: -X (specify method, e.g., -X POST), -d (send data in POST body), -F (send form data, including file uploads).
Headers: -H (add a custom header, e.g., -H "Content-Type: application/json").
Authentication: -u (username:password for basic auth), -k (allow insecure SSL connections, not recommended).
Follow redirects: -L (re-request the URL if the server responds with a 3xx redirect).
Download resume: -C - (continue a previous download from where it stopped).

For example, to send a JSON POST request with a custom header:

curl -X POST -H "Content-Type: application/json" -d '{"name":"John","age":30}' https://api.example.com/users

Working with HTTP Requests

curl is often used to test APIs. The -d option sends data as the request body, usually with a POST method. If you use -d without -X, curl automatically uses POST. For a GET request with query parameters, you can just include them in the URL:

curl "https://api.example.com/search?q=curl&limit=10"

To send a file as the request body, use --data-binary @filename or -d @filename. The @ symbol tells curl to read the content from a file:

curl -X PUT -d @data.json https://api.example.com/resource/1

For multipart form data (like a web form with file upload), use -F:

curl -F "username=johndoe" -F "avatar=@photo.jpg" https://example.com/upload

Handling Output and Errors

By default, curl prints a progress meter to the terminal. In scripts, you usually want to suppress it with -s (silent). However, -s also hides error messages, so combine it with -S to show errors:

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

To see the full request and response (including headers and TLS handshake), use -v. This is invaluable for debugging:

curl -v https://example.com

curl returns an exit code: 0 means success, non-zero indicates an error (e.g., 6 could not resolve host, 7 failed to connect, 28 timeout). You can check the exit code in a shell script with $?.

To limit the time curl spends on a request, use --max-time (total time) or --connect-timeout (connection only):

curl --max-time 10 https://example.com

Common Problems and Solutions

Here are typical issues users face and how to resolve them:

SSL certificate errors: If you get “certificate verify failed”, the server’s certificate is not trusted. You can bypass with -k, but it is safer to update your CA certificates or fix the server.
Redirects not followed: If you get a 301/302 response but no content, add -L to follow redirects automatically.
Data not sent as expected: Remember that -d sends data as application/x-www-form-urlencoded by default. For JSON, set the Content-Type header explicitly.
Progress meter cluttering output: Use -s to silence it, but keep -S to see errors.
Cannot upload file: Ensure the path is correct and use @ before the filename in -d or -F.

A common misconception is that curl is only for HTTP. In reality, it supports many protocols. For instance, you can download an FTP file with:

curl ftp://ftp.example.com/file.txt -u username:password

curl vs. wget

Both curl and wget are command-line downloaders, but they have different strengths. wget is simpler for recursive downloads and mirroring websites, while curl offers more control over requests and supports more protocols. curl is better for API testing because it lets you set headers, methods, and data. wget is often preferred for downloading entire sites. For most one-off file downloads, either works, but curl is more versatile in scripts.

Security and Best Practices

When using curl, keep these points in mind:

Never pass passwords in the command line if you can avoid it, because they may be visible in process lists. Use --netrc or environment variables.
Avoid using -k (insecure) in production; it disables SSL verification and exposes you to man-in-the-middle attacks.
Be careful with -d containing shell special characters; quote the data properly or use a file.
When downloading files, verify the checksum if the provider offers one.
Use --max-time to prevent curl from hanging indefinitely.

curl is a powerful tool, but with power comes responsibility. Always understand what a command does before running it, especially if it involves sending data to a remote server.

Frequently Asked Questions

How do I save a curl output to a file?

Use -o filename to save the response body to a file, or -O to save with the remote file’s name. For example, curl -o page.html https://example.com saves the HTML to page.html.

How do I send a POST request with curl?

Use -X POST and -d 'data'. For JSON, add -H "Content-Type: application/json". Example: curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' https://api.example.com/endpoint.

How do I see the HTTP status code?

Use -w "%{http_code}" to print the status code after the response. For example, curl -s -o /dev/null -w "%{http_code}" https://example.com prints only the status code (like 200).

Why does curl return an empty response?

Possible reasons: the server returns a redirect (use -L), the request method is wrong (try -X GET), or the server requires specific headers (add with -H). Check with -v to see the full exchange.

How do I download a file with a different name?

Use -o newname.ext to save the file under a different name. For example, curl -o myfile.zip https://example.com/download.zip saves the content as myfile.zip.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →