FreeBSD Manual Pages

home | help

curl(1) curl Manual curl(1)

NAME
curl - transfer a URL

SYNOPSIS
curl [options / URLs]

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, MQTTS, POP3, POP3S, 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.

URL
The URL syntax is protocol-dependent. You can 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 hostname prefixes. For example, for hostnames 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 per-
formed 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.

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:

https://fun.example/{one,two,three}.jpg

sftp://{one,two,three}.example/README

Do sequences of alphanumeric series by using [] as in:

ftp://ftp.example.com/file[1-100].txt

With leading zeroes:

ftp://ftp.example.com/file[001-100].txt

With letters through the alphabet:

ftp://ftp.example.com/file[a-z].txt

Nested sequences are not supported, but you can use several ones next to
each other:

https://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:

https://example.com/file[1-100:10].txt

https://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 spe-
cial, like for example '&', '?' and '*'.

Switch off globbing with --globoff.

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 be expanded in option parameters using "{{name}}" 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 vari-
able. Insert "{{" verbatim in the string by prefixing it with a backslash,
like "\{{".

You can access and expand environment variables by importing them with
"--variable %name". This imports the variable called "name" but exits with
an error if that environment variable is not already set. To provide a de-
fault value in case it is not already set, use "--variable %name=content"
or "--variable %name@content".

Example: get the USER environment variable and expand 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", output the contents as a JSON quoted
string with "json", URL encode the string with "url", base64 encode it with
"b64" and base64 decode it with "64dec". To apply functions 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
causes an 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
when 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 8.3.0.

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.

PROTOCOLS
curl supports numerous protocols, or put in URL terms: schemes. Your par-
ticular build may not support them all.

DICT Lets you lookup words using online dictionaries.

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. Only absolute paths.

FTP(S) curl supports the File Transfer Protocol with a lot of tweaks and
levers. With or without using TLS.

GOPHER(S)
Retrieve files.

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.

IMAP(S)Using the mail reading protocol, curl can download emails for you.
With or without using TLS.

LDAP(S)curl can do directory lookups for you, with or without TLS.

MQTT curl supports MQTT version 3. Downloading over MQTT equals subscrib-
ing to a topic while uploading/posting equals publishing on a topic.
MQTT over TLS is not supported (yet).

POP3(S)Downloading from a pop3 server means getting an email. With or with-
out using TLS.

RTSP curl supports RTSP 1.0 downloads.

SCP curl supports SSH version 2 scp transfers.

SFTP curl supports SFTP (draft 5) done over SSH version 2.

SMB(S) curl supports SMB version 1 for upload and download.

SMTP(S)Uploading contents to an SMTP server means sending an email. With or
without TLS.

TELNET Fetching a telnet URL starts an interactive session where it sends
what it reads on stdin and outputs what the server sends it.

TFTP curl can do TFTP downloads and uploads.

WS(S) WebSocket done over HTTP/1. WSS implies that it works over HTTPS.

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 used
suffixes ("k" for kilo, "M" for mega, "G" for giga, "T" for tera, "P" for
peta and "E" for exa) are 1024 based. For example 1k is 1024 bytes. 1M is
1048576 bytes. Strictly speaking this makes the units kibibyte and mebibyte
etc.

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 dis-
ables 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.

VERSION
This man page describes curl 8.20.0. If you use a later version, chances
are this man page does not fully document it. If you use an earlier ver-
sion, this document tries to include version information about which spe-
cific 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 incarna-
tion: https://curl.se/docs/manpage.html

OPTIONS
Options start with one or two dashes. Many of the options require an addi-
tional 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, re-
quires 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-". In this list we mostly 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.

If the long option name ends with an equals sign ("="), the argument is the
text following on its right side. (Added in 8.16.0)

The first argument that is exactly two dashes ("--"), marks the end of op-
tions; any argument after the end of options is interpreted as a URL argu-
ment even if it starts with a dash.

curl does little to no verification of the contents of command line argu-
ments. Passing in "creative octets" like newlines might trigger unexpected
results.

The following options are global: --fail-early, --libcurl, --parallel-imme-
diate, --parallel-max-host, --parallel-max, --parallel, --progress-bar,
--rate, --show-error, --stderr, --styled-output, --trace-ascii,
--trace-config, --trace-ids, --trace-time, --trace and --verbose.

ALL OPTIONS
--abstract-unix-socket <path>
(HTTP) Connect to the server through an abstract Unix domain socket,
instead of using the network. Note: netstat shows the path of an ab-
stract socket prefixed with "@", however the <path> argument should
not have this leading character.

If --abstract-unix-socket is provided several times, the last set
value is used.

Example:
curl --abstract-unix-socket socketpath https://example.com

See also --proxy.

-I, --head
(HTTP FTP FILE) Fetch the headers only. HTTP-servers feature the
command HEAD which this uses to get nothing but the header of a doc-
ument. When used on an FTP or FILE URL, curl displays the file size
and last modification time only.

Providing --head multiple times has no extra effect. Disable it
again with --no-head.

Example:
curl -I https://example.com

See also --get, --verbose and --trace-ascii.

-H, --header <header/@file>
(HTTP IMAP SMTP) Extra header to include in information sent. When
used within an HTTP request, it is added to the regular request
headers.

For an IMAP or SMTP MIME uploaded mail built with --form options, it
is prepended to the resulting MIME document, effectively including
it at the mail global level. It does not affect raw uploaded mails.

You may specify any number of extra headers. Note that if you should
add a custom header that has the same name as one of the internal
ones curl would use, your externally set header is used instead of
the internal one. This allows you to make even trickier stuff than
curl would normally do. You should not replace internally set head-
ers without knowing perfectly well what you are doing. Remove an in-
ternal header by giving a replacement without content on the right
side of the colon, as in: -H "Host:". If you send the custom header
with no-value then its header must be terminated with a semicolon,
such as -H "X-Custom-Header;" to send "X-Custom-Header:".

curl makes sure that each header you add/replace is sent with the
proper end-of-line marker, you should thus not add that as a part of
the header content: do not add newlines or carriage returns, they
only mess things up for you. curl passes on the verbatim string you
give it without any filter or other safe guards. That includes white
space and control characters.

This option can take an argument in @filename style, which then adds
a header for each line in the input file. Using @- makes curl read
the header file from stdin.

Please note that most anti-spam utilities check the presence and
value of several MIME mail headers: these are "From:", "To:",
"Date:" and "Subject:" among others and should be added with this
option.

You need --proxy-header to send custom headers intended for an HTTP
proxy.

Passing on a "Transfer-Encoding: chunked" header when doing an HTTP
request with a request body, makes curl send the data using chunked
encoding.

WARNING: headers set with this option are set in all HTTP requests -
even after redirects are followed, like when told with --location.
This can lead to the header being sent to other hosts than the orig-
inal host, so sensitive headers should be used with caution combined
with following redirects.

"Authorization:" and "Cookie:" headers are explicitly not passed on
in HTTP requests when following redirects to other origins, unless
--location-trusted is used.

--header can be used several times in a command line

Examples:
curl -H "X-First-Name: Joe" https://example.com
curl -H "User-Agent: yes-please/2000" https://example.com
curl -H "Host:" https://example.com
curl -H @headers.txt https://example.com

See also --user-agent, --referer and --proxy-header.

-h, --help <subject>
Usage help. Provide help for the subject given as an optional argu-
ment.

If no argument is provided, curl displays the most important command
line arguments.

The argument can either be a category or a command line option. When
a category is provided, curl shows all command line options within
the given category. Specify category "all" to list all available op-
tions.

If "category" is specified, curl displays all available help cate-
gories.

If the provided subject is instead an existing command line option,
specified either in its short form with a single dash and a single
letter, or in the long form with two dashes and a longer name, curl
displays a help text for that option in the terminal.

The help output is extensive for some options.

If the provided command line option is not known, curl says so.

Examples:
curl --help all
curl --help --insecure
curl --help -f

See also --proxy.

--ntlm (HTTP) Use NTLM authentication. The NTLM authentication method was
designed by Microsoft and is used by IIS web servers. It is a pro-
prietary protocol, reverse-engineered by clever people and imple-
mented in curl based on their efforts. This kind of behavior should
not be endorsed, you should encourage everyone who uses NTLM to
switch to a public and documented authentication method instead,
such as Digest.

If you want to enable NTLM for your proxy authentication, then use
--proxy-ntlm.

Providing --ntlm multiple times has no extra effect. Disable it
again with --no-ntlm.

Example:
curl --ntlm -u user:password https://example.com

For --ntlm to work, it requires that the underlying libcurl is built
to support TLS. See also --proxy-ntlm.

--ntlm-wb
(HTTP) Deprecated option (added in 8.8.0).

Enabled NTLM much in the style --ntlm does, but handed over the au-
thentication to a separate executable that was executed when needed.

Providing --ntlm-wb multiple times has no extra effect.

Example:
curl --ntlm-wb -u user:password https://example.com

See also --proxy.

-U, --proxy-user <user:password>
Specify the username and password to use for proxy authentication.

If you use a Windows SSPI-enabled curl binary and do either Negoti-
ate or NTLM authentication then you can tell curl to select the
username and password from your environment by specifying a single
colon with this option: "-U :".

On systems where it works, curl hides the given option argument from
process listings. This is not enough to protect credentials from
possibly getting seen by other users on the same system as they
still are visible for a moment before being cleared. Such sensitive
data should be retrieved from a file instead or similar and never
used in clear text in a command line.

If --proxy-user is provided several times, the last set value is
used.

Example:
curl --proxy-user smith:secret -x proxy https://example.com

See also --proxy.

--pubkey <key>
(SFTP SCP) Public key filename. Allows you to provide your public
key in this separate file.

curl attempts to automatically extract the public key from the pri-
vate key file, so passing this option is generally not required.
Note that this public key extraction requires libcurl to be linked
against a copy of libssh2 1.2.8 or higher that is itself linked
against OpenSSL.

If --pubkey is provided several times, the last set value is used.

Example:
curl --pubkey file.pub sftp://example.com/

See also --socks5.

--socks5-gssapi
(GSS/kerberos) Use GSS-API authentication when connecting to a
SOCKS5 proxy. The GSS-API authentication is enabled by default (if
curl is compiled with GSS-API support). Use --socks5-basic to force
username/password authentication to SOCKS5 proxies.

Providing --socks5-gssapi multiple times has no extra effect. Dis-
able it again with --no-socks5-gssapi.

Example:
curl --socks5-gssapi --socks5 hostname:4096 https://example.com

See also --socks5.

--socks5-gssapi-nec
(GSS/kerberos) As part of the GSS-API negotiation a protection mode
is negotiated. RFC 1961 says in section 4.3/4.4 it should be pro-
tected, but the NEC reference implementation does not. The option
--socks5-gssapi-nec allows the unprotected exchange of the protec-
tion mode negotiation.

Providing --socks5-gssapi-nec multiple times has no extra effect.
Disable it again with --no-socks5-gssapi-nec.

Example:
curl --socks5-gssapi-nec --socks5 hostname:4096 https://example.com

See also --socks5.

--socks5-gssapi-service <name>
Set the service name for a socks server. Default is
rcmd/server-fqdn.

If --socks5-gssapi-service is provided several times, the last set
value is used.

Example:
curl --socks5-gssapi-service sockd --socks5 hostname:4096 https://example.com

See also --socks5.

--socks5-hostname <host[:port]>
Use the specified SOCKS5 proxy (and let the proxy resolve the host-
name). If the port number is not specified, it is assumed at port
1080.

To specify the proxy on a Unix domain socket, use localhost for host
and append the absolute path to the domain socket. For example:
"socks5h://localhost/path/to/socket.sock" (the scheme may be omit-
ted).

This option overrides any previous use of --proxy, as they are mutu-
ally exclusive.

This option is superfluous since you can specify a socks5 hostname
proxy with --proxy using a socks5h:// protocol prefix.

If --socks5-hostname is provided several times, the last set value
is used.

Example:
curl --socks5-hostname proxy.example:7000 https://example.com

This option is mutually exclusive with --proxy, --socks4, --socks4a
and --socks5. See also --socks5 and --socks4a.

-Y, --speed-limit <speed>
If a transfer is slower than this set speed (in bytes per second)
for a given number of seconds, it gets aborted. The time period is
set with --speed-time and is 30 seconds by default.

If --speed-limit is provided several times, the last set value is
used.

Example:
curl --speed-limit 300 --speed-time 10 https://example.com

See also --speed-time, --limit-rate and --max-time.

-y, --speed-time <seconds>
If a transfer runs slower than speed-limit bytes per second during a
speed-time period, the transfer is aborted. If speed-time is used,
the default speed-limit is 1 unless set with --speed-limit.

This option controls transfers (in both directions) but does not af-
fect slow connects etc. If this is a concern for you, try the --con-
nect-timeout option.

If --speed-time is provided several times, the last set value is
used.

Example:
curl --speed-limit 300 --speed-time 10 https://example.com

See also --speed-limit and --limit-rate.

--ssl (FTP IMAP POP3 SMTP LDAP) Warning: this is considered an insecure
option. Consider using --ssl-reqd instead to be sure curl upgrades
to a secure connection.

Try to use SSL/TLS for the connection - often referred to as START-
TLS or STLS because of the involved commands. Reverts to a non-se-
cure connection if the server does not support SSL/TLS. See also
--ftp-ssl-control and --ssl-reqd for different levels of encryption
required.

This option is handled in LDAP (added in 7.81.0). It is fully sup-
ported by the OpenLDAP backend and ignored by the generic ldap back-
end.

Please note that a server may close the connection if the negotia-
tion fails.

This option was formerly known as --ftp-ssl. That option name can
still be used but might be removed in a future version.

Providing --ssl multiple times has no extra effect. Disable it
again with --no-ssl.

Example:
curl --ssl pop3://example.com/

See also --ssl-reqd, --insecure and --ciphers.

--ssl-allow-beast
(TLS) Do not work around a security flaw in the TLS1.0 protocol
known as BEAST. If this option is not used, the TLS layer may use
workarounds known to cause interoperability problems with some older
server implementations.

This option only changes how curl does TLS 1.0 and has no effect on
later TLS versions.

WARNING: this option loosens the TLS security, and by using this
flag you ask for exactly that.

Providing --ssl-allow-beast multiple times has no extra effect.
Disable it again with --no-ssl-allow-beast.

Example:
curl --ssl-allow-beast https://example.com

See also --proxy-ssl-allow-beast and --insecure.

--ssl-auto-client-cert
(TLS) (Schannel) Automatically locate and use a client certificate
for authentication, when requested by the server. Since the server
can request any certificate that supports client authentication in
the OS certificate store it could be a privacy violation and unex-
pected.

Providing --ssl-auto-client-cert multiple times has no extra effect.
Disable it again with --no-ssl-auto-client-cert.

Example:
curl --ssl-auto-client-cert https://example.com

Added in 7.77.0. See also --proxy-ssl-auto-client-cert.

--ssl-no-revoke
(TLS) (Schannel) Disable certificate revocation checks. WARNING:
this option loosens the SSL security, and by using this flag you ask
for exactly that.

Providing --ssl-no-revoke multiple times has no extra effect. Dis-
able it again with --no-ssl-no-revoke.

Example:
curl --ssl-no-revoke https://example.com

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages