259 lines
11 KiB
Plaintext
259 lines
11 KiB
Plaintext
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
.\" *
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
.\" * you should have received as part of this distribution. The terms
|
|
.\" * are also available at https://curl.se/docs/copyright.html.
|
|
.\" *
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
.\" * KIND, either express or implied.
|
|
.\" *
|
|
.\" * SPDX-License-Identifier: curl
|
|
.\" *
|
|
.\" **************************************************************************
|
|
.\"
|
|
.\" DO NOT EDIT. Generated by the curl project gen.pl man page generator.
|
|
.\"
|
|
.TH curl 1 "%DATE" "curl %VERSION" "curl Manual"
|
|
.SH NAME
|
|
curl \- transfer a URL
|
|
.SH SYNOPSIS
|
|
.B curl [options / URLs]
|
|
.SH DESCRIPTION
|
|
**curl** is a tool for transferring data from or to a server using URLs. It
|
|
supports these protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS,
|
|
IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP,
|
|
SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS.
|
|
|
|
curl is powered by libcurl for all transfer-related features. See
|
|
*libcurl(3)* for details.
|
|
.SH URL
|
|
The URL syntax is protocol-dependent. You find a detailed description in
|
|
RFC 3986.
|
|
|
|
If you provide a URL without a leading **protocol://** scheme, curl guesses
|
|
what protocol you want. It then defaults to HTTP but assumes others based on
|
|
often-used host name prefixes. For example, for host names starting with
|
|
"ftp." curl assumes you want FTP.
|
|
|
|
You can specify any amount of URLs on the command line. They are fetched in a
|
|
sequential manner in the specified order unless you use --parallel. You can
|
|
specify command line options and URLs mixed and in any order on the command
|
|
line.
|
|
|
|
curl attempts to reuse connections when doing multiple transfers, so that
|
|
getting many files from the same server do not use multiple connects and setup
|
|
handshakes. This improves speed. Connection reuse can only be done for URLs
|
|
specified for a single command line invocation and cannot be performed between
|
|
separate curl runs.
|
|
|
|
Provide an IPv6 zone id in the URL with an escaped percentage sign. Like in
|
|
|
|
"http://[fe80::3%25eth0]/"
|
|
|
|
Everything provided on the command line that is not a command line option or
|
|
its argument, curl assumes is a URL and treats it as such.
|
|
.SH GLOBBING
|
|
You can specify multiple URLs or parts of URLs by writing lists within braces
|
|
or ranges within brackets. We call this "globbing".
|
|
|
|
Provide a list with three different names like this:
|
|
|
|
"http://site.{one,two,three}.com"
|
|
|
|
or you can get sequences of alphanumeric series by using [] as in:
|
|
|
|
"ftp://ftp.example.com/file[1-100].txt"
|
|
|
|
"ftp://ftp.example.com/file[001-100].txt" (with leading zeros)
|
|
|
|
"ftp://ftp.example.com/file[a-z].txt"
|
|
|
|
Nested sequences are not supported, but you can use several ones next to each
|
|
other:
|
|
|
|
"http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html"
|
|
|
|
You can specify a step counter for the ranges to get every Nth number or
|
|
letter:
|
|
|
|
"http://example.com/file[1-100:10].txt"
|
|
|
|
"http://example.com/file[a-z:2].txt"
|
|
|
|
When using [] or {} sequences when invoked from a command line prompt, you
|
|
probably have to put the full URL within double quotes to avoid the shell from
|
|
interfering with it. This also goes for other characters treated special, like
|
|
for example '&', '?' and '*'.
|
|
|
|
Switch off globbing with --globoff.
|
|
.SH VARIABLES
|
|
curl supports command line variables (added in 8.3.0). Set variables with
|
|
--variable name=content or --variable name@file (where "file" can be stdin if
|
|
set to a single dash (-)).
|
|
|
|
Variable contents can expanded in option parameters using "{{name}}" (without
|
|
the quotes) if the option name is prefixed with "--expand-". This gets the
|
|
contents of the variable "name" inserted, or a blank if the name does not
|
|
exist as a variable. Insert "{{" verbatim in the string by prefixing it with a
|
|
backslash, like "\\{{".
|
|
|
|
You an access and expand environment variables by first importing them. You
|
|
can select to either require the environment variable to be set or you can
|
|
provide a default value in case it is not already set. Plain --variable %name
|
|
imports the variable called 'name' but exits with an error if that environment
|
|
variable is not already set. To provide a default value if it is not set, use
|
|
--variable %name=content or --variable %name@content.
|
|
|
|
Example. Get the USER environment variable into the URL, fail if USER is not
|
|
set:
|
|
|
|
--variable '%USER'
|
|
--expand-url = "https://example.com/api/{{USER}}/method"
|
|
|
|
When expanding variables, curl supports a set of functions that can make the
|
|
variable contents more convenient to use. It can trim leading and trailing
|
|
white space with *trim*, it can output the contents as a JSON quoted string
|
|
with *json*, URL encode the string with *url* or base64 encode it with
|
|
*b64*. You apply function to a variable expansion, add them colon separated to
|
|
the right side of the variable. Variable content holding null bytes that are
|
|
not encoded when expanded cause error.
|
|
|
|
Example: get the contents of a file called $HOME/.secret into a variable
|
|
called "fix". Make sure that the content is trimmed and percent-encoded sent
|
|
as POST data:
|
|
|
|
--variable %HOME
|
|
--expand-variable fix@{{HOME}}/.secret
|
|
--expand-data "{{fix:trim:url}}"
|
|
https://example.com/
|
|
|
|
Command line variables and expansions were added in in 8.3.0.
|
|
.SH OUTPUT
|
|
If not told otherwise, curl writes the received data to stdout. It can be
|
|
instructed to instead save that data into a local file, using the --output or
|
|
--remote-name options. If curl is given multiple URLs to transfer on the
|
|
command line, it similarly needs multiple options for where to save them.
|
|
|
|
curl does not parse or otherwise "understand" the content it gets or writes as
|
|
output. It does no encoding or decoding, unless explicitly asked to with
|
|
dedicated command line options.
|
|
.SH PROTOCOLS
|
|
curl supports numerous protocols, or put in URL terms: schemes. Your
|
|
particular build may not support them all.
|
|
.IP DICT
|
|
Lets you lookup words using online dictionaries.
|
|
.IP FILE
|
|
Read or write local files. curl does not support accessing file:// URL
|
|
remotely, but when running on Microsoft Windows using the native UNC approach
|
|
works.
|
|
.IP FTP(S)
|
|
curl supports the File Transfer Protocol with a lot of tweaks and levers. With
|
|
or without using TLS.
|
|
.IP GOPHER(S)
|
|
Retrieve files.
|
|
.IP HTTP(S)
|
|
curl supports HTTP with numerous options and variations. It can speak HTTP
|
|
version 0.9, 1.0, 1.1, 2 and 3 depending on build options and the correct
|
|
command line options.
|
|
.IP IMAP(S)
|
|
Using the mail reading protocol, curl can "download" emails for you. With or
|
|
without using TLS.
|
|
.IP LDAP(S)
|
|
curl can do directory lookups for you, with or without TLS.
|
|
.IP MQTT
|
|
curl supports MQTT version 3. Downloading over MQTT equals "subscribe" to a
|
|
topic while uploading/posting equals "publish" on a topic. MQTT over TLS is
|
|
not supported (yet).
|
|
.IP POP3(S)
|
|
Downloading from a pop3 server means getting a mail. With or without using
|
|
TLS.
|
|
.IP RTMP(S)
|
|
The **Realtime Messaging Protocol** is primarily used to serve streaming media
|
|
and curl can download it.
|
|
.IP RTSP
|
|
curl supports RTSP 1.0 downloads.
|
|
.IP SCP
|
|
curl supports SSH version 2 scp transfers.
|
|
.IP SFTP
|
|
curl supports SFTP (draft 5) done over SSH version 2.
|
|
.IP SMB(S)
|
|
curl supports SMB version 1 for upload and download.
|
|
.IP SMTP(S)
|
|
Uploading contents to an SMTP server means sending an email. With or without
|
|
TLS.
|
|
.IP TELNET
|
|
Telling curl to fetch a telnet URL starts an interactive session where it
|
|
sends what it reads on stdin and outputs what the server sends it.
|
|
.IP TFTP
|
|
curl can do TFTP downloads and uploads.
|
|
.SH "PROGRESS METER"
|
|
curl normally displays a progress meter during operations, indicating the
|
|
amount of transferred data, transfer speeds and estimated time left, etc. The
|
|
progress meter displays the transfer rate in bytes per second. The suffixes
|
|
(k, M, G, T, P) are 1024 based. For example 1k is 1024 bytes. 1M is 1048576
|
|
bytes.
|
|
|
|
curl displays this data to the terminal by default, so if you invoke curl to
|
|
do an operation and it is about to write data to the terminal, it
|
|
*disables* the progress meter as otherwise it would mess up the output
|
|
mixing progress meter and response data.
|
|
|
|
If you want a progress meter for HTTP POST or PUT requests, you need to
|
|
redirect the response output to a file, using shell redirect (>), --output or
|
|
similar.
|
|
|
|
This does not apply to FTP upload as that operation does not spit out any
|
|
response data to the terminal.
|
|
|
|
If you prefer a progress "bar" instead of the regular meter, --progress-bar is
|
|
your friend. You can also disable the progress meter completely with the
|
|
--silent option.
|
|
.SH VERSION
|
|
This man page describes curl %VERSION. If you use a later version, chances are
|
|
this man page does not fully document it. If you use an earlier version, this
|
|
document tries to include version information about which specific version
|
|
that introduced changes.
|
|
|
|
You can always learn which the latest curl version is by running
|
|
|
|
curl https://curl.se/info
|
|
|
|
The online version of this man page is always showing the latest incarnation:
|
|
https://curl.se/docs/manpage.html
|
|
.SH OPTIONS
|
|
Options start with one or two dashes. Many of the options require an
|
|
additional value next to them. If provided text does not start with a dash, it
|
|
is presumed to be and treated as a URL.
|
|
|
|
The short "single-dash" form of the options, -d for example, may be used with
|
|
or without a space between it and its value, although a space is a recommended
|
|
separator. The long "double-dash" form, --data for example, requires a space
|
|
between it and its value.
|
|
|
|
Short version options that do not need any additional values can be used
|
|
immediately next to each other, like for example you can specify all the
|
|
options *-O*, *-L* and *-v* at once as *-OLv*.
|
|
|
|
In general, all boolean options are enabled with --**option** and yet again
|
|
disabled with --**no-**option. That is, you use the same option name but
|
|
prefix it with "no-". However, in this list we mostly only list and show the
|
|
*--option* version of them.
|
|
|
|
When --next is used, it resets the parser state and you start again with a
|
|
clean option state, except for the options that are "global". Global options
|
|
retain their values and meaning even after --next.
|
|
|
|
The following options are global:
|
|
%GLOBALS.
|