> For the complete documentation index, see [llms.txt](https://www.pranaypourkar.co.in/the-programmers-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pranaypourkar.co.in/the-programmers-guide/api/api-testing/tools/curl.md). # 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
OptionDescription
-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
-OSaves the file using the remote file name
-i or --includeIncludes response headers in the output
-I or --headSends a HEAD request (returns headers only)
-v or --verbosePrints detailed info for debugging (request/response, SSL handshake, etc.)
-s or --silentHides progress bar and error messages
-S or --show-errorShows error even when --silent is used
-L or --locationFollows redirects (3xx responses)
-k or --insecureIgnores SSL certificate validation (not recommended in production)
--compressedRequests a compressed response (e.g., gzip)
--http1.1, --http2, --http3Forces 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
--failFails silently on HTTP errors (no body output on 400/500)
## Common curl Commands ### 1. GET Request (default method) ```bash curl https://api.example.com/users ``` Sends a GET request to fetch data. ### 2. POST Request with JSON Body ```bash curl -X POST https://api.example.com/users \ -H "Content-Type: application/json" \ -d '{"name":"Alice","email":"alice@example.com"}' ``` * `-X` specifies the HTTP method (POST) * `-H` adds a header * `-d` sends data in the request body ### 3. PUT Request ```bash curl -X PUT https://api.example.com/users/123 \ -H "Content-Type: application/json" \ -d '{"email":"alice@newdomain.com"}' ``` Used to update existing data. ### 4. DELETE Request ```bash curl -X DELETE https://api.example.com/users/123 ``` Deletes a resource by ID. ### 5. Custom Headers ```bash curl https://api.example.com/data \ -H "Authorization: Bearer " \ -H "Accept: application/json" ``` Adds headers like auth tokens and Accept types. ### 6. Form Submission (application/x-www-form-urlencoded) ```bash curl -X POST https://api.example.com/login \ -d "username=admin&password=secret" ``` Mimics a form submission. ### 7. File Upload ```bash 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 ```bash curl https://example.com/image.jpg -o image.jpg ``` Downloads and saves the file. ### 9. View Response Headers ```bash curl -I https://api.example.com ``` Shows HTTP headers only, without the response body. ### 10. Verbose Output (for debugging) ```bash curl -v https://api.example.com ``` Prints detailed request/response information, including headers and connection steps. ### 11. Basic Authentication ```bash curl -u username:password https://api.example.com/secure ``` Adds a `Authorization: Basic` header. ### 12. Bearer Token Authentication ```bash curl -H "Authorization: Bearer " https://api.example.com ``` Used for OAuth 2.0 or JWT-secured APIs. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://www.pranaypourkar.co.in/the-programmers-guide/api/api-testing/tools/curl.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.