What is curl?
Author: Domeny.ForSale editorial team Published
In brief: curl is a command-line tool for transferring data between a computer and a server. Among other things, it lets you download a file, check a website’s response and send data to an API, an interface that enables communication between programs. It works without a graphical browser, making it useful for diagnostics and automation.
What is curl used for, and how does it differ from a browser?
You run curl in a terminal: enter a command, an address and optional parameters that specify how it should behave. The tool supports various communication protocols, including HTTP and HTTPS, which websites use. In practice, it is often used to check web services and work with APIs.
A browser downloads a page, interprets its code and displays an interface. By default, curl prints the received data in the terminal—for example, HTML code or a JSON response, a text-based data format used by many APIs. It does not execute JavaScript or render the page, so it cannot replace testing the page’s appearance and behaviour in a browser.
For example, if a form on a website is not working, curl can help check whether the server accepts the request and how it responds. However, it will not show whether the form’s button is correctly connected to the JavaScript code.
curl is associated with the libcurl library, which developers can use in their own applications. The curl command is a ready-to-use program; libcurl is a set of functions for building software that transfers data.
How do you check whether the tool is available and make your first request?
Open a terminal and enter:
curl --version
If curl is available, you will see its version number and information about supported features. If the system does not recognise the command, install the tool using your system’s package manager or follow the curl project’s official instructions. The availability of protocols and options may depend on the version and how the program was built.
In some older Windows PowerShell environments, the name curl may refer to a different command. In that case, use curl.exe to invoke the correct program.
The simplest request looks like this:
curl https://example.com
For an HTTP or HTTPS address, curl makes a GET request by default—a request to retrieve a resource. It prints the response to standard output, usually the terminal. Put addresses containing special characters, such as &, in quotation marks so that the shell does not interpret them as part of its own syntax.
How do you check headers and redirects?
HTTP headers are information accompanying a request or response, such as the type of content being transferred and caching instructions. To ask the server for just the response headers, use:
curl -I https://example.com
The -I option sends a HEAD request. Not every server handles it in the same way as GET. If you want to see the response headers for a normal page retrieval along with its content, use -i.
By default, curl does not follow HTTP redirects. The -L option allows it to follow the address specified by the server:
curl -i -L https://example.com
The code 200 usually indicates a successful response, 404—a missing resource, and 500—a server-side error. However, the code alone does not prove that the page is working correctly: a 200 response may contain a message about a problem instead of the expected data.
For more detailed diagnostics, use -v, which shows connection details and the headers exchanged, among other things. Before sharing such a log, remove tokens, cookies and other confidential information.
How do you download a file and send data to an API?
To save the response to a file instead of displaying it in the terminal, use the -o option:
curl -f -L -o document.pdf https://example.com/dokument.pdf
This is a syntax example—the specified file may not exist. -o sets the local filename, -L handles redirects, and -f causes an error to be reported for HTTP responses indicating failure, generally from code 400 onwards. Without -f, curl may finish successfully despite receiving an error page. Saving to an existing file may overwrite its contents.
Sending data to an API might look like this:
curl -i https://api.example.com/items -H "Content-Type: application/json" --data '{"name":"test"}'
The -H option adds a header, while --data supplies the request body and selects the POST method by default, which is often used to send data. This example assumes a terminal compatible with Bash shell syntax; quoting rules on Windows may differ. Check the documentation for the specific API for the actual address, required fields and authentication method.
How do you use curl safely?
curl can not only read data but also perform operations that change the state of a service. Before running someone else’s command, check the destination address, the data being sent and the options. An API call may create a record, delete a resource or trigger a paid operation.
Do not routinely use the -k or --insecure option: it disables verification of the TLS certificate, which helps confirm the server’s identity. It is better to investigate a certificate error than to hide it. Do not run a downloaded script without checking its contents either, especially with a command that connects curl directly to a shell.
To begin, retrieve a public resource using curl -i, inspect the response code and headers, and only then move on to requests that send data.
See also: What is an API?
Read also
