cURL is a free, open-source command-line tool from the curl project for transferring data to and from servers through URLs. It runs on Windows, macOS, Linux and other systems, and uses the libcurl library for its transfer operations. Commands and scripts control its requests, file transfers and output destinations.
Receiving a URL
A curl request starts with a URL that identifies the protocol, server and resource. Protocol choices include HTTP, HTTPS, FTP, FTPS, SFTP and SCP. Available protocols depend on the particular build; the –version command lists its capabilities.
Without an output option, curl sends response bytes to standard output, where a terminal can display them or another program can consume them. The -o option supplies a local filename, while -O takes the filename from the URL. Saving normally overwrites an existing destination; –no-clobber chooses another name. Curl passes response data onward without interpreting HTML or running JavaScript.
Sending HTTP request data
Curl lets you choose an HTTP method, add request headers and supply a body from text or a file. The payload format that the server expects determines which data option fits the request:
- –data sends a regular POST body, with a default content type for URL-encoded form data.
- –form builds a multipart form submission from named fields and files, including file-upload fields.
- –json sends a POST body with JSON content and acceptance headers; input can come from a string, file or standard input.
The JSON option transfers the bytes you provide without validating their structure. Curl also leaves JSON responses for another program to parse. When a server returns a redirect, –location lets curl follow it and request the destination.
Uploading local files
For a file transfer, curl accepts a local filename through -T or –upload-file and a destination URL. With HTTP, that operation uses PUT, which requires a server that permits this method. FTP and SFTP destinations identify the remote directory and filename. A destination ending with a slash keeps the local filename on the server.
The –append option adds data to an FTP or SFTP target instead of replacing its contents. Upload forms use the separate multipart request mechanism.
Credentials and session cookies
Curl accepts usernames and passwords for account-based transfers, and SSH transfers can use a private key. Authentication options select the scheme that the server expects. A proxy setting can route requests through an HTTP, HTTPS or SOCKS proxy.
For HTTP sessions, –cookie loads cookie values or a cookie file. Curl sends matching cookies according to their domain and path rules. The –cookie-jar option writes the resulting cookie collection after the requests finish. A later command can load that file and continue using those session values.
Curl checks TLS certificates by default, including the certificate signature and the hostname in the URL. A custom CA file can supply additional trust information. The trust-store mechanism depends on the TLS backend that the build uses.
Several transfers in one command
Curl processes multiple URLs sequentially unless you enable –parallel. Parallel mode starts several transfers together, and –parallel-max controls how many may run simultaneously. A separate per-host control limits concurrent connections to each origin.
Each download needs its own output instruction when you want separate local files. Curl matches those instructions to URLs in their order. It can reuse connections between transfers within one invocation, but separate commands do not share that connection cache. Brace lists and bracket ranges can generate related URLs without enumerating every address.
Resuming and retrying
Curl can continue a partial download from an explicit byte offset. With automatic continuation, it checks the local destination’s length and asks the server for the remaining data. Resume depends on the protocol and server supporting that request. Byte-range requests can retrieve only a particular portion of a resource.
The –retry option adds further attempts after transient failures, including timeouts and certain HTTP or FTP responses. Curl normally makes only one attempt. Retry settings can change the delay and limit the overall retry period, while a separate timeout limits an individual transfer.
Command files and transfer reports
Curl can read its options from a plain-text configuration file through –config. Each line supplies an option and its argument; URL entries use an explicit url setting. This file can hold the same transfer settings that a command line supplies.
Verbose mode reports connection activity, TLS information and request or response headers. After a transfer, –write-out fills a format string with values such as response codes and timing measurements. The –fail option makes HTTP error responses produce a failure status and suppresses their response body. The –fail-with-body alternative reports failure while retaining that response data.
