[Curl](https://curl.se/) is a powerful command-line utility and underlying library (libcurl) used to transfer data across a wide range of network protocols, including HTTP, HTTPS, FTP, FTPS, SCP, SFTP, LDAP, MQTT, and more. It supports features like proxy support, user authentication, cookies, file uploads, and SSL connections, making it a go-to tool for developers, system administrators, and anyone working with web APIs or networked services. This article walks you through using `curl` to perform a variety of HTTP requests from your terminal. You’ll learn how to download files, set custom headers, work with different HTTP methods, handle redirects, send JSON payloads, authenticate with servers, and troubleshoot using verbose mode. Whether you're testing APIs or automating network operations, curl is a powerful tool to have in your workflow. ## The Short Answer Version If you just want a quick reference for common `curl` commands, here’s a compact list of essentials: ``` # Basic GET request $ curl https://example.com # Save output to file $ curl -o page.html https://example.com # Follow redirects $ curl -L http://example.com # Send POST form data $ curl -d "name=John&age=30" -X POST https://example.com # Send JSON payload $ curl -X POST -H "Content-Type: application/json" -d '{"name":"John"}' https://example.com # Add custom header $ curl -H "Authorization: Bearer " https://api.example.com # Basic auth $ curl -u user:pass https://example.com ``` ## Using Curl This section expands on the quick reference above and explains basic `curl` operations in more detail, including file downloads, protocol handling, and request formatting. These commands are commonly used for testing connectivity or fetching public web content. The basic syntax of the `curl` command is: ```console $ curl [options] ``` ### `curl` Command Options | Option | Description | | --------------- | ------------------------------------------------------------ | | `-o ` | Save output to the specified file | | `-O` | Save with the same name as the remote file | | `-C -` | Resume an interrupted download | | `-v` | Enable verbose mode (request/response debugging) | | `-s` | Silent mode, hides progress meter | | `-L` | Follow redirects | | `-I` | Fetch only response headers | | `-X ` | Set HTTP method (`GET`, `POST`, `DELETE`, etc.) | | `-d ` | Send POST form data | | `-H "

"` | Add custom headers (e.g., `Content-Type`, `Authorization`) | | `--user-agent` | Override the default User-Agent string | | `-u user:pass` | Send basic authentication credentials | | `-F` | Upload file using multipart form | | `--fail` | Exit with error on 4xx/5xx responses, suppresses body output | | `-w` | Output custom variables like time taken (`%{time_total}`) | ## Detailed Usage The following sections explain how each curl command works in more detail. You'll find examples, syntax breakdowns, and usage notes to help you understand what each option does and when to use it. These walkthroughs complement the quick reference section above for users who prefer step-by-step explanations. ### Download a Webpage To download a webpage and print its source code to the terminal. #### Command Syntax ```console $ curl ``` #### Example ```console $ curl https://www.example.com/index.html ``` ### Use FTP Protocol To retrieve a file using FTP. #### Command Syntax ```console $ curl ftp:/// ``` #### Example ```console $ curl ftp://ftp.example.com/public/readme.txt ``` ### Save Output to a File Save the downloaded output to a local file instead of printing it to the terminal. #### Command Syntax ```console $ curl -o $ curl -O ``` * `-o`: Save output with a custom filename. * `-O`: Save output using the remote filename. #### Example ```console $ curl -o localcopy.html https://example.com/index.html $ curl -O https://example.com/index.html ``` ### Resume an Interrupted Download If a download was interrupted (e.g., due to network issues), use this option to resume it from where it left off instead of restarting from scratch. #### Command Syntax ```console $ curl -C -O ``` * `-C -`: Resume download. * `-O`: Save using remote file name. #### Example ```console $ curl -C -O https://example.com/bigfile.zip ``` ### Enable Verbose Output Enable verbose output to debug request/response communication. #### Command Syntax ```console $ curl -v ``` * `-v`: Verbose mode. #### Example ```console $ curl -v https://example.com ``` ## Making HTTP Requests Curl provides a wide range of options to interact with web services. This section covers how to inspect headers, follow redirects, change HTTP methods, and customize request headers. ### Get Only Response Headers Fetch only the response headers of a URL. #### Command Syntax ```console $ curl -I ``` * `-I` or `--head`: Fetch headers only. #### Example ```console $ curl -I https://example.com ``` ### Follow Redirects Enable following of HTTP 3xx redirects. #### Command Syntax ```console $ curl -L ``` * `-L`: Follow redirects. #### Example ```console $ curl -L http://example.com ``` ### Change the HTTP Method Set a custom HTTP method using `-X`. #### Command Syntax ```console $ curl -X [METHOD] ``` * `-X`: Specify HTTP method (e.g., `GET`, `POST`, `DELETE`). #### Example ```console $ curl -X DELETE https://example.com/resource/123 ``` ### Add Custom Headers Use the `-H` flag to add one or more HTTP headers. #### Command Syntax ```console $ curl -H "Header-Name: value" ``` #### Example ```console $ curl -H "User-Agent: Mozilla/5.0" -H "Cache-Control: no-cache" https://example.com ``` ### Set a Custom User-Agent Use `--user-agent` to define the request’s User-Agent string. #### Command Syntax ```console $ curl --user-agent "[Agent String]" ``` #### Example ```console $ curl --user-agent "Mozilla/5.0 (Macintosh)" https://example.com ``` ### Send Form or JSON Data (POST) Use `curl` to send form-encoded or JSON data in HTTP POST requests. This is essential for interacting with REST APIs or submitting data to a server. #### Command Syntax ```console $ curl -d "" -X POST $ curl -X POST -H "Content-Type: application/json" -d '' ``` #### Example ```console $ curl -d "name=John&age=30" -X POST https://example.com $ curl -X POST -H "Content-Type: application/json" -d '{"name":"John"}' https://example.com ``` ### Basic Authentication When accessing resources protected by HTTP Basic Auth, use the `-u` option to include your credentials directly in the request. #### Command Syntax ```console $ curl -u : ``` #### Example ```console $ curl -u admin:secret https://example.com ``` ## Advanced Usage and Tips This section covers advanced curl patterns commonly used in scripts, automation, and API integrations. ??? note "Common Advanced Patterns" These advanced curl patterns are useful for scripting, performance testing, secure authentication, and API reliability. ### Exit on HTTP Errors (`--fail`) Make curl exit silently with a non-zero code when HTTP errors like 404 or 500 occur. This avoids printing error pages. #### Command Syntax ```console $ curl --fail ``` * `--fail`: Exit silently on HTTP errors (4xx, 5xx). #### Example ```console $ curl --fail https://example.com/missing-file ``` Use this in scripts to halt execution when a URL is unreachable or responds with an error. ### Measure HTTP Request Time (`-w`) Print the total time taken to complete a request. Useful for latency measurement and benchmarking. #### Command Syntax ```console $ curl -w "%{time_total}\n" -o /dev/null -s ``` * `-w`: Custom output after completion. * `%{time_total}`: Total transfer time. * `-o /dev/null`: Discard body. * `-s`: Silent mode to suppress progress. #### Example ```console $ curl -w "%{time_total}\n" -o /dev/null -s https://example.com ``` This helps measure API response time or network latency. ### Upload Files (`-F`) Upload files using a multipart form submission. #### Command Syntax ```console $ curl -F "key=@filename.ext" ``` * `-F`: Send form field with file. * `@filename.ext`: Reads the file from local disk. #### Example ```console $ curl -F "file=@report.pdf" https://example.com/upload ``` Use `-F` for uploading files as part of a form. Use `--data-binary` if you want to send raw files. ### Authenticate with Bearer Token Use bearer tokens to access secured APIs (e.g., OAuth2 access tokens). #### Command Syntax ```console $ curl -H "Authorization: Bearer " ``` * `-H`: Set a custom header. * `Authorization: Bearer`: Required for most modern APIs. #### Example ```console $ curl -H "Authorization: Bearer abc123" https://api.example.com/data ``` This is required when accessing private endpoints on services like GitHub, Stripe, or cloud APIs. ### Quiet or Debug Output (`-s`, `-v`) Adjust output visibility depending on your need. #### Silent Mode Syntax ```console $ curl -s ``` * `-s`: Suppress progress bar and errors. #### Verbose Mode Syntax ```console $ curl -v ``` * `-v`: Show full request and response details. #### Example ```console $ curl -s https://example.com ``` ```console $ curl -v https://example.com ``` Use `-s` for scripts and logging. Use `-v` when debugging failures or testing headers. ## Conclusion Curl is an essential tool for developers and system administrators who need to interact with web servers, APIs, and remote resources from the command line. This article covered both quick-use examples and detailed explanations for common `curl` operations such as downloading files, handling headers, sending data, and authenticating requests. For further exploration, refer to the [official curl documentation](https://curl.se/docs/) or [man page](https://man7.org/linux/man-pages/man1/curl.1.html) to discover protocol-specific features, scripting tricks, and advanced usage patterns.

Articles Tagged: Linux Commands