1curl(1) Curl Manual curl(1)
2
6 curl - transfer a URL
7
9 curl [options / URLs]
10
12 curl is a tool for transfering data from or to a server. It supports
13 these protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS,
14 IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP,
15 SFTP, SMB, SMBS, SMTP, SMTPS, TELNET or TFTP. The command is designed
16 to work without user interaction.
17 curl offers a busload of useful tricks like proxy support, user authen‐
19 tication, FTP upload, HTTP post, SSL connections, cookies, file trans‐
20 fer resume and more. As you will see below, the number of features will
21 make your head spin!
22 curl is powered by libcurl for all transfer-related features. See
24 libcurl(3) for details.
25
27 The URL syntax is protocol-dependent. You'll find a detailed descrip‐
28 tion in RFC 3986.
29 You can specify multiple URLs or parts of URLs by writing part sets
31 within braces and quoting the URL as in:
32 "http://site.{one,two,three}.com"
34 or you can get sequences of alphanumeric series by using [] as in:
36 "ftp://ftp.example.com/file[1-100].txt"
38 "ftp://ftp.example.com/file[001-100].txt" (with leading zeros)
40 "ftp://ftp.example.com/file[a-z].txt"
42 Nested sequences are not supported, but you can use several ones next
44 to each other:
45 "http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html"
47 You can specify any amount of URLs on the command line. They will be
49 fetched in a sequential manner in the specified order. You can specify
50 command line options and URLs mixed and in any order on the command
51 line.
52 You can specify a step counter for the ranges to get every Nth number
54 or letter:
55 "http://example.com/file[1-100:10].txt"
57 "http://example.com/file[a-z:2].txt"
59 When using [] or {} sequences when invoked from a command line prompt,
61 you probably have to put the full URL within double quotes to avoid the
62 shell from interfering with it. This also goes for other characters
63 treated special, like for example '&', '?' and '*'.
64 Provide the IPv6 zone index in the URL with an escaped percentage sign
66 and the interface name. Like in
67 "http://[fe80::3%25eth0]/"
69 If you specify URL without protocol:// prefix, curl will attempt to
71 guess what protocol you might want. It will then default to HTTP but
72 try other protocols based on often-used host name prefixes. For exam‐
73 ple, for host names starting with "ftp." curl will assume you want to
74 speak FTP.
75 curl will do its best to use what you pass to it as a URL. It is not
77 trying to validate it as a syntactically correct URL by any means but
78 is instead very liberal with what it accepts.
79 curl will attempt to re-use connections for multiple file transfers, so
81 that getting many files from the same server will not do multiple con‐
82 nects / handshakes. This improves speed. Of course this is only done on
83 files specified on a single command line and cannot be used between
84 separate curl invocations.
85
87 If not told otherwise, curl writes the received data to stdout. It can
88 be instructed to instead save that data into a local file, using the
89 -o, --output or -O, --remote-name options. If curl is given multiple
90 URLs to transfer on the command line, it similarly needs multiple op‐
91 tions for where to save them.
92 curl does not parse or otherwise "understand" the content it gets or
94 writes as output. It does no encoding or decoding, unless explicitly
95 asked to with dedicated command line options.
96
98 curl supports numerous protocols, or put in URL terms: schemes. Your
99 particular build may not support them all.
100 DICT Lets you lookup words using online dictionaries.
102 FILE Read or write local files. curl does not support accessing
104 file:// URL remotely, but when running on Microsoft Windows us‐
105 ing the native UNC approach will work.
106 FTP(S) curl supports the File Transfer Protocol with a lot of tweaks
108 and levers. With or without using TLS.
109 GOPHER(S)
111 Retrieve files.
112 HTTP(S)
114 curl supports HTTP with numerous options and variations. It can
115 speak HTTP version 0.9, 1.0, 1.1, 2 and 3 depending on build op‐
116 tions and the correct command line options.
117 IMAP(S)
119 Using the mail reading protocol, curl can "download" emails for
120 you. With or without using TLS.
121 LDAP(S)
123 curl can do directory lookups for you, with or without TLS.
124 MQTT curl supports MQTT version 3. Downloading over MQTT equals "sub‐
126 scribe" to a topic while uploading/posting equals "publish" on a
127 topic. MQTT over TLS is not supported (yet).
128 POP3(S)
130 Downloading from a pop3 server means getting a mail. With or
131 without using TLS.
132 RTMP(S)
134 The Realtime Messaging Protocol is primarily used to server
135 streaming media and curl can download it.
136 RTSP curl supports RTSP 1.0 downloads.
138 SCP curl supports SSH version 2 scp transfers.
140 SFTP curl supports SFTP (draft 5) done over SSH version 2.
142 SMB(S) curl supports SMB version 1 for upload and download.
144 SMTP(S)
146 Uploading contents to an SMTP server means sending an email.
147 With or without TLS.
148 TELNET Telling curl to fetch a telnet URL starts an interactive session
150 where it sends what it reads on stdin and outputs what the
151 server sends it.
152 TFTP curl can do TFTP downloads and uploads.
154
156 curl normally displays a progress meter during operations, indicating
157 the amount of transferred data, transfer speeds and estimated time
158 left, etc. The progress meter displays number of bytes and the speeds
159 are in bytes per second. The suffixes (k, M, G, T, P) are 1024 based.
160 For example 1k is 1024 bytes. 1M is 1048576 bytes.
161 curl displays this data to the terminal by default, so if you invoke
163 curl to do an operation and it is about to write data to the terminal,
164 it disables the progress meter as otherwise it would mess up the output
165 mixing progress meter and response data.
166 If you want a progress meter for HTTP POST or PUT requests, you need to
168 redirect the response output to a file, using shell redirect (>), -o,
169 --output or similar.
170 This does not apply to FTP upload as that operation does not spit out
172 any response data to the terminal.
173 If you prefer a progress "bar" instead of the regular meter, -#,
175 --progress-bar is your friend. You can also disable the progress meter
176 completely with the -s, --silent option.
177
179 Options start with one or two dashes. Many of the options require an
180 additional value next to them.
181 The short "single-dash" form of the options, -d for example, may be
183 used with or without a space between it and its value, although a space
184 is a recommended separator. The long "double-dash" form, -d, --data for
185 example, requires a space between it and its value.
186 Short version options that don't need any additional values can be used
188 immediately next to each other, like for example you can specify all
189 the options -O, -L and -v at once as -OLv.
190 In general, all boolean options are enabled with --option and yet again
192 disabled with --no-option. That is, you use the exact same option name
193 but prefix it with "no-". However, in this list we mostly only list and
194 show the --option version of them. (This concept with --no options was
195 added in 7.19.0. Previously most options were toggled on/off through
196 repeated use of the same command line option.)
197 --abstract-unix-socket <path>
199 (HTTP) Connect through an abstract Unix domain socket, instead
200 of using the network. Note: netstat shows the path of an ab‐
201 stract socket prefixed with '@', however the <path> argument
202 should not have this leading character.
203 Example:
205 curl --abstract-unix-socket socketpath https://example.com
206 Added in 7.53.0.
208 --alt-svc <file name>
210 (HTTPS) This option enables the alt-svc parser in curl. If the
211 file name points to an existing alt-svc cache file, that will be
212 used. After a completed transfer, the cache will be saved to the
213 file name again if it has been modified.
214 Specify a "" file name (zero length) to avoid loading/saving and
216 make curl just handle the cache in memory.
217 If this option is used several times, curl will load contents
219 from all the files but the last one will be used for saving.
220 Example:
222 curl --alt-svc svc.txt https://example.com
223 Added in 7.64.1.
225 --anyauth
227 (HTTP) Tells curl to figure out authentication method by itself,
228 and use the most secure one the remote site claims to support.
229 This is done by first doing a request and checking the response-
230 headers, thus possibly inducing an extra network round-trip.
231 This is used instead of setting a specific authentication
232 method, which you can do with --basic, --digest, --ntlm, and
233 --negotiate.
234 Using --anyauth is not recommended if you do uploads from stdin,
236 since it may require data to be sent twice and then the client
237 must be able to rewind. If the need should arise when uploading
238 from stdin, the upload operation will fail.
239 Used together with -u, --user.
241 Example:
243 curl --anyauth --user me:pwd https://example.com
244 See also --proxy-anyauth, --basic and --digest.
246 -a, --append
248 (FTP SFTP) When used in an upload, this makes curl append to the
249 target file instead of overwriting it. If the remote file
250 doesn't exist, it will be created. Note that this flag is ig‐
251 nored by some SFTP servers (including OpenSSH).
252 Example:
254 curl --upload-file local --append ftp://example.com/
255 --aws-sigv4 <provider1[:provider2[:region[:service]]]>
257 Use AWS V4 signature authentication in the transfer.
258 The provider argument is a string that is used by the algorithm
260 when creating outgoing authentication headers.
261 The region argument is a string that points to a geographic area
263 of a resources collection (region-code) when the region name is
264 omitted from the endpoint.
265 The service argument is a string that points to a function pro‐
267 vided by a cloud (service-code) when the service name is omitted
268 from the endpoint.
269 Example:
271 curl --aws-sigv4 "aws:amz:east-2:es" --user "key:secret" https://example.com
272 Added in 7.75.0.
274 --basic
276 (HTTP) Tells curl to use HTTP Basic authentication with the re‐
277 mote host. This is the default and this option is usually point‐
278 less, unless you use it to override a previously set option that
279 sets a different authentication method (such as --ntlm, --di‐
280 gest, or --negotiate).
281 Used together with -u, --user.
283 Example:
285 curl -u name:password --basic https://example.com
286 See also --proxy-basic.
288 --cacert <file>
290 (TLS) Tells curl to use the specified certificate file to verify
291 the peer. The file may contain multiple CA certificates. The
292 certificate(s) must be in PEM format. Normally curl is built to
293 use a default file for this, so this option is typically used to
294 alter that default file.
295 curl recognizes the environment variable named 'CURL_CA_BUNDLE'
297 if it is set, and uses the given path as a path to a CA cert
298 bundle. This option overrides that variable.
299 The windows version of curl will automatically look for a CA
301 certs file named ´curl-ca-bundle.crt´, either in the same direc‐
302 tory as curl.exe, or in the Current Working Directory, or in any
303 folder along your PATH.
304 If curl is built against the NSS SSL library, the NSS PEM
306 PKCS#11 module (libnsspem.so) needs to be available for this op‐
307 tion to work properly.
308 (iOS and macOS only) If curl is built against Secure Transport,
310 then this option is supported for backward compatibility with
311 other SSL engines, but it should not be set. If the option is
312 not set, then curl will use the certificates in the system and
313 user Keychain to verify the peer, which is the preferred method
314 of verifying the peer's certificate chain.
315 (Schannel only) This option is supported for Schannel in Windows
317 7 or later with libcurl 7.60 or later. This option is supported
318 for backward compatibility with other SSL engines; instead it is
319 recommended to use Windows' store of root certificates (the de‐
320 fault for Schannel).
321 If this option is used several times, the last one will be used.
323 Example:
325 curl --cacert CA-file.txt https://example.com
326 --capath <dir>
328 (TLS) Tells curl to use the specified certificate directory to
329 verify the peer. Multiple paths can be provided by separating
330 them with ":" (e.g. "path1:path2:path3"). The certificates must
331 be in PEM format, and if curl is built against OpenSSL, the di‐
332 rectory must have been processed using the c_rehash utility sup‐
333 plied with OpenSSL. Using --capath can allow OpenSSL-powered
334 curl to make SSL-connections much more efficiently than using
335 --cacert if the --cacert file contains many CA certificates.
336 If this option is set, the default capath value will be ignored,
338 and if it is used several times, the last one will be used.
339 Example:
341 curl --capath /local/directory https://example.com
342 --cert-status
344 (TLS) Tells curl to verify the status of the server certificate
345 by using the Certificate Status Request (aka. OCSP stapling) TLS
346 extension.
347 If this option is enabled and the server sends an invalid (e.g.
349 expired) response, if the response suggests that the server cer‐
350 tificate has been revoked, or no response at all is received,
351 the verification fails.
352 This is currently only implemented in the OpenSSL, GnuTLS and
354 NSS backends.
355 Example:
357 curl --cert-status https://example.com
358 Added in 7.41.0.
360 --cert-type <type>
362 (TLS) Tells curl what type the provided client certificate is
363 using. PEM, DER, ENG and P12 are recognized types. If not spec‐
364 ified, PEM is assumed.
365 If this option is used several times, the last one will be used.
367 Example:
369 curl --cert-type PEM --cert file https://example.com
370 See also -E, --cert, --key and --key-type.
372 -E, --cert <certificate[:password]>
374 (TLS) Tells curl to use the specified client certificate file
375 when getting a file with HTTPS, FTPS or another SSL-based proto‐
376 col. The certificate must be in PKCS#12 format if using Secure
377 Transport, or PEM format if using any other engine. If the op‐
378 tional password isn't specified, it will be queried for on the
379 terminal. Note that this option assumes a "certificate" file
380 that is the private key and the client certificate concatenated!
381 See -E, --cert and --key to specify them independently.
382 If curl is built against the NSS SSL library then this option
384 can tell curl the nickname of the certificate to use within the
385 NSS database defined by the environment variable SSL_DIR (or by
386 default /etc/pki/nssdb). If the NSS PEM PKCS#11 module (lib‐
387 nsspem.so) is available then PEM files may be loaded. If you
388 want to use a file from the current directory, please precede it
389 with "./" prefix, in order to avoid confusion with a nickname.
390 If the nickname contains ":", it needs to be preceded by "\" so
391 that it is not recognized as password delimiter. If the nick‐
392 name contains "\", it needs to be escaped as "\\" so that it is
393 not recognized as an escape character.
394 If curl is built against OpenSSL library, and the engine pkcs11
396 is available, then a PKCS#11 URI (RFC 7512) can be used to spec‐
397 ify a certificate located in a PKCS#11 device. A string begin‐
398 ning with "pkcs11:" will be interpreted as a PKCS#11 URI. If a
399 PKCS#11 URI is provided, then the --engine option will be set as
400 "pkcs11" if none was provided and the --cert-type option will be
401 set as "ENG" if none was provided.
402 (iOS and macOS only) If curl is built against Secure Transport,
404 then the certificate string can either be the name of a certifi‐
405 cate/private key in the system or user keychain, or the path to
406 a PKCS#12-encoded certificate and private key. If you want to
407 use a file from the current directory, please precede it with
408 "./" prefix, in order to avoid confusion with a nickname.
409 (Schannel only) Client certificates must be specified by a path
411 expression to a certificate store. (Loading PFX is not sup‐
412 ported; you can import it to a store first). You can use "<store
413 location>\<store name>\<thumbprint>" to refer to a certificate
414 in the system certificates store, for example, "Curren‐
415 tUser\MY\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a". Thumbprint
416 is usually a SHA-1 hex string which you can see in certificate
417 details. Following store locations are supported: CurrentUser,
418 LocalMachine, CurrentService, Services, CurrentUserGroupPolicy,
419 LocalMachineGroupPolicy, LocalMachineEnterprise.
420 If this option is used several times, the last one will be used.
422 Example:
424 curl --cert certfile --key keyfile https://example.com
425 See also --cert-type, --key and --key-type.
427 --ciphers <list of ciphers>
429 (TLS) Specifies which ciphers to use in the connection. The list
430 of ciphers must specify valid ciphers. Read up on SSL cipher
431 list details on this URL:
432 https://curl.se/docs/ssl-ciphers.html
434 If this option is used several times, the last one will be used.
436 Example:
438 curl --ciphers ECDHE-ECDSA-AES256-CCM8 https://example.com
439 --compressed-ssh
441 (SCP SFTP) Enables built-in SSH compression. This is a request,
442 not an order; the server may or may not do it.
443 Example:
445 curl --compressed-ssh sftp://example.com/
446 Added in 7.56.0.
448 --compressed
450 (HTTP) Request a compressed response using one of the algorithms
451 curl supports, and automatically decompress the content. Headers
452 are not modified.
453 If this option is used and the server sends an unsupported en‐
455 coding, curl will report an error. This is a request, not an or‐
456 der; the server may or may not deliver data compressed.
457 Example:
459 curl --compressed https://example.com
460 -K, --config <file>
462 Specify a text file to read curl arguments from. The command
464 line arguments found in the text file will be used as if they
465 were provided on the command line.
466 Options and their parameters must be specified on the same line
468 in the file, separated by whitespace, colon, or the equals sign.
469 Long option names can optionally be given in the config file
470 without the initial double dashes and if so, the colon or equals
471 characters can be used as separators. If the option is specified
472 with one or two dashes, there can be no colon or equals charac‐
473 ter between the option and its parameter.
474 If the parameter contains whitespace (or starts with : or =),
476 the parameter must be enclosed within quotes. Within double
477 quotes, the following escape sequences are available: \\, \",
478 \t, \n, \r and \v. A backslash preceding any other letter is ig‐
479 nored.
480 If the first column of a config line is a '#' character, the
482 rest of the line will be treated as a comment.
483 Only write one option per physical line in the config file.
485 Specify the filename to -K, --config as '-' to make curl read
487 the file from stdin.
488 Note that to be able to specify a URL in the config file, you
490 need to specify it using the --url option, and not by simply
491 writing the URL on its own line. So, it could look similar to
492 this:
493 url = "https://curl.se/docs/"
495 When curl is invoked, it (unless -q, --disable is used) checks
497 for a default config file and uses it if found, even when this
498 option is used. The default config file is checked for in the
499 following places in this order:
500 1) Use the CURL_HOME environment variable if set
502 2) Use the XDG_CONFIG_HOME environment variable if set (Added in
504 7.73.0)
505 3) Use the HOME environment variable if set
507 4) Non-windows: use getpwuid to find the home directory
509 5) Windows: use APPDATA if set
511 6) Windows: use "USERPROFILE\Application Data" if set
513 7) On windows, if there is no .curlrc file in the home dir, it
515 checks for one in the same dir the curl executable is placed. On
516 Unix-like systems, it will simply try to load .curlrc from the
517 determined home dir.
518 # --- Example file ---
520 # this is a comment
521 url = "example.com"
522 output = "curlhere.html"
523 user-agent = "superagent/1.0"
524 # and fetch another URL too
526 url = "example.com/docs/manpage.html"
527 -O
528 referer = "http://nowhereatall.example.com/"
529 # --- End of example file ---
530 This option can be used multiple times to load multiple config
532 files.
533 Example:
535 curl --config file.txt https://example.com
536 --connect-timeout <fractional seconds>
538 Maximum time in seconds that you allow curl's connection to
539 take. This only limits the connection phase, so if curl con‐
540 nects within the given period it will continue - if not it will
541 exit. Since version 7.32.0, this option accepts decimal values.
542 If this option is used several times, the last one will be used.
544 Examples:
546 curl --connect-timeout 20 https://example.com
547 curl --connect-timeout 3.14 https://example.com
548 See also -m, --max-time.
550 --connect-to <HOST1:PORT1:HOST2:PORT2>
552 For a request to the given HOST1:PORT1 pair, connect to
554 HOST2:PORT2 instead. This option is suitable to direct requests
555 at a specific server, e.g. at a specific cluster node in a clus‐
556 ter of servers. This option is only used to establish the net‐
557 work connection. It does NOT affect the hostname/port that is
558 used for TLS/SSL (e.g. SNI, certificate verification) or for the
559 application protocols. "HOST1" and "PORT1" may be the empty
560 string, meaning "any host/port". "HOST2" and "PORT2" may also be
561 the empty string, meaning "use the request's original
562 host/port".
563 A "host" specified to this option is compared as a string, so it
565 needs to match the name used in request URL. It can be either
566 numerical such as "127.0.0.1" or the full host name such as "ex‐
567 ample.org".
568 This option can be used many times to add many connect rules.
570 Example:
572 curl --connect-to example.com:443:example.net:8443 https://example.com
573 See also --resolve and -H, --header. Added in 7.49.0.
575 -C, --continue-at <offset>
577 Continue/Resume a previous file transfer at the given offset.
578 The given offset is the exact number of bytes that will be
579 skipped, counting from the beginning of the source file before
580 it is transferred to the destination. If used with uploads, the
581 FTP server command SIZE will not be used by curl.
582 Use "-C -" to tell curl to automatically find out where/how to
584 resume the transfer. It then uses the given output/input files
585 to figure that out.
586 If this option is used several times, the last one will be used.
588 Examples:
590 curl -C - https://example.com
591 curl -C 400 https://example.com
592 See also -r, --range.
594 -c, --cookie-jar <filename>
596 (HTTP) Specify to which file you want curl to write all cookies
597 after a completed operation. Curl writes all cookies from its
598 in-memory cookie storage to the given file at the end of opera‐
599 tions. If no cookies are known, no data will be written. The
600 file will be written using the Netscape cookie file format. If
601 you set the file name to a single dash, "-", the cookies will be
602 written to stdout.
603 This command line option will activate the cookie engine that
605 makes curl record and use cookies. Another way to activate it is
606 to use the -b, --cookie option.
607 If the cookie jar can't be created or written to, the whole curl
609 operation won't fail or even report an error clearly. Using -v,
610 --verbose will get a warning displayed, but that is the only
611 visible feedback you get about this possibly lethal situation.
612 If this option is used several times, the last specified file
614 name will be used.
615 Examples:
617 curl -c store-here.txt https://example.com
618 curl -c store-here.txt -b read-these https://example.com
619 -b, --cookie <data|filename>
621 (HTTP) Pass the data to the HTTP server in the Cookie header. It
622 is supposedly the data previously received from the server in a
623 "Set-Cookie:" line. The data should be in the format
624 "NAME1=VALUE1; NAME2=VALUE2".
625 If no '=' symbol is used in the argument, it is instead treated
627 as a filename to read previously stored cookie from. This option
628 also activates the cookie engine which will make curl record in‐
629 coming cookies, which may be handy if you're using this in com‐
630 bination with the -L, --location option or do multiple URL
631 transfers on the same invoke. If the file name is exactly a mi‐
632 nus ("-"), curl will instead read the contents from stdin.
633 The file format of the file to read cookies from should be plain
635 HTTP headers (Set-Cookie style) or the Netscape/Mozilla cookie
636 file format.
637 The file specified with -b, --cookie is only used as input. No
639 cookies will be written to the file. To store cookies, use the
640 -c, --cookie-jar option.
641 If you use the Set-Cookie file format and don't specify a domain
643 then the cookie is not sent since the domain will never match.
644 To address this, set a domain in Set-Cookie line (doing that
645 will include sub-domains) or preferably: use the Netscape for‐
646 mat.
647 This option can be used multiple times.
649 Users very often want to both read cookies from a file and write
651 updated cookies back to a file, so using both -b, --cookie and
652 -c, --cookie-jar in the same command line is common.
653 Examples:
655 curl -b cookiefile https://example.com
656 curl -b cookiefile -c cookiefile https://example.com
657 --create-dirs
659 When used in conjunction with the -o, --output option, curl will
660 create the necessary local directory hierarchy as needed. This
661 option creates the directories mentioned with the -o, --output
662 option, nothing else. If the --output file name uses no direc‐
663 tory, or if the directories it mentions already exist, no direc‐
664 tories will be created.
665 Created dirs are made with mode 0750 on unix style file systems.
667 To create remote directories when using FTP or SFTP, try --ftp-
669 create-dirs.
670 Example:
672 curl --create-dirs --output local/dir/file https://example.com
673 --create-file-mode <mode>
675 (SFTP SCP FILE) When curl is used to create files remotely using
676 one of the supported protocols, this option allows the user to
677 set which 'mode' to set on the file at creation time, instead of
678 the default 0644.
679 This option takes an octal number as argument.
681 If this option is used several times, the last one will be used.
683 Example:
685 curl --create-file-mode 0777 -T localfile sftp://example.com/new
686 See also --ftp-create-dirs. Added in 7.75.0.
688 --crlf (FTP SMTP) Convert LF to CRLF in upload. Useful for MVS
690 (OS/390).
691 (SMTP added in 7.40.0)
693 Example:
695 curl --crlf -T file ftp://example.com/
696 --crlfile <file>
698 (TLS) Provide a file using PEM format with a Certificate Revoca‐
699 tion List that may specify peer certificates that are to be con‐
700 sidered revoked.
701 If this option is used several times, the last one will be used.
703 Example:
705 curl --crlfile rejects.txt https://example.com
706 Added in 7.19.7.
708 --curves <algorithm list>
710 (TLS) Tells curl to request specific curves to use during SSL
711 session establishment according to RFC 8422, 5.1. Multiple al‐
712 gorithms can be provided by separating them with ":" (e.g.
713 "X25519:P-521"). The parameter is available identically in the
714 "openssl s_client/s_server" utilities.
715 --curves allows a OpenSSL powered curl to make SSL-connections
717 with exactly the (EC) curve requested by the client, avoiding
718 intransparent client/server negotiations.
719 If this option is set, the default curves list built into
721 openssl will be ignored.
722 Example:
724 curl --curves X25519 https://example.com
725 Added in 7.73.0.
727 --data-ascii <data>
729 (HTTP) This is just an alias for -d, --data.
730 Example:
732 curl --data-ascii @file https://example.com
733 --data-binary <data>
735 (HTTP) This posts data exactly as specified with no extra pro‐
736 cessing whatsoever.
737 If you start the data with the letter @, the rest should be a
739 filename. Data is posted in a similar manner as -d, --data
740 does, except that newlines and carriage returns are preserved
741 and conversions are never done.
742 Like -d, --data the default content-type sent to the server is
744 application/x-www-form-urlencoded. If you want the data to be
745 treated as arbitrary binary data by the server then set the con‐
746 tent-type to octet-stream: -H "Content-Type: application/octet-
747 stream".
748 If this option is used several times, the ones following the
750 first will append data as described in -d, --data.
751 Example:
753 curl --data-binary @filename https://example.com
754 --data-raw <data>
756 (HTTP) This posts data similarly to -d, --data but without the
757 special interpretation of the @ character.
758 Examples:
760 curl --data-raw "hello" https://example.com
761 curl --data-raw "@at@at@" https://example.com
762 See also -d, --data. Added in 7.43.0.
764 --data-urlencode <data>
766 (HTTP) This posts data, similar to the other -d, --data options
767 with the exception that this performs URL-encoding.
768 To be CGI-compliant, the <data> part should begin with a name
770 followed by a separator and a content specification. The <data>
771 part can be passed to curl using one of the following syntaxes:
772 content
774 This will make curl URL-encode the content and pass that
775 on. Just be careful so that the content doesn't contain
776 any = or @ symbols, as that will then make the syntax
777 match one of the other cases below!
778 =content
780 This will make curl URL-encode the content and pass that
781 on. The preceding = symbol is not included in the data.
782 name=content
784 This will make curl URL-encode the content part and pass
785 that on. Note that the name part is expected to be URL-
786 encoded already.
787 @filename
789 This will make curl load data from the given file (in‐
790 cluding any newlines), URL-encode that data and pass it
791 on in the POST.
792 name@filename
794 This will make curl load data from the given file (in‐
795 cluding any newlines), URL-encode that data and pass it
796 on in the POST. The name part gets an equal sign ap‐
797 pended, resulting in name=urlencoded-file-content. Note
798 that the name is expected to be URL-encoded already.
799 Examples:
801 curl --data-urlencode name=val https://example.com
802 curl --data-urlencode =encodethis https://example.com
803 curl --data-urlencode name@file https://example.com
804 curl --data-urlencode @fileonly https://example.com
805 See also -d, --data and --data-raw. Added in 7.18.0.
807 -d, --data <data>
809 (HTTP MQTT) Sends the specified data in a POST request to the
810 HTTP server, in the same way that a browser does when a user has
811 filled in an HTML form and presses the submit button. This will
812 cause curl to pass the data to the server using the content-type
813 application/x-www-form-urlencoded. Compare to -F, --form.
814 --data-raw is almost the same but does not have a special inter‐
816 pretation of the @ character. To post data purely binary, you
817 should instead use the --data-binary option. To URL-encode the
818 value of a form field you may use --data-urlencode.
819 If any of these options is used more than once on the same com‐
821 mand line, the data pieces specified will be merged together
822 with a separating &-symbol. Thus, using '-d name=daniel -d
823 skill=lousy' would generate a post chunk that looks like
824 'name=daniel&skill=lousy'.
825 If you start the data with the letter @, the rest should be a
827 file name to read the data from, or - if you want curl to read
828 the data from stdin. Posting data from a file named 'foobar'
829 would thus be done with -d, --data @foobar. When -d, --data is
830 told to read from a file like that, carriage returns and new‐
831 lines will be stripped out. If you don't want the @ character to
832 have a special interpretation use --data-raw instead.
833 Examples:
835 curl -d "name=curl" https://example.com
836 curl -d "name=curl" -d "tool=cmdline" https://example.com
837 curl -d @filename https://example.com
838 See also --data-binary, --data-urlencode and --data-raw. This
840 option overrides -F, --form and -I, --head and -T, --upload-
841 file.
842 --delegation <LEVEL>
844 (GSS/kerberos) Set LEVEL to tell the server what it is allowed
845 to delegate when it comes to user credentials.
846 none Don't allow any delegation.
848 policy Delegates if and only if the OK-AS-DELEGATE flag is set
850 in the Kerberos service ticket, which is a matter of
851 realm policy.
852 always Unconditionally allow the server to delegate.
854 If this option is used several times, the last one will be used.
856 Example:
858 curl --delegation "none" https://example.com
859 --digest
861 (HTTP) Enables HTTP Digest authentication. This is an authenti‐
862 cation scheme that prevents the password from being sent over
863 the wire in clear text. Use this in combination with the normal
864 -u, --user option to set user name and password.
865 If this option is used several times, only the first one is
867 used.
868 Example:
870 curl -u name:password --digest https://example.com
871 See also -u, --user, --proxy-digest and --anyauth. This option
873 overrides --basic and --ntlm and --negotiate.
874 --disable-eprt
876 (FTP) Tell curl to disable the use of the EPRT and LPRT commands
877 when doing active FTP transfers. Curl will normally always first
878 attempt to use EPRT, then LPRT before using PORT, but with this
879 option, it will use PORT right away. EPRT and LPRT are exten‐
880 sions to the original FTP protocol, and may not work on all
881 servers, but they enable more functionality in a better way than
882 the traditional PORT command.
883 --eprt can be used to explicitly enable EPRT again and --no-eprt
885 is an alias for --disable-eprt.
886 If the server is accessed using IPv6, this option will have no
888 effect as EPRT is necessary then.
889 Disabling EPRT only changes the active behavior. If you want to
891 switch to passive mode you need to not use -P, --ftp-port or
892 force it with --ftp-pasv.
893 Example:
895 curl --disable-eprt ftp://example.com/
896 --disable-epsv
898 (FTP) Tell curl to disable the use of the EPSV command when do‐
899 ing passive FTP transfers. Curl will normally always first at‐
900 tempt to use EPSV before PASV, but with this option, it will not
901 try using EPSV.
902 --epsv can be used to explicitly enable EPSV again and --no-epsv
904 is an alias for --disable-epsv.
905 If the server is an IPv6 host, this option will have no effect
907 as EPSV is necessary then.
908 Disabling EPSV only changes the passive behavior. If you want to
910 switch to active mode you need to use -P, --ftp-port.
911 Example:
913 curl --disable-epsv ftp://example.com/
914 -q, --disable
916 If used as the first parameter on the command line, the curlrc
917 config file will not be read and used. See the -K, --config for
918 details on the default config file search path.
919 Example:
921 curl -q https://example.com
922 --disallow-username-in-url
924 (HTTP) This tells curl to exit if passed a url containing a
925 username. This is probably most useful when the URL is being
926 provided at run-time or similar.
927 Example:
929 curl --disallow-username-in-url https://example.com
930 See also --proto. Added in 7.61.0.
932 --dns-interface <interface>
934 (DNS) Tell curl to send outgoing DNS requests through <inter‐
935 face>. This option is a counterpart to --interface (which does
936 not affect DNS). The supplied string must be an interface name
937 (not an address).
938 Example:
940 curl --dns-interface eth0 https://example.com
941 See also --dns-ipv4-addr and --dns-ipv6-addr. --dns-interface
943 requires that the underlying libcurl was built to support c-
944 ares. Added in 7.33.0.
945 --dns-ipv4-addr <address>
947 (DNS) Tell curl to bind to <ip-address> when making IPv4 DNS re‐
948 quests, so that the DNS requests originate from this address.
949 The argument should be a single IPv4 address.
950 If this option is used several times, the last one will be used.
952 Example:
954 curl --dns-ipv4-addr 10.1.2.3 https://example.com
955 See also --dns-interface and --dns-ipv6-addr. --dns-ipv4-addr
957 requires that the underlying libcurl was built to support c-
958 ares. Added in 7.33.0.
959 --dns-ipv6-addr <address>
961 (DNS) Tell curl to bind to <ip-address> when making IPv6 DNS re‐
962 quests, so that the DNS requests originate from this address.
963 The argument should be a single IPv6 address.
964 If this option is used several times, the last one will be used.
966 Example:
968 curl --dns-ipv6-addr 2a04:4e42::561 https://example.com
969 See also --dns-interface and --dns-ipv4-addr. --dns-ipv6-addr
971 requires that the underlying libcurl was built to support c-
972 ares. Added in 7.33.0.
973 --dns-servers <addresses>
975 Set the list of DNS servers to be used instead of the system de‐
976 fault. The list of IP addresses should be separated with com‐
977 mas. Port numbers may also optionally be given as :<port-number>
978 after each IP address.
979 If this option is used several times, the last one will be used.
981 Example:
983 curl --dns-servers 192.168.0.1,192.168.0.2 https://example.com
984 --dns-servers requires that the underlying libcurl was built to
986 support c-ares. Added in 7.33.0.
987 --doh-cert-status
989 (all) Same as --cert-status but used for DoH (DNS-over-HTTPS).
990 Example:
992 curl --doh-cert-status --doh-url https://doh.example https://example.com
993 Added in 7.76.0.
995 --doh-insecure
997 (all) Same as -k, --insecure but used for DoH (DNS-over-HTTPS).
998 Example:
1000 curl --doh-insecure --doh-url https://doh.example https://example.com
1001 Added in 7.76.0.
1003 --doh-url <URL>
1005 (all) Specifies which DNS-over-HTTPS (DoH) server to use to re‐
1006 solve hostnames, instead of using the default name resolver
1007 mechanism. The URL must be HTTPS.
1008 Some SSL options that you set for your transfer will apply to
1010 DoH since the name lookups take place over SSL. However, the
1011 certificate verification settings are not inherited and can be
1012 controlled separately via --doh-insecure and --doh-cert-status.
1013 If this option is used several times, the last one will be used.
1015 Example:
1017 curl --doh-url https://doh.example https://example.com
1018 Added in 7.62.0.
1020 -D, --dump-header <filename>
1022 (HTTP FTP) Write the received protocol headers to the specified
1023 file. If no headers are received, the use of this option will
1024 create an empty file.
1025 When used in FTP, the FTP server response lines are considered
1027 being "headers" and thus are saved there.
1028 If this option is used several times, the last one will be used.
1030 Example:
1032 curl --dump-header store.txt https://example.com
1033 See also -o, --output.
1035 --egd-file <file>
1037 (TLS) Specify the path name to the Entropy Gathering Daemon
1038 socket. The socket is used to seed the random engine for SSL
1039 connections.
1040 Example:
1042 curl --egd-file /random/here https://example.com
1043 See also --random-file.
1045 --engine <name>
1047 (TLS) Select the OpenSSL crypto engine to use for cipher opera‐
1048 tions. Use --engine list to print a list of build-time supported
1049 engines. Note that not all (and possibly none) of the engines
1050 may be available at run-time.
1051 Example:
1053 curl --engine flavor https://example.com
1054 --etag-compare <file>
1056 (HTTP) This option makes a conditional HTTP request for the spe‐
1057 cific ETag read from the given file by sending a custom If-None-
1058 Match header using the stored ETag.
1059 For correct results, make sure that the specified file contains
1061 only a single line with the desired ETag. An empty file is
1062 parsed as an empty ETag.
1063 Use the option --etag-save to first save the ETag from a re‐
1065 sponse, and then use this option to compare against the saved
1066 ETag in a subsequent request.
1067 Example:
1069 curl --etag-compare etag.txt https://example.com
1070 Added in 7.68.0.
1072 --etag-save <file>
1074 (HTTP) This option saves an HTTP ETag to the specified file. An
1075 ETag is a caching related header, usually returned in a re‐
1076 sponse.
1077 If no ETag is sent by the server, an empty file is created.
1079 Example:
1081 curl --etag-save storetag.txt https://example.com
1082 Added in 7.68.0.
1084 --expect100-timeout <seconds>
1086 (HTTP) Maximum time in seconds that you allow curl to wait for a
1087 100-continue response when curl emits an Expects: 100-continue
1088 header in its request. By default curl will wait one second.
1089 This option accepts decimal values! When curl stops waiting, it
1090 will continue as if the response has been received.
1091 Example:
1093 curl --expect100-timeout 2.5 -T file https://example.com
1094 See also --connect-timeout. Added in 7.47.0.
1096 --fail-early
1098 Fail and exit on the first detected transfer error.
1099 When curl is used to do multiple transfers on the command line,
1101 it will attempt to operate on each given URL, one by one. By de‐
1102 fault, it will ignore errors if there are more URLs given and
1103 the last URL's success will determine the error code curl re‐
1104 turns. So early failures will be "hidden" by subsequent success‐
1105 ful transfers.
1106 Using this option, curl will instead return an error on the
1108 first transfer that fails, independent of the amount of URLs
1109 that are given on the command line. This way, no transfer fail‐
1110 ures go undetected by scripts and similar.
1111 This option is global and does not need to be specified for each
1113 use of -:, --next.
1114 This option does not imply -f, --fail, which causes transfers to
1116 fail due to the server's HTTP status code. You can combine the
1117 two options, however note -f, --fail is not global and is there‐
1118 fore contained by -:, --next.
1119 Example:
1121 curl --fail-early https://example.com https://two.example
1122 Added in 7.52.0.
1124 --fail-with-body
1126 (HTTP) Return an error on server errors where the HTTP response
1127 code is 400 or greater). In normal cases when an HTTP server
1128 fails to deliver a document, it returns an HTML document stating
1129 so (which often also describes why and more). This flag will
1130 still allow curl to output and save that content but also to re‐
1131 turn error 22.
1132 This is an alternative option to -f, --fail which makes curl
1134 fail for the same circumstances but without saving the content.
1135 Example:
1137 curl --fail-with-body https://example.com
1138 See also -f, --fail. Added in 7.76.0.
1140 -f, --fail
1142 (HTTP) Fail silently (no output at all) on server errors. This
1143 is mostly done to enable scripts etc to better deal with failed
1144 attempts. In normal cases when an HTTP server fails to deliver a
1145 document, it returns an HTML document stating so (which often
1146 also describes why and more). This flag will prevent curl from
1147 outputting that and return error 22.
1148 This method is not fail-safe and there are occasions where non-
1150 successful response codes will slip through, especially when au‐
1151 thentication is involved (response codes 401 and 407).
1152 Example:
1154 curl --fail https://example.com
1155 See also --fail-with-body.
1157 --false-start
1159 (TLS) Tells curl to use false start during the TLS handshake.
1160 False start is a mode where a TLS client will start sending ap‐
1161 plication data before verifying the server's Finished message,
1162 thus saving a round trip when performing a full handshake.
1163 This is currently only implemented in the NSS and Secure Trans‐
1165 port (on iOS 7.0 or later, or OS X 10.9 or later) backends.
1166 Example:
1168 curl --false-start https://example.com
1169 Added in 7.42.0.
1171 --form-string <name=string>
1173 (HTTP SMTP IMAP) Similar to -F, --form except that the value
1174 string for the named parameter is used literally. Leading '@'
1175 and '<' characters, and the ';type=' string in the value have no
1176 special meaning. Use this in preference to -F, --form if there's
1177 any possibility that the string value may accidentally trigger
1178 the '@' or '<' features of -F, --form.
1179 Example:
1181 curl --form-string "data" https://example.com
1182 See also -F, --form.
1184 -F, --form <name=content>
1186 (HTTP SMTP IMAP) For HTTP protocol family, this lets curl emu‐
1187 late a filled-in form in which a user has pressed the submit
1188 button. This causes curl to POST data using the Content-Type
1189 multipart/form-data according to RFC 2388.
1190 For SMTP and IMAP protocols, this is the means to compose a mul‐
1192 tipart mail message to transmit.
1193 This enables uploading of binary files etc. To force the 'con‐
1195 tent' part to be a file, prefix the file name with an @ sign. To
1196 just get the content part from a file, prefix the file name with
1197 the symbol <. The difference between @ and < is then that @
1198 makes a file get attached in the post as a file upload, while
1199 the < makes a text field and just get the contents for that text
1200 field from a file.
1201 Tell curl to read content from stdin instead of a file by using
1203 - as filename. This goes for both @ and < constructs. When stdin
1204 is used, the contents is buffered in memory first by curl to de‐
1205 termine its size and allow a possible resend. Defining a part's
1206 data from a named non-regular file (such as a named pipe or sim‐
1207 ilar) is unfortunately not subject to buffering and will be ef‐
1208 fectively read at transmission time; since the full size is un‐
1209 known before the transfer starts, such data is sent as chunks by
1210 HTTP and rejected by IMAP.
1211 Example: send an image to an HTTP server, where 'profile' is the
1213 name of the form-field to which the file portrait.jpg will be
1214 the input:
1215 curl -F profile=@portrait.jpg https://example.com/upload.cgi
1217 Example: send your name and shoe size in two text fields to the
1219 server:
1220 curl -F name=John -F shoesize=11 https://example.com/
1222 Example: send your essay in a text field to the server. Send it
1224 as a plain text field, but get the contents for it from a local
1225 file:
1226 curl -F "story=<hugefile.txt" https://example.com/
1228 You can also tell curl what Content-Type to use by using
1230 'type=', in a manner similar to:
1231 curl -F "web=@index.html;type=text/html" example.com
1233 or
1235 curl -F "name=daniel;type=text/foo" example.com
1237 You can also explicitly change the name field of a file upload
1239 part by setting filename=, like this:
1240 curl -F "file=@localfile;filename=nameinpost" example.com
1242 If filename/path contains ',' or ';', it must be quoted by dou‐
1244 ble-quotes like:
1245 curl -F "file=@\"local,file\";filename=\"name;in;post\"" exam‐
1247 ple.com
1248 or
1250 curl -F 'file=@"local,file";filename="name;in;post"' exam‐
1252 ple.com
1253 Note that if a filename/path is quoted by double-quotes, any
1255 double-quote or backslash within the filename must be escaped by
1256 backslash.
1257 Quoting must also be applied to non-file data if it contains
1259 semicolons, leading/trailing spaces or leading double quotes:
1260 curl -F 'colors="red; green; blue";type=text/x-myapp' exam‐
1262 ple.com
1263 You can add custom headers to the field by setting headers=,
1265 like
1266 curl -F "submit=OK;headers=\"X-submit-type: OK\"" example.com
1268 or
1270 curl -F "submit=OK;headers=@headerfile" example.com
1272 The headers= keyword may appear more that once and above notes
1274 about quoting apply. When headers are read from a file, Empty
1275 lines and lines starting with '#' are comments and ignored; each
1276 header can be folded by splitting between two words and starting
1277 the continuation line with a space; embedded carriage-returns
1278 and trailing spaces are stripped. Here is an example of a
1279 header file contents:
1280 # This file contain two headers.
1282 X-header-1: this is a header
1283 # The following header is folded.
1285 X-header-2: this is
1286 another header
1287 To support sending multipart mail messages, the syntax is ex‐
1290 tended as follows:
1291 - name can be omitted: the equal sign is the first character of
1292 the argument,
1293 - if data starts with '(', this signals to start a new multi‐
1294 part: it can be followed by a content type specification.
1295 - a multipart can be terminated with a '=)' argument.
1296 Example: the following command sends an SMTP mime e-mail con‐
1298 sisting in an inline part in two alternative formats: plain text
1299 and HTML. It attaches a text file:
1300 curl -F '=(;type=multipart/alternative' \
1302 -F '=plain text message' \
1303 -F '= <body>HTML message</body>;type=text/html' \
1304 -F '=)' -F '=@textfile.txt' ... smtp://example.com
1305 Data can be encoded for transfer using encoder=. Available en‐
1307 codings are binary and 8bit that do nothing else than adding the
1308 corresponding Content-Transfer-Encoding header, 7bit that only
1309 rejects 8-bit characters with a transfer error, quoted-printable
1310 and base64 that encodes data according to the corresponding
1311 schemes, limiting lines length to 76 characters.
1312 Example: send multipart mail with a quoted-printable text mes‐
1314 sage and a base64 attached file:
1315 curl -F '=text message;encoder=quoted-printable' \
1317 -F '=@localfile;encoder=base64' ... smtp://example.com
1318 See further examples and details in the MANUAL.
1320 This option can be used multiple times.
1322 Example:
1324 curl --form "name=curl" --form "file=@loadthis" https://example.com
1325 This option overrides -d, --data and -I, --head and -T, --up‐
1327 load-file.
1328 --ftp-account <data>
1330 (FTP) When an FTP server asks for "account data" after user name
1331 and password has been provided, this data is sent off using the
1332 ACCT command.
1333 If this option is used several times, the last one will be used.
1335 Example:
1337 curl --ftp-account "mr.robot" ftp://example.com/
1338 Added in 7.13.0.
1340 --ftp-alternative-to-user <command>
1342 (FTP) If authenticating with the USER and PASS commands fails,
1343 send this command. When connecting to Tumbleweed's Secure
1344 Transport server over FTPS using a client certificate, using
1345 "SITE AUTH" will tell the server to retrieve the username from
1346 the certificate.
1347 Example:
1349 curl --ftp-alternative-to-user "U53r" ftp://example.com
1350 Added in 7.15.5.
1352 --ftp-create-dirs
1354 (FTP SFTP) When an FTP or SFTP URL/operation uses a path that
1355 doesn't currently exist on the server, the standard behavior of
1356 curl is to fail. Using this option, curl will instead attempt to
1357 create missing directories.
1358 Example:
1360 curl --ftp-create-dirs -T file ftp://example.com/remote/path/file
1361 See also --create-dirs.
1363 --ftp-method <method>
1365 (FTP) Control what method curl should use to reach a file on an
1366 FTP(S) server. The method argument should be one of the follow‐
1367 ing alternatives:
1368 multicwd
1370 curl does a single CWD operation for each path part in
1371 the given URL. For deep hierarchies this means very many
1372 commands. This is how RFC 1738 says it should be done.
1373 This is the default but the slowest behavior.
1374 nocwd curl does no CWD at all. curl will do SIZE, RETR, STOR
1376 etc and give a full path to the server for all these com‐
1377 mands. This is the fastest behavior.
1378 singlecwd
1380 curl does one CWD with the full target directory and then
1381 operates on the file "normally" (like in the multicwd
1382 case). This is somewhat more standards compliant than
1383 'nocwd' but without the full penalty of 'multicwd'.
1384 Examples:
1386 curl --ftp-method multicwd ftp://example.com/dir1/dir2/file
1387 curl --ftp-method nocwd ftp://example.com/dir1/dir2/file
1388 curl --ftp-method singlecwd ftp://example.com/dir1/dir2/file
1389 Added in 7.15.1.
1391 --ftp-pasv
1393 (FTP) Use passive mode for the data connection. Passive is the
1394 internal default behavior, but using this option can be used to
1395 override a previous -P, --ftp-port option.
1396 If this option is used several times, only the first one is
1398 used. Undoing an enforced passive really isn't doable but you
1399 must then instead enforce the correct -P, --ftp-port again.
1400 Passive mode means that curl will try the EPSV command first and
1402 then PASV, unless --disable-epsv is used.
1403 Example:
1405 curl --ftp-pasv ftp://example.com/
1406 See also --disable-epsv. Added in 7.11.0.
1408 -P, --ftp-port <address>
1410 (FTP) Reverses the default initiator/listener roles when con‐
1411 necting with FTP. This option makes curl use active mode. curl
1412 then tells the server to connect back to the client's specified
1413 address and port, while passive mode asks the server to setup an
1414 IP address and port for it to connect to. <address> should be
1415 one of:
1416 interface
1418 e.g. "eth0" to specify which interface's IP address you
1419 want to use (Unix only)
1420 IP address
1422 e.g. "192.168.10.1" to specify the exact IP address
1423 host name
1425 e.g. "my.host.domain" to specify the machine
1426 - make curl pick the same IP address that is already used
1428 for the control connection
1429 If this option is used several times, the last one will be used. Dis‐
1431 able the use of PORT with --ftp-pasv. Disable the attempt to use the
1432 EPRT command instead of PORT by using --disable-eprt. EPRT is really
1433 PORT++.
1434 Since 7.19.5, you can append ":[start]-[end]" to the right of the ad‐
1436 dress, to tell curl what TCP port range to use. That means you specify
1437 a port range, from a lower to a higher number. A single number works as
1438 well, but do note that it increases the risk of failure since the port
1439 may not be available.
1440 Examples:
1442 curl -P - ftp:/example.com
1443 curl -P eth0 ftp:/example.com
1444 curl -P 192.168.0.2 ftp:/example.com
1445 See also --ftp-pasv and --disable-eprt.
1447 --ftp-pret
1449 (FTP) Tell curl to send a PRET command before PASV (and EPSV).
1450 Certain FTP servers, mainly drftpd, require this non-standard
1451 command for directory listings as well as up and downloads in
1452 PASV mode.
1453 Example:
1455 curl --ftp-pret ftp://example.com/
1456 Added in 7.20.0.
1458 --ftp-skip-pasv-ip
1460 (FTP) Tell curl to not use the IP address the server suggests in
1461 its response to curl's PASV command when curl connects the data
1462 connection. Instead curl will re-use the same IP address it al‐
1463 ready uses for the control connection.
1464 Since curl 7.74.0 this option is enabled by default.
1466 This option has no effect if PORT, EPRT or EPSV is used instead
1468 of PASV.
1469 Example:
1471 curl --ftp-skip-pasv-ip ftp://example.com/
1472 See also --ftp-pasv. Added in 7.14.2.
1474 --ftp-ssl-ccc-mode <active/passive>
1476 (FTP) Sets the CCC mode. The passive mode will not initiate the
1477 shutdown, but instead wait for the server to do it, and will not
1478 reply to the shutdown from the server. The active mode initiates
1479 the shutdown and waits for a reply from the server.
1480 Example:
1482 curl --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/
1483 See also --ftp-ssl-ccc. Added in 7.16.2.
1485 --ftp-ssl-ccc
1487 (FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS
1488 layer after authenticating. The rest of the control channel com‐
1489 munication will be unencrypted. This allows NAT routers to fol‐
1490 low the FTP transaction. The default mode is passive.
1491 Example:
1493 curl --ftp-ssl-ccc ftps://example.com/
1494 See also --ssl and --ftp-ssl-ccc-mode. Added in 7.16.1.
1496 --ftp-ssl-control
1498 (FTP) Require SSL/TLS for the FTP login, clear for transfer.
1499 Allows secure authentication, but non-encrypted data transfers
1500 for efficiency. Fails the transfer if the server doesn't sup‐
1501 port SSL/TLS.
1502 Example:
1504 curl --ftp-ssl-control ftp://example.com
1505 Added in 7.16.0.
1507 -G, --get
1509 When used, this option will make all data specified with -d,
1510 --data, --data-binary or --data-urlencode to be used in an HTTP
1511 GET request instead of the POST request that otherwise would be
1512 used. The data will be appended to the URL with a '?' separator.
1513 If used in combination with -I, --head, the POST data will in‐
1515 stead be appended to the URL with a HEAD request.
1516 If this option is used several times, only the first one is
1518 used. This is because undoing a GET doesn't make sense, but you
1519 should then instead enforce the alternative method you prefer.
1520 Examples:
1522 curl --get https://example.com
1523 curl --get -d "tool=curl" -d "age=old" https://example.com
1524 curl --get -I -d "tool=curl" https://example.com
1525 -g, --globoff
1527 This option switches off the "URL globbing parser". When you set
1528 this option, you can specify URLs that contain the letters {}[]
1529 without having curl itself interpret them. Note that these let‐
1530 ters are not normal legal URL contents but they should be en‐
1531 coded according to the URI standard.
1532 Example:
1534 curl -g "https://example.com/{[]}}}}"
1535 --happy-eyeballs-timeout-ms <milliseconds>
1537 Happy Eyeballs is an algorithm that attempts to connect to both
1538 IPv4 and IPv6 addresses for dual-stack hosts, giving IPv6 a
1539 head-start of the specified number of milliseconds. If the IPv6
1540 address cannot be connected to within that time, then a connec‐
1541 tion attempt is made to the IPv4 address in parallel. The first
1542 connection to be established is the one that is used.
1543 The range of suggested useful values is limited. Happy Eyeballs
1545 RFC 6555 says "It is RECOMMENDED that connection attempts be
1546 paced 150-250 ms apart to balance human factors against network
1547 load." libcurl currently defaults to 200 ms. Firefox and Chrome
1548 currently default to 300 ms.
1549 If this option is used several times, the last one will be used.
1551 Example:
1553 curl --happy-eyeballs-timeout-ms 500 https://example.com
1554 Added in 7.59.0.
1556 --haproxy-protocol
1558 (HTTP) Send a HAProxy PROXY protocol v1 header at the beginning
1559 of the connection. This is used by some load balancers and re‐
1560 verse proxies to indicate the client's true IP address and port.
1561 This option is primarily useful when sending test requests to a
1563 service that expects this header.
1564 Example:
1566 curl --haproxy-protocol https://example.com
1567 Added in 7.60.0.
1569 -I, --head
1571 (HTTP FTP FILE) Fetch the headers only! HTTP-servers feature the
1572 command HEAD which this uses to get nothing but the header of a
1573 document. When used on an FTP or FILE file, curl displays the
1574 file size and last modification time only.
1575 Example:
1577 curl -I https://example.com
1578 -H, --header <header/@file>
1580 (HTTP) Extra header to include in the request when sending HTTP
1581 to a server. You may specify any number of extra headers. Note
1582 that if you should add a custom header that has the same name as
1583 one of the internal ones curl would use, your externally set
1584 header will be used instead of the internal one. This allows you
1585 to make even trickier stuff than curl would normally do. You
1586 should not replace internally set headers without knowing per‐
1587 fectly well what you're doing. Remove an internal header by giv‐
1588 ing a replacement without content on the right side of the
1589 colon, as in: -H "Host:". If you send the custom header with no-
1590 value then its header must be terminated with a semicolon, such
1591 as -H "X-Custom-Header;" to send "X-Custom-Header:".
1592 curl will make sure that each header you add/replace is sent
1594 with the proper end-of-line marker, you should thus not add that
1595 as a part of the header content: do not add newlines or carriage
1596 returns, they will only mess things up for you.
1597 This option can take an argument in @filename style, which then
1599 adds a header for each line in the input file. Using @- will
1600 make curl read the header file from stdin. Added in 7.55.0.
1601 You need --proxy-header to send custom headers intended for a
1603 HTTP proxy. Added in 7.37.0.
1604 Passing on a "Transfer-Encoding: chunked" header when doing a
1606 HTTP request with a request body, will make curl send the data
1607 using chunked encoding.
1608 WARNING: headers set with this option will be set in all re‐
1610 quests - even after redirects are followed, like when told with
1611 -L, --location. This can lead to the header being sent to other
1612 hosts than the original host, so sensitive headers should be
1613 used with caution combined with following redirects.
1614 This option can be used multiple times to add/replace/remove
1616 multiple headers.
1617 Examples:
1619 curl -H "X-First-Name: Joe" https://example.com
1620 curl -H "User-Agent: yes-please/2000" https://example.com
1621 curl -H "Host:" https://example.com
1622 See also -A, --user-agent and -e, --referer.
1624 -h, --help <category>
1626 Usage help. This lists all commands of the <category>. If no
1627 arg was provided, curl will display the most important command
1628 line arguments. If the argument "all" was provided, curl will
1629 display all options available. If the argument "category" was
1630 provided, curl will display all categories and their meanings.
1631 Example:
1633 curl --help all
1634 --hostpubmd5 <md5>
1636 (SFTP SCP) Pass a string containing 32 hexadecimal digits. The
1637 string should be the 128 bit MD5 checksum of the remote host's
1638 public key, curl will refuse the connection with the host unless
1639 the md5sums match.
1640 Example:
1642 curl --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/
1643 Added in 7.17.1.
1645 --hsts <file name>
1647 (HTTPS) This option enables HSTS for the transfer. If the file
1648 name points to an existing HSTS cache file, that will be used.
1649 After a completed transfer, the cache will be saved to the file
1650 name again if it has been modified.
1651 Specify a "" file name (zero length) to avoid loading/saving and
1653 make curl just handle HSTS in memory.
1654 If this option is used several times, curl will load contents
1656 from all the files but the last one will be used for saving.
1657 Example:
1659 curl --hsts cache.txt https://example.com
1660 Added in 7.74.0.
1662 --http0.9
1664 (HTTP) Tells curl to be fine with HTTP version 0.9 response.
1665 HTTP/0.9 is a completely headerless response and therefore you
1667 can also connect with this to non-HTTP servers and still get a
1668 response since curl will simply transparently downgrade - if al‐
1669 lowed.
1670 Since curl 7.66.0, HTTP/0.9 is disabled by default.
1672 Example:
1674 curl --http0.9 https://example.com
1675 -0, --http1.0
1677 (HTTP) Tells curl to use HTTP version 1.0 instead of using its
1678 internally preferred HTTP version.
1679 Example:
1681 curl --http1.0 https://example.com
1682 This option overrides --http1.1 and --http2.
1684 --http1.1
1686 (HTTP) Tells curl to use HTTP version 1.1.
1687 Example:
1689 curl --http1.1 https://example.com
1690 This option overrides -0, --http1.0 and --http2. Added in
1692 7.33.0.
1693 --http2-prior-knowledge
1695 (HTTP) Tells curl to issue its non-TLS HTTP requests using
1696 HTTP/2 without HTTP/1.1 Upgrade. It requires prior knowledge
1697 that the server supports HTTP/2 straight away. HTTPS requests
1698 will still do HTTP/2 the standard way with negotiated protocol
1699 version in the TLS handshake.
1700 Example:
1702 curl --http2-prior-knowledge https://example.com
1703 --http2-prior-knowledge requires that the underlying libcurl was
1705 built to support HTTP/2. This option overrides --http1.1 and -0,
1706 --http1.0 and --http2. Added in 7.49.0.
1707 --http2
1709 (HTTP) Tells curl to use HTTP version 2.
1710 For HTTPS, this means curl will attempt to negotiate HTTP/2 in
1712 the TLS handshake. curl does this by default.
1713 For HTTP, this means curl will attempt to upgrade the request to
1715 HTTP/2 using the Upgrade: request header.
1716 Example:
1718 curl --http2 https://example.com
1719 See also --http1.1 and --http3. --http2 requires that the under‐
1721 lying libcurl was built to support HTTP/2. This option overrides
1722 --http1.1 and -0, --http1.0 and --http2-prior-knowledge. Added
1723 in 7.33.0.
1724 --http3
1726 (HTTP) WARNING: this option is experimental. Do not use in pro‐
1727 duction.
1728 Tells curl to use HTTP version 3 directly to the host and port
1730 number used in the URL. A normal HTTP/3 transaction will be done
1731 to a host and then get redirected via Alt-Svc, but this option
1732 allows a user to circumvent that when you know that the target
1733 speaks HTTP/3 on the given host and port.
1734 This option will make curl fail if a QUIC connection cannot be
1736 established, it cannot fall back to a lower HTTP version on its
1737 own.
1738 Example:
1740 curl --http3 https://example.com
1741 See also --http1.1 and --http2. --http3 requires that the under‐
1743 lying libcurl was built to support HTTP/3. This option overrides
1744 --http1.1 and -0, --http1.0 and --http2 and --http2-prior-knowl‐
1745 edge. Added in 7.66.0.
1746 --ignore-content-length
1748 (FTP HTTP) For HTTP, Ignore the Content-Length header. This is
1749 particularly useful for servers running Apache 1.x, which will
1750 report incorrect Content-Length for files larger than 2 giga‐
1751 bytes.
1752 For FTP (since 7.46.0), skip the RETR command to figure out the
1754 size before downloading a file.
1755 This option doesn't work for HTTP if libcurl was built to use
1757 hyper.
1758 Example:
1760 curl --ignore-content-length https://example.com
1761 -i, --include
1763 Include the HTTP response headers in the output. The HTTP re‐
1764 sponse headers can include things like server name, cookies,
1765 date of the document, HTTP version and more...
1766 To view the request headers, consider the -v, --verbose option.
1768 Example:
1770 curl -i https://example.com
1771 See also -v, --verbose.
1773 -k, --insecure
1775 (TLS) By default, every SSL connection curl makes is verified to
1776 be secure. This option allows curl to proceed and operate even
1777 for server connections otherwise considered insecure.
1778 The server connection is verified by making sure the server's
1780 certificate contains the right name and verifies successfully
1781 using the cert store.
1782 See this online resource for further details:
1784 https://curl.se/docs/sslcerts.html
1785 WARNING: this makes the transfer insecure.
1787 Example:
1789 curl --insecure https://example.com
1790 See also --proxy-insecure and --cacert.
1792 --interface <name>
1794 Perform an operation using a specified interface. You can enter
1796 interface name, IP address or host name. An example could look
1797 like:
1798 curl --interface eth0:1 https://www.example.com/
1800 If this option is used several times, the last one will be used.
1802 On Linux it can be used to specify a VRF, but the binary needs
1804 to either have CAP_NET_RAW or to be run as root. More informa‐
1805 tion about Linux VRF: https://www.kernel.org/doc/Documenta‐
1806 tion/networking/vrf.txt
1807 Example:
1809 curl --interface eth0 https://example.com
1810 See also --dns-interface.
1812 -4, --ipv4
1814 This option tells curl to resolve names to IPv4 addresses only,
1815 and not for example try IPv6.
1816 Example:
1818 curl --ipv4 https://example.com
1819 See also --http1.1 and --http2. This option overrides -6,
1821 --ipv6.
1822 -6, --ipv6
1824 This option tells curl to resolve names to IPv6 addresses only,
1825 and not for example try IPv4.
1826 Example:
1828 curl --ipv6 https://example.com
1829 See also --http1.1 and --http2. This option overrides -4,
1831 --ipv4.
1832 -j, --junk-session-cookies
1834 (HTTP) When curl is told to read cookies from a given file, this
1835 option will make it discard all "session cookies". This will ba‐
1836 sically have the same effect as if a new session is started.
1837 Typical browsers always discard session cookies when they're
1838 closed down.
1839 Example:
1841 curl --junk-session-cookies -b cookies.txt https://example.com
1842 See also -b, --cookie and -c, --cookie-jar.
1844 --keepalive-time <seconds>
1846 This option sets the time a connection needs to remain idle be‐
1847 fore sending keepalive probes and the time between individual
1848 keepalive probes. It is currently effective on operating systems
1849 offering the TCP_KEEPIDLE and TCP_KEEPINTVL socket options
1850 (meaning Linux, recent AIX, HP-UX and more). This option has no
1851 effect if --no-keepalive is used.
1852 If this option is used several times, the last one will be used.
1854 If unspecified, the option defaults to 60 seconds.
1855 Example:
1857 curl --keepalive-time 20 https://example.com
1858 Added in 7.18.0.
1860 --key-type <type>
1862 (TLS) Private key file type. Specify which type your --key pro‐
1863 vided private key is. DER, PEM, and ENG are supported. If not
1864 specified, PEM is assumed.
1865 If this option is used several times, the last one will be used.
1867 Example:
1869 curl --key-type DER --key here https://example.com
1870 --key <key>
1872 (TLS SSH) Private key file name. Allows you to provide your pri‐
1873 vate key in this separate file. For SSH, if not specified, curl
1874 tries the following candidates in order: '~/.ssh/id_rsa',
1875 '~/.ssh/id_dsa', './id_rsa', './id_dsa'.
1876 If curl is built against OpenSSL library, and the engine pkcs11
1878 is available, then a PKCS#11 URI (RFC 7512) can be used to spec‐
1879 ify a private key located in a PKCS#11 device. A string begin‐
1880 ning with "pkcs11:" will be interpreted as a PKCS#11 URI. If a
1881 PKCS#11 URI is provided, then the --engine option will be set as
1882 "pkcs11" if none was provided and the --key-type option will be
1883 set as "ENG" if none was provided.
1884 If this option is used several times, the last one will be used.
1886 Example:
1888 curl --cert certificate --key here https://example.com
1889 --krb <level>
1891 (FTP) Enable Kerberos authentication and use. The level must be
1892 entered and should be one of 'clear', 'safe', 'confidential', or
1893 'private'. Should you use a level that is not one of these,
1894 'private' will instead be used.
1895 If this option is used several times, the last one will be used.
1897 Example:
1899 curl --krb clear ftp://example.com/
1900 --krb requires that the underlying libcurl was built to support
1902 Kerberos.
1903 --libcurl <file>
1905 Append this option to any ordinary curl command line, and you
1906 will get libcurl-using C source code written to the file that
1907 does the equivalent of what your command-line operation does!
1908 This option is global and does not need to be specified for each
1910 use of -:, --next.
1911 If this option is used several times, the last given file name
1913 will be used.
1914 Example:
1916 curl --libcurl client.c https://example.com
1917 Added in 7.16.1.
1919 --limit-rate <speed>
1921 Specify the maximum transfer rate you want curl to use - for
1922 both downloads and uploads. This feature is useful if you have a
1923 limited pipe and you'd like your transfer not to use your entire
1924 bandwidth. To make it slower than it otherwise would be.
1925 The given speed is measured in bytes/second, unless a suffix is
1927 appended. Appending 'k' or 'K' will count the number as kilo‐
1928 bytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it
1929 gigabytes. The suffixes (k, M, G, T, P) are 1024 based. For ex‐
1930 ample 1k is 1024. Examples: 200K, 3m and 1G.
1931 If you also use the -Y, --speed-limit option, that option will
1933 take precedence and might cripple the rate-limiting slightly, to
1934 help keeping the speed-limit logic working.
1935 If this option is used several times, the last one will be used.
1937 Examples:
1939 curl --limit-rate 100K https://example.com
1940 curl --limit-rate 1000 https://example.com
1941 curl --limit-rate 10M https://example.com
1942 -l, --list-only
1944 (FTP POP3) (FTP) When listing an FTP directory, this switch
1945 forces a name-only view. This is especially useful if the user
1946 wants to machine-parse the contents of an FTP directory since
1947 the normal directory view doesn't use a standard look or format.
1948 When used like this, the option causes an NLST command to be
1949 sent to the server instead of LIST.
1950 Note: Some FTP servers list only files in their response to
1952 NLST; they do not include sub-directories and symbolic links.
1953 (POP3) When retrieving a specific email from POP3, this switch
1955 forces a LIST command to be performed instead of RETR. This is
1956 particularly useful if the user wants to see if a specific mes‐
1957 sage-id exists on the server and what size it is.
1958 Note: When combined with -X, --request, this option can be used
1960 to send a UIDL command instead, so the user may use the email's
1961 unique identifier rather than its message-id to make the re‐
1962 quest.
1963 Example:
1965 curl --list-only ftp://example.com/dir/
1966 Added in 4.0.
1968 --local-port <num/range>
1970 Set a preferred single number or range (FROM-TO) of local port
1971 numbers to use for the connection(s). Note that port numbers by
1972 nature are a scarce resource that will be busy at times so set‐
1973 ting this range to something too narrow might cause unnecessary
1974 connection setup failures.
1975 Example:
1977 curl --local-port 1000-3000 https://example.com
1978 Added in 7.15.2.
1980 --location-trusted
1982 (HTTP) Like -L, --location, but will allow sending the name +
1983 password to all hosts that the site may redirect to. This may or
1984 may not introduce a security breach if the site redirects you to
1985 a site to which you'll send your authentication info (which is
1986 plaintext in the case of HTTP Basic authentication).
1987 Example:
1989 curl --location-trusted -u user:password https://example.com
1990 See also -u, --user.
1992 -L, --location
1994 (HTTP) If the server reports that the requested page has moved
1995 to a different location (indicated with a Location: header and a
1996 3XX response code), this option will make curl redo the request
1997 on the new place. If used together with -i, --include or -I,
1998 --head, headers from all requested pages will be shown. When au‐
1999 thentication is used, curl only sends its credentials to the
2000 initial host. If a redirect takes curl to a different host, it
2001 won't be able to intercept the user+password. See also --loca‐
2002 tion-trusted on how to change this. You can limit the amount of
2003 redirects to follow by using the --max-redirs option.
2004 When curl follows a redirect and if the request is a POST, it
2006 will send the following request with a GET if the HTTP response
2007 was 301, 302, or 303. If the response code was any other 3xx
2008 code, curl will re-send the following request using the same un‐
2009 modified method.
2010 You can tell curl to not change POST requests to GET after a 30x
2012 response by using the dedicated options for that: --post301,
2013 --post302 and --post303.
2014 The method set with -X, --request overrides the method curl
2016 would otherwise select to use.
2017 Example:
2019 curl -L https://example.com
2020 --login-options <options>
2022 (IMAP POP3 SMTP) Specify the login options to use during server
2023 authentication.
2024 You can use login options to specify protocol specific options
2026 that may be used during authentication. At present only IMAP,
2027 POP3 and SMTP support login options. For more information about
2028 login options please see RFC 2384, RFC 5092 and IETF draft
2029 draft-earhart-url-smtp-00.txt
2030 If this option is used several times, the last one will be used.
2032 Example:
2034 curl --login-options 'AUTH=*' imap://example.com
2035 Added in 7.34.0.
2037 --mail-auth <address>
2039 (SMTP) Specify a single address. This will be used to specify
2040 the authentication address (identity) of a submitted message
2041 that is being relayed to another server.
2042 Example:
2044 curl --mail-auth user@example.come -T mail smtp://example.com/
2045 See also --mail-rcpt and --mail-from. Added in 7.25.0.
2047 --mail-from <address>
2049 (SMTP) Specify a single address that the given mail should get
2050 sent from.
2051 Example:
2053 curl --mail-from user@example.com -T mail smtp://example.com/
2054 See also --mail-rcpt and --mail-auth. Added in 7.20.0.
2056 --mail-rcpt-allowfails
2058 (SMTP) When sending data to multiple recipients, by default curl
2059 will abort SMTP conversation if at least one of the recipients
2060 causes RCPT TO command to return an error.
2061 The default behavior can be changed by passing --mail-rcpt-al‐
2063 lowfails command-line option which will make curl ignore errors
2064 and proceed with the remaining valid recipients.
2065 If all recipients trigger RCPT TO failures and this flag is
2067 specified, curl will still abort the SMTP conversation and re‐
2068 turn the error received from to the last RCPT TO command.
2069 Example:
2071 curl --mail-rcpt-allowfails --mail-rcpt dest@example.com smtp://example.com
2072 Added in 7.69.0.
2074 --mail-rcpt <address>
2076 (SMTP) Specify a single e-mail address, user name or mailing
2077 list name. Repeat this option several times to send to multiple
2078 recipients.
2079 When performing an address verification (VRFY command), the re‐
2081 cipient should be specified as the user name or user name and
2082 domain (as per Section 3.5 of RFC5321). (Added in 7.34.0)
2083 When performing a mailing list expand (EXPN command), the recip‐
2085 ient should be specified using the mailing list name, such as
2086 "Friends" or "London-Office". (Added in 7.34.0)
2087 Example:
2089 curl --mail-rcpt user@example.net smtp://example.com
2090 Added in 7.20.0.
2092 -M, --manual
2094 Manual. Display the huge help text.
2095 Example:
2097 curl --manual
2098 --max-filesize <bytes>
2100 (FTP HTTP MQTT) Specify the maximum size (in bytes) of a file to
2101 download. If the file requested is larger than this value, the
2102 transfer will not start and curl will return with exit code 63.
2103 A size modifier may be used. For example, Appending 'k' or 'K'
2105 will count the number as kilobytes, 'm' or 'M' makes it
2106 megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K,
2107 3m and 1G. (Added in 7.58.0)
2108 NOTE: The file size is not always known prior to download, and
2110 for such files this option has no effect even if the file trans‐
2111 fer ends up being larger than this given limit. Example:
2112 curl --max-filesize 100K https://example.com
2113 See also --limit-rate.
2115 --max-redirs <num>
2117 (HTTP) Set maximum number of redirections to follow. When -L,
2118 --location is used, to prevent curl from following too many
2119 redirects, by default, the limit is set to 50 redirects. Set
2120 this option to -1 to make it unlimited.
2121 If this option is used several times, the last one will be used.
2123 Example:
2125 curl --max-redirs 3 --location https://example.com
2126 -m, --max-time <fractional seconds>
2128 Maximum time in seconds that you allow the whole operation to
2129 take. This is useful for preventing your batch jobs from hang‐
2130 ing for hours due to slow networks or links going down. Since
2131 7.32.0, this option accepts decimal values, but the actual time‐
2132 out will decrease in accuracy as the specified timeout increases
2133 in decimal precision.
2134 If this option is used several times, the last one will be used.
2136 Examples:
2138 curl --max-time 10 https://example.com
2139 curl --max-time 2.92 https://example.com
2140 See also --connect-timeout.
2142 --metalink
2144 This option was previously used to specify a metalink resource.
2145 Metalink support has been disabled in curl since 7.78.0 for se‐
2146 curity reasons.
2147 Example:
2149 curl --metalink file https://example.com
2150 Added in 7.27.0.
2152 --negotiate
2154 (HTTP) Enables Negotiate (SPNEGO) authentication.
2155 This option requires a library built with GSS-API or SSPI sup‐
2157 port. Use -V, --version to see if your curl supports GSS-
2158 API/SSPI or SPNEGO.
2159 When using this option, you must also provide a fake -u, --user
2161 option to activate the authentication code properly. Sending a
2162 '-u :' is enough as the user name and password from the -u,
2163 --user option aren't actually used.
2164 If this option is used several times, only the first one is
2166 used.
2167 Example:
2169 curl --negotiate -u : https://example.com
2170 See also --basic, --ntlm, --anyauth and --proxy-negotiate.
2172 --netrc-file <filename>
2174 This option is similar to -n, --netrc, except that you provide
2175 the path (absolute or relative) to the netrc file that curl
2176 should use. You can only specify one netrc file per invocation.
2177 If several --netrc-file options are provided, the last one will
2178 be used.
2179 It will abide by --netrc-optional if specified.
2181 Example:
2183 curl --netrc-file netrc https://example.com
2184 This option overrides -n, --netrc. Added in 7.21.5.
2186 --netrc-optional
2188 Very similar to -n, --netrc, but this option makes the .netrc
2189 usage optional and not mandatory as the -n, --netrc option does.
2190 Example:
2192 curl --netrc-optional https://example.com
2193 See also --netrc-file. This option overrides -n, --netrc.
2195 -n, --netrc
2197 Makes curl scan the .netrc (_netrc on Windows) file in the
2198 user's home directory for login name and password. This is typi‐
2199 cally used for FTP on Unix. If used with HTTP, curl will enable
2200 user authentication. See netrc(5) and ftp(1) for details on the
2201 file format. Curl will not complain if that file doesn't have
2202 the right permissions (it should be neither world- nor group-
2203 readable). The environment variable "HOME" is used to find the
2204 home directory.
2205 A quick and very simple example of how to setup a .netrc to al‐
2207 low curl to FTP to the machine host.domain.com with user name
2208 'myself' and password 'secret' should look similar to:
2209 machine host.domain.com login myself password secret
2211 Example:
2213 curl --netrc https://example.com
2214 -:, --next
2216 Tells curl to use a separate operation for the following URL and
2217 associated options. This allows you to send several URL re‐
2218 quests, each with their own specific options, for example, such
2219 as different user names or custom requests for each.
2220 -:, --next will reset all local options and only global ones
2222 will have their values survive over to the operation following
2223 the -:, --next instruction. Global options include -v, --ver‐
2224 bose, --trace, --trace-ascii and --fail-early.
2225 For example, you can do both a GET and a POST in a single com‐
2227 mand line:
2228 curl www1.example.com --next -d postthis www2.example.com
2230 Examples:
2232 curl https://example.com --next -d postthis www2.example.com
2233 curl -I https://example.com --next https://example.net/
2234 Added in 7.36.0.
2236 --no-alpn
2238 (HTTPS) Disable the ALPN TLS extension. ALPN is enabled by de‐
2239 fault if libcurl was built with an SSL library that supports
2240 ALPN. ALPN is used by a libcurl that supports HTTP/2 to negoti‐
2241 ate HTTP/2 support with the server during https sessions.
2242 Example:
2244 curl --no-alpn https://example.com
2245 See also --no-npn and --http2. --no-alpn requires that the un‐
2247 derlying libcurl was built to support TLS. Added in 7.36.0.
2248 -N, --no-buffer
2250 Disables the buffering of the output stream. In normal work sit‐
2251 uations, curl will use a standard buffered output stream that
2252 will have the effect that it will output the data in chunks, not
2253 necessarily exactly when the data arrives. Using this option
2254 will disable that buffering.
2255 Note that this is the negated option name documented. You can
2257 thus use --buffer to enforce the buffering.
2258 Example:
2260 curl --no-buffer https://example.com
2261 --no-keepalive
2263 Disables the use of keepalive messages on the TCP connection.
2264 curl otherwise enables them by default.
2265 Note that this is the negated option name documented. You can
2267 thus use --keepalive to enforce keepalive.
2268 Example:
2270 curl --no-keepalive https://example.com
2271 --no-npn
2273 (HTTPS) Disable the NPN TLS extension. NPN is enabled by default
2274 if libcurl was built with an SSL library that supports NPN. NPN
2275 is used by a libcurl that supports HTTP/2 to negotiate HTTP/2
2276 support with the server during https sessions.
2277 Example:
2279 curl --no-npn https://example.com
2280 See also --no-alpn and --http2. --no-npn requires that the un‐
2282 derlying libcurl was built to support TLS. Added in 7.36.0.
2283 --no-progress-meter
2285 Option to switch off the progress meter output without muting or
2286 otherwise affecting warning and informational messages like -s,
2287 --silent does.
2288 Note that this is the negated option name documented. You can
2290 thus use --progress-meter to enable the progress meter again.
2291 Example:
2293 curl --no-progress-meter -o store https://example.com
2294 See also -v, --verbose and -s, --silent. Added in 7.67.0.
2296 --no-sessionid
2298 (TLS) Disable curl's use of SSL session-ID caching. By default
2299 all transfers are done using the cache. Note that while nothing
2300 should ever get hurt by attempting to reuse SSL session-IDs,
2301 there seem to be broken SSL implementations in the wild that may
2302 require you to disable this in order for you to succeed.
2303 Note that this is the negated option name documented. You can
2305 thus use --sessionid to enforce session-ID caching.
2306 Example:
2308 curl --no-sessionid https://example.com
2309 Added in 7.16.0.
2311 --noproxy <no-proxy-list>
2313 Comma-separated list of hosts for which not to use a proxy, if
2314 one is specified. The only wildcard is a single * character,
2315 which matches all hosts, and effectively disables the proxy.
2316 Each name in this list is matched as either a domain which con‐
2317 tains the hostname, or the hostname itself. For example, lo‐
2318 cal.com would match local.com, local.com:80, and www.local.com,
2319 but not www.notlocal.com.
2320 Since 7.53.0, This option overrides the environment variables
2322 that disable the proxy ('no_proxy' and 'NO_PROXY'). If there's
2323 an environment variable disabling a proxy, you can set the no‐
2324 proxy list to "" to override it.
2325 Example:
2327 curl --noproxy "www.example" https://example.com
2328 Added in 7.19.4.
2330 --ntlm-wb
2332 (HTTP) Enables NTLM much in the style --ntlm does, but hand over
2333 the authentication to the separate binary ntlmauth application
2334 that is executed when needed.
2335 Example:
2337 curl --ntlm-wb -u user:password https://example.com
2338 See also --ntlm and --proxy-ntlm.
2340 --ntlm (HTTP) Enables NTLM authentication. The NTLM authentication
2342 method was designed by Microsoft and is used by IIS web servers.
2343 It is a proprietary protocol, reverse-engineered by clever peo‐
2344 ple and implemented in curl based on their efforts. This kind of
2345 behavior should not be endorsed, you should encourage everyone
2346 who uses NTLM to switch to a public and documented authentica‐
2347 tion method instead, such as Digest.
2348 If you want to enable NTLM for your proxy authentication, then
2350 use --proxy-ntlm.
2351 If this option is used several times, only the first one is
2353 used.
2354 Example:
2356 curl --ntlm -u user:password https://example.com
2357 See also --proxy-ntlm. --ntlm requires that the underlying
2359 libcurl was built to support TLS. This option overrides --basic
2360 and --negotiate and --digest and --anyauth.
2361 --oauth2-bearer <token>
2363 (IMAP POP3 SMTP HTTP) Specify the Bearer Token for OAUTH 2.0
2364 server authentication. The Bearer Token is used in conjunction
2365 with the user name which can be specified as part of the --url
2366 or -u, --user options.
2367 The Bearer Token and user name are formatted according to RFC
2369 6750.
2370 If this option is used several times, the last one will be used.
2372 Example:
2374 curl --oauth2-bearer "mF_9.B5f-4.1JqM" https://example.com
2375 --output-dir <dir>
2377 This option specifies the directory in which files should be
2379 stored, when -O, --remote-name or -o, --output are used.
2380 The given output directory is used for all URLs and output op‐
2382 tions on the command line, up until the first -:, --next.
2383 If the specified target directory doesn't exist, the operation
2385 will fail unless --create-dirs is also used.
2386 If this option is used multiple times, the last specified direc‐
2388 tory will be used.
2389 Example:
2391 curl --output-dir "tmp" -O https://example.com
2392 See also -O, --remote-name and -J, --remote-header-name. Added
2394 in 7.73.0.
2395 -o, --output <file>
2397 Write output to <file> instead of stdout. If you are using {} or
2398 [] to fetch multiple documents, you should quote the URL and you
2399 can use '#' followed by a number in the <file> specifier. That
2400 variable will be replaced with the current string for the URL
2401 being fetched. Like in:
2402 curl "http://{one,two}.example.com" -o "file_#1.txt"
2404 or use several variables like:
2406 curl "http://{site,host}.host[1-5].com" -o "#1_#2"
2408 You may use this option as many times as the number of URLs you
2410 have. For example, if you specify two URLs on the same command
2411 line, you can use it like this:
2412 curl -o aa example.com -o bb example.net
2414 and the order of the -o options and the URLs doesn't matter,
2416 just that the first -o is for the first URL and so on, so the
2417 above command line can also be written as
2418 curl example.com example.net -o aa -o bb
2420 See also the --create-dirs option to create the local directo‐
2422 ries dynamically. Specifying the output as '-' (a single dash)
2423 will force the output to be done to stdout.
2424 To suppress response bodies, you can redirect output to
2426 /dev/null:
2427 curl example.com -o /dev/null
2429 Or for Windows use nul:
2431 curl example.com -o nul
2433 Examples:
2435 curl -o file https://example.com
2436 curl "http://{one,two}.example.com" -o "file_#1.txt"
2437 curl "http://{site,host}.host[1-5].com" -o "#1_#2"
2438 curl -o file https://example.com -o file2 https://example.net
2439 See also -O, --remote-name, --remote-name-all and -J, --remote-
2441 header-name.
2442 --parallel-immediate
2444 When doing parallel transfers, this option will instruct curl
2445 that it should rather prefer opening up more connections in par‐
2446 allel at once rather than waiting to see if new transfers can be
2447 added as multiplexed streams on another connection.
2448 This option is global and does not need to be specified for each
2450 use of -:, --next.
2451 Example:
2453 curl --parallel-immediate -Z https://example.com -o file1 https://example.com -o file2
2454 See also -Z, --parallel and --parallel-max. Added in 7.68.0.
2456 --parallel-max <num>
2458 When asked to do parallel transfers, using -Z, --parallel, this
2459 option controls the maximum amount of transfers to do simultane‐
2460 ously.
2461 This option is global and does not need to be specified for each
2463 use of -:, --next.
2464 The default is 50.
2466 Example:
2468 curl --parallel-max 100 -Z https://example.com ftp://example.com/
2469 See also -Z, --parallel. Added in 7.66.0.
2471 -Z, --parallel
2473 Makes curl perform its transfers in parallel as compared to the
2474 regular serial manner.
2475 This option is global and does not need to be specified for each
2477 use of -:, --next.
2478 Example:
2480 curl --parallel https://example.com -o file1 https://example.com -o file2
2481 Added in 7.66.0.
2483 --pass <phrase>
2485 (SSH TLS) Passphrase for the private key.
2486 If this option is used several times, the last one will be used.
2488 Example:
2490 curl --pass secret --key file https://example.com
2491 --path-as-is
2493 Tell curl to not handle sequences of /../ or /./ in the given
2494 URL path. Normally curl will squash or merge them according to
2495 standards but with this option set you tell it not to do that.
2496 Example:
2498 curl --path-as-is https://example.com/../../etc/passwd
2499 Added in 7.42.0.
2501 --pinnedpubkey <hashes>
2503 (TLS) Tells curl to use the specified public key file (or
2504 hashes) to verify the peer. This can be a path to a file which
2505 contains a single public key in PEM or DER format, or any number
2506 of base64 encoded sha256 hashes preceded by ´sha256//´ and sepa‐
2507 rated by ´;´
2508 When negotiating a TLS or SSL connection, the server sends a
2510 certificate indicating its identity. A public key is extracted
2511 from this certificate and if it does not exactly match the pub‐
2512 lic key provided to this option, curl will abort the connection
2513 before sending or receiving any data.
2514 PEM/DER support:
2516 7.39.0: OpenSSL, GnuTLS and GSKit
2518 7.43.0: NSS and wolfSSL
2520 7.47.0: mbedtls
2522 sha256 support:
2524 7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL
2526 7.47.0: mbedtls
2528 Other SSL backends not supported.
2530 If this option is used several times, the last one will be used.
2532 Examples:
2534 curl --pinnedpubkey keyfile https://example.com
2535 curl --pinnedpubkey 'sha256//ce118b51897f4452dc' https://example.com
2536 --post301
2538 (HTTP) Tells curl to respect RFC 7231/6.4.2 and not convert POST
2539 requests into GET requests when following a 301 redirection. The
2540 non-RFC behavior is ubiquitous in web browsers, so curl does the
2541 conversion by default to maintain consistency. However, a server
2542 may require a POST to remain a POST after such a redirection.
2543 This option is meaningful only when using -L, --location.
2544 Example:
2546 curl --post301 --location -d "data" https://example.com
2547 See also --post302, --post303 and -L, --location. Added in
2549 7.17.1.
2550 --post302
2552 (HTTP) Tells curl to respect RFC 7231/6.4.3 and not convert POST
2553 requests into GET requests when following a 302 redirection. The
2554 non-RFC behavior is ubiquitous in web browsers, so curl does the
2555 conversion by default to maintain consistency. However, a server
2556 may require a POST to remain a POST after such a redirection.
2557 This option is meaningful only when using -L, --location.
2558 Example:
2560 curl --post302 --location -d "data" https://example.com
2561 See also --post301, --post303 and -L, --location. Added in
2563 7.19.1.
2564 --post303
2566 (HTTP) Tells curl to violate RFC 7231/6.4.4 and not convert POST
2567 requests into GET requests when following 303 redirections. A
2568 server may require a POST to remain a POST after a 303 redirect‐
2569 ion. This option is meaningful only when using -L, --location.
2570 Example:
2572 curl --post303 --location -d "data" https://example.com
2573 See also --post302, --post301 and -L, --location. Added in
2575 7.26.0.
2576 --preproxy [protocol://]host[:port]
2578 Use the specified SOCKS proxy before connecting to an HTTP or
2579 HTTPS -x, --proxy. In such a case curl first connects to the
2580 SOCKS proxy and then connects (through SOCKS) to the HTTP or
2581 HTTPS proxy. Hence pre proxy.
2582 The pre proxy string should be specified with a protocol:// pre‐
2584 fix to specify alternative proxy protocols. Use socks4://,
2585 socks4a://, socks5:// or socks5h:// to request the specific
2586 SOCKS version to be used. No protocol specified will make curl
2587 default to SOCKS4.
2588 If the port number is not specified in the proxy string, it is
2590 assumed to be 1080.
2591 User and password that might be provided in the proxy string are
2593 URL decoded by curl. This allows you to pass in special charac‐
2594 ters such as @ by using %40 or pass in a colon with %3a.
2595 If this option is used several times, the last one will be used.
2597 Example:
2599 curl --preproxy socks5://proxy.example -x http://http.example https://example.com
2600 Added in 7.52.0.
2602 -#, --progress-bar
2604 Make curl display transfer progress as a simple progress bar in‐
2605 stead of the standard, more informational, meter.
2606 This progress bar draws a single line of '#' characters across
2608 the screen and shows a percentage if the transfer size is known.
2609 For transfers without a known size, there will be space ship
2610 (-=o=-) that moves back and forth but only while data is being
2611 transferred, with a set of flying hash sign symbols on top.
2612 This option is global and does not need to be specified for each
2614 use of -:, --next.
2615 Example:
2617 curl -# -O https://example.com
2618 --proto-default <protocol>
2620 Tells curl to use protocol for any URL missing a scheme name.
2621 An unknown or unsupported protocol causes error CURLE_UNSUP‐
2623 PORTED_PROTOCOL (1).
2624 This option does not change the default proxy protocol (http).
2626 Without this option set, curl guesses protocol based on the host
2628 name, see --url for details.
2629 Example:
2631 curl --proto-default https ftp.example.com
2632 Added in 7.45.0.
2634 --proto-redir <protocols>
2636 Tells curl to limit what protocols it may use on redirect. Pro‐
2637 tocols denied by --proto are not overridden by this option. See
2638 --proto for how protocols are represented.
2639 Example, allow only HTTP and HTTPS on redirect:
2641 curl --proto-redir -all,http,https http://example.com
2643 By default curl will allow HTTP, HTTPS, FTP and FTPS on redirect
2645 (7.65.2). Older versions of curl allowed all protocols on redi‐
2646 rect except several disabled for security reasons: Since 7.19.4
2647 FILE and SCP are disabled, and since 7.40.0 SMB and SMBS are
2648 also disabled. Specifying all or +all enables all protocols on
2649 redirect, including those disabled for security.
2650 Example:
2652 curl --proto-redir =http,https https://example.com
2653 Added in 7.20.2.
2655 --proto <protocols>
2657 Tells curl to limit what protocols it may use for transfers.
2658 Protocols are evaluated left to right, are comma separated, and
2659 are each a protocol name or 'all', optionally prefixed by zero
2660 or more modifiers. Available modifiers are:
2661 + Permit this protocol in addition to protocols already permit‐
2663 ted (this is the default if no modifier is used).
2664 - Deny this protocol, removing it from the list of protocols
2666 already permitted.
2667 = Permit only this protocol (ignoring the list already permit‐
2669 ted), though subject to later modification by subsequent en‐
2670 tries in the comma separated list.
2671 For example:
2673 --proto -ftps uses the default protocols, but disables ftps
2675 --proto -all,https,+http
2677 only enables http and https
2678 --proto =http,https
2680 also only enables http and https
2681 Unknown protocols produce a warning. This allows scripts to
2683 safely rely on being able to disable potentially dangerous pro‐
2684 tocols, without relying upon support for that protocol being
2685 built into curl to avoid an error.
2686 This option can be used multiple times, in which case the effect
2688 is the same as concatenating the protocols into one instance of
2689 the option.
2690 Example:
2692 curl --proto =http,https,sftp https://example.com
2693 See also --proto-redir and --proto-default. Added in 7.20.2.
2695 --proxy-anyauth
2697 Tells curl to pick a suitable authentication method when commu‐
2698 nicating with the given HTTP proxy. This might cause an extra
2699 request/response round-trip.
2700 Example:
2702 curl --proxy-anyauth --proxy-user user:passwd -x proxy https://example.com
2703 See also -x, --proxy, --proxy-basic and --proxy-digest. Added in
2705 7.13.2.
2706 --proxy-basic
2708 Tells curl to use HTTP Basic authentication when communicating
2709 with the given proxy. Use --basic for enabling HTTP Basic with a
2710 remote host. Basic is the default authentication method curl
2711 uses with proxies.
2712 Example:
2714 curl --proxy-basic --proxy-user user:passwd -x proxy https://example.com
2715 See also -x, --proxy, --proxy-anyauth and --proxy-digest.
2717 --proxy-cacert <file>
2719 Same as --cacert but used in HTTPS proxy context.
2720 Example:
2722 curl --proxy-cacert CA-file.txt -x https://proxy https://example.com
2723 See also --proxy-capath, --cacert, --capath and -x, --proxy.
2725 Added in 7.52.0.
2726 --proxy-capath <dir>
2728 Same as --capath but used in HTTPS proxy context.
2729 Example:
2731 curl --proxy-capath /local/directory -x https://proxy https://example.com
2732 See also --proxy-cacert, -x, --proxy and --capath. Added in
2734 7.52.0.
2735 --proxy-cert-type <type>
2737 Same as --cert-type but used in HTTPS proxy context.
2738 Example:
2740 curl --proxy-cert-type PEM --proxy-cert file -x https://proxy https://example.com
2741 Added in 7.52.0.
2743 --proxy-cert <cert[:passwd]>
2745 Same as -E, --cert but used in HTTPS proxy context.
2746 Example:
2748 curl --proxy-cert file -x https://proxy https://example.com
2749 Added in 7.52.0.
2751 --proxy-ciphers <list>
2753 Same as --ciphers but used in HTTPS proxy context.
2754 Example:
2756 curl --proxy-ciphers ECDHE-ECDSA-AES256-CCM8 -x https://proxy https://example.com
2757 Added in 7.52.0.
2759 --proxy-crlfile <file>
2761 Same as --crlfile but used in HTTPS proxy context.
2762 Example:
2764 curl --proxy-crlfile rejects.txt -x https://proxy https://example.com
2765 Added in 7.52.0.
2767 --proxy-digest
2769 Tells curl to use HTTP Digest authentication when communicating
2770 with the given proxy. Use --digest for enabling HTTP Digest with
2771 a remote host.
2772 Example:
2774 curl --proxy-digest --proxy-user user:passwd -x proxy https://example.com
2775 See also -x, --proxy, --proxy-anyauth and --proxy-basic.
2777 --proxy-header <header/@file>
2779 (HTTP) Extra header to include in the request when sending HTTP
2780 to a proxy. You may specify any number of extra headers. This is
2781 the equivalent option to -H, --header but is for proxy communi‐
2782 cation only like in CONNECT requests when you want a separate
2783 header sent to the proxy to what is sent to the actual remote
2784 host.
2785 curl will make sure that each header you add/replace is sent
2787 with the proper end-of-line marker, you should thus not add that
2788 as a part of the header content: do not add newlines or carriage
2789 returns, they will only mess things up for you.
2790 Headers specified with this option will not be included in re‐
2792 quests that curl knows will not be sent to a proxy.
2793 Starting in 7.55.0, this option can take an argument in @file‐
2795 name style, which then adds a header for each line in the input
2796 file. Using @- will make curl read the header file from stdin.
2797 This option can be used multiple times to add/replace/remove
2799 multiple headers.
2800 Examples:
2802 curl --proxy-header "X-First-Name: Joe" -x http://proxy https://example.com
2803 curl --proxy-header "User-Agent: surprise" -x http://proxy https://example.com
2804 curl --proxy-header "Host:" -x http://proxy https://example.com
2805 Added in 7.37.0.
2807 --proxy-insecure
2809 Same as -k, --insecure but used in HTTPS proxy context.
2810 Example:
2812 curl --proxy-insecure -x https://proxy https://example.com
2813 Added in 7.52.0.
2815 --proxy-key-type <type>
2817 Same as --key-type but used in HTTPS proxy context.
2818 Example:
2820 curl --proxy-key-type DER --proxy-key here -x https://proxy https://example.com
2821 Added in 7.52.0.
2823 --proxy-key <key>
2825 Same as --key but used in HTTPS proxy context.
2826 Example:
2828 curl --proxy-key here -x https://proxy https://example.com
2829 --proxy-negotiate
2831 Tells curl to use HTTP Negotiate (SPNEGO) authentication when
2832 communicating with the given proxy. Use --negotiate for enabling
2833 HTTP Negotiate (SPNEGO) with a remote host.
2834 Example:
2836 curl --proxy-negotiate --proxy-user user:passwd -x proxy https://example.com
2837 See also --proxy-anyauth and --proxy-basic. Added in 7.17.1.
2839 --proxy-ntlm
2841 Tells curl to use HTTP NTLM authentication when communicating
2842 with the given proxy. Use --ntlm for enabling NTLM with a remote
2843 host.
2844 Example:
2846 curl --proxy-ntlm --proxy-user user:passwd -x http://proxy https://example.com
2847 See also --proxy-negotiate and --proxy-anyauth.
2849 --proxy-pass <phrase>
2851 Same as --pass but used in HTTPS proxy context.
2852 Example:
2854 curl --proxy-pass secret --proxy-key here -x https://proxy https://example.com
2855 Added in 7.52.0.
2857 --proxy-pinnedpubkey <hashes>
2859 (TLS) Tells curl to use the specified public key file (or
2860 hashes) to verify the proxy. This can be a path to a file which
2861 contains a single public key in PEM or DER format, or any number
2862 of base64 encoded sha256 hashes preceded by ´sha256//´ and sepa‐
2863 rated by ´;´
2864 When negotiating a TLS or SSL connection, the server sends a
2866 certificate indicating its identity. A public key is extracted
2867 from this certificate and if it does not exactly match the pub‐
2868 lic key provided to this option, curl will abort the connection
2869 before sending or receiving any data.
2870 If this option is used several times, the last one will be used.
2872 Examples:
2874 curl --proxy-pinnedpubkey keyfile https://example.com
2875 curl --proxy-pinnedpubkey 'sha256//ce118b51897f4452dc' https://example.com
2876 --proxy-service-name <name>
2878 This option allows you to change the service name for proxy ne‐
2879 gotiation.
2880 Example:
2882 curl --proxy-service-name "shrubbery" -x proxy https://example.com
2883 Added in 7.43.0.
2885 --proxy-ssl-allow-beast
2887 Same as --ssl-allow-beast but used in HTTPS proxy context.
2888 Example:
2890 curl --proxy-ssl-allow-beast -x https://proxy https://example.com
2891 Added in 7.52.0.
2893 --proxy-ssl-auto-client-cert
2895 Same as --ssl-auto-client-cert but used in HTTPS proxy context.
2896 Example:
2898 curl --proxy-ssl-auto-client-cert -x https://proxy https://example.com
2899 Added in 7.77.0.
2901 --proxy-tls13-ciphers <ciphersuite list>
2903 (TLS) Specifies which cipher suites to use in the connection to
2904 your HTTPS proxy when it negotiates TLS 1.3. The list of ciphers
2905 suites must specify valid ciphers. Read up on TLS 1.3 cipher
2906 suite details on this URL:
2907 https://curl.se/docs/ssl-ciphers.html
2909 This option is currently used only when curl is built to use
2911 OpenSSL 1.1.1 or later. If you are using a different SSL backend
2912 you can try setting TLS 1.3 cipher suites by using the --proxy-
2913 ciphers option.
2914 If this option is used several times, the last one will be used.
2916 Example:
2918 curl --proxy-tls13-ciphers TLS_AES_128_GCM_SHA256 -x proxy https://example.com
2919 --proxy-tlsauthtype <type>
2921 Same as --tlsauthtype but used in HTTPS proxy context.
2922 Example:
2924 curl --proxy-tlsauthtype SRP -x https://proxy https://example.com
2925 Added in 7.52.0.
2927 --proxy-tlspassword <string>
2929 Same as --tlspassword but used in HTTPS proxy context.
2930 Example:
2932 curl --proxy-tlspassword passwd -x https://proxy https://example.com
2933 Added in 7.52.0.
2935 --proxy-tlsuser <name>
2937 Same as --tlsuser but used in HTTPS proxy context.
2938 Example:
2940 curl --proxy-tlsuser smith -x https://proxy https://example.com
2941 Added in 7.52.0.
2943 --proxy-tlsv1
2945 Same as -1, --tlsv1 but used in HTTPS proxy context.
2946 Example:
2948 curl --proxy-tlsv1 -x https://proxy https://example.com
2949 Added in 7.52.0.
2951 -U, --proxy-user <user:password>
2953 Specify the user name and password to use for proxy authentica‐
2954 tion.
2955 If you use a Windows SSPI-enabled curl binary and do either Ne‐
2957 gotiate or NTLM authentication then you can tell curl to select
2958 the user name and password from your environment by specifying a
2959 single colon with this option: "-U :".
2960 On systems where it works, curl will hide the given option argu‐
2962 ment from process listings. This is not enough to protect cre‐
2963 dentials from possibly getting seen by other users on the same
2964 system as they will still be visible for a brief moment before
2965 cleared. Such sensitive data should be retrieved from a file in‐
2966 stead or similar and never used in clear text in a command line.
2967 If this option is used several times, the last one will be used.
2969 Example:
2971 curl --proxy-user name:pwd -x proxy https://example.com
2972 -x, --proxy [protocol://]host[:port]
2974 Use the specified proxy.
2975 The proxy string can be specified with a protocol:// prefix. No
2977 protocol specified or http:// will be treated as HTTP proxy. Use
2978 socks4://, socks4a://, socks5:// or socks5h:// to request a spe‐
2979 cific SOCKS version to be used. (The protocol support was added
2980 in curl 7.21.7)
2981 HTTPS proxy support via https:// protocol prefix was added in
2983 7.52.0 for OpenSSL, GnuTLS and NSS.
2984 Unrecognized and unsupported proxy protocols cause an error
2986 since 7.52.0. Prior versions may ignore the protocol and use
2987 http:// instead.
2988 If the port number is not specified in the proxy string, it is
2990 assumed to be 1080.
2991 This option overrides existing environment variables that set
2993 the proxy to use. If there's an environment variable setting a
2994 proxy, you can set proxy to "" to override it.
2995 All operations that are performed over an HTTP proxy will trans‐
2997 parently be converted to HTTP. It means that certain protocol
2998 specific operations might not be available. This is not the case
2999 if you can tunnel through the proxy, as one with the -p, --prox‐
3000 ytunnel option.
3001 User and password that might be provided in the proxy string are
3003 URL decoded by curl. This allows you to pass in special charac‐
3004 ters such as @ by using %40 or pass in a colon with %3a.
3005 The proxy host can be specified the exact same way as the proxy
3007 environment variables, including the protocol prefix (http://)
3008 and the embedded user + password.
3009 If this option is used several times, the last one will be used.
3011 Example:
3013 curl --proxy http://proxy.example https://example.com
3014 --proxy1.0 <host[:port]>
3016 Use the specified HTTP 1.0 proxy. If the port number is not
3017 specified, it is assumed at port 1080.
3018 The only difference between this and the HTTP proxy option -x,
3020 --proxy, is that attempts to use CONNECT through the proxy will
3021 specify an HTTP 1.0 protocol instead of the default HTTP 1.1.
3022 Example:
3024 curl --proxy1.0 -x http://proxy https://example.com
3025 -p, --proxytunnel
3027 When an HTTP proxy is used -x, --proxy, this option will make
3028 curl tunnel through the proxy. The tunnel approach is made with
3029 the HTTP proxy CONNECT request and requires that the proxy al‐
3030 lows direct connect to the remote port number curl wants to tun‐
3031 nel through to.
3032 To suppress proxy CONNECT response headers when curl is set to
3034 output headers use --suppress-connect-headers.
3035 Example:
3037 curl --proxytunnel -x http://proxy https://example.com
3038 See also -x, --proxy.
3040 --pubkey <key>
3042 (SFTP SCP) Public key file name. Allows you to provide your pub‐
3043 lic key in this separate file.
3044 If this option is used several times, the last one will be used.
3046 (As of 7.39.0, curl attempts to automatically extract the public
3048 key from the private key file, so passing this option is gener‐
3049 ally not required. Note that this public key extraction requires
3050 libcurl to be linked against a copy of libssh2 1.2.8 or higher
3051 that is itself linked against OpenSSL.)
3052 Example:
3054 curl --pubkey file.pub sftp://example.com/
3055 -Q, --quote <command>
3057 (FTP SFTP) Send an arbitrary command to the remote FTP or SFTP
3058 server. Quote commands are sent BEFORE the transfer takes place
3059 (just after the initial PWD command in an FTP transfer, to be
3060 exact). To make commands take place after a successful transfer,
3061 prefix them with a dash '-'. To make commands be sent after
3062 curl has changed the working directory, just before the transfer
3063 command(s), prefix the command with a '+' (this is only sup‐
3064 ported for FTP). You may specify any number of commands.
3065 By default curl will stop at first failure. To make curl con‐
3067 tinue even if the command fails, prefix the command with an as‐
3068 terisk (*). Otherwise, if the server returns failure for one of
3069 the commands, the entire operation will be aborted.
3070 You must send syntactically correct FTP commands as RFC 959 de‐
3072 fines to FTP servers, or one of the commands listed below to
3073 SFTP servers.
3074 This option can be used multiple times.
3076 SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP
3078 quote commands itself before sending them to the server. File
3079 names may be quoted shell-style to embed spaces or special char‐
3080 acters. Following is the list of all supported SFTP quote com‐
3081 mands:
3082 atime date file
3084 The atime command sets the last access time of the file
3085 named by the file operand. The <date expression> can be
3086 all sorts of date strings, see the curl_getdate(3) man
3087 page for date expression details. (Added in 7.73.0)
3088 chgrp group file
3090 The chgrp command sets the group ID of the file named by
3091 the file operand to the group ID specified by the group
3092 operand. The group operand is a decimal integer group ID.
3093 chmod mode file
3095 The chmod command modifies the file mode bits of the
3096 specified file. The mode operand is an octal integer mode
3097 number.
3098 chown user file
3100 The chown command sets the owner of the file named by the
3101 file operand to the user ID specified by the user oper‐
3102 and. The user operand is a decimal integer user ID.
3103 ln source_file target_file
3105 The ln and symlink commands create a symbolic link at the
3106 target_file location pointing to the source_file loca‐
3107 tion.
3108 mkdir directory_name
3110 The mkdir command creates the directory named by the di‐
3111 rectory_name operand.
3112 mtime date file
3114 The mtime command sets the last modification time of the
3115 file named by the file operand. The <date expression> can
3116 be all sorts of date strings, see the curl_getdate(3) man
3117 page for date expression details. (Added in 7.73.0)
3118 pwd The pwd command returns the absolute pathname of the cur‐
3120 rent working directory.
3121 rename source target
3123 The rename command renames the file or directory named by
3124 the source operand to the destination path named by the
3125 target operand.
3126 rm file
3128 The rm command removes the file specified by the file op‐
3129 erand.
3130 rmdir directory
3132 The rmdir command removes the directory entry specified
3133 by the directory operand, provided it is empty.
3134 symlink source_file target_file
3136 See ln.
3137 Example:
3139 curl --quote "DELE file" ftp://example.com/foo
3140 --random-file <file>
3142 Specify the path name to file containing what will be considered
3143 as random data. The data may be used to seed the random engine
3144 for SSL connections. See also the --egd-file option.
3145 Example:
3147 curl --random-file rubbish https://example.com
3148 -r, --range <range>
3150 (HTTP FTP SFTP FILE) Retrieve a byte range (i.e. a partial docu‐
3151 ment) from an HTTP/1.1, FTP or SFTP server or a local FILE.
3152 Ranges can be specified in a number of ways.
3153 0-499 specifies the first 500 bytes
3155 500-999 specifies the second 500 bytes
3157 -500 specifies the last 500 bytes
3159 9500- specifies the bytes from offset 9500 and forward
3161 0-0,-1 specifies the first and last byte only(*)(HTTP)
3163 100-199,500-599
3165 specifies two separate 100-byte ranges(*) (HTTP)
3166 (*) = NOTE that this will cause the server to reply with a mul‐
3168 tipart response, which will be returned as-is by curl! Parsing
3169 or otherwise transforming this response is the responsibility of
3170 the caller.
3171 Only digit characters (0-9) are valid in the 'start' and 'stop'
3173 fields of the 'start-stop' range syntax. If a non-digit charac‐
3174 ter is given in the range, the server's response will be unspec‐
3175 ified, depending on the server's configuration.
3176 You should also be aware that many HTTP/1.1 servers do not have
3178 this feature enabled, so that when you attempt to get a range,
3179 you'll instead get the whole document.
3180 FTP and SFTP range downloads only support the simple 'start-
3182 stop' syntax (optionally with one of the numbers omitted). FTP
3183 use depends on the extended FTP command SIZE.
3184 If this option is used several times, the last one will be used.
3186 Example:
3188 curl --range 22-44 https://example.com
3189 --raw (HTTP) When used, it disables all internal HTTP decoding of con‐
3191 tent or transfer encodings and instead makes them passed on un‐
3192 altered, raw.
3193 Example:
3195 curl --raw https://example.com
3196 Added in 7.16.2.
3198 -e, --referer <URL>
3200 (HTTP) Sends the "Referrer Page" information to the HTTP server.
3201 This can also be set with the -H, --header flag of course. When
3202 used with -L, --location you can append ";auto" to the -e,
3203 --referer URL to make curl automatically set the previous URL
3204 when it follows a Location: header. The ";auto" string can be
3205 used alone, even if you don't set an initial -e, --referer.
3206 If this option is used several times, the last one will be used.
3208 Examples:
3210 curl --referer "https://fake.example" https://example.com
3211 curl --referer "https://fake.example;auto" -L https://example.com
3212 curl --referer ";auto" -L https://example.com
3213 See also -A, --user-agent and -H, --header.
3215 -J, --remote-header-name
3217 (HTTP) This option tells the -O, --remote-name option to use the
3218 server-specified Content-Disposition filename instead of ex‐
3219 tracting a filename from the URL.
3220 If the server specifies a file name and a file with that name
3222 already exists in the current working directory it will not be
3223 overwritten and an error will occur. If the server doesn't spec‐
3224 ify a file name then this option has no effect.
3225 There's no attempt to decode %-sequences (yet) in the provided
3227 file name, so this option may provide you with rather unexpected
3228 file names.
3229 WARNING: Exercise judicious use of this option, especially on
3231 Windows. A rogue server could send you the name of a DLL or
3232 other file that could possibly be loaded automatically by Win‐
3233 dows or some third party software.
3234 Example:
3236 curl -OJ https://example.com/file
3237 --remote-name-all
3239 This option changes the default action for all given URLs to be
3240 dealt with as if -O, --remote-name were used for each one. So if
3241 you want to disable that for a specific URL after --remote-name-
3242 all has been used, you must use "-o -" or --no-remote-name.
3243 Example:
3245 curl --remote-name-all ftp://example.com/file1 ftp://example.com/file2
3246 Added in 7.19.0.
3248 -O, --remote-name
3250 Write output to a local file named like the remote file we get.
3251 (Only the file part of the remote file is used, the path is cut
3252 off.)
3253 The file will be saved in the current working directory. If you
3255 want the file saved in a different directory, make sure you
3256 change the current working directory before invoking curl with
3257 this option.
3258 The remote file name to use for saving is extracted from the
3260 given URL, nothing else, and if it already exists it will be
3261 overwritten. If you want the server to be able to choose the
3262 file name refer to -J, --remote-header-name which can be used in
3263 addition to this option. If the server chooses a file name and
3264 that name already exists it will not be overwritten.
3265 There is no URL decoding done on the file name. If it has %20 or
3267 other URL encoded parts of the name, they will end up as-is as
3268 file name.
3269 You may use this option as many times as the number of URLs you
3271 have.
3272 Example:
3274 curl -O https://example.com/filename
3275 -R, --remote-time
3277 When used, this will make curl attempt to figure out the time‐
3278 stamp of the remote file, and if that is available make the lo‐
3279 cal file get that same timestamp.
3280 Example:
3282 curl --remote-time -o foo https://example.com
3283 --request-target <path>
3285 (HTTP) Tells curl to use an alternative "target" (path) instead
3286 of using the path as provided in the URL. Particularly useful
3287 when wanting to issue HTTP requests without leading slash or
3288 other data that doesn't follow the regular URL pattern, like
3289 "OPTIONS *".
3290 Example:
3292 curl --request-target "*" -X OPTIONS https://example.com
3293 Added in 7.55.0.
3295 -X, --request <command>
3297 (HTTP) Specifies a custom request method to use when communicat‐
3298 ing with the HTTP server. The specified request method will be
3299 used instead of the method otherwise used (which defaults to
3300 GET). Read the HTTP 1.1 specification for details and explana‐
3301 tions. Common additional HTTP requests include PUT and DELETE,
3302 but related technologies like WebDAV offers PROPFIND, COPY, MOVE
3303 and more.
3304 Normally you don't need this option. All sorts of GET, HEAD,
3306 POST and PUT requests are rather invoked by using dedicated com‐
3307 mand line options.
3308 This option only changes the actual word used in the HTTP re‐
3310 quest, it does not alter the way curl behaves. So for example if
3311 you want to make a proper HEAD request, using -X HEAD will not
3312 suffice. You need to use the -I, --head option.
3313 The method string you set with -X, --request will be used for
3315 all requests, which if you for example use -L, --location may
3316 cause unintended side-effects when curl doesn't change request
3317 method according to the HTTP 30x response codes - and similar.
3318 (FTP) Specifies a custom FTP command to use instead of LIST when
3320 doing file lists with FTP.
3321 (POP3) Specifies a custom POP3 command to use instead of LIST or
3323 RETR. (Added in 7.26.0)
3324 (IMAP) Specifies a custom IMAP command to use instead of LIST.
3326 (Added in 7.30.0)
3327 (SMTP) Specifies a custom SMTP command to use instead of HELP or
3329 VRFY. (Added in 7.34.0)
3330 If this option is used several times, the last one will be used.
3332 Examples:
3334 curl -X "DELETE" https://example.com
3335 curl -X NLST ftp://example.com/
3336 --resolve <[+]host:port:addr[,addr]...>
3338 Provide a custom address for a specific host and port pair. Us‐
3339 ing this, you can make the curl requests(s) use a specified ad‐
3340 dress and prevent the otherwise normally resolved address to be
3341 used. Consider it a sort of /etc/hosts alternative provided on
3342 the command line. The port number should be the number used for
3343 the specific protocol the host will be used for. It means you
3344 need several entries if you want to provide address for the same
3345 host but different ports.
3346 By specifying '*' as host you can tell curl to resolve any host
3348 and specific port pair to the specified address. Wildcard is re‐
3349 solved last so any --resolve with a specific host and port will
3350 be used first.
3351 The provided address set by this option will be used even if -4,
3353 --ipv4 or -6, --ipv6 is set to make curl use another IP version.
3354 By prefixing the host with a '+' you can make the entry time out
3356 after curl's default timeout (1 minute). Note that this will
3357 only make sense for long running parallel transfers with a lot
3358 of files. In such cases, if this option is used curl will try to
3359 resolve the host as it normally would once the timeout has ex‐
3360 pired.
3361 Support for providing the IP address within [brackets] was added
3363 in 7.57.0.
3364 Support for providing multiple IP addresses per entry was added
3366 in 7.59.0.
3367 Support for resolving with wildcard was added in 7.64.0.
3369 Support for the '+' prefix was was added in 7.75.0.
3371 This option can be used many times to add many host names to re‐
3373 solve.
3374 Example:
3376 curl --resolve example.com:443:127.0.0.1 https://example.com
3377 Added in 7.21.3.
3379 --retry-all-errors
3381 Retry on any error. This option is used together with --retry.
3382 This option is the "sledgehammer" of retrying. Do not use this
3384 option by default (eg in curlrc), there may be unintended conse‐
3385 quences such as sending or receiving duplicate data. Do not use
3386 with redirected input or output. You'd be much better off han‐
3387 dling your unique problems in shell script. Please read the ex‐
3388 ample below.
3389 WARNING: For server compatibility curl attempts to retry failed
3391 flaky transfers as close as possible to how they were started,
3392 but this is not possible with redirected input or output. For
3393 example, before retrying it removes output data from a failed
3394 partial transfer that was written to an output file. However
3395 this is not true of data redirected to a | pipe or > file, which
3396 are not reset. We strongly suggest don't parse or record output
3397 via redirect in combination with this option, since you may re‐
3398 ceive duplicate data.
3399 By default curl will not error on an HTTP response code that in‐
3401 dicates an HTTP error, if the transfer was successful. For exam‐
3402 ple, if a server replies 404 Not Found and the reply is fully
3403 received then that is not an error. When --retry is used then
3404 curl will retry on some HTTP response codes that indicate tran‐
3405 sient HTTP errors, but that does not include most 4xx response
3406 codes such as 404. If you want to retry on all response codes
3407 that indicate HTTP errors (4xx and 5xx) then combine with -f,
3408 --fail.
3409 Example:
3411 curl --retry-all-errors https://example.com
3412 Added in 7.71.0.
3414 --retry-connrefused
3416 In addition to the other conditions, consider ECONNREFUSED as a
3417 transient error too for --retry. This option is used together
3418 with --retry.
3419 Example:
3421 curl --retry-connrefused --retry https://example.com
3422 Added in 7.52.0.
3424 --retry-delay <seconds>
3426 Make curl sleep this amount of time before each retry when a
3427 transfer has failed with a transient error (it changes the de‐
3428 fault backoff time algorithm between retries). This option is
3429 only interesting if --retry is also used. Setting this delay to
3430 zero will make curl use the default backoff time.
3431 If this option is used several times, the last one will be used.
3433 Example:
3435 curl --retry-delay 5 --retry https://example.com
3436 Added in 7.12.3.
3438 --retry-max-time <seconds>
3440 The retry timer is reset before the first transfer attempt. Re‐
3441 tries will be done as usual (see --retry) as long as the timer
3442 hasn't reached this given limit. Notice that if the timer hasn't
3443 reached the limit, the request will be made and while perform‐
3444 ing, it may take longer than this given time period. To limit a
3445 single request´s maximum time, use -m, --max-time. Set this op‐
3446 tion to zero to not timeout retries.
3447 If this option is used several times, the last one will be used.
3449 Example:
3451 curl --retry-max-time 30 --retry 10 https://example.com
3452 Added in 7.12.3.
3454 --retry <num>
3456 If a transient error is returned when curl tries to perform a
3457 transfer, it will retry this number of times before giving up.
3458 Setting the number to 0 makes curl do no retries (which is the
3459 default). Transient error means either: a timeout, an FTP 4xx
3460 response code or an HTTP 408, 429, 500, 502, 503 or 504 response
3461 code.
3462 When curl is about to retry a transfer, it will first wait one
3464 second and then for all forthcoming retries it will double the
3465 waiting time until it reaches 10 minutes which then will be the
3466 delay between the rest of the retries. By using --retry-delay
3467 you disable this exponential backoff algorithm. See also
3468 --retry-max-time to limit the total time allowed for retries.
3469 Since curl 7.66.0, curl will comply with the Retry-After: re‐
3471 sponse header if one was present to know when to issue the next
3472 retry.
3473 If this option is used several times, the last one will be used.
3475 Example:
3477 curl --retry 7 https://example.com
3478 Added in 7.12.3.
3480 --sasl-authzid <identity>
3482 Use this authorisation identity (authzid), during SASL PLAIN au‐
3483 thentication, in addition to the authentication identity (auth‐
3484 cid) as specified by -u, --user.
3485 If the option isn't specified, the server will derive the au‐
3487 thzid from the authcid, but if specified, and depending on the
3488 server implementation, it may be used to access another user's
3489 inbox, that the user has been granted access to, or a shared
3490 mailbox for example.
3491 Example:
3493 curl --sasl-authzid zid imap://example.com/
3494 Added in 7.66.0.
3496 --sasl-ir
3498 Enable initial response in SASL authentication.
3499 Example:
3501 curl --sasl-ir imap://example.com/
3502 Added in 7.31.0.
3504 --service-name <name>
3506 This option allows you to change the service name for SPNEGO.
3507 Examples: --negotiate --service-name sockd would use
3509 sockd/server-name.
3510 Example:
3512 curl --service-name sockd/server https://example.com
3513 Added in 7.43.0.
3515 -S, --show-error
3517 When used with -s, --silent, it makes curl show an error message
3518 if it fails.
3519 This option is global and does not need to be specified for each
3521 use of -:, --next.
3522 Example:
3524 curl --show-error --silent https://example.com
3525 See also --no-progress-meter.
3527 -s, --silent
3529 Silent or quiet mode. Don't show progress meter or error mes‐
3530 sages. Makes Curl mute. It will still output the data you ask
3531 for, potentially even to the terminal/stdout unless you redirect
3532 it.
3533 Use -S, --show-error in addition to this option to disable
3535 progress meter but still show error messages.
3536 Example:
3538 curl -s https://example.com
3539 See also -v, --verbose, --stderr and --no-progress-meter.
3541 --socks4 <host[:port]>
3543 Use the specified SOCKS4 proxy. If the port number is not speci‐
3544 fied, it is assumed at port 1080. Using this socket type make
3545 curl resolve the host name and passing the address on to the
3546 proxy.
3547 This option overrides any previous use of -x, --proxy, as they
3549 are mutually exclusive.
3550 Since 7.21.7, this option is superfluous since you can specify a
3552 socks4 proxy with -x, --proxy using a socks4:// protocol prefix.
3553 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
3555 the same time -x, --proxy is used with an HTTP/HTTPS proxy. In
3556 such a case curl first connects to the SOCKS proxy and then con‐
3557 nects (through SOCKS) to the HTTP or HTTPS proxy.
3558 If this option is used several times, the last one will be used.
3560 Example:
3562 curl --socks4 hostname:4096 https://example.com
3563 Added in 7.15.2.
3565 --socks4a <host[:port]>
3567 Use the specified SOCKS4a proxy. If the port number is not spec‐
3568 ified, it is assumed at port 1080. This asks the proxy to re‐
3569 solve the host name.
3570 This option overrides any previous use of -x, --proxy, as they
3572 are mutually exclusive.
3573 Since 7.21.7, this option is superfluous since you can specify a
3575 socks4a proxy with -x, --proxy using a socks4a:// protocol pre‐
3576 fix.
3577 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
3579 the same time -x, --proxy is used with an HTTP/HTTPS proxy. In
3580 such a case curl first connects to the SOCKS proxy and then con‐
3581 nects (through SOCKS) to the HTTP or HTTPS proxy.
3582 If this option is used several times, the last one will be used.
3584 Example:
3586 curl --socks4a hostname:4096 https://example.com
3587 Added in 7.18.0.
3589 --socks5-basic
3591 Tells curl to use username/password authentication when connect‐
3592 ing to a SOCKS5 proxy. The username/password authentication is
3593 enabled by default. Use --socks5-gssapi to force GSS-API au‐
3594 thentication to SOCKS5 proxies.
3595 Example:
3597 curl --socks5-basic --socks5 hostname:4096 https://example.com
3598 Added in 7.55.0.
3600 --socks5-gssapi-nec
3602 As part of the GSS-API negotiation a protection mode is negoti‐
3603 ated. RFC 1961 says in section 4.3/4.4 it should be protected,
3604 but the NEC reference implementation does not. The option
3605 --socks5-gssapi-nec allows the unprotected exchange of the pro‐
3606 tection mode negotiation.
3607 Example:
3609 curl --socks5-gssapi-nec --socks5 hostname:4096 https://example.com
3610 Added in 7.19.4.
3612 --socks5-gssapi-service <name>
3614 The default service name for a socks server is rcmd/server-fqdn.
3615 This option allows you to change it.
3616 Examples: --socks5 proxy-name --socks5-gssapi-service sockd
3618 would use sockd/proxy-name --socks5 proxy-name --socks5-gssapi-
3619 service sockd/real-name would use sockd/real-name for cases
3620 where the proxy-name does not match the principal name.
3621 Example:
3623 curl --socks5-gssapi-service sockd --socks5 hostname:4096 https://example.com
3624 Added in 7.19.4.
3626 --socks5-gssapi
3628 Tells curl to use GSS-API authentication when connecting to a
3629 SOCKS5 proxy. The GSS-API authentication is enabled by default
3630 (if curl is compiled with GSS-API support). Use --socks5-basic
3631 to force username/password authentication to SOCKS5 proxies.
3632 Example:
3634 curl --socks5-gssapi --socks5 hostname:4096 https://example.com
3635 Added in 7.55.0.
3637 --socks5-hostname <host[:port]>
3639 Use the specified SOCKS5 proxy (and let the proxy resolve the
3640 host name). If the port number is not specified, it is assumed
3641 at port 1080.
3642 This option overrides any previous use of -x, --proxy, as they
3644 are mutually exclusive.
3645 Since 7.21.7, this option is superfluous since you can specify a
3647 socks5 hostname proxy with -x, --proxy using a socks5h:// proto‐
3648 col prefix.
3649 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
3651 the same time -x, --proxy is used with an HTTP/HTTPS proxy. In
3652 such a case curl first connects to the SOCKS proxy and then con‐
3653 nects (through SOCKS) to the HTTP or HTTPS proxy.
3654 If this option is used several times, the last one will be used.
3656 Example:
3658 curl --socks5-hostname proxy.example:7000 https://example.com
3659 Added in 7.18.0.
3661 --socks5 <host[:port]>
3663 Use the specified SOCKS5 proxy - but resolve the host name lo‐
3664 cally. If the port number is not specified, it is assumed at
3665 port 1080.
3666 This option overrides any previous use of -x, --proxy, as they
3668 are mutually exclusive.
3669 Since 7.21.7, this option is superfluous since you can specify a
3671 socks5 proxy with -x, --proxy using a socks5:// protocol prefix.
3672 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
3674 the same time -x, --proxy is used with an HTTP/HTTPS proxy. In
3675 such a case curl first connects to the SOCKS proxy and then con‐
3676 nects (through SOCKS) to the HTTP or HTTPS proxy.
3677 If this option is used several times, the last one will be used.
3679 This option (as well as --socks4) does not work with IPV6, FTPS
3681 or LDAP.
3682 Example:
3684 curl --socks5 proxy.example:7000 https://example.com
3685 Added in 7.18.0.
3687 -Y, --speed-limit <speed>
3689 If a download is slower than this given speed (in bytes per sec‐
3690 ond) for speed-time seconds it gets aborted. speed-time is set
3691 with -y, --speed-time and is 30 if not set.
3692 If this option is used several times, the last one will be used.
3694 Example:
3696 curl --speed-limit 300 --speed-time 10 https://example.com
3697 -y, --speed-time <seconds>
3699 If a download is slower than speed-limit bytes per second during
3700 a speed-time period, the download gets aborted. If speed-time is
3701 used, the default speed-limit will be 1 unless set with -Y,
3702 --speed-limit.
3703 This option controls transfers and thus will not affect slow
3705 connects etc. If this is a concern for you, try the --connect-
3706 timeout option.
3707 If this option is used several times, the last one will be used.
3709 Example:
3711 curl --speed-limit 300 --speed-time 10 https://example.com
3712 --ssl-allow-beast
3714 This option tells curl to not work around a security flaw in the
3715 SSL3 and TLS1.0 protocols known as BEAST. If this option isn't
3716 used, the SSL layer may use workarounds known to cause interop‐
3717 erability problems with some older SSL implementations.
3718 WARNING: this option loosens the SSL security, and by using this
3720 flag you ask for exactly that.
3721 Example:
3723 curl --ssl-allow-beast https://example.com
3724 Added in 7.25.0.
3726 --ssl-auto-client-cert
3728 Tell libcurl to automatically locate and use a client certifi‐
3729 cate for authentication, when requested by the server. This op‐
3730 tion is only supported for Schannel (the native Windows SSL li‐
3731 brary). Prior to 7.77.0 this was the default behavior in libcurl
3732 with Schannel. Since the server can request any certificate that
3733 supports client authentication in the OS certificate store it
3734 could be a privacy violation and unexpected.
3735 Example:
3737 curl --ssl-auto-client-cert https://example.com
3738 See also --proxy-ssl-auto-client-cert. Added in 7.77.0.
3740 --ssl-no-revoke
3742 (Schannel) This option tells curl to disable certificate revoca‐
3743 tion checks. WARNING: this option loosens the SSL security, and
3744 by using this flag you ask for exactly that.
3745 Example:
3747 curl --ssl-no-revoke https://example.com
3748 Added in 7.44.0.
3750 --ssl-reqd
3752 (FTP IMAP POP3 SMTP) Require SSL/TLS for the connection. Termi‐
3753 nates the connection if the server doesn't support SSL/TLS.
3754 This option was formerly known as --ftp-ssl-reqd.
3756 Example:
3758 curl --ssl-reqd ftp://example.com
3759 Added in 7.20.0.
3761 --ssl-revoke-best-effort
3763 (Schannel) This option tells curl to ignore certificate revoca‐
3764 tion checks when they failed due to missing/offline distribution
3765 points for the revocation check lists.
3766 Example:
3768 curl --ssl-revoke-best-effort https://example.com
3769 Added in 7.70.0.
3771 --ssl (FTP IMAP POP3 SMTP) Try to use SSL/TLS for the connection. Re‐
3773 verts to a non-secure connection if the server doesn't support
3774 SSL/TLS. See also --ftp-ssl-control and --ssl-reqd for differ‐
3775 ent levels of encryption required.
3776 This option was formerly known as --ftp-ssl (Added in 7.11.0).
3778 That option name can still be used but will be removed in a fu‐
3779 ture version.
3780 Example:
3782 curl --ssl pop3://example.com/
3783 Added in 7.20.0.
3785 -2, --sslv2
3787 (SSL) This option previously asked curl to use SSLv2, but start‐
3788 ing in curl 7.77.0 this instruction is ignored. SSLv2 is widely
3789 considered insecure (see RFC 6176).
3790 Example:
3792 curl --sslv2 https://example.com
3793 See also --http1.1 and --http2. -2, --sslv2 requires that the
3795 underlying libcurl was built to support TLS. This option over‐
3796 rides -3, --sslv3 and -1, --tlsv1 and --tlsv1.1 and --tlsv1.2.
3797 -3, --sslv3
3799 (SSL) This option previously asked curl to use SSLv3, but start‐
3800 ing in curl 7.77.0 this instruction is ignored. SSLv3 is widely
3801 considered insecure (see RFC 7568).
3802 Example:
3804 curl --sslv3 https://example.com
3805 See also --http1.1 and --http2. -3, --sslv3 requires that the
3807 underlying libcurl was built to support TLS. This option over‐
3808 rides -2, --sslv2 and -1, --tlsv1 and --tlsv1.1 and --tlsv1.2.
3809 --stderr <file>
3811 Redirect all writes to stderr to the specified file instead. If
3812 the file name is a plain '-', it is instead written to stdout.
3813 This option is global and does not need to be specified for each
3815 use of -:, --next.
3816 If this option is used several times, the last one will be used.
3818 Example:
3820 curl --stderr output.txt https://example.com
3821 See also -v, --verbose and -s, --silent.
3823 --styled-output
3825 Enables the automatic use of bold font styles when writing HTTP
3826 headers to the terminal. Use --no-styled-output to switch them
3827 off.
3828 This option is global and does not need to be specified for each
3830 use of -:, --next.
3831 Example:
3833 curl --styled-output -I https://example.com
3834 Added in 7.61.0.
3836 --suppress-connect-headers
3838 When -p, --proxytunnel is used and a CONNECT request is made
3839 don't output proxy CONNECT response headers. This option is
3840 meant to be used with -D, --dump-header or -i, --include which
3841 are used to show protocol headers in the output. It has no ef‐
3842 fect on debug options such as -v, --verbose or --trace, or any
3843 statistics.
3844 Example:
3846 curl --suppress-connect-headers --include -x proxy https://example.com
3847 See also -D, --dump-header, -i, --include and -p, --proxytunnel.
3849 --tcp-fastopen
3851 Enable use of TCP Fast Open (RFC7413).
3852 Example:
3854 curl --tcp-fastopen https://example.com
3855 Added in 7.49.0.
3857 --tcp-nodelay
3859 Turn on the TCP_NODELAY option. See the curl_easy_setopt(3) man
3860 page for details about this option.
3861 Since 7.50.2, curl sets this option by default and you need to
3863 explicitly switch it off if you don't want it on.
3864 Example:
3866 curl --tcp-nodelay https://example.com
3867 Added in 7.11.2.
3869 -t, --telnet-option <opt=val>
3871 Pass options to the telnet protocol. Supported options are:
3872 TTYPE=<term> Sets the terminal type.
3874 XDISPLOC=<X display> Sets the X display location.
3876 NEW_ENV=<var,val> Sets an environment variable.
3878 Example:
3880 curl -t TTYPE=vt100 telnet://example.com/
3881 --tftp-blksize <value>
3883 (TFTP) Set TFTP BLKSIZE option (must be >512). This is the block
3884 size that curl will try to use when transferring data to or from
3885 a TFTP server. By default 512 bytes will be used.
3886 If this option is used several times, the last one will be used.
3888 Example:
3890 curl --tftp-blksize 1024 tftp://example.com/file
3891 Added in 7.20.0.
3893 --tftp-no-options
3895 (TFTP) Tells curl not to send TFTP options requests.
3896 This option improves interop with some legacy servers that do
3898 not acknowledge or properly implement TFTP options. When this
3899 option is used --tftp-blksize is ignored.
3900 Example:
3902 curl --tftp-no-options tftp://192.168.0.1/
3903 Added in 7.48.0.
3905 -z, --time-cond <time>
3907 (HTTP FTP) Request a file that has been modified later than the
3908 given time and date, or one that has been modified before that
3909 time. The <date expression> can be all sorts of date strings or
3910 if it doesn't match any internal ones, it is taken as a filename
3911 and tries to get the modification date (mtime) from <file> in‐
3912 stead. See the curl_getdate(3) man pages for date expression de‐
3913 tails.
3914 Start the date expression with a dash (-) to make it request for
3916 a document that is older than the given date/time, default is a
3917 document that is newer than the specified date/time.
3918 If this option is used several times, the last one will be used.
3920 Examples:
3922 curl -z "Wed 01 Sep 2021 12:18:00" https://example.com
3923 curl -z "-Wed 01 Sep 2021 12:18:00" https://example.com
3924 curl -z file https://example.com
3925 --tls-max <VERSION>
3927 (SSL) VERSION defines maximum supported TLS version. The minimum
3928 acceptable version is set by tlsv1.0, tlsv1.1, tlsv1.2 or
3929 tlsv1.3.
3930 If the connection is done without TLS, this option has no ef‐
3932 fect. This includes QUIC-using (HTTP/3) transfers.
3933 default
3936 Use up to recommended TLS version.
3937 1.0 Use up to TLSv1.0.
3939 1.1 Use up to TLSv1.1.
3941 1.2 Use up to TLSv1.2.
3943 1.3 Use up to TLSv1.3.
3945 Examples:
3947 curl --tls-max 1.2 https://example.com
3948 curl --tls-max 1.3 --tlsv1.2 https://example.com
3949 See also --tlsv1.0, --tlsv1.1, --tlsv1.2 and --tlsv1.3. --tls-max re‐
3951 quires that the underlying libcurl was built to support TLS. Added in
3952 7.54.0.
3953 --tls13-ciphers <ciphersuite list>
3955 (TLS) Specifies which cipher suites to use in the connection if
3956 it negotiates TLS 1.3. The list of ciphers suites must specify
3957 valid ciphers. Read up on TLS 1.3 cipher suite details on this
3958 URL:
3959 https://curl.se/docs/ssl-ciphers.html
3961 This option is currently used only when curl is built to use
3963 OpenSSL 1.1.1 or later. If you are using a different SSL backend
3964 you can try setting TLS 1.3 cipher suites by using the --ciphers
3965 option.
3966 If this option is used several times, the last one will be used.
3968 Example:
3970 curl --tls13-ciphers TLS_AES_128_GCM_SHA256 https://example.com
3971 --tlsauthtype <type>
3973 Set TLS authentication type. Currently, the only supported op‐
3974 tion is "SRP", for TLS-SRP (RFC 5054). If --tlsuser and
3975 --tlspassword are specified but --tlsauthtype is not, then this
3976 option defaults to "SRP". This option works only if the under‐
3977 lying libcurl is built with TLS-SRP support, which requires
3978 OpenSSL or GnuTLS with TLS-SRP support.
3979 Example:
3981 curl --tlsauthtype SRP https://example.com
3982 Added in 7.21.4.
3984 --tlspassword <string>
3986 Set password for use with the TLS authentication method speci‐
3987 fied with --tlsauthtype. Requires that --tlsuser also be set.
3988 This doesn't work with TLS 1.3.
3990 Example:
3992 curl --tlspassword pwd --tlsuser user https://example.com
3993 Added in 7.21.4.
3995 --tlsuser <name>
3997 Set username for use with the TLS authentication method speci‐
3998 fied with --tlsauthtype. Requires that --tlspassword also is
3999 set.
4000 This doesn't work with TLS 1.3.
4002 Example:
4004 curl --tlspassword pwd --tlsuser user https://example.com
4005 Added in 7.21.4.
4007 --tlsv1.0
4009 (TLS) Forces curl to use TLS version 1.0 or later when connect‐
4010 ing to a remote TLS server.
4011 In old versions of curl this option was documented to allow
4013 _only_ TLS 1.0, but behavior was inconsistent depending on the
4014 TLS library. Use --tls-max if you want to set a maximum TLS ver‐
4015 sion.
4016 Example:
4018 curl --tlsv1.0 https://example.com
4019 Added in 7.34.0.
4021 --tlsv1.1
4023 (TLS) Forces curl to use TLS version 1.1 or later when connect‐
4024 ing to a remote TLS server.
4025 In old versions of curl this option was documented to allow
4027 _only_ TLS 1.1, but behavior was inconsistent depending on the
4028 TLS library. Use --tls-max if you want to set a maximum TLS ver‐
4029 sion.
4030 Example:
4032 curl --tlsv1.1 https://example.com
4033 Added in 7.34.0.
4035 --tlsv1.2
4037 (TLS) Forces curl to use TLS version 1.2 or later when connect‐
4038 ing to a remote TLS server.
4039 In old versions of curl this option was documented to allow
4041 _only_ TLS 1.2, but behavior was inconsistent depending on the
4042 TLS library. Use --tls-max if you want to set a maximum TLS ver‐
4043 sion.
4044 Example:
4046 curl --tlsv1.2 https://example.com
4047 Added in 7.34.0.
4049 --tlsv1.3
4051 (TLS) Forces curl to use TLS version 1.3 or later when connect‐
4052 ing to a remote TLS server.
4053 If the connection is done without TLS, this option has no ef‐
4055 fect. This includes QUIC-using (HTTP/3) transfers.
4056 Note that TLS 1.3 is not supported by all TLS backends.
4058 Example:
4060 curl --tlsv1.3 https://example.com
4061 Added in 7.52.0.
4063 -1, --tlsv1
4065 (SSL) Tells curl to use at least TLS version 1.x when negotiat‐
4066 ing with a remote TLS server. That means TLS version 1.0 or
4067 higher
4068 Example:
4070 curl --tlsv1 https://example.com
4071 See also --http1.1 and --http2. -1, --tlsv1 requires that the
4073 underlying libcurl was built to support TLS. This option over‐
4074 rides --tlsv1.1 and --tlsv1.2 and --tlsv1.3.
4075 --tr-encoding
4077 (HTTP) Request a compressed Transfer-Encoding response using one
4078 of the algorithms curl supports, and uncompress the data while
4079 receiving it.
4080 Example:
4082 curl --tr-encoding https://example.com
4083 Added in 7.21.6.
4085 --trace-ascii <file>
4087 Enables a full trace dump of all incoming and outgoing data, in‐
4088 cluding descriptive information, to the given output file. Use
4089 "-" as filename to have the output sent to stdout.
4090 This is very similar to --trace, but leaves out the hex part and
4092 only shows the ASCII part of the dump. It makes smaller output
4093 that might be easier to read for untrained humans.
4094 This option is global and does not need to be specified for each
4096 use of -:, --next.
4097 If this option is used several times, the last one will be used.
4099 Example:
4101 curl --trace-ascii log.txt https://example.com
4102 This option overrides --trace and -v, --verbose.
4104 --trace-time
4106 Prepends a time stamp to each trace or verbose line that curl
4107 displays.
4108 This option is global and does not need to be specified for each
4110 use of -:, --next.
4111 Example:
4113 curl --trace-time --trace-ascii output https://example.com
4114 Added in 7.14.0.
4116 --trace <file>
4118 Enables a full trace dump of all incoming and outgoing data, in‐
4119 cluding descriptive information, to the given output file. Use
4120 "-" as filename to have the output sent to stdout. Use "%" as
4121 filename to have the output sent to stderr.
4122 This option is global and does not need to be specified for each
4124 use of -:, --next.
4125 If this option is used several times, the last one will be used.
4127 Example:
4129 curl --trace log.txt https://example.com
4130 This option overrides -v, --verbose and --trace-ascii.
4132 --unix-socket <path>
4134 (HTTP) Connect through this Unix domain socket, instead of using
4135 the network.
4136 Example:
4138 curl --unix-socket socket-path https://example.com
4139 Added in 7.40.0.
4141 -T, --upload-file <file>
4143 This transfers the specified local file to the remote URL. If
4144 there is no file part in the specified URL, curl will append the
4145 local file name. NOTE that you must use a trailing / on the last
4146 directory to really prove to Curl that there is no file name or
4147 curl will think that your last directory name is the remote file
4148 name to use. That will most likely cause the upload operation to
4149 fail. If this is used on an HTTP(S) server, the PUT command will
4150 be used.
4151 Use the file name "-" (a single dash) to use stdin instead of a
4153 given file. Alternately, the file name "." (a single period)
4154 may be specified instead of "-" to use stdin in non-blocking
4155 mode to allow reading server output while stdin is being up‐
4156 loaded.
4157 You can specify one -T, --upload-file for each URL on the com‐
4159 mand line. Each -T, --upload-file + URL pair specifies what to
4160 upload and to where. curl also supports "globbing" of the -T,
4161 --upload-file argument, meaning that you can upload multiple
4162 files to a single URL by using the same URL globbing style sup‐
4163 ported in the URL.
4164 When uploading to an SMTP server: the uploaded data is assumed
4166 to be RFC 5322 formatted. It has to feature the necessary set of
4167 headers and mail body formatted correctly by the user as curl
4168 will not transcode nor encode it further in any way.
4169 Examples:
4171 curl -T file https://example.com
4172 curl -T "img[1-1000].png" ftp://ftp.example.com/
4173 curl --upload-file "{file1,file2}" https://example.com
4174 --url <url>
4176 Specify a URL to fetch. This option is mostly handy when you
4177 want to specify URL(s) in a config file.
4178 If the given URL is missing a scheme name (such as "http://" or
4180 "ftp://" etc) then curl will make a guess based on the host. If
4181 the outermost sub-domain name matches DICT, FTP, IMAP, LDAP,
4182 POP3 or SMTP then that protocol will be used, otherwise HTTP
4183 will be used. Since 7.45.0 guessing can be disabled by setting a
4184 default protocol, see --proto-default for details.
4185 This option may be used any number of times. To control where
4187 this URL is written, use the -o, --output or the -O, --remote-
4188 name options.
4189 WARNING: On Windows, particular file:// accesses can be con‐
4191 verted to network accesses by the operating system. Beware!
4192 Example:
4194 curl --url https://example.com
4195 -B, --use-ascii
4197 (FTP LDAP) Enable ASCII transfer. For FTP, this can also be en‐
4198 forced by using a URL that ends with ";type=A". This option
4199 causes data sent to stdout to be in text mode for win32 systems.
4200 Example:
4202 curl -B ftp://example.com/README
4203 -A, --user-agent <name>
4205 (HTTP) Specify the User-Agent string to send to the HTTP server.
4206 To encode blanks in the string, surround the string with single
4207 quote marks. This header can also be set with the -H, --header
4208 or the --proxy-header options.
4209 If you give an empty argument to -A, --user-agent (""), it will
4211 remove the header completely from the request. If you prefer a
4212 blank header, you can set it to a single space (" ").
4213 If this option is used several times, the last one will be used.
4215 Example:
4217 curl -A "Agent 007" https://example.com
4218 -u, --user <user:password>
4220 Specify the user name and password to use for server authentica‐
4221 tion. Overrides -n, --netrc and --netrc-optional.
4222 If you simply specify the user name, curl will prompt for a
4224 password.
4225 The user name and passwords are split up on the first colon,
4227 which makes it impossible to use a colon in the user name with
4228 this option. The password can, still.
4229 On systems where it works, curl will hide the given option argu‐
4231 ment from process listings. This is not enough to protect cre‐
4232 dentials from possibly getting seen by other users on the same
4233 system as they will still be visible for a brief moment before
4234 cleared. Such sensitive data should be retrieved from a file in‐
4235 stead or similar and never used in clear text in a command line.
4236 When using Kerberos V5 with a Windows based server you should
4238 include the Windows domain name in the user name, in order for
4239 the server to successfully obtain a Kerberos Ticket. If you
4240 don't then the initial authentication handshake may fail.
4241 When using NTLM, the user name can be specified simply as the
4243 user name, without the domain, if there is a single domain and
4244 forest in your setup for example.
4245 To specify the domain name use either Down-Level Logon Name or
4247 UPN (User Principal Name) formats. For example, EXAMPLE\user and
4248 user@example.com respectively.
4249 If you use a Windows SSPI-enabled curl binary and perform Ker‐
4251 beros V5, Negotiate, NTLM or Digest authentication then you can
4252 tell curl to select the user name and password from your envi‐
4253 ronment by specifying a single colon with this option: "-u :".
4254 If this option is used several times, the last one will be used.
4256 Example:
4258 curl -u user:secret https://example.com
4259 -v, --verbose
4261 Makes curl verbose during the operation. Useful for debugging
4262 and seeing what's going on "under the hood". A line starting
4263 with '>' means "header data" sent by curl, '<' means "header
4264 data" received by curl that is hidden in normal cases, and a
4265 line starting with '*' means additional info provided by curl.
4266 If you only want HTTP headers in the output, -i, --include might
4268 be the option you're looking for.
4269 If you think this option still doesn't give you enough details,
4271 consider using --trace or --trace-ascii instead.
4272 This option is global and does not need to be specified for each
4274 use of -:, --next.
4275 Use -s, --silent to make curl really quiet.
4277 Example:
4279 curl --verbose https://example.com
4280 See also -i, --include. This option overrides --trace and
4282 --trace-ascii.
4283 -V, --version
4285 Displays information about curl and the libcurl version it uses.
4286 The first line includes the full version of curl, libcurl and
4288 other 3rd party libraries linked with the executable.
4289 The second line (starts with "Protocols:") shows all protocols
4291 that libcurl reports to support.
4292 The third line (starts with "Features:") shows specific features
4294 libcurl reports to offer. Available features include:
4295 alt-svc
4297 Support for the Alt-Svc: header is provided.
4298 AsynchDNS
4300 This curl uses asynchronous name resolves. Asynchronous
4301 name resolves can be done using either the c-ares or the
4302 threaded resolver backends.
4303 brotli Support for automatic brotli compression over HTTP(S).
4305 CharConv
4307 curl was built with support for character set conversions
4308 (like EBCDIC)
4309 Debug This curl uses a libcurl built with Debug. This enables
4311 more error-tracking and memory debugging etc. For curl-
4312 developers only!
4313 gsasl The built-in SASL authentication includes extensions to
4315 support SCRAM because libcurl was built with libgsasl.
4316 GSS-API
4318 GSS-API is supported.
4319 HSTS HSTS support is present.
4321 HTTP2 HTTP/2 support has been built-in.
4323 HTTP3 HTTP/3 support has been built-in.
4325 HTTPS-proxy
4327 This curl is built to support HTTPS proxy.
4328 IDN This curl supports IDN - international domain names.
4330 IPv6 You can use IPv6 with this.
4332 Kerberos
4334 Kerberos V5 authentication is supported.
4335 Largefile
4337 This curl supports transfers of large files, files larger
4338 than 2GB.
4339 libz Automatic decompression (via gzip, deflate) of compressed
4341 files over HTTP is supported.
4342 MultiSSL
4344 This curl supports multiple TLS backends.
4345 NTLM NTLM authentication is supported.
4347 NTLM_WB
4349 NTLM delegation to winbind helper is supported.
4350 PSL PSL is short for Public Suffix List and means that this
4352 curl has been built with knowledge about "public suf‐
4353 fixes".
4354 SPNEGO SPNEGO authentication is supported.
4356 SSL SSL versions of various protocols are supported, such as
4358 HTTPS, FTPS, POP3S and so on.
4359 SSPI SSPI is supported.
4361 TLS-SRP
4363 SRP (Secure Remote Password) authentication is supported
4364 for TLS.
4365 TrackMemory
4367 Debug memory tracking is supported.
4368 Unicode
4370 Unicode support on Windows.
4371 UnixSockets
4373 Unix sockets support is provided.
4374 zstd Automatic decompression (via zstd) of compressed files
4376 over HTTP is supported.
4377 Example:
4379 curl --version
4380 -w, --write-out <format>
4382 Make curl display information on stdout after a completed trans‐
4383 fer. The format is a string that may contain plain text mixed
4384 with any number of variables. The format can be specified as a
4385 literal "string", or you can have curl read the format from a
4386 file with "@filename" and to tell curl to read the format from
4387 stdin you write "@-".
4388 The variables present in the output format will be substituted
4390 by the value or text that curl thinks fit, as described below.
4391 All variables are specified as %{variable_name} and to output a
4392 normal % you just write them as %%. You can output a newline by
4393 using \n, a carriage return with \r and a tab space with \t.
4394 The output will be written to standard output, but this can be
4396 switched to standard error by using %{stderr}.
4397 NOTE: The %-symbol is a special symbol in the win32-environment,
4399 where all occurrences of % must be doubled when using this op‐
4400 tion.
4401 The variables available are:
4403 content_type The Content-Type of the requested document, if
4405 there was any.
4406 errormsg The error message. (Added in 7.75.0)
4408 exitcode The numerical exitcode of the transfer. (Added in
4410 7.75.0)
4411 filename_effective
4413 The ultimate filename that curl writes out to.
4414 This is only meaningful if curl is told to write
4415 to a file with the -O, --remote-name or -o,
4416 --output option. It's most useful in combination
4417 with the -J, --remote-header-name option. (Added
4418 in 7.26.0)
4419 ftp_entry_path The initial path curl ended up in when logging on
4421 to the remote FTP server. (Added in 7.15.4)
4422 http_code The numerical response code that was found in the
4424 last retrieved HTTP(S) or FTP(s) transfer. In
4425 7.18.2 the alias response_code was added to show
4426 the same info.
4427 http_connect The numerical code that was found in the last re‐
4429 sponse (from a proxy) to a curl CONNECT request.
4430 (Added in 7.12.4)
4431 http_version The http version that was effectively used.
4433 (Added in 7.50.0)
4434 json A JSON object with all available keys.
4436 local_ip The IP address of the local end of the most re‐
4438 cently done connection - can be either IPv4 or
4439 IPv6. (Added in 7.29.0)
4440 local_port The local port number of the most recently done
4442 connection. (Added in 7.29.0)
4443 method The http method used in the most recent HTTP re‐
4445 quest. (Added in 7.72.0)
4446 num_connects Number of new connects made in the recent trans‐
4448 fer. (Added in 7.12.3)
4449 num_headers The number of response headers in the most recent
4451 request (restarted at each
4452 redirect). Note that the status line IS NOT a
4453 header. (Added in 7.73.0)
4454 num_redirects Number of redirects that were followed in the re‐
4456 quest. (Added in 7.12.3)
4457 onerror The rest of the output is only shown if the
4459 transfer returned a non-zero error (Added in
4460 7.75.0)
4461 proxy_ssl_verify_result
4463 The result of the HTTPS proxy's SSL peer certifi‐
4464 cate verification that was requested. 0 means the
4465 verification was successful. (Added in 7.52.0)
4466 redirect_url When an HTTP request was made without -L, --loca‐
4468 tion to follow redirects (or when --max-redirs is
4469 met), this variable will show the actual URL a
4470 redirect would have gone to. (Added in 7.18.2)
4471 referer The Referer: header, if there was any. (Added in
4473 7.76.0)
4474 remote_ip The remote IP address of the most recently done
4476 connection - can be either IPv4 or IPv6. (Added
4477 in 7.29.0)
4478 remote_port The remote port number of the most recently done
4480 connection. (Added in 7.29.0)
4481 response_code The numerical response code that was found in the
4483 last transfer (formerly known as "http_code").
4484 (Added in 7.18.2)
4485 scheme The URL scheme (sometimes called protocol) that
4487 was effectively used. (Added in 7.52.0)
4488 size_download The total amount of bytes that were downloaded.
4490 This is the size of the body/data that was trans‐
4491 fered, excluding headers.
4492 size_header The total amount of bytes of the downloaded head‐
4494 ers.
4495 size_request The total amount of bytes that were sent in the
4497 HTTP request.
4498 size_upload The total amount of bytes that were uploaded.
4500 This is the size of the body/data that was trans‐
4501 fered, excluding headers.
4502 speed_download The average download speed that curl measured for
4504 the complete download. Bytes per second.
4505 speed_upload The average upload speed that curl measured for
4507 the complete upload. Bytes per second.
4508 ssl_verify_result
4510 The result of the SSL peer certificate verifica‐
4511 tion that was requested. 0 means the verification
4512 was successful. (Added in 7.19.0)
4513 stderr From this point on, the -w, --write-out output
4515 will be written to standard error. (Added in
4516 7.63.0)
4517 stdout From this point on, the -w, --write-out output
4519 will be written to standard output. This is the
4520 default, but can be used to switch back after
4521 switching to stderr. (Added in 7.63.0)
4522 time_appconnect
4524 The time, in seconds, it took from the start un‐
4525 til the SSL/SSH/etc connect/handshake to the re‐
4526 mote host was completed. (Added in 7.19.0)
4527 time_connect The time, in seconds, it took from the start un‐
4529 til the TCP connect to the remote host (or proxy)
4530 was completed.
4531 time_namelookup
4533 The time, in seconds, it took from the start un‐
4534 til the name resolving was completed.
4535 time_pretransfer
4537 The time, in seconds, it took from the start un‐
4538 til the file transfer was just about to begin.
4539 This includes all pre-transfer commands and nego‐
4540 tiations that are specific to the particular pro‐
4541 tocol(s) involved.
4542 time_redirect The time, in seconds, it took for all redirection
4544 steps including name lookup, connect, pretransfer
4545 and transfer before the final transaction was
4546 started. time_redirect shows the complete execu‐
4547 tion time for multiple redirections. (Added in
4548 7.12.3)
4549 time_starttransfer
4551 The time, in seconds, it took from the start un‐
4552 til the first byte was just about to be trans‐
4553 ferred. This includes time_pretransfer and also
4554 the time the server needed to calculate the re‐
4555 sult.
4556 time_total The total time, in seconds, that the full opera‐
4558 tion lasted.
4559 url The URL that was fetched. (Added in 7.75.0)
4561 urlnum The URL index number of this transfer, 0-indexed.
4563 De-globbed URLs share the same index number as
4564 the origin globbed URL. (Added in 7.75.0)
4565 url_effective The URL that was fetched last. This is most mean‐
4567 ingful if you've told curl to follow location:
4568 headers.
4569 If this option is used several times, the last one will be used.
4571 Example:
4573 curl -w '%{http_code}\n' https://example.com
4574 --xattr
4576 When saving output to a file, this option tells curl to store
4577 certain file metadata in extended file attributes. Currently,
4578 the URL is stored in the xdg.origin.url attribute and, for HTTP,
4579 the content type is stored in the mime_type attribute. If the
4580 file system does not support extended attributes, a warning is
4581 issued.
4582 Example:
4584 curl --xattr -o storage https://example.com
4585
4587 ~/.curlrc
4588 Default config file, see -K, --config for details.
4589
4591 The environment variables can be specified in lower case or upper case.
4592 The lower case version has precedence. http_proxy is an exception as it
4593 is only available in lower case.
4594 Using an environment variable to set the proxy has the same effect as
4596 using the -x, --proxy option.
4597 http_proxy [protocol://]<host>[:port]
4600 Sets the proxy server to use for HTTP.
4601 HTTPS_PROXY [protocol://]<host>[:port]
4603 Sets the proxy server to use for HTTPS.
4604 [url-protocol]_PROXY [protocol://]<host>[:port]
4606 Sets the proxy server to use for [url-protocol], where the pro‐
4607 tocol is a protocol that curl supports and as specified in a
4608 URL. FTP, FTPS, POP3, IMAP, SMTP, LDAP, etc.
4609 ALL_PROXY [protocol://]<host>[:port]
4611 Sets the proxy server to use if no protocol-specific proxy is
4612 set.
4613 NO_PROXY <comma-separated list of hosts/domains>
4615 list of host names that shouldn't go through any proxy. If set
4616 to an asterisk '*' only, it matches all hosts. Each name in this
4617 list is matched as either a domain name which contains the host‐
4618 name, or the hostname itself.
4619 This environment variable disables use of the proxy even when
4621 specified with the -x, --proxy option. That is NO_PROXY=di‐
4622 rect.example.com curl -x http://proxy.example.com http://di‐
4623 rect.example.com accesses the target URL directly, and
4624 NO_PROXY=direct.example.com curl -x http://proxy.example.com
4625 http://somewhere.example.com accesses the target URL through the
4626 proxy.
4627 The list of host names can also be include numerical IP ad‐
4629 dresses, and IPv6 versions should then be given without enclos‐
4630 ing brackets.
4631 IPv6 numerical addresses are compared as strings, so they will
4633 only match if the representations are the same: "::1" is the
4634 same as "::0:1" but they don't match.
4635 CURL_SSL_BACKEND <TLS backend>
4637 If curl was built with support for "MultiSSL", meaning that it
4638 has built-in support for more than one TLS backend, this envi‐
4639 ronment variable can be set to the case insensitive name of the
4640 particular backend to use when curl is invoked. Setting a name
4641 that isn't a built-in alternative will make curl stay with the
4642 default.
4643 SSL backend names (case-insensitive): bearssl, gnutls, gskit,
4645 mbedtls, mesalink, nss, openssl, rustls, schannel, secure-trans‐
4646 port, wolfssl
4647 QLOGDIR <directory name>
4649 If curl was built with HTTP/3 support, setting this environment
4650 variable to a local directory will make curl produce qlogs in
4651 that directory, using file names named after the destination
4652 connection id (in hex). Do note that these files can become
4653 rather large. Works with both QUIC backends.
4654 SSLKEYLOGFILE <file name>
4656 If you set this environment variable to a file name, curl will
4657 store TLS secrets from its connections in that file when invoked
4658 to enable you to analyze the TLS traffic in real time using net‐
4659 work analyzing tools such as Wireshark. This works with the fol‐
4660 lowing TLS backends: OpenSSL, libressl, BoringSSL, GnuTLS, NSS
4661 and wolfSSL.
4662
4664 Since curl version 7.21.7, the proxy string may be specified with a
4665 protocol:// prefix to specify alternative proxy protocols.
4666 If no protocol is specified in the proxy string or if the string
4668 doesn't match a supported one, the proxy will be treated as an HTTP
4669 proxy.
4670 The supported proxy protocol prefixes are as follows:
4672 http://
4674 Makes it use it as an HTTP proxy. The default if no scheme pre‐
4675 fix is used.
4676 https://
4678 Makes it treated as an HTTPS proxy.
4679 socks4://
4681 Makes it the equivalent of --socks4
4682 socks4a://
4684 Makes it the equivalent of --socks4a
4685 socks5://
4687 Makes it the equivalent of --socks5
4688 socks5h://
4690 Makes it the equivalent of --socks5-hostname
4691
4693 There are a bunch of different error codes and their corresponding er‐
4694 ror messages that may appear under error conditions. At the time of
4695 this writing, the exit codes are:
4696 1 Unsupported protocol. This build of curl has no support for this
4698 protocol.
4699 2 Failed to initialize.
4701 3 URL malformed. The syntax was not correct.
4703 4 A feature or option that was needed to perform the desired re‐
4705 quest was not enabled or was explicitly disabled at build-time.
4706 To make curl able to do this, you probably need another build of
4707 libcurl!
4708 5 Couldn't resolve proxy. The given proxy host could not be re‐
4710 solved.
4711 6 Couldn't resolve host. The given remote host could not be re‐
4713 solved.
4714 7 Failed to connect to host.
4716 8 Weird server reply. The server sent data curl couldn't parse.
4718 9 FTP access denied. The server denied login or denied access to
4720 the particular resource or directory you wanted to reach. Most
4721 often you tried to change to a directory that doesn't exist on
4722 the server.
4723 10 FTP accept failed. While waiting for the server to connect back
4725 when an active FTP session is used, an error code was sent over
4726 the control connection or similar.
4727 11 FTP weird PASS reply. Curl couldn't parse the reply sent to the
4729 PASS request.
4730 12 During an active FTP session while waiting for the server to
4732 connect back to curl, the timeout expired.
4733 13 FTP weird PASV reply, Curl couldn't parse the reply sent to the
4735 PASV request.
4736 14 FTP weird 227 format. Curl couldn't parse the 227-line the
4738 server sent.
4739 15 FTP can't get host. Couldn't resolve the host IP we got in the
4741 227-line.
4742 16 HTTP/2 error. A problem was detected in the HTTP2 framing layer.
4744 This is somewhat generic and can be one out of several problems,
4745 see the error message for details.
4746 17 FTP couldn't set binary. Couldn't change transfer method to bi‐
4748 nary.
4749 18 Partial file. Only a part of the file was transferred.
4751 19 FTP couldn't download/access the given file, the RETR (or simi‐
4753 lar) command failed.
4754 21 FTP quote error. A quote command returned error from the server.
4756 22 HTTP page not retrieved. The requested url was not found or re‐
4758 turned another error with the HTTP error code being 400 or
4759 above. This return code only appears if -f, --fail is used.
4760 23 Write error. Curl couldn't write data to a local filesystem or
4762 similar.
4763 25 FTP couldn't STOR file. The server denied the STOR operation,
4765 used for FTP uploading.
4766 26 Read error. Various reading problems.
4768 27 Out of memory. A memory allocation request failed.
4770 28 Operation timeout. The specified time-out period was reached ac‐
4772 cording to the conditions.
4773 30 FTP PORT failed. The PORT command failed. Not all FTP servers
4775 support the PORT command, try doing a transfer using PASV in‐
4776 stead!
4777 31 FTP couldn't use REST. The REST command failed. This command is
4779 used for resumed FTP transfers.
4780 33 HTTP range error. The range "command" didn't work.
4782 34 HTTP post error. Internal post-request generation error.
4784 35 SSL connect error. The SSL handshaking failed.
4786 36 Bad download resume. Couldn't continue an earlier aborted down‐
4788 load.
4789 37 FILE couldn't read file. Failed to open the file. Permissions?
4791 38 LDAP cannot bind. LDAP bind operation failed.
4793 39 LDAP search failed.
4795 41 Function not found. A required LDAP function was not found.
4797 42 Aborted by callback. An application told curl to abort the oper‐
4799 ation.
4800 43 Internal error. A function was called with a bad parameter.
4802 45 Interface error. A specified outgoing interface could not be
4804 used.
4805 47 Too many redirects. When following redirects, curl hit the maxi‐
4807 mum amount.
4808 48 Unknown option specified to libcurl. This indicates that you
4810 passed a weird option to curl that was passed on to libcurl and
4811 rejected. Read up in the manual!
4812 49 Malformed telnet option.
4814 51 The peer's SSL certificate or SSH MD5 fingerprint was not OK.
4816 52 The server didn't reply anything, which here is considered an
4818 error.
4819 53 SSL crypto engine not found.
4821 54 Cannot set SSL crypto engine as default.
4823 55 Failed sending network data.
4825 56 Failure in receiving network data.
4827 58 Problem with the local certificate.
4829 59 Couldn't use specified SSL cipher.
4831 60 Peer certificate cannot be authenticated with known CA certifi‐
4833 cates.
4834 61 Unrecognized transfer encoding.
4836 62 Invalid LDAP URL.
4838 63 Maximum file size exceeded.
4840 64 Requested FTP SSL level failed.
4842 65 Sending the data requires a rewind that failed.
4844 66 Failed to initialise SSL Engine.
4846 67 The user name, password, or similar was not accepted and curl
4848 failed to log in.
4849 68 File not found on TFTP server.
4851 69 Permission problem on TFTP server.
4853 70 Out of disk space on TFTP server.
4855 71 Illegal TFTP operation.
4857 72 Unknown TFTP transfer ID.
4859 73 File already exists (TFTP).
4861 74 No such user (TFTP).
4863 75 Character conversion failed.
4865 76 Character conversion functions required.
4867 77 Problem reading the SSL CA cert (path? access rights?).
4869 78 The resource referenced in the URL does not exist.
4871 79 An unspecified error occurred during the SSH session.
4873 80 Failed to shut down the SSL connection.
4875 82 Could not load CRL file, missing or wrong format (added in
4877 7.19.0).
4878 83 Issuer check failed (added in 7.19.0).
4880 84 The FTP PRET command failed.
4882 85 Mismatch of RTSP CSeq numbers.
4884 86 Mismatch of RTSP Session Identifiers.
4886 87 Unable to parse FTP file list.
4888 88 FTP chunk callback reported error.
4890 89 No connection available, the session will be queued.
4892 90 SSL public key does not matched pinned public key.
4894 91 Invalid SSL certificate status.
4896 92 Stream error in HTTP/2 framing layer.
4898 93 An API function was called from inside a callback.
4900 94 An authentication function returned an error.
4902 95 A problem was detected in the HTTP/3 layer. This is somewhat
4904 generic and can be one out of several problems, see the error
4905 message for details.
4906 96 QUIC connection error. This error may be caused by an SSL li‐
4908 brary error. QUIC is the protocol used for HTTP/3 transfers.
4909 XX More error codes will appear here in future releases. The exist‐
4911 ing ones are meant to never change.
4912
4914 Daniel Stenberg is the main author, but the whole list of contributors
4915 is found in the separate THANKS file.
4916
4918 https://curl.se
4919
4921 ftp(1), wget(1)
4922Curl 7.79.1 November 16, 2016 curl(1)