curl.1

.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2007, 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 http://curl.haxx.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.
.\" *
.\" * $Id$
.\" **************************************************************************
.\"
.TH curl 1 "28 Feb 2007" "Curl 7.16.2" "Curl Manual"
.SH NAME
curl \- transfer a URL
.SH SYNOPSIS
.B curl [options]
.I [URL...]
.SH DESCRIPTION
.B 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 connections, 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 features. See
.BR libcurl (3)
for details.
.SH 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 leading 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 specified order.

Since curl 7.15.1 you can also specify step counter for the ranges, so that
you can get every Nth number or letter:

 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.
.SH "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
\fIdisables\fP 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, \fI-#\fP is your
friend.
.SH OPTIONS
.IP "-a/--append"
(FTP) When used in an FTP upload, this will tell curl to append to the target
file instead of overwriting 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.
.IP "-A/--user-agent <agent string>"
(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 \fI-H/--header\fP option of course.

If this option is set more than once, the last one will be the one that's
used.
.IP "--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 authentication
method, which you can do with \fI--basic\fP, \fI--digest\fP, \fI--ntlm\fP, and
\fI--negotiate\fP.

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.
.IP "-b/--cookie <name=data>"
(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 activates the "cookie parser" which will
make curl record incoming cookies too, which may be handy if you're using this
in combination with the \fI-L/--location\fP option. The file format of the
file to read cookies from should be plain HTTP headers or the Netscape/Mozilla
cookie file format.

\fBNOTE\fP that the file specified with \fI-b/--cookie\fP is only used as
input. No cookies will be stored in the file. To store cookies, use the
\fI-c/--cookie-jar\fP option or you could even save the HTTP headers to a file
using \fI-D/--dump-header\fP!

If this option is set more than once, the last one will be the one that's
used.
.IP "-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.
.IP "--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 previously
set option that sets a different authentication method (such as \fI--ntlm\fP,
\fI--digest\fP and \fI--negotiate\fP).

If this option is used several times, the following occurrences make no
difference.
.IP "--ciphers <list of ciphers>"
(SSL) Specifies which ciphers to use in the connection. The list of ciphers
must be using valid ciphers. Read up on SSL cipher list details on this URL:
\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP

NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of
NSS ciphers is in the NSSCipherSuite entry at this URL:
\fIhttp://directory.fedora.redhat.com/docs/mod_nss.html#Directives\fP

If this option is used several times, the last one will override the others.
.IP "--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 occurrence will toggle it on/off.
.IP "--connect-timeout <seconds>"
Maximum time in seconds that you allow the connection 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 \fI-m/--max-time\fP option.

If this option is used several times, the last one will be used.
.IP "-c/--cookie-jar <file name>"
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.

.B 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 warning
displayed, but that is the only visible feedback you get about this possibly
lethal situation.