123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254 |
- .\" **************************************************************************
- .\" * _ _ ____ _
- .\" * 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 will be 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 re-use 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 re-use 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]/"
- .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
- Starting in curl 8.3.0, curl supports command line variables. 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, will 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
- will work.
- .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.
- 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
- will retain their values and meaning even after --next.
- The following options are global:
- %GLOBALS.
|