Curl
About
curl is a command-line tool used to transfer data to or from a server using various internet protocols. It is widely used by developers to test REST APIs, download files, and simulate client requests.
It is short for "Client URL" and supports protocols like HTTP, HTTPS, FTP, SFTP, and more. In API development, curl is commonly used to send HTTP requests and inspect server responses.
Why Use curl?
To test API endpoints from the terminal
To simulate real HTTP requests (GET, POST, PUT, DELETE)
To send custom headers, payloads, or authentication tokens
To debug issues like authentication failures or incorrect responses
Basic Syntax
curl [options] [URL]Curl Options
-X or --request <METHOD>
Specifies the HTTP method (GET, POST, PUT, DELETE, etc.)
-H or --header <HEADER>
Adds a custom header (e.g., Content-Type, Authorization)
-d or --data <DATA>
Sends data in the body (used with POST, PUT, etc.)
--data-raw <DATA>
Sends raw, unprocessed data
--data-urlencode <DATA>
Sends URL-encoded data
-F or --form <KEY=VALUE>
Sends form data, including file uploads (multipart/form-data)
-u or --user <user:password>
Uses basic authentication
-o or --output <file>
Saves the response body to a file
-O
Saves the file using the remote file name
-i or --include
Includes response headers in the output
-I or --head
Sends a HEAD request (returns headers only)
-v or --verbose
Prints detailed info for debugging (request/response, SSL handshake, etc.)
-s or --silent
Hides progress bar and error messages
-S or --show-error
Shows error even when --silent is used
-L or --location
Follows redirects (3xx responses)
-k or --insecure
Ignores SSL certificate validation (not recommended in production)
--compressed
Requests a compressed response (e.g., gzip)
--http1.1, --http2, --http3
Forces use of specific HTTP protocol versions
--url <URL>
Specifies the URL explicitly (used in scripts)
--max-time <seconds>
Sets a timeout for the entire request
--connect-timeout <seconds>
Sets timeout for connection phase only
--retry <n>
Automatically retries the request up to n times
-e or --referer <URL>
Sets the Referer header
-A or --user-agent <string>
Sets a custom User-Agent header
--cert <file>
Uses a client certificate (for mTLS)
--key <file>
Specifies the private key file for --cert
--cacert <file>
Uses a custom CA certificate file
--cookie <data>
Sends cookies with the request
--cookie-jar <file>
Stores received cookies into a file
--trace <file>
Logs a full trace of the request/response (headers + body)
--trace-ascii <file>
Logs trace in a human-readable format
--fail
Fails silently on HTTP errors (no body output on 400/500)
Common curl Commands
1. GET Request (default method)
curl https://api.example.com/usersSends a GET request to fetch data.
2. POST Request with JSON Body
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"Alice","email":"[email protected]"}'-Xspecifies the HTTP method (POST)-Hadds a header-dsends data in the request body
3. PUT Request
curl -X PUT https://api.example.com/users/123 \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]"}'Used to update existing data.
4. DELETE Request
curl -X DELETE https://api.example.com/users/123Deletes a resource by ID.
5. Custom Headers
curl https://api.example.com/data \
-H "Authorization: Bearer <token>" \
-H "Accept: application/json"Adds headers like auth tokens and Accept types.
6. Form Submission (application/x-www-form-urlencoded)
curl -X POST https://api.example.com/login \
-d "username=admin&password=secret"Mimics a form submission.
7. File Upload
curl -X POST https://api.example.com/upload \
-F "file=@path/to/file.jpg"Uses multipart/form-data for uploading files.
8. Save Response to File
curl https://example.com/image.jpg -o image.jpgDownloads and saves the file.
9. View Response Headers
curl -I https://api.example.comShows HTTP headers only, without the response body.
10. Verbose Output (for debugging)
curl -v https://api.example.comPrints detailed request/response information, including headers and connection steps.
11. Basic Authentication
curl -u username:password https://api.example.com/secureAdds a Authorization: Basic header.
12. Bearer Token Authentication
curl -H "Authorization: Bearer <token>" https://api.example.comUsed for OAuth 2.0 or JWT-secured APIs.
Last updated