curl(1) Curl Manual curl(1)
NAME
curl - transfer a URL
SYNOPSIS
curl [options] [URL...]
DESCRIPTION
curl is a tool to transfer data from or to a server, using
one of the supported protocols (HTTP, HTTPS, FTP, FTPS,
SCP, SFTP, TFTP, DICT, TELNET, LDAP or FILE). The command
is designed to work without user interaction.
curl offers a busload of useful tricks like proxy support,
user authentication, ftp upload, HTTP post, SSL connec-
tions, cookies, file transfer resume and more. As you will
see below, the amount of features will make your head
spin!
curl is powered by libcurl for all transfer-related fea-
tures. See libcurl(3) for details.
URL
The URL syntax is protocol dependent. You'll find a
detailed description in RFC 3986.
You can specify multiple URLs or parts of URLs by writing
part sets within braces as in:
http://site.{one,two,three}.com
or you can get sequences of alphanumeric series by using
[] as in:
ftp://ftp.numericals.com/file[1-100].txt
ftp://ftp.numericals.com/file[001-100].txt (with lead-
ing zeros)
ftp://ftp.letters.com/file[a-z].txt
No nesting of the sequences is supported at the moment,
but you can use several ones next to each other:
http://any.org/archive[1996-1999]/vol[1-4]/part{a,b,c}.html
You can specify any amount of URLs on the command line.
They will be fetched in a sequential manner in the speci-
fied order.
Since curl 7.15.1 you can also specify step counter for
the ranges, so that you can get every Nth number or let-
ter:
http://www.numericals.com/file[1-100:10].txt
http://www.letters.com/file[a-z:2].txt
If you specify URL without protocol:// prefix, curl will
attempt to guess what protocol you might want. It will
then default to HTTP but try other protocols based on
often-used host name prefixes. For example, for host names
starting with "ftp." curl will assume you want to speak
FTP.
Curl will attempt to re-use connections for multiple file
transfers, so that getting many files from the same server
will not do multiple connects / handshakes. This improves
speed. Of course this is only done on files specified on a
single command line and cannot be used between separate
curl invokes.
PROGRESS METER
curl normally displays a progress meter during operations,
indicating amount of transfered data, transfer speeds and
estimated time left etc.
However, since curl displays data to the terminal by
default, 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 (>), -o [file] or similar.
It is not the same case for FTP upload as that operation
is not spitting out any response data to the terminal.
If you prefer a progress "bar" instead of the regular
meter, -# is your friend.
OPTIONS
-a/--append
(FTP) When used in an FTP upload, this will tell
curl to append to the target file instead of over-
writing it. If the file doesn't exist, it will be
created.
If this option is used twice, the second one will
disable append mode again.
-A/--user-agent
(HTTP) Specify the User-Agent string to send to the
HTTP server. Some badly done CGIs fail if its not
set to "Mozilla/4.0". To encode blanks in the
string, surround the string with single quote
marks. This can also be set with the -H/--header
option of course.
If this option is set more than once, the last one
will be the one that's used.
--anyauth
(HTTP) Tells curl to figure out authentication
method by itself, and use the most secure one the
remote site claims it supports. This is done by
first doing a request and checking the response-
headers, thus inducing an extra network round-trip.
This is used instead of setting a specific authen-
tication method, which you can do with --basic,
--digest, --ntlm, and --negotiate.
Note that using --anyauth is not recommended if you
do uploads from stdin, since it may require data to
be sent twice and then the client must be able to
rewind. If the need should arise when uploading
from stdin, the upload operation will fail.
If this option is used several times, the following
occurrences make no difference.
-b/--cookie
(HTTP) Pass the data to the HTTP server as a
cookie. It is supposedly the data previously
received from the server in a "Set-Cookie:" line.
The data should be in the format "NAME1=VALUE1;
NAME2=VALUE2".
If no '=' letter is used in the line, it is treated
as a filename to use to read previously stored
cookie lines from, which should be used in this
session if they match. Using this method also acti-
vates the "cookie parser" which will make curl
record incoming cookies too, which may be handy if
you're using this in combination with the
-L/--location option. The file format of the file
to read cookies from should be plain HTTP headers
or the Netscape/Mozilla cookie file format.
NOTE that the file specified with -b/--cookie is
only used as input. No cookies will be stored in
the file. To store cookies, use the -c/--cookie-jar
option or you could even save the HTTP headers to a
file using -D/--dump-header!
If this option is set more than once, the last one
will be the one that's used.
-B/--use-ascii
Enable ASCII transfer when using FTP or LDAP. For
FTP, this can also be enforced by using an URL that
ends with ";type=A". This option causes data sent
to stdout to be in text mode for win32 systems.
If this option is used twice, the second one will
disable ASCII usage.
--basic
(HTTP) Tells curl to use HTTP Basic authentication.
This is the default and this option is usually
pointless, unless you use it to override a previ-
ously set option that sets a different authentica-
tion method (such as --ntlm, --digest and --negoti-
ate).
If this option is used several times, the following
occurrences make no difference.
--ciphers
(SSL) Specifies which ciphers to use in the connec-
tion. The list of ciphers must be using valid
ciphers. Read up on SSL cipher list details on this
URL: http://www.openssl.org/docs/apps/ciphers.html
NSS ciphers are done differently than OpenSSL and
GnuTLS. The full list of NSS ciphers is in the NSS-
CipherSuite entry at this URL: http://direc-
tory.fedora.redhat.com/docs/mod_nss.html#Directives
If this option is used several times, the last one
will override the others.
--compressed
(HTTP) Request a compressed response using one of
the algorithms libcurl supports, and return the
uncompressed document. If this option is used and
the server sends an unsupported encoding, Curl will
report an error.
If this option is used several times, each occur-
rence will toggle it on/off.
--connect-timeout
Maximum time in seconds that you allow the connec-
tion to the server to take. This only limits the
connection phase, once curl has connected this
option is of no more use. See also the -m/--max-
time option.
If this option is used several times, the last one
will be used.
-c/--cookie-jar
Specify to which file you want curl to write all
cookies after a completed operation. Curl writes
all cookies previously read from a specified file
as well as all cookies received from remote
server(s). If no cookies are known, no file will be
written. The file will be written using the
Netscape cookie file format. If you set the file
name to a single dash, "-", the cookies will be
written to stdout.
NOTE If the cookie jar can't be created or written
to, the whole curl operation won't fail or even
report an error clearly. Using -v will get a warn-
ing displayed, but that is the only visible feed-
back you get about this possibly lethal situation.
If this option is used several times, the last
specified file name will be used.
-C/--continue-at
Continue/Resume a previous file transfer at the
given offset. The given offset is the exact number
of bytes that will be skipped counted from the
beginning of the source file before it is trans-
ferred to the destination. If used with uploads,
the ftp server command SIZE will not be used by
curl.
Use "-C -" to tell curl to automatically find out
where/how to resume the transfer. It then uses the
given output/input files to figure that out.
If this option is used several times, the last one
will be used.
--create-dirs
When used in conjunction with the -o option, curl
will create the necessary local directory hierarchy
as needed. This option creates the dirs mentioned
with the -o option, nothing else. If the -o file
name uses no dir or if the dirs it mentions already
exist, no dir will be created.
To create remote directories when using FTP, try
--ftp-create-dirs.
--crlf (FTP) Convert LF to CRLF in upload. Useful for MVS
(OS/390).
If this option is used several times, the following
occurrences make no difference.
-d/--data
(HTTP) Sends the specified data in a POST request
to the HTTP server, in a way that can emulate as if
a user has filled in a HTML form and pressed the
submit button. Note that the data is sent exactly
as specified with no extra processing (with all
newlines cut off). The data is expected to be
"url-encoded". This will cause curl to pass the
data to the server using the content-type applica-
tion/x-www-form-urlencoded. Compare to -F/--form.
If this option is used more than once on the same
command line, the data pieces specified will be
merged together with a separating &-letter. Thus,
using '-d name=daniel -d skill=lousy' would gener-
ate a post chunk that looks like
'name=daniel&skill=lousy'.
If you start the data with the letter @, the rest
should be a file name to read the data from, or -
if you want curl to read the data from stdin. The
contents of the file must already be url-encoded.
Multiple files can also be specified. Posting data
from a file named 'foobar' would thus be done with
--data @foobar".
To post data purely binary, you should instead use
the --data-binary option.
-d/--data is the same as --data-ascii.
If this option is used several times, the ones fol-
lowing the first will append data.
--data-ascii
(HTTP) This is an alias for the -d/--data option.
If this option is used several times, the ones fol-
lowing the first will append data.
--data-binary
(HTTP) This posts data in a similar manner as
--data-ascii does, although when using this option
the entire context of the posted data is kept as-
is. If you want to post a binary file without the
strip-newlines feature of the --data-ascii option,
this is for you.
If this option is used several times, the ones fol-
lowing the first will append data.
--digest
(HTTP) Enables HTTP Digest authentication. This is
a authentication that prevents the password from
being sent over the wire in clear text. Use this in
combination with the normal -u/--user option to set
user name and password. See also --ntlm, --negoti-
ate and --anyauth for related options.
If this option is used several times, the following
occurrences make no difference.
--disable-eprt
(FTP) Tell curl to disable the use of the EPRT and
LPRT commands when doing active FTP transfers. Curl
will normally always first attempt to use EPRT,
then LPRT before using PORT, but with this option,
it will use PORT right away. EPRT and LPRT are
extensions to the original FTP protocol, may not
work on all servers but enable more functionality
in a better way than the traditional PORT command.
If this option is used several times, each occur-
rence will toggle this on/off.
--disable-epsv
(FTP) Tell curl to disable the use of the EPSV com-
mand when doing passive FTP transfers. Curl will
normally always first attempt to use EPSV before
PASV, but with this option, it will not try using
EPSV.
If this option is used several times, each occur-
rence will toggle this on/off.
-D/--dump-header
Write the protocol headers to the specified file.
This option is handy to use when you want to store
the headers that a HTTP site sends to you. Cookies
from the headers could then be read in a second
curl invoke by using the -b/--cookie option! The
-c/--cookie-jar option is however a better way to
store cookies.
When used on FTP, the ftp server response lines are
considered being "headers" and thus are saved
there.
If this option is used several times, the last one
will be used.
-e/--referer
(HTTP) Sends the "Referer Page" information to the
HTTP server. This can also be set with the
-H/--header flag of course. When used with
-L/--location you can append ";auto" to the --ref-
erer URL to make curl automatically set the previ-
ous URL when it follows a Location: header. The
";auto" string can be used alone, even if you don't
set an initial --referer.
If this option is used several times, the last one
will be used.
--engine
Select the OpenSSL crypto engine to use for cipher
operations. Use --engine list to print a list of
build-time supported engines. Note that not all (or
none) of the engines may be available at run-time.
--environment
(RISC OS ONLY) Sets a range of environment vari-
ables, using the names the -w option supports, to
easier allow extraction of useful information after
having run curl.
If this option is used several times, each occur-
rence will toggle this on/off.
--egd-file
(SSL) Specify the path name to the Entropy Gather-
ing Daemon socket. The socket is used to seed the
random engine for SSL connections. See also the
--random-file option.
-E/--cert
(SSL) Tells curl to use the specified certificate
file when getting a file with HTTPS or FTPS. The
certificate must be in PEM format. If the optional
password isn't specified, it will be queried for on
the terminal. Note that this option assumes a "cer-
tificate" file that is the private key and the pri-
vate certificate concatenated! See --cert and --key
to specify them independently.
If curl is built against the NSS SSL library then
this option tells curl the nickname of the certifi-
cate to use within the NSS database defined by
--cacert.
If this option is used several times, the last one
will be used.
--cert-type
(SSL) Tells curl what certificate type the provided
certificate is in. PEM, DER and ENG are recognized
types. If not specified, PEM is assumed.
If this option is used several times, the last one
will be used.
--cacert
(SSL) Tells curl to use the specified certificate
file to verify the peer. The file may contain mul-
tiple CA certificates. The certificate(s) must be
in PEM format.
curl recognizes the environment variable named
'CURL_CA_BUNDLE' if that is set, and uses the given
path as a path to a CA cert bundle. This option
overrides that variable.
The windows version of curl will automatically look
for a CA certs file named 'curl-ca-bundle.crt',
either in the same directory as curl.exe, or in the
Current Working Directory, or in any folder along
your PATH.
If curl is built against the NSS SSL library then
this option tells curl the directory that the NSS
certificate database resides in.
If this option is used several times, the last one
will be used.
--capath
(SSL) Tells curl to use the specified certificate
directory to verify the peer. The certificates must
be in PEM format, and the directory must have been
processed using the c_rehash utility supplied with
openssl. Using --capath can allow curl to make SSL-
connections much more efficiently than using --cac-
ert if the --cacert file contains many CA certifi-
cates.
If this option is used several times, the last one
will be used.
-f/--fail
(HTTP) Fail silently (no output at all) on server
errors. This is mostly done like this to better
enable scripts etc to better deal with failed
attempts. In normal cases when a HTTP server fails
to deliver a document, it returns an HTML document
stating so (which often also describes why and
more). This flag will prevent curl from outputting
that and return error 22.
This method is not fail-safe and there are occa-
sions where non-succesful response codes will slip
through, especially when authentication is involved
(response codes 401 and 407).
If this option is used twice, the second will again
disable silent failure.
--ftp-account [data]
(FTP) When an FTP server asks for "account data"
after user name and password has been provided,
this data is sent off using the ACCT command.
(Added in 7.13.0)
If this option is used twice, the second will over-
ride the previous use.
--ftp-create-dirs
(FTP) When an FTP URL/operation uses a path that
doesn't currently exist on the server, the standard
behavior of curl is to fail. Using this option,
curl will instead attempt to create missing direc-
tories.
If this option is used twice, the second will again
disable directory creation.
--ftp-method [method]
(FTP) Control what method curl should use to reach
a file on a FTP(S) server. The method argument
should be one of the following alternatives:
multicwd
curl does a single CWD operation for each
path part in the given URL. For deep hierar-
chies this means very many commands. This is
how RFC1738 says it should be done. This is
the default but the slowest behavior.
nocwd curl does no CWD at all. curl will do SIZE,
RETR, STOR etc and give a full path to the
server for all these commands. This is the
fastest behavior.
singlecwd
curl does one CWD with the full target
directory and then operates on the file
"normally" (like in the multicwd case). This
is somewhat more standards compliant than
'nocwd' but without the full penalty of
'multicwd'.
--ftp-pasv
(FTP) Use PASV when transferring. PASV is the
internal default behavior, but using this option
can be used to override a previous --ftp-port
option. (Added in 7.11.0)
If this option is used several times, the following
occurrences make no difference.
--ftp-alternative-to-user
(FTP) If authenticating with the USER and PASS com-
mands fails, send this command. When connecting to
Tumbleweed's Secure Transport server over FTPS
using a client certificate, using "SITE AUTH" will
tell the server to retrieve the username from the
certificate. (Added in 7.15.5)
--ftp-skip-pasv-ip
(FTP) Tell curl to not use the IP address the
server suggests in its response to curl's PASV com-
mand when curl connects the data connection.
Instead curl will re-use the same IP address it
already uses for the control connection. (Added in
7.14.2)
This option has no effect if PORT, EPRT or EPSV is
used instead of PASV.
If this option is used twice, the second will again
use the server's suggested address.
--ftp-ssl
(FTP) Try to use SSL/TLS for the FTP connection.
Reverts to a non-secure connection if the server
doesn't support SSL/TLS. See also --ftp-ssl-con-
trol and --ftp-ssl-reqd for different levels of
encryption required. (Added in 7.11.0)
If this option is used twice, the second will again
disable this.
--ftp-ssl-control
(FTP) Require SSL/TLS for the ftp login, clear for
transfer. Allows secure authentication, but non-
encrypted data transfers for efficiency. Fails the
transfer if the server doesn't support SSL/TLS.
(Added in 7.16.0)
If this option is used twice, the second will again
disable this.
--ftp-ssl-reqd
(FTP) Require SSL/TLS for the FTP connection. Ter-
minates the connection if the server doesn't sup-
port SSL/TLS. (Added in 7.15.5)
If this option is used twice, the second will again
disable this.
--ftp-ssl-ccc
(FTP) Use CCC (Clear Command Channel) Shuts down
the SSL/TLS layer after authenticating. The rest of
the control channel communication will be unen-
crypted. This allows NAT routers to follow the FTP
transaction. The default mode is passive. See
--ftp-ssl-ccc-mode for other modes. (Added in
7.16.1)
If this option is used twice, the second will again
disable this.
--ftp-ssl-ccc-mode [active/passive]
(FTP) Use CCC (Clear Command Channel) Sets the CCC
mode. The passive mode will not initiate the shut-
down, but instead wait for the server to do it, and
will not reply to the shutdown from the server. The
active mode initiates the shutdown and waits for a
reply from the server. (Added in 7.16.2)
-F/--form
(HTTP) This lets curl emulate a filled in form in
which a user has pressed the submit button. This
causes curl to POST data using the Content-Type
multipart/form-data according to RFC1867. This
enables uploading of binary files etc. To force the
'content' part to be a file, prefix the file name
with an @ sign. To just get the content part from a
file, prefix the file name with the letter <. The
difference between @ and < is then that @ makes a
file get attached in the post as a file upload,
while the < makes a text field and just get the
contents for that text field from a file.
Example, to send your password file to the server,
where 'password' is the name of the form-field to
which /etc/passwd will be the input:
curl -F password=@/etc/passwd www.mypasswords.com
To read the file's content from stdin instead of a
file, use - where the file name should've been.
This goes for both @ and < constructs.
You can also tell curl what Content-Type to use by
using 'type=', in a manner similar to:
curl -F "web=@index.html;type=text/html" url.com
or
curl -F "name=daniel;type=text/foo" url.com
You can also explicitly change the name field of an
file upload part by setting filename=, like this:
curl -F "file=@localfile;filename=nameinpost"
url.com
See further examples and details in the MANUAL.
This option can be used multiple times.
--form-string
(HTTP) Similar to --form except that the value
string for the named parameter is used literally.
Leading '@' and '<' characters, and the ';type='
string in the value have no special meaning. Use
this in preference to --form if there's any possi-
bility that the string value may accidentally trig-
ger the '@' or '<' features of --form.
-g/--globoff
This option switches off the "URL globbing parser".
When you set this option, you can specify URLs that
contain the letters {}[] without having them being
interpreted by curl itself. Note that these letters
are not normal legal URL contents but they should
be encoded according to the URI standard.
-G/--get
When used, this option will make all data specified
with -d/--data or --data-binary to be used in a
HTTP GET request instead of the POST request that
otherwise would be used. The data will be appended
to the URL with a '?' separator.
If used in combination with -I, the POST data will
instead be appended to the URL with a HEAD request.
If this option is used several times, the following
occurrences make no difference.
-h/--help
Usage help.
-H/--header
(HTTP) Extra header to use when getting a web page.
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 will be 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 headers
without knowing perfectly well what you're doing.
Remove an internal header by giving a replacement
without content on the right side of the colon, as
in: -H "Host:".
curl will make sure that each header you
add/replace get 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 will only mess things up for you.
See also the -A/--user-agent and -e/--referer
options.
This option can be used multiple times to
add/replace/remove multiple headers.
--ignore-content-length
(HTTP) Ignore the Content-Length header. This is
particularly useful for servers running Apache 1.x,
which will report incorrect Content-Length for
files larger than 2 gigabytes.
-i/--include
(HTTP) Include the HTTP-header in the output. The
HTTP-header includes things like server-name, date
of the document, HTTP-version and more...
If this option is used twice, the second will again
disable header include.
--interface
Perform an operation using a specified interface.
You can enter interface name, IP address or host
name. An example could look like:
curl --interface eth0:1 http://www.netscape.com/
If this option is used several times, the last one
will be used.
-I/--head
(HTTP/FTP/FILE) Fetch the HTTP-header only! HTTP-
servers feature the command HEAD which this uses to
get nothing but the header of a document. When used
on a FTP or FILE file, curl displays the file size
and last modification time only.
If this option is used twice, the second will again
disable header only.
-j/--junk-session-cookies
(HTTP) When curl is told to read cookies from a
given file, this option will make it discard all
"session cookies". This will basically have the
same effect as if a new session is started. Typical
browsers always discard session cookies when
they're closed down.
If this option is used several times, each occur-
rence will toggle this on/off.
-k/--insecure
(SSL) This option explicitly allows curl to perform
"insecure" SSL connections and transfers. All SSL
connections are attempted to be made secure by
using the CA certificate bundle installed by
default. This makes all connections considered
"insecure" to fail unless -k/--insecure is used.
See this online resource for further details:
http://curl.haxx.se/docs/sslcerts.html
If this option is used twice, the second time will
again disable it.
--key
(SSL/SSH) Private key file name. Allows you to pro-
vide your private key in this separate file.
If this option is used several times, the last one
will be used.
--key-type
(SSL) Private key file type. Specify which type
your --key provided private key is. DER, PEM and
ENG are supported. If not specified, PEM is
assumed.
If this option is used several times, the last one
will be used.
--krb4
(FTP) Enable kerberos4 authentication and use. The
level must be entered and should be one of 'clear',
'safe', 'confidential' or 'private'. Should you use
a level that is not one of these, 'private' will
instead be used.
This option requires that the library was built
with kerberos4 support. This is not very common.
Use -V/--version to see if your curl supports it.
If this option is used several times, the last one
will be used.
-K/--config
Specify which config file to read curl arguments
from. The config file is a text file in which com-
mand line arguments can be written which then will
be used as if they were written on the actual com-
mand line. Options and their parameters must be
specified on the same config file line. If the
parameter is to contain white spaces, the parameter
must be enclosed within quotes. If the first col-
umn of a config line is a '#' character, the rest
of the line will be treated as a comment. Only
write one option per physical line in the config
file.
Specify the filename to -K/--config as '-' to make
curl read the file from stdin.
Note that to be able to specify a URL in the config
file, you need to specify it using the --url
option, and not by simply writing the URL on its
own line. So, it could look similar to this:
url = "http://curl.haxx.se/docs/"
Long option names can optionally be given in the
config file without the initial double dashes.
When curl is invoked, it always (unless -q is used)
checks for a default config file and uses it if
found. The default config file is checked for in
the following places in this order:
1) curl tries to find the "home dir": It first
checks for the CURL_HOME and then the HOME environ-
ment variables. Failing that, it uses getpwuid() on
unix-like systems (which returns the home dir given
the current user in your system). On Windows, it
then checks for the APPDATA variable, or as a last
resort the '%USERPROFILE%0lication Data'.
2) On windows, if there is no _curlrc file in the
home dir, it checks for one in the same dir the
executable curl is placed. On unix-like systems, it
will simply try to load .curlrc from the determined
home dir.
# --- Example file ---
# this is a comment
url = "curl.haxx.se"
output = "curlhere.html"
user-agent = "superagent/1.0"
# and fetch another URL too
url = "curl.haxx.se/docs/manpage.html"
-O
referer = "http://nowhereatall.com/"
# --- End of example file ---
This option can be used multiple times to load mul-
tiple config files.
--libcurl
Append this option to any ordinary curl command
line, and you will get a libcurl-using source code
written to the file that does the equivalent opera-
tion of what your command line operation does!
If this option is used several times, the last
given file name will be used.
--limit-rate
Specify the maximum transfer rate you want curl to
use. This feature is useful if you have a limited
pipe and you'd like your transfer not use your
entire bandwidth.
The given speed is measured in bytes/second, unless
a suffix is appended. Appending 'k' or 'K' will
count the number as kilobytes, 'm' or M' makes it
megabytes while 'g' or 'G' makes it gigabytes.
Examples: 200K, 3m and 1G.
The given rate is the average speed, counted during
the entire transfer. It means that curl might use
higher transfer speeds in short bursts, but over
time it uses no more than the given rate.
If you are also using the -Y/--speed-limit option,
that option will take precedence and might cripple
the rate-limiting slightly, to help keeping the
speed-limit logic working.
If this option is used several times, the last one
will be used.
-l/--list-only
(FTP) When listing an FTP directory, this switch
forces a name-only view. Especially useful if you
want to machine-parse the contents of an FTP direc-
tory since the normal directory view doesn't use a
standard look or format.
This option causes an FTP NLST command to be sent.
Some FTP servers list only files in their response
to NLST; they do not include subdirectories and
symbolic links.
If this option is used twice, the second will again
disable list only.
--local-port [-num]
Set a prefered number or range of local port num-
bers to use for the connection(s). Note that port
numbers by nature is a scarce resource that will be
busy at times so setting this range to something
too narrow might cause unnecessary connection setup
failures. (Added in 7.15.2)
-L/--location
(HTTP/HTTPS) If the server reports that the
requested page has moved to a different location
(indicated with a Location: header and a 3XX
response code) this option will make curl redo the
request on the new place. If used together with
-i/--include or -I/--head, headers from all
requested pages will be shown. When authentication
is used, curl only sends its credentials to the
initial host. If a redirect takes curl to a differ-
ent host, it won't be able to intercept the
user+password. See also --location-trusted on how
to change this. You can limit the amount of redi-
rects to follow by using the --max-redirs option.
If this option is used twice, the second will again
disable location following.
--location-trusted
(HTTP/HTTPS) Like -L/--location, but will allow
sending the name + password to all hosts that the
site may redirect to. This may or may not introduce
a security breach if the site redirects you do a
site to which you'll send your authentication info
(which is plaintext in the case of HTTP Basic
authentication).
If this option is used twice, the second will again
disable location following.
--max-filesize
Specify the maximum size (in bytes) of a file to
download. If the file requested is larger than this
value, the transfer will not start and curl will
return with exit code 63.
NOTE: The file size is not always known prior to
download, and for such files this option has no
effect even if the file transfer ends up being
larger than this given limit. This concerns both
FTP and HTTP transfers.
-m/--max-time
Maximum time in seconds that you allow the whole
operation to take. This is useful for preventing
your batch jobs from hanging for hours due to slow
networks or links going down. See also the --con-
nect-timeout option.
If this option is used several times, the last one
will be used.
-M/--manual
Manual. Display the huge help text.
-n/--netrc
Makes curl scan the .netrc file in the user's home
directory for login name and password. This is typ-
ically used for ftp on unix. If used with http,
curl will enable user authentication. See netrc(4)
or ftp(1) for details on the file format. Curl will
not complain if that file hasn't the right permis-
sions (it should not be world nor group readable).
The environment variable "HOME" is used to find the
home directory.
A quick and very simple example of how to setup a
.netrc to allow curl to ftp to the machine
host.domain.com with user name 'myself' and pass-
word 'secret' should look similar to:
machine host.domain.com login myself password
secret
If this option is used twice, the second will again
disable netrc usage.
--netrc-optional
Very similar to --netrc, but this option makes the
.netrc usage optional and not mandatory as the
--netrc does.
--negotiate
(HTTP) Enables GSS-Negotiate authentication. The
GSS-Negotiate method was designed by Microsoft and
is used in their web applications. It is primarily
meant as a support for Kerberos5 authentication but
may be also used along with another authentication
methods. For more information see IETF draft draft-
brezak-spnego-http-04.txt.
This option requires that the library was built
with GSSAPI support. This is not very common. Use
-V/--version to see if your version supports GSS-
Negotiate.
When using this option, you must also provide a
fake -u/--user option to activate the authentica-
tion code properly. Sending a '-u :' is enough as
the user name and password from the -u option
aren't actually used.
If this option is used several times, the following
occurrences make no difference.
-N/--no-buffer
Disables the buffering of the output stream. In
normal work situations, curl will use a standard
buffered output stream that will have the effect
that it will output the data in chunks, not neces-
sarily exactly when the data arrives. Using this
option will disable that buffering.
If this option is used twice, the second will again
switch on buffering.
--no-sessionid
(SSL) Disable curl's use of SSL session-ID caching.
By default all transfers are done using the cache.
Note that while nothing ever should get hurt by
attempting to reuse SSL session-IDs, there seem to
be broken SSL implementations in the wild that may
require you to disable this in order for you to
succeed. (Added in 7.16.0)
If this option is used twice, the second will again
switch on use of the session cache.
--ntlm (HTTP) Enables NTLM authentication. The NTLM
authentication method was designed by Microsoft and
is used by IIS web servers. It is a proprietary
protocol, reversed engineered by clever people and
implemented 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 authenti-
cation, then use --proxy-ntlm.
This option requires that the library was built
with SSL support. Use -V/--version to see if your
curl supports NTLM.
If this option is used several times, the following
occurrences make no difference.
-o/--output
Write output to instead of stdout. If you
are using {} or [] to fetch multiple documents, you
can use '#' followed by a number in the
specifier. That variable will be replaced with the
current string for the URL being fetched. Like in:
curl http://{one,two}.site.com -o "file_#1.txt"
or use several variables like:
curl http://{site,host}.host[1-5].com -o "#1_#2"
You may use this option as many times as you have
number of URLs.
See also the --create-dirs option to create the
local directories dynamically.
-O/--remote-name
Write output to a local file named like the remote
file we get. (Only the file part of the remote file
is used, the path is cut off.)
The remote file name to use for saving is extracted
from the given URL, nothing else.
You may use this option as many times as you have
number of URLs.
--pass
(SSL/SSH) Pass phrase for the private key
If this option is used several times, the last one
will be used.
--proxy-anyauth
Tells curl to pick a suitable authentication method
when communicating with the given proxy. This will
cause an extra request/response round-trip. (Added
in 7.13.2)
If this option is used twice, the second will again
disable the proxy use-any authentication.
--proxy-basic
Tells curl to use HTTP Basic authentication when
communicating with the given proxy. Use --basic for
enabling HTTP Basic with a remote host. Basic is
the default authentication method curl uses with
proxies.
If this option is used twice, the second will again
disable proxy HTTP Basic authentication.
--proxy-digest
Tells curl to use HTTP Digest authentication when
communicating with the given proxy. Use --digest
for enabling HTTP Digest with a remote host.
If this option is used twice, the second will again
disable proxy HTTP Digest.
--proxy-ntlm
Tells curl to use HTTP NTLM authentication when
communicating with the given proxy. Use --ntlm for
enabling NTLM with a remote host.
If this option is used twice, the second will again
disable proxy HTTP NTLM.
-p/--proxytunnel
When an HTTP proxy is used (-x/--proxy), this
option will cause non-HTTP protocols to attempt to
tunnel through the proxy instead of merely using it
to do HTTP-like operations. The tunnel approach is
made with the HTTP proxy CONNECT request and
requires that the proxy allows direct connect to
the remote port number curl wants to tunnel through
to.
If this option is used twice, the second will again
disable proxy tunnel.
--pubkey
(SSH) Public key file name. Allows you to provide
your public key in this separate file.
If this option is used several times, the last one
will be used.
-P/--ftp-port
(FTP) Reverses the initiator/listener roles when
connecting with ftp. This switch makes Curl use the
PORT command instead of PASV. In practice, PORT
tells the server to connect to the client's speci-
fied address and port, while PASV asks the server
for an ip address and port to connect to.
should be one of:
interface
i.e "eth0" to specify which interface's IP
address you want to use (Unix only)
IP address
i.e "192.168.10.1" to specify exact IP num-
ber
host name
i.e "my.host.domain" to specify machine
- make curl pick the same IP address that is
already used for the control connection
If this option is used several times, the last one will be
used. Disable the use of PORT with --ftp-pasv. Disable the
attempt to use the EPRT command instead of PORT by using
--disable-eprt. EPRT is really PORT++.
-q If used as the first parameter on the command line,
the curlrc config file will not be read and used.
See the -K/--config for details on the default con-
fig file search path.
-Q/--quote
(FTP) Send an arbitrary command to the remote FTP
server. Quote commands are sent BEFORE the transfer
is taking place (just after the initial PWD command
to be exact). To make commands take place after a
successful transfer, prefix them with a dash '-'.
To make commands get sent after libcurl has changed
working directory, just before the transfer com-
mand(s), prefix the command with '+'. You may spec-
ify any amount of commands. If the server returns
failure for one of the commands, the entire opera-
tion will be aborted. You must send syntactically
correct FTP commands as RFC959 defines.
This option can be used multiple times.
--random-file
(SSL) Specify the path name to file containing what
will be considered as random data. The data is used
to seed the random engine for SSL connections. See
also the --egd-file option.
-r/--range
(HTTP/FTP) Retrieve a byte range (i.e a partial
document) from a HTTP/1.1 or FTP server. Ranges can
be specified in a number of ways.
0-499 specifies the first 500 bytes
500-999 specifies the second 500 bytes
-500 specifies the last 500 bytes
9500- specifies the bytes from offset 9500 and
forward
0-0,-1 specifies the first and last byte
only(*)(H)
500-700,600-799
specifies 300 bytes from offset 500(H)
100-199,500-599
specifies two separate 100 bytes
ranges(*)(H)
(*) = NOTE that this will cause the server to reply with a
multipart response!
You should also be aware that many HTTP/1.1 servers do not
have this feature enabled, so that when you attempt to get
a range, you'll instead get the whole document.
FTP range downloads only support the simple syntax 'start-
stop' (optionally with one of the numbers omitted). It
depends on the non-RFC command SIZE.
If this option is used several times, the last one will be
used.
--raw When used, it disables all internal HTTP decoding
of content or transfer encodings and instead makes
them passed on unaltered, raw. (Added in 7.16.2)
If this option is used several times, each occur-
rence toggles this on/off.
-R/--remote-time
When used, this will make libcurl attempt to figure
out the timestamp of the remote file, and if that
is available make the local file get that same
timestamp.
If this option is used twice, the second time dis-
ables this again.
--retry
If a transient error is returned when curl tries to
perform a transfer, it will retry this number of
times before giving up. Setting the number to 0
makes curl do no retries (which is the default).
Transient error means either: a timeout, an FTP 5xx
response code or an HTTP 5xx response code.
When curl is about to retry a transfer, it will
first wait one second and then for all forthcoming
retries it will double the waiting time until it
reaches 10 minutes which then will be the delay
between the rest of the retries. By using --retry-
delay you disable this exponential backoff algo-
rithm. See also --retry-max-time to limit the total
time allowed for retries. (Added in 7.12.3)
If this option is used multiple times, the last
occurrence decide the amount.
--retry-delay
Make curl sleep this amount of time between each
retry when a transfer has failed with a transient
error (it changes the default backoff time algo-
rithm between retries). This option is only inter-
esting if --retry is also used. Setting this delay
to zero will make curl use the default backoff
time. (Added in 7.12.3)
If this option is used multiple times, the last
occurrence decide the amount.
--retry-max-time
The retry timer is reset before the first transfer
attempt. Retries will be done as usual (see
--retry) as long as the timer hasn't reached this
given limit. Notice that if the timer hasn't
reached the limit, the request will be made and
while performing, it may take longer than this
given time period. To limit a single request's max-
imum time, use -m/--max-time. Set this option to
zero to not timeout retries. (Added in 7.12.3)
If this option is used multiple times, the last
occurrence decide the amount.
-s/--silent
Silent mode. Don't show progress meter or error
messages. Makes Curl mute.
If this option is used twice, the second will again
disable silent mode.
-S/--show-error
When used with -s it makes curl show error message
if it fails.
If this option is used twice, the second will again
disable show error.
--socks4
Use the specified SOCKS4 proxy. If the port number
is not specified, it is assumed at port 1080.
(Added in 7.15.2)
This option overrides any previous use of
-x/--proxy, as they are mutually exclusive.
If this option is used several times, the last one
will be used.
--socks5
Use the specified SOCKS5 proxy. If the port number
is not specified, it is assumed at port 1080.
(Added in 7.11.1)
This option overrides any previous use of
-x/--proxy, as they are mutually exclusive.
If this option is used several times, the last one
will be used. (This option was previously wrongly
documented and used as --socks without the number
appended.)
--stderr
Redirect all writes to stderr to the specified file
instead. If the file name is a plain '-', it is
instead written to stdout. This option has no point
when you're using a shell with decent redirecting
capabilities.
If this option is used several times, the last one
will be used.
--tcp-nodelay
Turn on the TCP_NODELAY option. See the
curl_easy_setopt(3) man page for details about this
option. (Added in 7.11.2)
If this option is used several times, each occur-
rence toggles this on/off.
-t/--telnet-option
Pass options to the telnet protocol. Supported
options are:
TTYPE= Sets the terminal type.
XDISPLOC= Sets the X display location.
NEW_ENV= Sets an environment variable.
-T/--upload-file
This transfers the specified local file to the
remote URL. If there is no file part in the speci-
fied URL, Curl will append the local file name.
NOTE that you must use a trailing / on the last
directory to really prove to Curl that there is no
file name or curl will think that your last direc-
tory name is the remote file name to use. That will
most likely cause the upload operation to fail. If
this is used on a http(s) server, the PUT command
will be used.
Use the file name "-" (a single dash) to use stdin
instead of a given file.
You can specify one -T for each URL on the command
line. Each -T + URL pair specifies what to upload
and to where. curl also supports "globbing" of the
-T argument, meaning that you can upload multiple
files to a single URL by using the same URL glob-
bing style supported in the URL, like this:
curl -T "{file1,file2}" http://www.upload-
tothissite.com
or even
curl -T "img[1-1000].png" ftp://ftp.picturema-
nia.com/upload/
--trace
Enables a full trace dump of all incoming and out-
going data, including descriptive information, to
the given output file. Use "-" as filename to have
the output sent to stdout.
This option overrides previous uses of -v/--verbose
or --trace-ascii.
If this option is used several times, the last one
will be used.
--trace-ascii
Enables a full trace dump of all incoming and out-
going data, including descriptive information, to
the given output file. Use "-" as filename to have
the output sent to stdout.
This is very similar to --trace, but leaves out the
hex part and only shows the ASCII part of the dump.
It makes smaller output that might be easier to
read for untrained humans.
This option overrides previous uses of -v/--verbose
or --trace.
If this option is used several times, the last one
will be used.
--trace-time
Prepends a time stamp to each trace or verbose line
that curl displays. (Added in 7.14.0)
If this option is used several times, each occur-
rence will toggle it on/off.
-u/--user
Specify user and password to use for server authen-
tication. Overrides -n/--netrc and --netrc-
optional.
If you use an SSPI-enabled curl binary and do NTLM
autentication, you can force curl to pick up the
user name and password from your environment by
simply specifying a single colon with this option:
"-u :".
If this option is used several times, the last one
will be used.
-U/--proxy-user
Specify user and password to use for proxy authen-
tication.
If you use an SSPI-enabled curl binary and do NTLM
autentication, you can force curl to pick up the
user name and password from your environment by
simply specifying a single colon with this option:
"-U :".
If this option is used several times, the last one
will be used.
--url
Specify a URL to fetch. This option is mostly handy
when you want to specify URL(s) in a config file.
This option may be used any number of times. To
control where this URL is written, use the
-o/--output or the -O/--remote-name options.
-v/--verbose
Makes the fetching more verbose/talkative. Mostly
usable for debugging. Lines starting with '>' means
"header data" sent by curl, '<' means "header data"
received by curl that is hidden in normal cases and
lines starting with '*' means additional info pro-
vided by curl.
Note that if you only want HTTP headers in the out-
put, -i/--include might be option you're looking
for.
If you think this option still doesn't give you
enough details, consider using --trace or --trace-
ascii instead.
This option overrides previous uses of --trace-
ascii or --trace.
If this option is used twice, the second will do
nothing extra.
-V/--version
Displays information about curl and the libcurl
version it uses.
The first line includes the full version of curl,
libcurl and other 3rd party libraries linked with
the executable.
The second line (starts with "Protocols:") shows
all protocols that libcurl reports to support.
The third line (starts with "Features:") shows spe-
cific features libcurl reports to offer. Available
features include:
IPv6 You can use IPv6 with this.
krb4 Krb4 for ftp is supported.
SSL HTTPS and FTPS are supported.
libz Automatic decompression of compressed files
over HTTP is supported.
NTLM NTLM authentication is supported.
GSS-Negotiate
Negotiate authentication is supported.
Debug This curl uses a libcurl built with Debug.
This enables more error-tracking and memory
debugging etc. For curl-developers only!
AsynchDNS
This curl uses asynchronous name resolves.
SPNEGO SPNEGO Negotiate authentication is sup-
ported.
Largefile
This curl supports transfers of large files,
files larger than 2GB.
IDN This curl supports IDN - international
domain names.
SSPI SSPI is supported. If you use NTLM and set a
blank user name, curl will authenticate with
your current user and password.
-w/--write-out
Defines what to display on stdout after a completed
and successful operation. The format is a string
that may contain plain text mixed with any number
of variables. The string can be specified as
"string", to get read from a particular file you
specify it "@filename" and to tell curl to read the
format from stdin you write "@-".
The variables present in the output format will be
substituted by the value or text that curl thinks
fit, as described below. All variables are speci-
fied like %{variable_name} and to output a normal %
you just write them like %%. You can output a new-
line by using \n, a carriage return with \r and a
tab space with \t.
NOTE: The %-letter is a special letter in the
win32-environment, where all occurrences of % must
be doubled when using this option.
Available variables are at this point:
url_effective The URL that was fetched last. This
is mostly meaningful if you've told
curl to follow location: headers.
http_code The numerical code that was found in
the last retrieved HTTP(S) page.
http_connect The numerical code that was found in
the last response (from a proxy) to
a curl CONNECT request. (Added in
7.12.4)
time_total The total time, in seconds, that the
full operation lasted. The time will
be displayed with millisecond reso-
lution.
time_namelookup
The time, in seconds, it took from
the start until the name resolving
was completed.
time_connect The time, in seconds, it took from
the start until the connect to the
remote host (or proxy) was com-
pleted.
time_pretransfer
The time, in seconds, it took from
the start until the file transfer is
just about to begin. This includes
all pre-transfer commands and nego-
tiations that are specific to the
particular protocol(s) involved.
time_redirect The time, in seconds, it took for
all redirection steps include name
lookup, connect, pretransfer and
transfer before final transaction
was started. time_redirect shows the
complete execution time for multiple
redirections. (Added in 7.12.3)
time_starttransfer
The time, in seconds, it took from
the start until the first byte is
just about to be transferred. This
includes time_pretransfer and also
the time the server needs to calcu-
late the result.
size_download The total amount of bytes that were
downloaded.
size_upload The total amount of bytes that were
uploaded.
size_header The total amount of bytes of the
downloaded headers.
size_request The total amount of bytes that were
sent in the HTTP request.
speed_download The average download speed that curl
measured for the complete download.
speed_upload The average upload speed that curl
measured for the complete upload.
content_type The Content-Type of the requested
document, if there was any.
num_connects Number of new connects made in the
recent transfer. (Added in 7.12.3)
num_redirects Number of redirects that were fol-
lowed in the request. (Added in
7.12.3)
ftp_entry_path The initial path libcurl ended up in
when logging on to the remote FTP
server. (Added in 7.15.4)
If this option is used several times, the last one will be
used.
-x/--proxy
Use specified HTTP proxy. If the port number is not
specified, it is assumed at port 1080.
This option overrides existing environment vari-
ables that sets proxy to use. If there's an envi-
ronment variable setting a proxy, you can set proxy
to "" to override it.
Note that all operations that are performed over a
HTTP proxy will transparently be converted to HTTP.
It means that certain protocol specific operations
might not be available. This is not the case if you
can tunnel through the proxy, as done with the
-p/--proxytunnel option.
Starting with 7.14.1, the proxy host can be speci-
fied the exact same way as the proxy environment
variables, include protocol prefix (http://) and
embedded user + password.
If this option is used several times, the last one
will be used.
-X/--request
(HTTP) Specifies a custom request method to use
when communicating with the HTTP server. The spec-
ified request will be used instead of the method
otherwise used (which defaults to GET). Read the
HTTP 1.1 specification for details and explana-
tions.
(FTP) Specifies a custom FTP command to use instead
of LIST when doing file lists with ftp.
If this option is used several times, the last one
will be used.
-y/--speed-time