1curl(1) curl Manual curl(1)
2
3
4
6 curl - transfer a URL
7
9 curl [options / URLs]
10
12 curl is a tool for transferring 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
18 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
23 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 find a detailed description
28 in RFC 3986.
29
30 You can specify multiple URLs or parts of URLs by writing part sets
31 within braces and quoting the URL as in:
32
33 "http://site.{one,two,three}.com"
34
35 or you can get sequences of alphanumeric series by using [] as in:
36
37 "ftp://ftp.example.com/file[1-100].txt"
38
39 "ftp://ftp.example.com/file[001-100].txt" (with leading zeros)
40
41 "ftp://ftp.example.com/file[a-z].txt"
42
43 Nested sequences are not supported, but you can use several ones next
44 to each other:
45
46 "http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html"
47
48 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
53 You can specify a step counter for the ranges to get every Nth number
54 or letter:
55
56 "http://example.com/file[1-100:10].txt"
57
58 "http://example.com/file[a-z:2].txt"
59
60 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
65 Provide the IPv6 zone index in the URL with an escaped percentage sign
66 and the interface name. Like in
67
68 "http://[fe80::3%25eth0]/"
69
70 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
76 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 fairly liberal with what it accepts.
79
80 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 --output or --remote-name options. If curl is given multiple URLs to
90 transfer on the command line, it similarly needs multiple options for
91 where to save them.
92
93 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
101 DICT Lets you lookup words using online dictionaries.
102
103 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
107 FTP(S) curl supports the File Transfer Protocol with a lot of tweaks
108 and levers. With or without using TLS.
109
110 GOPHER(S)
111 Retrieve files.
112
113 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
118 IMAP(S)
119 Using the mail reading protocol, curl can "download" emails for
120 you. With or without using TLS.
121
122 LDAP(S)
123 curl can do directory lookups for you, with or without TLS.
124
125 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
129 POP3(S)
130 Downloading from a pop3 server means getting a mail. With or
131 without using TLS.
132
133 RTMP(S)
134 The Realtime Messaging Protocol is primarily used to server
135 streaming media and curl can download it.
136
137 RTSP curl supports RTSP 1.0 downloads.
138
139 SCP curl supports SSH version 2 scp transfers.
140
141 SFTP curl supports SFTP (draft 5) done over SSH version 2.
142
143 SMB(S) curl supports SMB version 1 for upload and download.
144
145 SMTP(S)
146 Uploading contents to an SMTP server means sending an email.
147 With or without TLS.
148
149 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
153 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
162 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
167 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 (>),
169 --output or similar.
170
171 This does not apply to FTP upload as that operation does not spit out
172 any response data to the terminal.
173
174 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 --silent option.
177
179 Options start with one or two dashes. Many of the options require an
180 additional value next to them.
181
182 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, --data for ex‐
185 ample, requires a space between it and its value.
186
187 Short version options that do not need any additional values can be
188 used immediately next to each other, like for example you can specify
189 all the options -O, -L and -v at once as -OLv.
190
191 In general, all boolean options are enabled with --option and yet again
192 disabled with --no-option. That is, you use the same option name but
193 prefix it with "no-". However, in this list we mostly only list and
194 show the --option version of them.
195
196 --abstract-unix-socket <path>
197 (HTTP) Connect through an abstract Unix domain socket, instead
198 of using the network. Note: netstat shows the path of an ab‐
199 stract socket prefixed with '@', however the <path> argument
200 should not have this leading character.
201
202 Example:
203 curl --abstract-unix-socket socketpath https://example.com
204
205 See also --unix-socket. Added in 7.53.0.
206
207 --alt-svc <file name>
208 (HTTPS) This option enables the alt-svc parser in curl. If the
209 file name points to an existing alt-svc cache file, that will be
210 used. After a completed transfer, the cache will be saved to the
211 file name again if it has been modified.
212
213 Specify a "" file name (zero length) to avoid loading/saving and
214 make curl just handle the cache in memory.
215
216 If this option is used several times, curl will load contents
217 from all the files but the last one will be used for saving.
218
219 Example:
220 curl --alt-svc svc.txt https://example.com
221
222 See also --resolve and --connect-to. Added in 7.64.1.
223
224 --anyauth
225 (HTTP) Tells curl to figure out authentication method by itself,
226 and use the most secure one the remote site claims to support.
227 This is done by first doing a request and checking the response-
228 headers, thus possibly inducing an extra network round-trip.
229 This is used instead of setting a specific authentication
230 method, which you can do with --basic, --digest, --ntlm, and
231 --negotiate.
232
233 Using --anyauth is not recommended if you do uploads from stdin,
234 since it may require data to be sent twice and then the client
235 must be able to rewind. If the need should arise when uploading
236 from stdin, the upload operation will fail.
237
238 Used together with -u, --user.
239
240 Example:
241 curl --anyauth --user me:pwd https://example.com
242
243 See also --proxy-anyauth, --basic and --digest.
244
245 -a, --append
246 (FTP SFTP) When used in an upload, this makes curl append to the
247 target file instead of overwriting it. If the remote file does
248 not exist, it will be created. Note that this flag is ignored by
249 some SFTP servers (including OpenSSH).
250
251 Example:
252 curl --upload-file local --append ftp://example.com/
253
254 See also -r, --range and -C, --continue-at.
255
256 --aws-sigv4 <provider1[:provider2[:region[:service]]]>
257 Use AWS V4 signature authentication in the transfer.
258
259 The provider argument is a string that is used by the algorithm
260 when creating outgoing authentication headers.
261
262 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
266 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
270 Example:
271 curl --aws-sigv4 "aws:amz:east-2:es" --user "key:secret" https://example.com
272
273 See also --basic and -u, --user. Added in 7.75.0.
274
275 --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
282 Used together with -u, --user.
283
284 Example:
285 curl -u name:password --basic https://example.com
286
287 See also --proxy-basic.
288
289 --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
296 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
300 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
305 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
309 (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
316 (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
322 If this option is used several times, the last one will be used.
323
324 Example:
325 curl --cacert CA-file.txt https://example.com
326
327 See also --capath and -k, --insecure.
328
329 --capath <dir>
330 (TLS) Tells curl to use the specified certificate directory to
331 verify the peer. Multiple paths can be provided by separating
332 them with ":" (e.g. "path1:path2:path3"). The certificates must
333 be in PEM format, and if curl is built against OpenSSL, the di‐
334 rectory must have been processed using the c_rehash utility sup‐
335 plied with OpenSSL. Using --capath can allow OpenSSL-powered
336 curl to make SSL-connections much more efficiently than using
337 --cacert if the --cacert file contains many CA certificates.
338
339 If this option is set, the default capath value will be ignored,
340 and if it is used several times, the last one will be used.
341
342 Example:
343 curl --capath /local/directory https://example.com
344
345 See also --cacert and -k, --insecure.
346
347 --cert-status
348 (TLS) Tells curl to verify the status of the server certificate
349 by using the Certificate Status Request (aka. OCSP stapling) TLS
350 extension.
351
352 If this option is enabled and the server sends an invalid (e.g.
353 expired) response, if the response suggests that the server cer‐
354 tificate has been revoked, or no response at all is received,
355 the verification fails.
356
357 This is currently only implemented in the OpenSSL, GnuTLS and
358 NSS backends.
359
360 Example:
361 curl --cert-status https://example.com
362
363 See also --pinnedpubkey. Added in 7.41.0.
364
365 --cert-type <type>
366 (TLS) Tells curl what type the provided client certificate is
367 using. PEM, DER, ENG and P12 are recognized types.
368
369 The default type depends on the TLS backend and is usually PEM,
370 however for Secure Transport and Schannel it is P12. If --cert
371 is a pkcs11: URI then ENG is the default type.
372
373 If this option is used several times, the last one will be used.
374
375 Example:
376 curl --cert-type PEM --cert file https://example.com
377
378 See also -E, --cert, --key and --key-type.
379
380 -E, --cert <certificate[:password]>
381 (TLS) Tells curl to use the specified client certificate file
382 when getting a file with HTTPS, FTPS or another SSL-based proto‐
383 col. The certificate must be in PKCS#12 format if using Secure
384 Transport, or PEM format if using any other engine. If the op‐
385 tional password is not specified, it will be queried for on the
386 terminal. Note that this option assumes a certificate file that
387 is the private key and the client certificate concatenated. See
388 --cert and --key to specify them independently.
389
390 In the <certificate> portion of the argument, you must escape
391 the character ":" as "\:" so that it is not recognized as the
392 password delimiter. Similarly, you must escape the character "\"
393 as "\\" so that it is not recognized as an escape character.
394
395 If curl is built against the NSS SSL library then this option
396 can tell curl the nickname of the certificate to use within the
397 NSS database defined by the environment variable SSL_DIR (or by
398 default /etc/pki/nssdb). If the NSS PEM PKCS#11 module (lib‐
399 nsspem.so) is available then PEM files may be loaded.
400
401 If you provide a path relative to the current directory, you
402 must prefix the path with "./" in order to avoid confusion with
403 an NSS database nickname.
404
405 If curl is built against OpenSSL library, and the engine pkcs11
406 is available, then a PKCS#11 URI (RFC 7512) can be used to spec‐
407 ify a certificate located in a PKCS#11 device. A string begin‐
408 ning with "pkcs11:" will be interpreted as a PKCS#11 URI. If a
409 PKCS#11 URI is provided, then the --engine option will be set as
410 "pkcs11" if none was provided and the --cert-type option will be
411 set as "ENG" if none was provided.
412
413 (iOS and macOS only) If curl is built against Secure Transport,
414 then the certificate string can either be the name of a certifi‐
415 cate/private key in the system or user keychain, or the path to
416 a PKCS#12-encoded certificate and private key. If you want to
417 use a file from the current directory, please precede it with
418 "./" prefix, in order to avoid confusion with a nickname.
419
420 (Schannel only) Client certificates must be specified by a path
421 expression to a certificate store. (Loading PFX is not sup‐
422 ported; you can import it to a store first). You can use "<store
423 location>\<store name>\<thumbprint>" to refer to a certificate
424 in the system certificates store, for example, "Curren‐
425 tUser\MY\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a". Thumbprint
426 is usually a SHA-1 hex string which you can see in certificate
427 details. Following store locations are supported: CurrentUser,
428 LocalMachine, CurrentService, Services, CurrentUserGroupPolicy,
429 LocalMachineGroupPolicy, LocalMachineEnterprise.
430
431 If this option is used several times, the last one will be used.
432
433 Example:
434 curl --cert certfile --key keyfile https://example.com
435
436 See also --cert-type, --key and --key-type.
437
438 --ciphers <list of ciphers>
439 (TLS) Specifies which ciphers to use in the connection. The list
440 of ciphers must specify valid ciphers. Read up on SSL cipher
441 list details on this URL:
442
443 https://curl.se/docs/ssl-ciphers.html
444
445 If this option is used several times, the last one will be used.
446
447 Example:
448 curl --ciphers ECDHE-ECDSA-AES256-CCM8 https://example.com
449
450 See also --tlsv1.3.
451
452 --compressed-ssh
453 (SCP SFTP) Enables built-in SSH compression. This is a request,
454 not an order; the server may or may not do it.
455
456 Example:
457 curl --compressed-ssh sftp://example.com/
458
459 See also --compressed. Added in 7.56.0.
460
461 --compressed
462 (HTTP) Request a compressed response using one of the algorithms
463 curl supports, and automatically decompress the content. Headers
464 are not modified.
465
466 If this option is used and the server sends an unsupported en‐
467 coding, curl will report an error. This is a request, not an or‐
468 der; the server may or may not deliver data compressed.
469
470 Example:
471 curl --compressed https://example.com
472
473 See also --compressed-ssh.
474
475 -K, --config <file>
476 Specify a text file to read curl arguments from. The command
477 line arguments found in the text file will be used as if they
478 were provided on the command line.
479
480 Options and their parameters must be specified on the same line
481 in the file, separated by whitespace, colon, or the equals sign.
482 Long option names can optionally be given in the config file
483 without the initial double dashes and if so, the colon or equals
484 characters can be used as separators. If the option is specified
485 with one or two dashes, there can be no colon or equals charac‐
486 ter between the option and its parameter.
487
488 If the parameter contains whitespace (or starts with : or =),
489 the parameter must be enclosed within quotes. Within double
490 quotes, the following escape sequences are available: \\, \",
491 \t, \n, \r and \v. A backslash preceding any other letter is ig‐
492 nored.
493
494 If the first column of a config line is a '#' character, the
495 rest of the line will be treated as a comment.
496
497 Only write one option per physical line in the config file.
498
499 Specify the filename to --config as '-' to make curl read the
500 file from stdin.
501
502 Note that to be able to specify a URL in the config file, you
503 need to specify it using the --url option, and not by simply
504 writing the URL on its own line. So, it could look similar to
505 this:
506
507 url = "https://curl.se/docs/"
508
509 # --- Example file ---
510 # this is a comment
511 url = "example.com"
512 output = "curlhere.html"
513 user-agent = "superagent/1.0"
514
515 # and fetch another URL too
516 url = "example.com/docs/manpage.html"
517 -O
518 referer = "http://nowhereatall.example.com/"
519 # --- End of example file ---
520
521 When curl is invoked, it (unless --disable is used) checks for a
522 default config file and uses it if found, even when --config is
523 used. The default config file is checked for in the following
524 places in this order:
525
526 1) "$CURL_HOME/.curlrc"
527
528 2) "$XDG_CONFIG_HOME/.curlrc" (Added in 7.73.0)
529
530 3) "$HOME/.curlrc"
531
532 4) Windows: "%USERPROFILE%\.curlrc"
533
534 5) Windows: "%APPDATA%\.curlrc"
535
536 6) Windows: "%USERPROFILE%\Application Data\.curlrc"
537
538 7) Non-Windows: use getpwuid to find the home directory
539
540 8) On Windows, if it finds no .curlrc file in the sequence de‐
541 scribed above, it checks for one in the same dir the curl exe‐
542 cutable is placed.
543
544 On Windows two filenames are checked per location: .curlrc and
545 _curlrc, preferring the former. Older versions on Windows
546 checked for _curlrc only.
547
548 This option can be used multiple times to load multiple config
549 files.
550
551 Example:
552 curl --config file.txt https://example.com
553
554 See also -q, --disable.
555
556 --connect-timeout <fractional seconds>
557 Maximum time in seconds that you allow curl's connection to
558 take. This only limits the connection phase, so if curl con‐
559 nects within the given period it will continue - if not it will
560 exit. Since version 7.32.0, this option accepts decimal values.
561
562 If this option is used several times, the last one will be used.
563
564 Examples:
565 curl --connect-timeout 20 https://example.com
566 curl --connect-timeout 3.14 https://example.com
567
568 See also -m, --max-time.
569
570 --connect-to <HOST1:PORT1:HOST2:PORT2>
571
572 For a request to the given HOST1:PORT1 pair, connect to
573 HOST2:PORT2 instead. This option is suitable to direct requests
574 at a specific server, e.g. at a specific cluster node in a clus‐
575 ter of servers. This option is only used to establish the net‐
576 work connection. It does NOT affect the hostname/port that is
577 used for TLS/SSL (e.g. SNI, certificate verification) or for the
578 application protocols. "HOST1" and "PORT1" may be the empty
579 string, meaning "any host/port". "HOST2" and "PORT2" may also be
580 the empty string, meaning "use the request's original
581 host/port".
582
583 A "host" specified to this option is compared as a string, so it
584 needs to match the name used in request URL. It can be either
585 numerical such as "127.0.0.1" or the full host name such as "ex‐
586 ample.org".
587
588 This option can be used many times to add many connect rules.
589
590 Example:
591 curl --connect-to example.com:443:example.net:8443 https://example.com
592
593 See also --resolve and -H, --header. Added in 7.49.0.
594
595 -C, --continue-at <offset>
596 Continue/Resume a previous file transfer at the given offset.
597 The given offset is the exact number of bytes that will be
598 skipped, counting from the beginning of the source file before
599 it is transferred to the destination. If used with uploads, the
600 FTP server command SIZE will not be used by curl.
601
602 Use "-C -" to tell curl to automatically find out where/how to
603 resume the transfer. It then uses the given output/input files
604 to figure that out.
605
606 If this option is used several times, the last one will be used.
607
608 Examples:
609 curl -C - https://example.com
610 curl -C 400 https://example.com
611
612 See also -r, --range.
613
614 -c, --cookie-jar <filename>
615 (HTTP) Specify to which file you want curl to write all cookies
616 after a completed operation. Curl writes all cookies from its
617 in-memory cookie storage to the given file at the end of opera‐
618 tions. If no cookies are known, no data will be written. The
619 file will be written using the Netscape cookie file format. If
620 you set the file name to a single dash, "-", the cookies will be
621 written to stdout.
622
623 This command line option will activate the cookie engine that
624 makes curl record and use cookies. Another way to activate it is
625 to use the --cookie option.
626
627 If the cookie jar cannot be created or written to, the whole
628 curl operation will not fail or even report an error clearly.
629 Using --verbose will get a warning displayed, but that is the
630 only visible feedback you get about this possibly lethal situa‐
631 tion.
632
633 If this option is used several times, the last specified file
634 name will be used.
635
636 Examples:
637 curl -c store-here.txt https://example.com
638 curl -c store-here.txt -b read-these https://example.com
639
640 See also -b, --cookie.
641
642 -b, --cookie <data|filename>
643 (HTTP) Pass the data to the HTTP server in the Cookie header. It
644 is supposedly the data previously received from the server in a
645 "Set-Cookie:" line. The data should be in the format
646 "NAME1=VALUE1; NAME2=VALUE2". This makes curl use the cookie
647 header with this content explicitly in all outgoing request(s).
648 If multiple requests are done due to authentication, followed
649 redirects or similar, they will all get this cookie passed on.
650
651 If no '=' symbol is used in the argument, it is instead treated
652 as a filename to read previously stored cookie from. This option
653 also activates the cookie engine which will make curl record in‐
654 coming cookies, which may be handy if you are using this in com‐
655 bination with the --location option or do multiple URL transfers
656 on the same invoke. If the file name is exactly a minus ("-"),
657 curl will instead read the contents from stdin.
658
659 The file format of the file to read cookies from should be plain
660 HTTP headers (Set-Cookie style) or the Netscape/Mozilla cookie
661 file format.
662
663 The file specified with --cookie is only used as input. No cook‐
664 ies will be written to the file. To store cookies, use the
665 --cookie-jar option.
666
667 If you use the Set-Cookie file format and do not specify a do‐
668 main then the cookie is not sent since the domain will never
669 match. To address this, set a domain in Set-Cookie line (doing
670 that will include sub-domains) or preferably: use the Netscape
671 format.
672
673 This option can be used multiple times.
674
675 Users often want to both read cookies from a file and write up‐
676 dated cookies back to a file, so using both --cookie and
677 --cookie-jar in the same command line is common.
678
679 Examples:
680 curl -b cookiefile https://example.com
681 curl -b cookiefile -c cookiefile https://example.com
682
683 See also -c, --cookie-jar and -j, --junk-session-cookies.
684
685 --create-dirs
686 When used in conjunction with the --output option, curl will
687 create the necessary local directory hierarchy as needed. This
688 option creates the directories mentioned with the --output op‐
689 tion, nothing else. If the --output file name uses no directory,
690 or if the directories it mentions already exist, no directories
691 will be created.
692
693 Created dirs are made with mode 0750 on unix style file systems.
694
695 To create remote directories when using FTP or SFTP, try --ftp-
696 create-dirs.
697
698 Example:
699 curl --create-dirs --output local/dir/file https://example.com
700
701 See also --ftp-create-dirs and --output-dir.
702
703 --create-file-mode <mode>
704 (SFTP SCP FILE) When curl is used to create files remotely using
705 one of the supported protocols, this option allows the user to
706 set which 'mode' to set on the file at creation time, instead of
707 the default 0644.
708
709 This option takes an octal number as argument.
710
711 If this option is used several times, the last one will be used.
712
713 Example:
714 curl --create-file-mode 0777 -T localfile sftp://example.com/new
715
716 See also --ftp-create-dirs. Added in 7.75.0.
717
718 --crlf (FTP SMTP) Convert LF to CRLF in upload. Useful for MVS
719 (OS/390).
720
721 (SMTP added in 7.40.0)
722
723 Example:
724 curl --crlf -T file ftp://example.com/
725
726 See also -B, --use-ascii.
727
728 --crlfile <file>
729 (TLS) Provide a file using PEM format with a Certificate Revoca‐
730 tion List that may specify peer certificates that are to be con‐
731 sidered revoked.
732
733 If this option is used several times, the last one will be used.
734
735 Example:
736 curl --crlfile rejects.txt https://example.com
737
738 See also --cacert and --capath.
739
740 --curves <algorithm list>
741 (TLS) Tells curl to request specific curves to use during SSL
742 session establishment according to RFC 8422, 5.1. Multiple al‐
743 gorithms can be provided by separating them with ":" (e.g.
744 "X25519:P-521"). The parameter is available identically in the
745 "openssl s_client/s_server" utilities.
746
747 --curves allows a OpenSSL powered curl to make SSL-connections
748 with exactly the (EC) curve requested by the client, avoiding
749 nontransparent client/server negotiations.
750
751 If this option is set, the default curves list built into
752 openssl will be ignored.
753
754 Example:
755 curl --curves X25519 https://example.com
756
757 See also --ciphers. Added in 7.73.0.
758
759 --data-ascii <data>
760 (HTTP) This is just an alias for -d, --data.
761
762 Example:
763 curl --data-ascii @file https://example.com
764
765 See also --data-binary, --data-raw and --data-urlencode.
766
767 --data-binary <data>
768 (HTTP) This posts data exactly as specified with no extra pro‐
769 cessing whatsoever.
770
771 If you start the data with the letter @, the rest should be a
772 filename. Data is posted in a similar manner as --data does, ex‐
773 cept that newlines and carriage returns are preserved and con‐
774 versions are never done.
775
776 Like --data the default content-type sent to the server is ap‐
777 plication/x-www-form-urlencoded. If you want the data to be
778 treated as arbitrary binary data by the server then set the con‐
779 tent-type to octet-stream: -H "Content-Type: application/octet-
780 stream".
781
782 If this option is used several times, the ones following the
783 first will append data as described in -d, --data.
784
785 Example:
786 curl --data-binary @filename https://example.com
787
788 See also --data-ascii.
789
790 --data-raw <data>
791 (HTTP) This posts data similarly to --data but without the spe‐
792 cial interpretation of the @ character.
793
794 Examples:
795 curl --data-raw "hello" https://example.com
796 curl --data-raw "@at@at@" https://example.com
797
798 See also -d, --data. Added in 7.43.0.
799
800 --data-urlencode <data>
801 (HTTP) This posts data, similar to the other --data options with
802 the exception that this performs URL-encoding.
803
804 To be CGI-compliant, the <data> part should begin with a name
805 followed by a separator and a content specification. The <data>
806 part can be passed to curl using one of the following syntaxes:
807
808 content
809 This will make curl URL-encode the content and pass that
810 on. Just be careful so that the content does not contain
811 any = or @ symbols, as that will then make the syntax
812 match one of the other cases below!
813
814 =content
815 This will make curl URL-encode the content and pass that
816 on. The preceding = symbol is not included in the data.
817
818 name=content
819 This will make curl URL-encode the content part and pass
820 that on. Note that the name part is expected to be URL-
821 encoded already.
822
823 @filename
824 This will make curl load data from the given file (in‐
825 cluding any newlines), URL-encode that data and pass it
826 on in the POST.
827
828 name@filename
829 This will make curl load data from the given file (in‐
830 cluding any newlines), URL-encode that data and pass it
831 on in the POST. The name part gets an equal sign ap‐
832 pended, resulting in name=urlencoded-file-content. Note
833 that the name is expected to be URL-encoded already.
834
835 Examples:
836 curl --data-urlencode name=val https://example.com
837 curl --data-urlencode =encodethis https://example.com
838 curl --data-urlencode name@file https://example.com
839 curl --data-urlencode @fileonly https://example.com
840
841 See also -d, --data and --data-raw.
842
843 -d, --data <data>
844 (HTTP MQTT) Sends the specified data in a POST request to the
845 HTTP server, in the same way that a browser does when a user has
846 filled in an HTML form and presses the submit button. This will
847 cause curl to pass the data to the server using the content-type
848 application/x-www-form-urlencoded. Compare to -F, --form.
849
850 --data-raw is almost the same but does not have a special inter‐
851 pretation of the @ character. To post data purely binary, you
852 should instead use the --data-binary option. To URL-encode the
853 value of a form field you may use --data-urlencode.
854
855 If any of these options is used more than once on the same com‐
856 mand line, the data pieces specified will be merged with a sepa‐
857 rating &-symbol. Thus, using '-d name=daniel -d skill=lousy'
858 would generate a post chunk that looks like
859 'name=daniel&skill=lousy'.
860
861 If you start the data with the letter @, the rest should be a
862 file name to read the data from, or - if you want curl to read
863 the data from stdin. Posting data from a file named 'foobar'
864 would thus be done with -d, --data @foobar. When --data is told
865 to read from a file like that, carriage returns and newlines
866 will be stripped out. If you do not want the @ character to have
867 a special interpretation use --data-raw instead.
868
869 Examples:
870 curl -d "name=curl" https://example.com
871 curl -d "name=curl" -d "tool=cmdline" https://example.com
872 curl -d @filename https://example.com
873
874 See also --data-binary, --data-urlencode and --data-raw. This
875 option is mutually exclusive to -F, --form and -I, --head and
876 -T, --upload-file.
877
878 --delegation <LEVEL>
879 (GSS/kerberos) Set LEVEL to tell the server what it is allowed
880 to delegate when it comes to user credentials.
881
882 none Do not allow any delegation.
883
884 policy Delegates if and only if the OK-AS-DELEGATE flag is set
885 in the Kerberos service ticket, which is a matter of
886 realm policy.
887
888 always Unconditionally allow the server to delegate.
889
890 If this option is used several times, the last one will be used.
891
892 Example:
893 curl --delegation "none" https://example.com
894
895 See also -k, --insecure and --ssl.
896
897 --digest
898 (HTTP) Enables HTTP Digest authentication. This is an authenti‐
899 cation scheme that prevents the password from being sent over
900 the wire in clear text. Use this in combination with the normal
901 --user option to set user name and password.
902
903 If this option is used several times, only the first one is
904 used.
905
906 Example:
907 curl -u name:password --digest https://example.com
908
909 See also -u, --user, --proxy-digest and --anyauth. This option
910 is mutually exclusive to --basic and --ntlm and --negotiate.
911
912 --disable-eprt
913 (FTP) Tell curl to disable the use of the EPRT and LPRT commands
914 when doing active FTP transfers. Curl will normally always first
915 attempt to use EPRT, then LPRT before using PORT, but with this
916 option, it will use PORT right away. EPRT and LPRT are exten‐
917 sions to the original FTP protocol, and may not work on all
918 servers, but they enable more functionality in a better way than
919 the traditional PORT command.
920
921 --eprt can be used to explicitly enable EPRT again and --no-eprt
922 is an alias for --disable-eprt.
923
924 If the server is accessed using IPv6, this option will have no
925 effect as EPRT is necessary then.
926
927 Disabling EPRT only changes the active behavior. If you want to
928 switch to passive mode you need to not use --ftp-port or force
929 it with --ftp-pasv.
930
931 Example:
932 curl --disable-eprt ftp://example.com/
933
934 See also --disable-epsv and -P, --ftp-port.
935
936 --disable-epsv
937 (FTP) Tell curl to disable the use of the EPSV command when do‐
938 ing passive FTP transfers. Curl will normally always first at‐
939 tempt to use EPSV before PASV, but with this option, it will not
940 try using EPSV.
941
942 --epsv can be used to explicitly enable EPSV again and --no-epsv
943 is an alias for --disable-epsv.
944
945 If the server is an IPv6 host, this option will have no effect
946 as EPSV is necessary then.
947
948 Disabling EPSV only changes the passive behavior. If you want to
949 switch to active mode you need to use -P, --ftp-port.
950
951 Example:
952 curl --disable-epsv ftp://example.com/
953
954 See also --disable-eprt and -P, --ftp-port.
955
956 -q, --disable
957 If used as the first parameter on the command line, the curlrc
958 config file will not be read and used. See the --config for de‐
959 tails on the default config file search path.
960
961 Example:
962 curl -q https://example.com
963
964 See also -K, --config.
965
966 --disallow-username-in-url
967 (HTTP) This tells curl to exit if passed a URL containing a
968 username. This is probably most useful when the URL is being
969 provided at runtime or similar.
970
971 Example:
972 curl --disallow-username-in-url https://example.com
973
974 See also --proto. Added in 7.61.0.
975
976 --dns-interface <interface>
977 (DNS) Tell curl to send outgoing DNS requests through <inter‐
978 face>. This option is a counterpart to --interface (which does
979 not affect DNS). The supplied string must be an interface name
980 (not an address).
981
982 Example:
983 curl --dns-interface eth0 https://example.com
984
985 See also --dns-ipv4-addr and --dns-ipv6-addr. --dns-interface
986 requires that the underlying libcurl was built to support c-
987 ares. Added in 7.33.0.
988
989 --dns-ipv4-addr <address>
990 (DNS) Tell curl to bind to <ip-address> when making IPv4 DNS re‐
991 quests, so that the DNS requests originate from this address.
992 The argument should be a single IPv4 address.
993
994 If this option is used several times, the last one will be used.
995
996 Example:
997 curl --dns-ipv4-addr 10.1.2.3 https://example.com
998
999 See also --dns-interface and --dns-ipv6-addr. --dns-ipv4-addr
1000 requires that the underlying libcurl was built to support c-
1001 ares. Added in 7.33.0.
1002
1003 --dns-ipv6-addr <address>
1004 (DNS) Tell curl to bind to <ip-address> when making IPv6 DNS re‐
1005 quests, so that the DNS requests originate from this address.
1006 The argument should be a single IPv6 address.
1007
1008 If this option is used several times, the last one will be used.
1009
1010 Example:
1011 curl --dns-ipv6-addr 2a04:4e42::561 https://example.com
1012
1013 See also --dns-interface and --dns-ipv4-addr. --dns-ipv6-addr
1014 requires that the underlying libcurl was built to support c-
1015 ares. Added in 7.33.0.
1016
1017 --dns-servers <addresses>
1018 Set the list of DNS servers to be used instead of the system de‐
1019 fault. The list of IP addresses should be separated with com‐
1020 mas. Port numbers may also optionally be given as :<port-number>
1021 after each IP address.
1022
1023 If this option is used several times, the last one will be used.
1024
1025 Example:
1026 curl --dns-servers 192.168.0.1,192.168.0.2 https://example.com
1027
1028 See also --dns-interface and --dns-ipv4-addr. --dns-servers re‐
1029 quires that the underlying libcurl was built to support c-ares.
1030 Added in 7.33.0.
1031
1032 --doh-cert-status
1033 Same as --cert-status but used for DoH (DNS-over-HTTPS).
1034
1035 Example:
1036 curl --doh-cert-status --doh-url https://doh.example https://example.com
1037
1038 See also --doh-insecure. Added in 7.76.0.
1039
1040 --doh-insecure
1041 Same as --insecure but used for DoH (DNS-over-HTTPS).
1042
1043 Example:
1044 curl --doh-insecure --doh-url https://doh.example https://example.com
1045
1046 See also --doh-url. Added in 7.76.0.
1047
1048 --doh-url <URL>
1049 Specifies which DNS-over-HTTPS (DoH) server to use to resolve
1050 hostnames, instead of using the default name resolver mechanism.
1051 The URL must be HTTPS.
1052
1053 Some SSL options that you set for your transfer will apply to
1054 DoH since the name lookups take place over SSL. However, the
1055 certificate verification settings are not inherited and can be
1056 controlled separately via --doh-insecure and --doh-cert-status.
1057
1058 This option is unset if an empty string "" is used as the URL.
1059 (Added in 7.85.0)
1060
1061 If this option is used several times, the last one will be used.
1062
1063 Example:
1064 curl --doh-url https://doh.example https://example.com
1065
1066 See also --doh-insecure. Added in 7.62.0.
1067
1068 -D, --dump-header <filename>
1069 (HTTP FTP) Write the received protocol headers to the specified
1070 file. If no headers are received, the use of this option will
1071 create an empty file.
1072
1073 When used in FTP, the FTP server response lines are considered
1074 being "headers" and thus are saved there.
1075
1076 If this option is used several times, the last one will be used.
1077
1078 Example:
1079 curl --dump-header store.txt https://example.com
1080
1081 See also -o, --output.
1082
1083 --egd-file <file>
1084 (TLS) Deprecated option. This option is ignored by curl since
1085 7.84.0. Prior to that it only had an effect on curl if built to
1086 use old versions of OpenSSL.
1087
1088 Specify the path name to the Entropy Gathering Daemon socket.
1089 The socket is used to seed the random engine for SSL connec‐
1090 tions.
1091
1092 Example:
1093 curl --egd-file /random/here https://example.com
1094
1095 See also --random-file.
1096
1097 --engine <name>
1098 (TLS) Select the OpenSSL crypto engine to use for cipher opera‐
1099 tions. Use --engine list to print a list of build-time supported
1100 engines. Note that not all (and possibly none) of the engines
1101 may be available at runtime.
1102
1103 Example:
1104 curl --engine flavor https://example.com
1105
1106 See also --ciphers and --curves.
1107
1108 --etag-compare <file>
1109 (HTTP) This option makes a conditional HTTP request for the spe‐
1110 cific ETag read from the given file by sending a custom If-None-
1111 Match header using the stored ETag.
1112
1113 For correct results, make sure that the specified file contains
1114 only a single line with the desired ETag. An empty file is
1115 parsed as an empty ETag.
1116
1117 Use the option --etag-save to first save the ETag from a re‐
1118 sponse, and then use this option to compare against the saved
1119 ETag in a subsequent request.
1120
1121 Example:
1122 curl --etag-compare etag.txt https://example.com
1123
1124 See also --etag-save and -z, --time-cond. Added in 7.68.0.
1125
1126 --etag-save <file>
1127 (HTTP) This option saves an HTTP ETag to the specified file. An
1128 ETag is a caching related header, usually returned in a re‐
1129 sponse.
1130
1131 If no ETag is sent by the server, an empty file is created.
1132
1133 Example:
1134 curl --etag-save storetag.txt https://example.com
1135
1136 See also --etag-compare. Added in 7.68.0.
1137
1138 --expect100-timeout <seconds>
1139 (HTTP) Maximum time in seconds that you allow curl to wait for a
1140 100-continue response when curl emits an Expects: 100-continue
1141 header in its request. By default curl will wait one second.
1142 This option accepts decimal values! When curl stops waiting, it
1143 will continue as if the response has been received.
1144
1145 Example:
1146 curl --expect100-timeout 2.5 -T file https://example.com
1147
1148 See also --connect-timeout. Added in 7.47.0.
1149
1150 --fail-early
1151 Fail and exit on the first detected transfer error.
1152
1153 When curl is used to do multiple transfers on the command line,
1154 it will attempt to operate on each given URL, one by one. By de‐
1155 fault, it will ignore errors if there are more URLs given and
1156 the last URL's success will determine the error code curl re‐
1157 turns. So early failures will be "hidden" by subsequent success‐
1158 ful transfers.
1159
1160 Using this option, curl will instead return an error on the
1161 first transfer that fails, independent of the amount of URLs
1162 that are given on the command line. This way, no transfer fail‐
1163 ures go undetected by scripts and similar.
1164
1165 This option is global and does not need to be specified for each
1166 use of -:, --next.
1167
1168 This option does not imply -f, --fail, which causes transfers to
1169 fail due to the server's HTTP status code. You can combine the
1170 two options, however note --fail is not global and is therefore
1171 contained by -:, --next.
1172
1173 Example:
1174 curl --fail-early https://example.com https://two.example
1175
1176 See also -f, --fail and --fail-with-body. Added in 7.52.0.
1177
1178 --fail-with-body
1179 (HTTP) Return an error on server errors where the HTTP response
1180 code is 400 or greater). In normal cases when an HTTP server
1181 fails to deliver a document, it returns an HTML document stating
1182 so (which often also describes why and more). This flag will
1183 still allow curl to output and save that content but also to re‐
1184 turn error 22.
1185
1186 This is an alternative option to --fail which makes curl fail
1187 for the same circumstances but without saving the content.
1188
1189 Example:
1190 curl --fail-with-body https://example.com
1191
1192 See also -f, --fail. This option is mutually exclusive to -f,
1193 --fail. Added in 7.76.0.
1194
1195 -f, --fail
1196 (HTTP) Fail fast with no output at all on server errors. This is
1197 useful to enable scripts and users to better deal with failed
1198 attempts. In normal cases when an HTTP server fails to deliver a
1199 document, it returns an HTML document stating so (which often
1200 also describes why and more). This flag will prevent curl from
1201 outputting that and return error 22.
1202
1203 This method is not fail-safe and there are occasions where non-
1204 successful response codes will slip through, especially when au‐
1205 thentication is involved (response codes 401 and 407).
1206
1207 Example:
1208 curl --fail https://example.com
1209
1210 See also --fail-with-body. This option is mutually exclusive to
1211 --fail-with-body.
1212
1213 --false-start
1214 (TLS) Tells curl to use false start during the TLS handshake.
1215 False start is a mode where a TLS client will start sending ap‐
1216 plication data before verifying the server's Finished message,
1217 thus saving a round trip when performing a full handshake.
1218
1219 This is currently only implemented in the NSS and Secure Trans‐
1220 port (on iOS 7.0 or later, or OS X 10.9 or later) backends.
1221
1222 Example:
1223 curl --false-start https://example.com
1224
1225 See also --tcp-fastopen. Added in 7.42.0.
1226
1227 --form-escape
1228 (HTTP) Tells curl to pass on names of multipart form fields and
1229 files using backslash-escaping instead of percent-encoding.
1230
1231 Example:
1232 curl --form-escape -F 'field\name=curl' -F 'file=@load"this' https://example.com
1233
1234 See also -F, --form. Added in 7.81.0.
1235
1236 --form-string <name=string>
1237 (HTTP SMTP IMAP) Similar to --form except that the value string
1238 for the named parameter is used literally. Leading '@' and '<'
1239 characters, and the ';type=' string in the value have no special
1240 meaning. Use this in preference to --form if there's any possi‐
1241 bility that the string value may accidentally trigger the '@' or
1242 '<' features of -F, --form.
1243
1244 Example:
1245 curl --form-string "data" https://example.com
1246
1247 See also -F, --form.
1248
1249 -F, --form <name=content>
1250 (HTTP SMTP IMAP) For HTTP protocol family, this lets curl emu‐
1251 late a filled-in form in which a user has pressed the submit
1252 button. This causes curl to POST data using the Content-Type
1253 multipart/form-data according to RFC 2388.
1254
1255 For SMTP and IMAP protocols, this is the means to compose a mul‐
1256 tipart mail message to transmit.
1257
1258 This enables uploading of binary files etc. To force the 'con‐
1259 tent' part to be a file, prefix the file name with an @ sign. To
1260 just get the content part from a file, prefix the file name with
1261 the symbol <. The difference between @ and < is then that @
1262 makes a file get attached in the post as a file upload, while
1263 the < makes a text field and just get the contents for that text
1264 field from a file.
1265
1266 Tell curl to read content from stdin instead of a file by using
1267 - as filename. This goes for both @ and < constructs. When stdin
1268 is used, the contents is buffered in memory first by curl to de‐
1269 termine its size and allow a possible resend. Defining a part's
1270 data from a named non-regular file (such as a named pipe or sim‐
1271 ilar) is unfortunately not subject to buffering and will be ef‐
1272 fectively read at transmission time; since the full size is un‐
1273 known before the transfer starts, such data is sent as chunks by
1274 HTTP and rejected by IMAP.
1275
1276 Example: send an image to an HTTP server, where 'profile' is the
1277 name of the form-field to which the file portrait.jpg will be
1278 the input:
1279
1280 curl -F profile=@portrait.jpg https://example.com/upload.cgi
1281
1282 Example: send your name and shoe size in two text fields to the
1283 server:
1284
1285 curl -F name=John -F shoesize=11 https://example.com/
1286
1287 Example: send your essay in a text field to the server. Send it
1288 as a plain text field, but get the contents for it from a local
1289 file:
1290
1291 curl -F "story=<hugefile.txt" https://example.com/
1292
1293 You can also tell curl what Content-Type to use by using
1294 'type=', in a manner similar to:
1295
1296 curl -F "web=@index.html;type=text/html" example.com
1297
1298 or
1299
1300 curl -F "name=daniel;type=text/foo" example.com
1301
1302 You can also explicitly change the name field of a file upload
1303 part by setting filename=, like this:
1304
1305 curl -F "file=@localfile;filename=nameinpost" example.com
1306
1307 If filename/path contains ',' or ';', it must be quoted by dou‐
1308 ble-quotes like:
1309
1310 curl -F "file=@\"local,file\";filename=\"name;in;post\"" example.com
1311
1312 or
1313
1314 curl -F 'file=@"local,file";filename="name;in;post"' example.com
1315
1316 Note that if a filename/path is quoted by double-quotes, any
1317 double-quote or backslash within the filename must be escaped by
1318 backslash.
1319
1320 Quoting must also be applied to non-file data if it contains
1321 semicolons, leading/trailing spaces or leading double quotes:
1322
1323 curl -F 'colors="red; green; blue";type=text/x-myapp' example.com
1324
1325 You can add custom headers to the field by setting headers=,
1326 like
1327
1328 curl -F "submit=OK;headers=\"X-submit-type: OK\"" example.com
1329
1330 or
1331
1332 curl -F "submit=OK;headers=@headerfile" example.com
1333
1334 The headers= keyword may appear more that once and above notes
1335 about quoting apply. When headers are read from a file, Empty
1336 lines and lines starting with '#' are comments and ignored; each
1337 header can be folded by splitting between two words and starting
1338 the continuation line with a space; embedded carriage-returns
1339 and trailing spaces are stripped. Here is an example of a
1340 header file contents:
1341
1342 # This file contain two headers.
1343 X-header-1: this is a header
1344
1345 # The following header is folded.
1346 X-header-2: this is
1347 another header
1348
1349 To support sending multipart mail messages, the syntax is ex‐
1350 tended as follows:
1351 - name can be omitted: the equal sign is the first character of
1352 the argument,
1353 - if data starts with '(', this signals to start a new multi‐
1354 part: it can be followed by a content type specification.
1355 - a multipart can be terminated with a '=)' argument.
1356
1357 Example: the following command sends an SMTP mime email consist‐
1358 ing in an inline part in two alternative formats: plain text and
1359 HTML. It attaches a text file:
1360
1361 curl -F '=(;type=multipart/alternative' \
1362 -F '=plain text message' \
1363 -F '= <body>HTML message</body>;type=text/html' \
1364 -F '=)' -F '=@textfile.txt' ... smtp://example.com
1365
1366 Data can be encoded for transfer using encoder=. Available en‐
1367 codings are binary and 8bit that do nothing else than adding the
1368 corresponding Content-Transfer-Encoding header, 7bit that only
1369 rejects 8-bit characters with a transfer error, quoted-printable
1370 and base64 that encodes data according to the corresponding
1371 schemes, limiting lines length to 76 characters.
1372
1373 Example: send multipart mail with a quoted-printable text mes‐
1374 sage and a base64 attached file:
1375
1376 curl -F '=text message;encoder=quoted-printable' \
1377 -F '=@localfile;encoder=base64' ... smtp://example.com
1378
1379 See further examples and details in the MANUAL.
1380
1381 This option can be used multiple times.
1382
1383 Example:
1384 curl --form "name=curl" --form "file=@loadthis" https://example.com
1385
1386 See also -d, --data, --form-string and --form-escape. This op‐
1387 tion is mutually exclusive to -d, --data and -I, --head and -T,
1388 --upload-file.
1389
1390 --ftp-account <data>
1391 (FTP) When an FTP server asks for "account data" after user name
1392 and password has been provided, this data is sent off using the
1393 ACCT command.
1394
1395 If this option is used several times, the last one will be used.
1396
1397 Example:
1398 curl --ftp-account "mr.robot" ftp://example.com/
1399
1400 See also -u, --user.
1401
1402 --ftp-alternative-to-user <command>
1403 (FTP) If authenticating with the USER and PASS commands fails,
1404 send this command. When connecting to Tumbleweed's Secure
1405 Transport server over FTPS using a client certificate, using
1406 "SITE AUTH" will tell the server to retrieve the username from
1407 the certificate.
1408
1409 Example:
1410 curl --ftp-alternative-to-user "U53r" ftp://example.com
1411
1412 See also --ftp-account and -u, --user.
1413
1414 --ftp-create-dirs
1415 (FTP SFTP) When an FTP or SFTP URL/operation uses a path that
1416 does not currently exist on the server, the standard behavior of
1417 curl is to fail. Using this option, curl will instead attempt to
1418 create missing directories.
1419
1420 Example:
1421 curl --ftp-create-dirs -T file ftp://example.com/remote/path/file
1422
1423 See also --create-dirs.
1424
1425 --ftp-method <method>
1426 (FTP) Control what method curl should use to reach a file on an
1427 FTP(S) server. The method argument should be one of the follow‐
1428 ing alternatives:
1429
1430 multicwd
1431 curl does a single CWD operation for each path part in
1432 the given URL. For deep hierarchies this means many com‐
1433 mands. This is how RFC 1738 says it should be done. This
1434 is the default but the slowest behavior.
1435
1436 nocwd curl does no CWD at all. curl will do SIZE, RETR, STOR
1437 etc and give a full path to the server for all these com‐
1438 mands. This is the fastest behavior.
1439
1440 singlecwd
1441 curl does one CWD with the full target directory and then
1442 operates on the file "normally" (like in the multicwd
1443 case). This is somewhat more standards compliant than
1444 'nocwd' but without the full penalty of 'multicwd'.
1445
1446 Examples:
1447 curl --ftp-method multicwd ftp://example.com/dir1/dir2/file
1448 curl --ftp-method nocwd ftp://example.com/dir1/dir2/file
1449 curl --ftp-method singlecwd ftp://example.com/dir1/dir2/file
1450
1451 See also -l, --list-only.
1452
1453 --ftp-pasv
1454 (FTP) Use passive mode for the data connection. Passive is the
1455 internal default behavior, but using this option can be used to
1456 override a previous --ftp-port option.
1457
1458 If this option is used several times, only the first one is
1459 used. Undoing an enforced passive really is not doable but you
1460 must then instead enforce the correct --ftp-port again.
1461
1462 Passive mode means that curl will try the EPSV command first and
1463 then PASV, unless --disable-epsv is used.
1464
1465 Example:
1466 curl --ftp-pasv ftp://example.com/
1467
1468 See also --disable-epsv.
1469
1470 -P, --ftp-port <address>
1471 (FTP) Reverses the default initiator/listener roles when con‐
1472 necting with FTP. This option makes curl use active mode. curl
1473 then tells the server to connect back to the client's specified
1474 address and port, while passive mode asks the server to setup an
1475 IP address and port for it to connect to. <address> should be
1476 one of:
1477
1478 interface
1479 e.g. "eth0" to specify which interface's IP address you
1480 want to use (Unix only)
1481
1482 IP address
1483 e.g. "192.168.10.1" to specify the exact IP address
1484
1485 host name
1486 e.g. "my.host.domain" to specify the machine
1487
1488 - make curl pick the same IP address that is already used
1489 for the control connection
1490
1491 If this option is used several times, the last one will be used. Dis‐
1492 able the use of PORT with --ftp-pasv. Disable the attempt to use the
1493 EPRT command instead of PORT by using --disable-eprt. EPRT is really
1494 PORT++.
1495
1496 You can also append ":[start]-[end]" to the right of the address, to
1497 tell curl what TCP port range to use. That means you specify a port
1498 range, from a lower to a higher number. A single number works as well,
1499 but do note that it increases the risk of failure since the port may
1500 not be available.
1501
1502
1503 Examples:
1504 curl -P - ftp:/example.com
1505 curl -P eth0 ftp:/example.com
1506 curl -P 192.168.0.2 ftp:/example.com
1507
1508 See also --ftp-pasv and --disable-eprt.
1509
1510 --ftp-pret
1511 (FTP) Tell curl to send a PRET command before PASV (and EPSV).
1512 Certain FTP servers, mainly drftpd, require this non-standard
1513 command for directory listings as well as up and downloads in
1514 PASV mode.
1515
1516 Example:
1517 curl --ftp-pret ftp://example.com/
1518
1519 See also -P, --ftp-port and --ftp-pasv.
1520
1521 --ftp-skip-pasv-ip
1522 (FTP) Tell curl to not use the IP address the server suggests in
1523 its response to curl's PASV command when curl connects the data
1524 connection. Instead curl will re-use the same IP address it al‐
1525 ready uses for the control connection.
1526
1527 Since curl 7.74.0 this option is enabled by default.
1528
1529 This option has no effect if PORT, EPRT or EPSV is used instead
1530 of PASV.
1531
1532 Example:
1533 curl --ftp-skip-pasv-ip ftp://example.com/
1534
1535 See also --ftp-pasv.
1536
1537 --ftp-ssl-ccc-mode <active/passive>
1538 (FTP) Sets the CCC mode. The passive mode will not initiate the
1539 shutdown, but instead wait for the server to do it, and will not
1540 reply to the shutdown from the server. The active mode initiates
1541 the shutdown and waits for a reply from the server.
1542
1543 Example:
1544 curl --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/
1545
1546 See also --ftp-ssl-ccc.
1547
1548 --ftp-ssl-ccc
1549 (FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS
1550 layer after authenticating. The rest of the control channel com‐
1551 munication will be unencrypted. This allows NAT routers to fol‐
1552 low the FTP transaction. The default mode is passive.
1553
1554 Example:
1555 curl --ftp-ssl-ccc ftps://example.com/
1556
1557 See also --ssl and --ftp-ssl-ccc-mode.
1558
1559 --ftp-ssl-control
1560 (FTP) Require SSL/TLS for the FTP login, clear for transfer.
1561 Allows secure authentication, but non-encrypted data transfers
1562 for efficiency. Fails the transfer if the server does not sup‐
1563 port SSL/TLS.
1564
1565 Example:
1566 curl --ftp-ssl-control ftp://example.com
1567
1568 See also --ssl.
1569
1570 -G, --get
1571 When used, this option will make all data specified with -d,
1572 --data, --data-binary or --data-urlencode to be used in an HTTP
1573 GET request instead of the POST request that otherwise would be
1574 used. The data will be appended to the URL with a '?' separator.
1575
1576 If used in combination with -I, --head, the POST data will in‐
1577 stead be appended to the URL with a HEAD request.
1578
1579 If this option is used several times, only the first one is
1580 used. This is because undoing a GET does not make sense, but you
1581 should then instead enforce the alternative method you prefer.
1582
1583 Examples:
1584 curl --get https://example.com
1585 curl --get -d "tool=curl" -d "age=old" https://example.com
1586 curl --get -I -d "tool=curl" https://example.com
1587
1588 See also -d, --data and -X, --request.
1589
1590 -g, --globoff
1591 This option switches off the "URL globbing parser". When you set
1592 this option, you can specify URLs that contain the letters {}[]
1593 without having curl itself interpret them. Note that these let‐
1594 ters are not normal legal URL contents but they should be en‐
1595 coded according to the URI standard.
1596
1597 Example:
1598 curl -g "https://example.com/{[]}}}}"
1599
1600 See also -K, --config and -q, --disable.
1601
1602 --happy-eyeballs-timeout-ms <milliseconds>
1603 Happy Eyeballs is an algorithm that attempts to connect to both
1604 IPv4 and IPv6 addresses for dual-stack hosts, giving IPv6 a
1605 head-start of the specified number of milliseconds. If the IPv6
1606 address cannot be connected to within that time, then a connec‐
1607 tion attempt is made to the IPv4 address in parallel. The first
1608 connection to be established is the one that is used.
1609
1610 The range of suggested useful values is limited. Happy Eyeballs
1611 RFC 6555 says "It is RECOMMENDED that connection attempts be
1612 paced 150-250 ms apart to balance human factors against network
1613 load." libcurl currently defaults to 200 ms. Firefox and Chrome
1614 currently default to 300 ms.
1615
1616 If this option is used several times, the last one will be used.
1617
1618 Example:
1619 curl --happy-eyeballs-timeout-ms 500 https://example.com
1620
1621 See also -m, --max-time and --connect-timeout. Added in 7.59.0.
1622
1623 --haproxy-protocol
1624 (HTTP) Send a HAProxy PROXY protocol v1 header at the beginning
1625 of the connection. This is used by some load balancers and re‐
1626 verse proxies to indicate the client's true IP address and port.
1627
1628 This option is primarily useful when sending test requests to a
1629 service that expects this header.
1630
1631 Example:
1632 curl --haproxy-protocol https://example.com
1633
1634 See also -x, --proxy. Added in 7.60.0.
1635
1636 -I, --head
1637 (HTTP FTP FILE) Fetch the headers only! HTTP-servers feature the
1638 command HEAD which this uses to get nothing but the header of a
1639 document. When used on an FTP or FILE file, curl displays the
1640 file size and last modification time only.
1641
1642 Example:
1643 curl -I https://example.com
1644
1645 See also -G, --get, -v, --verbose and --trace-ascii.
1646
1647 -H, --header <header/@file>
1648 (HTTP) Extra header to include in the request when sending HTTP
1649 to a server. You may specify any number of extra headers. Note
1650 that if you should add a custom header that has the same name as
1651 one of the internal ones curl would use, your externally set
1652 header will be used instead of the internal one. This allows you
1653 to make even trickier stuff than curl would normally do. You
1654 should not replace internally set headers without knowing per‐
1655 fectly well what you are doing. Remove an internal header by
1656 giving a replacement without content on the right side of the
1657 colon, as in: -H "Host:". If you send the custom header with no-
1658 value then its header must be terminated with a semicolon, such
1659 as -H "X-Custom-Header;" to send "X-Custom-Header:".
1660
1661 curl will make sure that each header you add/replace is sent
1662 with the proper end-of-line marker, you should thus not add that
1663 as a part of the header content: do not add newlines or carriage
1664 returns, they will only mess things up for you.
1665
1666 This option can take an argument in @filename style, which then
1667 adds a header for each line in the input file. Using @- will
1668 make curl read the header file from stdin. Added in 7.55.0.
1669
1670 You need --proxy-header to send custom headers intended for an
1671 HTTP proxy. Added in 7.37.0.
1672
1673 Passing on a "Transfer-Encoding: chunked" header when doing an
1674 HTTP request with a request body, will make curl send the data
1675 using chunked encoding.
1676
1677 WARNING: headers set with this option will be set in all re‐
1678 quests - even after redirects are followed, like when told with
1679 -L, --location. This can lead to the header being sent to other
1680 hosts than the original host, so sensitive headers should be
1681 used with caution combined with following redirects.
1682
1683 This option can be used multiple times to add/replace/remove
1684 multiple headers.
1685
1686 Examples:
1687 curl -H "X-First-Name: Joe" https://example.com
1688 curl -H "User-Agent: yes-please/2000" https://example.com
1689 curl -H "Host:" https://example.com
1690
1691 See also -A, --user-agent and -e, --referer.
1692
1693 -h, --help <category>
1694 Usage help. This lists all commands of the <category>. If no
1695 arg was provided, curl will display the most important command
1696 line arguments. If the argument "all" was provided, curl will
1697 display all options available. If the argument "category" was
1698 provided, curl will display all categories and their meanings.
1699
1700 Example:
1701 curl --help all
1702
1703 See also -v, --verbose.
1704
1705 --hostpubmd5 <md5>
1706 (SFTP SCP) Pass a string containing 32 hexadecimal digits. The
1707 string should be the 128 bit MD5 checksum of the remote host's
1708 public key, curl will refuse the connection with the host unless
1709 the md5sums match.
1710
1711 Example:
1712 curl --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/
1713
1714 See also --hostpubsha256.
1715
1716 --hostpubsha256 <sha256>
1717 (SFTP SCP) Pass a string containing a Base64-encoded SHA256 hash
1718 of the remote host's public key. Curl will refuse the connection
1719 with the host unless the hashes match.
1720
1721 Example:
1722 curl --hostpubsha256 NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ= sftp://example.com/
1723
1724 See also --hostpubmd5. Added in 7.80.0.
1725
1726 --hsts <file name>
1727 (HTTPS) This option enables HSTS for the transfer. If the file
1728 name points to an existing HSTS cache file, that will be used.
1729 After a completed transfer, the cache will be saved to the file
1730 name again if it has been modified.
1731
1732 Specify a "" file name (zero length) to avoid loading/saving and
1733 make curl just handle HSTS in memory.
1734
1735 If this option is used several times, curl will load contents
1736 from all the files but the last one will be used for saving.
1737
1738 Example:
1739 curl --hsts cache.txt https://example.com
1740
1741 See also --proto. Added in 7.74.0.
1742
1743 --http0.9
1744 (HTTP) Tells curl to be fine with HTTP version 0.9 response.
1745
1746 HTTP/0.9 is a completely headerless response and therefore you
1747 can also connect with this to non-HTTP servers and still get a
1748 response since curl will simply transparently downgrade - if al‐
1749 lowed.
1750
1751 Since curl 7.66.0, HTTP/0.9 is disabled by default.
1752
1753 Example:
1754 curl --http0.9 https://example.com
1755
1756 See also --http1.1, --http2 and --http3. Added in 7.64.0.
1757
1758 -0, --http1.0
1759 (HTTP) Tells curl to use HTTP version 1.0 instead of using its
1760 internally preferred HTTP version.
1761
1762 Example:
1763 curl --http1.0 https://example.com
1764
1765 See also --http0.9 and --http1.1. This option is mutually exclu‐
1766 sive to --http1.1 and --http2 and --http2-prior-knowledge and
1767 --http3.
1768
1769 --http1.1
1770 (HTTP) Tells curl to use HTTP version 1.1.
1771
1772 Example:
1773 curl --http1.1 https://example.com
1774
1775 See also -0, --http1.0 and --http0.9. This option is mutually
1776 exclusive to -0, --http1.0 and --http2 and --http2-prior-knowl‐
1777 edge and --http3. Added in 7.33.0.
1778
1779 --http2-prior-knowledge
1780 (HTTP) Tells curl to issue its non-TLS HTTP requests using
1781 HTTP/2 without HTTP/1.1 Upgrade. It requires prior knowledge
1782 that the server supports HTTP/2 straight away. HTTPS requests
1783 will still do HTTP/2 the standard way with negotiated protocol
1784 version in the TLS handshake.
1785
1786 Example:
1787 curl --http2-prior-knowledge https://example.com
1788
1789 See also --http2 and --http3. --http2-prior-knowledge requires
1790 that the underlying libcurl was built to support HTTP/2. This
1791 option is mutually exclusive to --http1.1 and -0, --http1.0 and
1792 --http2 and --http3. Added in 7.49.0.
1793
1794 --http2
1795 (HTTP) Tells curl to use HTTP version 2.
1796
1797 For HTTPS, this means curl will attempt to negotiate HTTP/2 in
1798 the TLS handshake. curl does this by default.
1799
1800 For HTTP, this means curl will attempt to upgrade the request to
1801 HTTP/2 using the Upgrade: request header.
1802
1803 When curl uses HTTP/2 over HTTPS, it does not itself insist on
1804 TLS 1.2 or higher even though that is required by the specifica‐
1805 tion. A user can add this version requirement with --tlsv1.2.
1806
1807 Example:
1808 curl --http2 https://example.com
1809
1810 See also --http1.1 and --http3. --http2 requires that the under‐
1811 lying libcurl was built to support HTTP/2. This option is mutu‐
1812 ally exclusive to --http1.1 and -0, --http1.0 and --http2-prior-
1813 knowledge and --http3. Added in 7.33.0.
1814
1815 --http3
1816 (HTTP) WARNING: this option is experimental. Do not use in pro‐
1817 duction.
1818
1819 Tells curl to use HTTP version 3 directly to the host and port
1820 number used in the URL. A normal HTTP/3 transaction will be done
1821 to a host and then get redirected via Alt-Svc, but this option
1822 allows a user to circumvent that when you know that the target
1823 speaks HTTP/3 on the given host and port.
1824
1825 This option will make curl fail if a QUIC connection cannot be
1826 established, it cannot fall back to a lower HTTP version on its
1827 own.
1828
1829 Example:
1830 curl --http3 https://example.com
1831
1832 See also --http1.1 and --http2. --http3 requires that the under‐
1833 lying libcurl was built to support HTTP/3. This option is mutu‐
1834 ally exclusive to --http1.1 and -0, --http1.0 and --http2 and
1835 --http2-prior-knowledge. Added in 7.66.0.
1836
1837 --ignore-content-length
1838 (FTP HTTP) For HTTP, Ignore the Content-Length header. This is
1839 particularly useful for servers running Apache 1.x, which will
1840 report incorrect Content-Length for files larger than 2 giga‐
1841 bytes.
1842
1843 For FTP (since 7.46.0), skip the RETR command to figure out the
1844 size before downloading a file.
1845
1846 This option does not work for HTTP if libcurl was built to use
1847 hyper.
1848
1849 Example:
1850 curl --ignore-content-length https://example.com
1851
1852 See also --ftp-skip-pasv-ip.
1853
1854 -i, --include
1855 Include the HTTP response headers in the output. The HTTP re‐
1856 sponse headers can include things like server name, cookies,
1857 date of the document, HTTP version and more...
1858
1859 To view the request headers, consider the --verbose option.
1860
1861 Example:
1862 curl -i https://example.com
1863
1864 See also -v, --verbose.
1865
1866 -k, --insecure
1867 (TLS SFTP SCP) By default, every secure connection curl makes is
1868 verified to be secure before the transfer takes place. This op‐
1869 tion makes curl skip the verification step and proceed without
1870 checking.
1871
1872 When this option is not used for protocols using TLS, curl veri‐
1873 fies the server's TLS certificate before it continues: that the
1874 certificate contains the right name which matches the host name
1875 used in the URL and that the certificate has been signed by a CA
1876 certificate present in the cert store. See this online resource
1877 for further details:
1878 https://curl.se/docs/sslcerts.html
1879
1880 For SFTP and SCP, this option makes curl skip the known_hosts
1881 verification. known_hosts is a file normally stored in the
1882 user's home directory in the ".ssh" subdirectory, which contains
1883 host names and their public keys.
1884
1885 WARNING: using this option makes the transfer insecure.
1886
1887 Example:
1888 curl --insecure https://example.com
1889
1890 See also --proxy-insecure, --cacert and --capath.
1891
1892 --interface <name>
1893 Perform an operation using a specified interface. You can enter
1894 interface name, IP address or host name. An example could look
1895 like:
1896
1897 curl --interface eth0:1 https://www.example.com/
1898
1899 If this option is used several times, the last one will be used.
1900
1901 On Linux it can be used to specify a VRF, but the binary needs
1902 to either have CAP_NET_RAW or to be run as root. More informa‐
1903 tion about Linux VRF: https://www.kernel.org/doc/Documenta‐
1904 tion/networking/vrf.txt
1905
1906 Example:
1907 curl --interface eth0 https://example.com
1908
1909 See also --dns-interface.
1910
1911 -4, --ipv4
1912 This option tells curl to use IPv4 addresses only, and not for
1913 example try IPv6.
1914
1915 Example:
1916 curl --ipv4 https://example.com
1917
1918 See also --http1.1 and --http2. This option is mutually exclu‐
1919 sive to -6, --ipv6.
1920
1921 -6, --ipv6
1922 This option tells curl to use IPv6 addresses only, and not for
1923 example try IPv4.
1924
1925 Example:
1926 curl --ipv6 https://example.com
1927
1928 See also --http1.1 and --http2. This option is mutually exclu‐
1929 sive to -4, --ipv4.
1930
1931 --json <data>
1932 (HTTP) Sends the specified JSON data in a POST request to the
1933 HTTP server. --json works as a shortcut for passing on these
1934 three options:
1935
1936 --data [arg]
1937 --header "Content-Type: application/json"
1938 --header "Accept: application/json"
1939
1940 There is no verification that the passed in data is actual JSON
1941 or that the syntax is correct.
1942
1943 If you start the data with the letter @, the rest should be a
1944 file name to read the data from, or a single dash (-) if you
1945 want curl to read the data from stdin. Posting data from a file
1946 named 'foobar' would thus be done with --json @foobar and to in‐
1947 stead read the data from stdin, use --json @-.
1948
1949 If this option is used more than once on the same command line,
1950 the additional data pieces will be concatenated to the previous
1951 before sending.
1952
1953 The headers this option sets can be overridden with --header as
1954 usual.
1955
1956 Examples:
1957 curl --json '{ "drink": "coffe" }' https://example.com
1958 curl --json '{ "drink":' --json ' "coffe" }' https://example.com
1959 curl --json @prepared https://example.com
1960 curl --json @- https://example.com < json.txt
1961
1962 See also --data-binary and --data-raw. This option is mutually
1963 exclusive to -F, --form and -I, --head and -T, --upload-file.
1964 Added in 7.82.0.
1965
1966 -j, --junk-session-cookies
1967 (HTTP) When curl is told to read cookies from a given file, this
1968 option will make it discard all "session cookies". This will ba‐
1969 sically have the same effect as if a new session is started.
1970 Typical browsers always discard session cookies when they are
1971 closed down.
1972
1973 Example:
1974 curl --junk-session-cookies -b cookies.txt https://example.com
1975
1976 See also -b, --cookie and -c, --cookie-jar.
1977
1978 --keepalive-time <seconds>
1979 This option sets the time a connection needs to remain idle be‐
1980 fore sending keepalive probes and the time between individual
1981 keepalive probes. It is currently effective on operating systems
1982 offering the TCP_KEEPIDLE and TCP_KEEPINTVL socket options
1983 (meaning Linux, recent AIX, HP-UX and more). Keepalives are
1984 used by the TCP stack to detect broken networks on idle connec‐
1985 tions. The number of missed keepalive probes before declaring
1986 the connection down is OS dependent and is commonly 9 or 10.
1987 This option has no effect if --no-keepalive is used.
1988
1989 If this option is used several times, the last one will be used.
1990 If unspecified, the option defaults to 60 seconds.
1991
1992 Example:
1993 curl --keepalive-time 20 https://example.com
1994
1995 See also --no-keepalive and -m, --max-time.
1996
1997 --key-type <type>
1998 (TLS) Private key file type. Specify which type your --key pro‐
1999 vided private key is. DER, PEM, and ENG are supported. If not
2000 specified, PEM is assumed.
2001
2002 If this option is used several times, the last one will be used.
2003
2004 Example:
2005 curl --key-type DER --key here https://example.com
2006
2007 See also --key.
2008
2009 --key <key>
2010 (TLS SSH) Private key file name. Allows you to provide your pri‐
2011 vate key in this separate file. For SSH, if not specified, curl
2012 tries the following candidates in order: '~/.ssh/id_rsa',
2013 '~/.ssh/id_dsa', './id_rsa', './id_dsa'.
2014
2015 If curl is built against OpenSSL library, and the engine pkcs11
2016 is available, then a PKCS#11 URI (RFC 7512) can be used to spec‐
2017 ify a private key located in a PKCS#11 device. A string begin‐
2018 ning with "pkcs11:" will be interpreted as a PKCS#11 URI. If a
2019 PKCS#11 URI is provided, then the --engine option will be set as
2020 "pkcs11" if none was provided and the --key-type option will be
2021 set as "ENG" if none was provided.
2022
2023 If curl is built against Secure Transport or Schannel then this
2024 option is ignored for TLS protocols (HTTPS, etc). Those backends
2025 expect the private key to be already present in the keychain or
2026 PKCS#12 file containing the certificate.
2027
2028 If this option is used several times, the last one will be used.
2029
2030 Example:
2031 curl --cert certificate --key here https://example.com
2032
2033 See also --key-type and -E, --cert.
2034
2035 --krb <level>
2036 (FTP) Enable Kerberos authentication and use. The level must be
2037 entered and should be one of 'clear', 'safe', 'confidential', or
2038 'private'. Should you use a level that is not one of these,
2039 'private' will instead be used.
2040
2041 If this option is used several times, the last one will be used.
2042
2043 Example:
2044 curl --krb clear ftp://example.com/
2045
2046 See also --delegation and --ssl. --krb requires that the under‐
2047 lying libcurl was built to support Kerberos.
2048
2049 --libcurl <file>
2050 Append this option to any ordinary curl command line, and you
2051 will get libcurl-using C source code written to the file that
2052 does the equivalent of what your command-line operation does!
2053
2054 This option is global and does not need to be specified for each
2055 use of -:, --next.
2056
2057 If this option is used several times, the last given file name
2058 will be used.
2059
2060 Example:
2061 curl --libcurl client.c https://example.com
2062
2063 See also -v, --verbose.
2064
2065 --limit-rate <speed>
2066 Specify the maximum transfer rate you want curl to use - for
2067 both downloads and uploads. This feature is useful if you have a
2068 limited pipe and you would like your transfer not to use your
2069 entire bandwidth. To make it slower than it otherwise would be.
2070
2071 The given speed is measured in bytes/second, unless a suffix is
2072 appended. Appending 'k' or 'K' will count the number as kilo‐
2073 bytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it
2074 gigabytes. The suffixes (k, M, G, T, P) are 1024 based. For ex‐
2075 ample 1k is 1024. Examples: 200K, 3m and 1G.
2076
2077 The rate limiting logic works on averaging the transfer speed to
2078 no more than the set threshold over a period of multiple sec‐
2079 onds.
2080
2081 If you also use the --speed-limit option, that option will take
2082 precedence and might cripple the rate-limiting slightly, to help
2083 keeping the speed-limit logic working.
2084
2085 If this option is used several times, the last one will be used.
2086
2087 Examples:
2088 curl --limit-rate 100K https://example.com
2089 curl --limit-rate 1000 https://example.com
2090 curl --limit-rate 10M https://example.com
2091
2092 See also -Y, --speed-limit and -y, --speed-time.
2093
2094 -l, --list-only
2095 (FTP POP3) (FTP) When listing an FTP directory, this switch
2096 forces a name-only view. This is especially useful if the user
2097 wants to machine-parse the contents of an FTP directory since
2098 the normal directory view does not use a standard look or for‐
2099 mat. When used like this, the option causes an NLST command to
2100 be sent to the server instead of LIST.
2101
2102 Note: Some FTP servers list only files in their response to
2103 NLST; they do not include sub-directories and symbolic links.
2104
2105 (POP3) When retrieving a specific email from POP3, this switch
2106 forces a LIST command to be performed instead of RETR. This is
2107 particularly useful if the user wants to see if a specific mes‐
2108 sage-id exists on the server and what size it is.
2109
2110 Note: When combined with -X, --request, this option can be used
2111 to send a UIDL command instead, so the user may use the email's
2112 unique identifier rather than its message-id to make the re‐
2113 quest.
2114
2115 Example:
2116 curl --list-only ftp://example.com/dir/
2117
2118 See also -Q, --quote and -X, --request.
2119
2120 --local-port <num/range>
2121 Set a preferred single number or range (FROM-TO) of local port
2122 numbers to use for the connection(s). Note that port numbers by
2123 nature are a scarce resource that will be busy at times so set‐
2124 ting this range to something too narrow might cause unnecessary
2125 connection setup failures.
2126
2127 Example:
2128 curl --local-port 1000-3000 https://example.com
2129
2130 See also -g, --globoff.
2131
2132 --location-trusted
2133 (HTTP) Like -L, --location, but will allow sending the name +
2134 password to all hosts that the site may redirect to. This may or
2135 may not introduce a security breach if the site redirects you to
2136 a site to which you will send your authentication info (which is
2137 plaintext in the case of HTTP Basic authentication).
2138
2139 Example:
2140 curl --location-trusted -u user:password https://example.com
2141
2142 See also -u, --user.
2143
2144 -L, --location
2145 (HTTP) If the server reports that the requested page has moved
2146 to a different location (indicated with a Location: header and a
2147 3XX response code), this option will make curl redo the request
2148 on the new place. If used together with --include or -I, --head,
2149 headers from all requested pages will be shown. When authentica‐
2150 tion is used, curl only sends its credentials to the initial
2151 host. If a redirect takes curl to a different host, it will not
2152 be able to intercept the user+password. See also --location-
2153 trusted on how to change this. You can limit the amount of redi‐
2154 rects to follow by using the --max-redirs option.
2155
2156 When curl follows a redirect and if the request is a POST, it
2157 will send the following request with a GET if the HTTP response
2158 was 301, 302, or 303. If the response code was any other 3xx
2159 code, curl will re-send the following request using the same un‐
2160 modified method.
2161
2162 You can tell curl to not change POST requests to GET after a 30x
2163 response by using the dedicated options for that: --post301,
2164 --post302 and --post303.
2165
2166 The method set with --request overrides the method curl would
2167 otherwise select to use.
2168
2169 Example:
2170 curl -L https://example.com
2171
2172 See also --resolve and --alt-svc.
2173
2174 --login-options <options>
2175 (IMAP LDAP POP3 SMTP) Specify the login options to use during
2176 server authentication.
2177
2178 You can use login options to specify protocol specific options
2179 that may be used during authentication. At present only IMAP,
2180 POP3 and SMTP support login options. For more information about
2181 login options please see RFC 2384, RFC 5092 and IETF draft
2182 draft-earhart-url-smtp-00.txt
2183
2184 If this option is used several times, the last one will be used.
2185
2186 Example:
2187 curl --login-options 'AUTH=*' imap://example.com
2188
2189 See also -u, --user. Added in 7.34.0.
2190
2191 --mail-auth <address>
2192 (SMTP) Specify a single address. This will be used to specify
2193 the authentication address (identity) of a submitted message
2194 that is being relayed to another server.
2195
2196 Example:
2197 curl --mail-auth user@example.come -T mail smtp://example.com/
2198
2199 See also --mail-rcpt and --mail-from.
2200
2201 --mail-from <address>
2202 (SMTP) Specify a single address that the given mail should get
2203 sent from.
2204
2205 Example:
2206 curl --mail-from user@example.com -T mail smtp://example.com/
2207
2208 See also --mail-rcpt and --mail-auth.
2209
2210 --mail-rcpt-allowfails
2211 (SMTP) When sending data to multiple recipients, by default curl
2212 will abort SMTP conversation if at least one of the recipients
2213 causes RCPT TO command to return an error.
2214
2215 The default behavior can be changed by passing --mail-rcpt-al‐
2216 lowfails command-line option which will make curl ignore errors
2217 and proceed with the remaining valid recipients.
2218
2219 If all recipients trigger RCPT TO failures and this flag is
2220 specified, curl will still abort the SMTP conversation and re‐
2221 turn the error received from to the last RCPT TO command.
2222
2223 Example:
2224 curl --mail-rcpt-allowfails --mail-rcpt dest@example.com smtp://example.com
2225
2226 See also --mail-rcpt. Added in 7.69.0.
2227
2228 --mail-rcpt <address>
2229 (SMTP) Specify a single email address, user name or mailing list
2230 name. Repeat this option several times to send to multiple re‐
2231 cipients.
2232
2233 When performing an address verification (VRFY command), the re‐
2234 cipient should be specified as the user name or user name and
2235 domain (as per Section 3.5 of RFC5321). (Added in 7.34.0)
2236
2237 When performing a mailing list expand (EXPN command), the recip‐
2238 ient should be specified using the mailing list name, such as
2239 "Friends" or "London-Office". (Added in 7.34.0)
2240
2241 Example:
2242 curl --mail-rcpt user@example.net smtp://example.com
2243
2244 See also --mail-rcpt-allowfails.
2245
2246 -M, --manual
2247 Manual. Display the huge help text.
2248
2249 Example:
2250 curl --manual
2251
2252 See also -v, --verbose, --libcurl and --trace.
2253
2254 --max-filesize <bytes>
2255 (FTP HTTP MQTT) Specify the maximum size (in bytes) of a file to
2256 download. If the file requested is larger than this value, the
2257 transfer will not start and curl will return with exit code 63.
2258
2259 A size modifier may be used. For example, Appending 'k' or 'K'
2260 will count the number as kilobytes, 'm' or 'M' makes it
2261 megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K,
2262 3m and 1G. (Added in 7.58.0)
2263
2264 NOTE: The file size is not always known prior to download, and
2265 for such files this option has no effect even if the file trans‐
2266 fer ends up being larger than this given limit. Example:
2267 curl --max-filesize 100K https://example.com
2268
2269 See also --limit-rate.
2270
2271 --max-redirs <num>
2272 (HTTP) Set maximum number of redirections to follow. When --lo‐
2273 cation is used, to prevent curl from following too many redi‐
2274 rects, by default, the limit is set to 50 redirects. Set this
2275 option to -1 to make it unlimited.
2276
2277 If this option is used several times, the last one will be used.
2278
2279 Example:
2280 curl --max-redirs 3 --location https://example.com
2281
2282 See also -L, --location.
2283
2284 -m, --max-time <fractional seconds>
2285 Maximum time in seconds that you allow each transfer to take.
2286 This is useful for preventing your batch jobs from hanging for
2287 hours due to slow networks or links going down. Since 7.32.0,
2288 this option accepts decimal values, but the actual timeout will
2289 decrease in accuracy as the specified timeout increases in deci‐
2290 mal precision.
2291
2292 If you enable retrying the transfer (--retry) then the maximum
2293 time counter is reset each time the transfer is retried. You can
2294 use --retry-max-time to limit the retry time.
2295
2296 If this option is used several times, the last one will be used.
2297
2298 Examples:
2299 curl --max-time 10 https://example.com
2300 curl --max-time 2.92 https://example.com
2301
2302 See also --connect-timeout and --retry-max-time.
2303
2304 --metalink
2305 This option was previously used to specify a metalink resource.
2306 Metalink support has been disabled in curl since 7.78.0 for se‐
2307 curity reasons.
2308
2309 Example:
2310 curl --metalink file https://example.com
2311
2312 See also -Z, --parallel.
2313
2314 --negotiate
2315 (HTTP) Enables Negotiate (SPNEGO) authentication.
2316
2317 This option requires a library built with GSS-API or SSPI sup‐
2318 port. Use --version to see if your curl supports GSS-API/SSPI or
2319 SPNEGO.
2320
2321 When using this option, you must also provide a fake --user op‐
2322 tion to activate the authentication code properly. Sending a '-u
2323 :' is enough as the user name and password from the --user op‐
2324 tion are not actually used.
2325
2326 If this option is used several times, only the first one is
2327 used.
2328
2329 Example:
2330 curl --negotiate -u : https://example.com
2331
2332 See also --basic, --ntlm, --anyauth and --proxy-negotiate.
2333
2334 --netrc-file <filename>
2335 This option is similar to -n, --netrc, except that you provide
2336 the path (absolute or relative) to the netrc file that curl
2337 should use. You can only specify one netrc file per invocation.
2338 If several --netrc-file options are provided, the last one will
2339 be used.
2340
2341 It will abide by --netrc-optional if specified.
2342
2343 Example:
2344 curl --netrc-file netrc https://example.com
2345
2346 See also -n, --netrc, -u, --user and -K, --config. This option
2347 is mutually exclusive to -n, --netrc.
2348
2349 --netrc-optional
2350 Similar to -n, --netrc, but this option makes the .netrc usage
2351 optional and not mandatory as the --netrc option does.
2352
2353 Example:
2354 curl --netrc-optional https://example.com
2355
2356 See also --netrc-file. This option is mutually exclusive to -n,
2357 --netrc.
2358
2359 -n, --netrc
2360 Makes curl scan the .netrc (_netrc on Windows) file in the
2361 user's home directory for login name and password. This is typi‐
2362 cally used for FTP on Unix. If used with HTTP, curl will enable
2363 user authentication. See netrc(5) and ftp(1) for details on the
2364 file format. Curl will not complain if that file does not have
2365 the right permissions (it should be neither world- nor group-
2366 readable). The environment variable "HOME" is used to find the
2367 home directory.
2368
2369 A quick and simple example of how to setup a .netrc to allow
2370 curl to FTP to the machine host.domain.com with user name 'my‐
2371 self' and password 'secret' could look similar to:
2372
2373 machine host.domain.com
2374 login myself
2375 password secret
2376
2377 Example:
2378 curl --netrc https://example.com
2379
2380 See also --netrc-file, -K, --config and -u, --user.
2381
2382 -:, --next
2383 Tells curl to use a separate operation for the following URL and
2384 associated options. This allows you to send several URL re‐
2385 quests, each with their own specific options, for example, such
2386 as different user names or custom requests for each.
2387
2388 --next will reset all local options and only global ones will
2389 have their values survive over to the operation following the
2390 --next instruction. Global options include -v, --verbose,
2391 --trace, --trace-ascii and --fail-early.
2392
2393 For example, you can do both a GET and a POST in a single com‐
2394 mand line:
2395
2396 curl www1.example.com --next -d postthis www2.example.com
2397
2398 Examples:
2399 curl https://example.com --next -d postthis www2.example.com
2400 curl -I https://example.com --next https://example.net/
2401
2402 See also -Z, --parallel and -K, --config. Added in 7.36.0.
2403
2404 --no-alpn
2405 (HTTPS) Disable the ALPN TLS extension. ALPN is enabled by de‐
2406 fault if libcurl was built with an SSL library that supports
2407 ALPN. ALPN is used by a libcurl that supports HTTP/2 to negoti‐
2408 ate HTTP/2 support with the server during https sessions.
2409
2410 Example:
2411 curl --no-alpn https://example.com
2412
2413 See also --no-npn and --http2. --no-alpn requires that the un‐
2414 derlying libcurl was built to support TLS. Added in 7.36.0.
2415
2416 -N, --no-buffer
2417 Disables the buffering of the output stream. In normal work sit‐
2418 uations, curl will use a standard buffered output stream that
2419 will have the effect that it will output the data in chunks, not
2420 necessarily exactly when the data arrives. Using this option
2421 will disable that buffering.
2422
2423 Note that this is the negated option name documented. You can
2424 thus use --buffer to enforce the buffering.
2425
2426 Example:
2427 curl --no-buffer https://example.com
2428
2429 See also -#, --progress-bar.
2430
2431 --no-clobber
2432 When used in conjunction with the -o, --output, -J, --remote-
2433 header-name, -O, --remote-name, or --remote-name-all options,
2434 curl avoids overwriting files that already exist. Instead, a dot
2435 and a number gets appended to the name of the file that would be
2436 created, up to filename.100 after which it will not create any
2437 file.
2438
2439 Note that this is the negated option name documented. You can
2440 thus use --clobber to enforce the clobbering, even if --remote-
2441 header-name or -J is specified.
2442
2443 Example:
2444 curl --no-clobber --output local/dir/file https://example.com
2445
2446 See also -o, --output and -O, --remote-name. Added in 7.83.0.
2447
2448 --no-keepalive
2449 Disables the use of keepalive messages on the TCP connection.
2450 curl otherwise enables them by default.
2451
2452 Note that this is the negated option name documented. You can
2453 thus use --keepalive to enforce keepalive.
2454
2455 Example:
2456 curl --no-keepalive https://example.com
2457
2458 See also --keepalive-time.
2459
2460 --no-npn
2461 (HTTPS) Disable the NPN TLS extension. NPN is enabled by default
2462 if libcurl was built with an SSL library that supports NPN. NPN
2463 is used by a libcurl that supports HTTP/2 to negotiate HTTP/2
2464 support with the server during https sessions.
2465
2466 Example:
2467 curl --no-npn https://example.com
2468
2469 See also --no-alpn and --http2. --no-npn requires that the un‐
2470 derlying libcurl was built to support TLS. Added in 7.36.0.
2471
2472 --no-progress-meter
2473 Option to switch off the progress meter output without muting or
2474 otherwise affecting warning and informational messages like
2475 --silent does.
2476
2477 Note that this is the negated option name documented. You can
2478 thus use --progress-meter to enable the progress meter again.
2479
2480 Example:
2481 curl --no-progress-meter -o store https://example.com
2482
2483 See also -v, --verbose and -s, --silent. Added in 7.67.0.
2484
2485 --no-sessionid
2486 (TLS) Disable curl's use of SSL session-ID caching. By default
2487 all transfers are done using the cache. Note that while nothing
2488 should ever get hurt by attempting to reuse SSL session-IDs,
2489 there seem to be broken SSL implementations in the wild that may
2490 require you to disable this in order for you to succeed.
2491
2492 Note that this is the negated option name documented. You can
2493 thus use --sessionid to enforce session-ID caching.
2494
2495 Example:
2496 curl --no-sessionid https://example.com
2497
2498 See also -k, --insecure.
2499
2500 --noproxy <no-proxy-list>
2501 Comma-separated list of hosts for which not to use a proxy, if
2502 one is specified. The only wildcard is a single * character,
2503 which matches all hosts, and effectively disables the proxy.
2504 Each name in this list is matched as either a domain which con‐
2505 tains the hostname, or the hostname itself. For example, lo‐
2506 cal.com would match local.com, local.com:80, and www.local.com,
2507 but not www.notlocal.com.
2508
2509 Since 7.53.0, This option overrides the environment variables
2510 that disable the proxy ('no_proxy' and 'NO_PROXY'). If there's
2511 an environment variable disabling a proxy, you can set the no‐
2512 proxy list to "" to override it.
2513
2514 Example:
2515 curl --noproxy "www.example" https://example.com
2516
2517 See also -x, --proxy.
2518
2519 --ntlm-wb
2520 (HTTP) Enables NTLM much in the style --ntlm does, but hand over
2521 the authentication to the separate binary ntlmauth application
2522 that is executed when needed.
2523
2524 Example:
2525 curl --ntlm-wb -u user:password https://example.com
2526
2527 See also --ntlm and --proxy-ntlm.
2528
2529 --ntlm (HTTP) Enables NTLM authentication. The NTLM authentication
2530 method was designed by Microsoft and is used by IIS web servers.
2531 It is a proprietary protocol, reverse-engineered by clever peo‐
2532 ple and implemented in curl based on their efforts. This kind of
2533 behavior should not be endorsed, you should encourage everyone
2534 who uses NTLM to switch to a public and documented authentica‐
2535 tion method instead, such as Digest.
2536
2537 If you want to enable NTLM for your proxy authentication, then
2538 use --proxy-ntlm.
2539
2540 If this option is used several times, only the first one is
2541 used.
2542
2543 Example:
2544 curl --ntlm -u user:password https://example.com
2545
2546 See also --proxy-ntlm. --ntlm requires that the underlying
2547 libcurl was built to support TLS. This option is mutually exclu‐
2548 sive to --basic and --negotiate and --digest and --anyauth.
2549
2550 --oauth2-bearer <token>
2551 (IMAP LDAP POP3 SMTP HTTP) Specify the Bearer Token for OAUTH
2552 2.0 server authentication. The Bearer Token is used in conjunc‐
2553 tion with the user name which can be specified as part of the
2554 --url or --user options.
2555
2556 The Bearer Token and user name are formatted according to RFC
2557 6750.
2558
2559 If this option is used several times, the last one will be used.
2560
2561 Example:
2562 curl --oauth2-bearer "mF_9.B5f-4.1JqM" https://example.com
2563
2564 See also --basic, --ntlm and --digest. Added in 7.33.0.
2565
2566 --output-dir <dir>
2567
2568 This option specifies the directory in which files should be
2569 stored, when --remote-name or --output are used.
2570
2571 The given output directory is used for all URLs and output op‐
2572 tions on the command line, up until the first -:, --next.
2573
2574 If the specified target directory does not exist, the operation
2575 will fail unless --create-dirs is also used.
2576
2577 If this option is used multiple times, the last specified direc‐
2578 tory will be used.
2579
2580 Example:
2581 curl --output-dir "tmp" -O https://example.com
2582
2583 See also -O, --remote-name and -J, --remote-header-name. Added
2584 in 7.73.0.
2585
2586 -o, --output <file>
2587 Write output to <file> instead of stdout. If you are using {} or
2588 [] to fetch multiple documents, you should quote the URL and you
2589 can use '#' followed by a number in the <file> specifier. That
2590 variable will be replaced with the current string for the URL
2591 being fetched. Like in:
2592
2593 curl "http://{one,two}.example.com" -o "file_#1.txt"
2594
2595 or use several variables like:
2596
2597 curl "http://{site,host}.host[1-5].com" -o "#1_#2"
2598
2599 You may use this option as many times as the number of URLs you
2600 have. For example, if you specify two URLs on the same command
2601 line, you can use it like this:
2602
2603 curl -o aa example.com -o bb example.net
2604
2605 and the order of the -o options and the URLs does not matter,
2606 just that the first -o is for the first URL and so on, so the
2607 above command line can also be written as
2608
2609 curl example.com example.net -o aa -o bb
2610
2611 See also the --create-dirs option to create the local directo‐
2612 ries dynamically. Specifying the output as '-' (a single dash)
2613 will force the output to be done to stdout.
2614
2615 To suppress response bodies, you can redirect output to
2616 /dev/null:
2617
2618 curl example.com -o /dev/null
2619
2620 Or for Windows use nul:
2621
2622 curl example.com -o nul
2623
2624 Examples:
2625 curl -o file https://example.com
2626 curl "http://{one,two}.example.com" -o "file_#1.txt"
2627 curl "http://{site,host}.host[1-5].com" -o "#1_#2"
2628 curl -o file https://example.com -o file2 https://example.net
2629
2630 See also -O, --remote-name, --remote-name-all and -J, --remote-
2631 header-name.
2632
2633 --parallel-immediate
2634 When doing parallel transfers, this option will instruct curl
2635 that it should rather prefer opening up more connections in par‐
2636 allel at once rather than waiting to see if new transfers can be
2637 added as multiplexed streams on another connection.
2638
2639 This option is global and does not need to be specified for each
2640 use of -:, --next.
2641
2642 Example:
2643 curl --parallel-immediate -Z https://example.com -o file1 https://example.com -o file2
2644
2645 See also -Z, --parallel and --parallel-max. Added in 7.68.0.
2646
2647 --parallel-max <num>
2648 When asked to do parallel transfers, using -Z, --parallel, this
2649 option controls the maximum amount of transfers to do simultane‐
2650 ously.
2651
2652 This option is global and does not need to be specified for each
2653 use of -:, --next.
2654
2655 The default is 50.
2656
2657 Example:
2658 curl --parallel-max 100 -Z https://example.com ftp://example.com/
2659
2660 See also -Z, --parallel. Added in 7.66.0.
2661
2662 -Z, --parallel
2663 Makes curl perform its transfers in parallel as compared to the
2664 regular serial manner.
2665
2666 This option is global and does not need to be specified for each
2667 use of -:, --next.
2668
2669 Example:
2670 curl --parallel https://example.com -o file1 https://example.com -o file2
2671
2672 See also -:, --next and -v, --verbose. Added in 7.66.0.
2673
2674 --pass <phrase>
2675 (SSH TLS) Passphrase for the private key.
2676
2677 If this option is used several times, the last one will be used.
2678
2679 Example:
2680 curl --pass secret --key file https://example.com
2681
2682 See also --key and -u, --user.
2683
2684 --path-as-is
2685 Tell curl to not handle sequences of /../ or /./ in the given
2686 URL path. Normally curl will squash or merge them according to
2687 standards but with this option set you tell it not to do that.
2688
2689 Example:
2690 curl --path-as-is https://example.com/../../etc/passwd
2691
2692 See also --request-target. Added in 7.42.0.
2693
2694 --pinnedpubkey <hashes>
2695 (TLS) Tells curl to use the specified public key file (or
2696 hashes) to verify the peer. This can be a path to a file which
2697 contains a single public key in PEM or DER format, or any number
2698 of base64 encoded sha256 hashes preceded by 'sha256//' and sepa‐
2699 rated by ';'.
2700
2701 When negotiating a TLS or SSL connection, the server sends a
2702 certificate indicating its identity. A public key is extracted
2703 from this certificate and if it does not exactly match the pub‐
2704 lic key provided to this option, curl will abort the connection
2705 before sending or receiving any data.
2706
2707 PEM/DER support:
2708
2709 7.39.0: OpenSSL, GnuTLS and GSKit
2710
2711 7.43.0: NSS and wolfSSL
2712
2713 7.47.0: mbedtls
2714
2715 sha256 support:
2716
2717 7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL
2718
2719 7.47.0: mbedtls
2720
2721 Other SSL backends not supported.
2722
2723 If this option is used several times, the last one will be used.
2724
2725 Examples:
2726 curl --pinnedpubkey keyfile https://example.com
2727 curl --pinnedpubkey 'sha256//ce118b51897f4452dc' https://example.com
2728
2729 See also --hostpubsha256. Added in 7.39.0.
2730
2731 --post301
2732 (HTTP) Tells curl to respect RFC 7231/6.4.2 and not convert POST
2733 requests into GET requests when following a 301 redirection. The
2734 non-RFC behavior is ubiquitous in web browsers, so curl does the
2735 conversion by default to maintain consistency. However, a server
2736 may require a POST to remain a POST after such a redirection.
2737 This option is meaningful only when using -L, --location.
2738
2739 Example:
2740 curl --post301 --location -d "data" https://example.com
2741
2742 See also --post302, --post303 and -L, --location.
2743
2744 --post302
2745 (HTTP) Tells curl to respect RFC 7231/6.4.3 and not convert POST
2746 requests into GET requests when following a 302 redirection. The
2747 non-RFC behavior is ubiquitous in web browsers, so curl does the
2748 conversion by default to maintain consistency. However, a server
2749 may require a POST to remain a POST after such a redirection.
2750 This option is meaningful only when using -L, --location.
2751
2752 Example:
2753 curl --post302 --location -d "data" https://example.com
2754
2755 See also --post301, --post303 and -L, --location.
2756
2757 --post303
2758 (HTTP) Tells curl to violate RFC 7231/6.4.4 and not convert POST
2759 requests into GET requests when following 303 redirections. A
2760 server may require a POST to remain a POST after a 303 redirect‐
2761 ion. This option is meaningful only when using -L, --location.
2762
2763 Example:
2764 curl --post303 --location -d "data" https://example.com
2765
2766 See also --post302, --post301 and -L, --location.
2767
2768 --preproxy [protocol://]host[:port]
2769 Use the specified SOCKS proxy before connecting to an HTTP or
2770 HTTPS -x, --proxy. In such a case curl first connects to the
2771 SOCKS proxy and then connects (through SOCKS) to the HTTP or
2772 HTTPS proxy. Hence pre proxy.
2773
2774 The pre proxy string should be specified with a protocol:// pre‐
2775 fix to specify alternative proxy protocols. Use socks4://,
2776 socks4a://, socks5:// or socks5h:// to request the specific
2777 SOCKS version to be used. No protocol specified will make curl
2778 default to SOCKS4.
2779
2780 If the port number is not specified in the proxy string, it is
2781 assumed to be 1080.
2782
2783 User and password that might be provided in the proxy string are
2784 URL decoded by curl. This allows you to pass in special charac‐
2785 ters such as @ by using %40 or pass in a colon with %3a.
2786
2787 If this option is used several times, the last one will be used.
2788
2789 Example:
2790 curl --preproxy socks5://proxy.example -x http://http.example https://example.com
2791
2792 See also -x, --proxy and --socks5. Added in 7.52.0.
2793
2794 -#, --progress-bar
2795 Make curl display transfer progress as a simple progress bar in‐
2796 stead of the standard, more informational, meter.
2797
2798 This progress bar draws a single line of '#' characters across
2799 the screen and shows a percentage if the transfer size is known.
2800 For transfers without a known size, there will be space ship
2801 (-=o=-) that moves back and forth but only while data is being
2802 transferred, with a set of flying hash sign symbols on top.
2803
2804 This option is global and does not need to be specified for each
2805 use of -:, --next.
2806
2807 Example:
2808 curl -# -O https://example.com
2809
2810 See also --styled-output.
2811
2812 --proto-default <protocol>
2813 Tells curl to use protocol for any URL missing a scheme name.
2814
2815 An unknown or unsupported protocol causes error CURLE_UNSUP‐
2816 PORTED_PROTOCOL (1).
2817
2818 This option does not change the default proxy protocol (http).
2819
2820 Without this option set, curl guesses protocol based on the host
2821 name, see --url for details.
2822
2823 Example:
2824 curl --proto-default https ftp.example.com
2825
2826 See also --proto and --proto-redir. Added in 7.45.0.
2827
2828 --proto-redir <protocols>
2829 Tells curl to limit what protocols it may use on redirect. Pro‐
2830 tocols denied by --proto are not overridden by this option. See
2831 --proto for how protocols are represented.
2832
2833 Example, allow only HTTP and HTTPS on redirect:
2834
2835 curl --proto-redir -all,http,https http://example.com
2836
2837 By default curl will only allow HTTP, HTTPS, FTP and FTPS on re‐
2838 direct (since 7.65.2). Specifying all or +all enables all proto‐
2839 cols on redirects, which is not good for security.
2840
2841 Example:
2842 curl --proto-redir =http,https https://example.com
2843
2844 See also --proto.
2845
2846 --proto <protocols>
2847 Tells curl to limit what protocols it may use for transfers.
2848 Protocols are evaluated left to right, are comma separated, and
2849 are each a protocol name or 'all', optionally prefixed by zero
2850 or more modifiers. Available modifiers are:
2851
2852 + Permit this protocol in addition to protocols already permit‐
2853 ted (this is the default if no modifier is used).
2854
2855 - Deny this protocol, removing it from the list of protocols
2856 already permitted.
2857
2858 = Permit only this protocol (ignoring the list already permit‐
2859 ted), though subject to later modification by subsequent en‐
2860 tries in the comma separated list.
2861
2862 For example:
2863
2864 --proto -ftps uses the default protocols, but disables ftps
2865
2866 --proto -all,https,+http
2867 only enables http and https
2868
2869 --proto =http,https
2870 also only enables http and https
2871
2872 Unknown protocols produce a warning. This allows scripts to
2873 safely rely on being able to disable potentially dangerous pro‐
2874 tocols, without relying upon support for that protocol being
2875 built into curl to avoid an error.
2876
2877 This option can be used multiple times, in which case the effect
2878 is the same as concatenating the protocols into one instance of
2879 the option.
2880
2881 Example:
2882 curl --proto =http,https,sftp https://example.com
2883
2884 See also --proto-redir and --proto-default.
2885
2886 --proxy-anyauth
2887 Tells curl to pick a suitable authentication method when commu‐
2888 nicating with the given HTTP proxy. This might cause an extra
2889 request/response round-trip.
2890
2891 Example:
2892 curl --proxy-anyauth --proxy-user user:passwd -x proxy https://example.com
2893
2894 See also -x, --proxy, --proxy-basic and --proxy-digest.
2895
2896 --proxy-basic
2897 Tells curl to use HTTP Basic authentication when communicating
2898 with the given proxy. Use --basic for enabling HTTP Basic with a
2899 remote host. Basic is the default authentication method curl
2900 uses with proxies.
2901
2902 Example:
2903 curl --proxy-basic --proxy-user user:passwd -x proxy https://example.com
2904
2905 See also -x, --proxy, --proxy-anyauth and --proxy-digest.
2906
2907 --proxy-cacert <file>
2908 Same as --cacert but used in HTTPS proxy context.
2909
2910 Example:
2911 curl --proxy-cacert CA-file.txt -x https://proxy https://example.com
2912
2913 See also --proxy-capath, --cacert, --capath and -x, --proxy.
2914 Added in 7.52.0.
2915
2916 --proxy-capath <dir>
2917 Same as --capath but used in HTTPS proxy context.
2918
2919 Example:
2920 curl --proxy-capath /local/directory -x https://proxy https://example.com
2921
2922 See also --proxy-cacert, -x, --proxy and --capath. Added in
2923 7.52.0.
2924
2925 --proxy-cert-type <type>
2926 Same as --cert-type but used in HTTPS proxy context.
2927
2928 Example:
2929 curl --proxy-cert-type PEM --proxy-cert file -x https://proxy https://example.com
2930
2931 See also --proxy-cert. Added in 7.52.0.
2932
2933 --proxy-cert <cert[:passwd]>
2934 Same as --cert but used in HTTPS proxy context.
2935
2936 Example:
2937 curl --proxy-cert file -x https://proxy https://example.com
2938
2939 See also --proxy-cert-type. Added in 7.52.0.
2940
2941 --proxy-ciphers <list>
2942 Same as --ciphers but used in HTTPS proxy context.
2943
2944 Example:
2945 curl --proxy-ciphers ECDHE-ECDSA-AES256-CCM8 -x https://proxy https://example.com
2946
2947 See also --ciphers, --curves and -x, --proxy. Added in 7.52.0.
2948
2949 --proxy-crlfile <file>
2950 Same as --crlfile but used in HTTPS proxy context.
2951
2952 Example:
2953 curl --proxy-crlfile rejects.txt -x https://proxy https://example.com
2954
2955 See also --crlfile and -x, --proxy. Added in 7.52.0.
2956
2957 --proxy-digest
2958 Tells curl to use HTTP Digest authentication when communicating
2959 with the given proxy. Use --digest for enabling HTTP Digest with
2960 a remote host.
2961
2962 Example:
2963 curl --proxy-digest --proxy-user user:passwd -x proxy https://example.com
2964
2965 See also -x, --proxy, --proxy-anyauth and --proxy-basic.
2966
2967 --proxy-header <header/@file>
2968 (HTTP) Extra header to include in the request when sending HTTP
2969 to a proxy. You may specify any number of extra headers. This is
2970 the equivalent option to --header but is for proxy communication
2971 only like in CONNECT requests when you want a separate header
2972 sent to the proxy to what is sent to the actual remote host.
2973
2974 curl will make sure that each header you add/replace is sent
2975 with the proper end-of-line marker, you should thus not add that
2976 as a part of the header content: do not add newlines or carriage
2977 returns, they will only mess things up for you.
2978
2979 Headers specified with this option will not be included in re‐
2980 quests that curl knows will not be sent to a proxy.
2981
2982 Starting in 7.55.0, this option can take an argument in @file‐
2983 name style, which then adds a header for each line in the input
2984 file. Using @- will make curl read the header file from stdin.
2985
2986 This option can be used multiple times to add/replace/remove
2987 multiple headers.
2988
2989 Examples:
2990 curl --proxy-header "X-First-Name: Joe" -x http://proxy https://example.com
2991 curl --proxy-header "User-Agent: surprise" -x http://proxy https://example.com
2992 curl --proxy-header "Host:" -x http://proxy https://example.com
2993
2994 See also -x, --proxy. Added in 7.37.0.
2995
2996 --proxy-insecure
2997 Same as --insecure but used in HTTPS proxy context.
2998
2999 Example:
3000 curl --proxy-insecure -x https://proxy https://example.com
3001
3002 See also -x, --proxy and -k, --insecure. Added in 7.52.0.
3003
3004 --proxy-key-type <type>
3005 Same as --key-type but used in HTTPS proxy context.
3006
3007 Example:
3008 curl --proxy-key-type DER --proxy-key here -x https://proxy https://example.com
3009
3010 See also --proxy-key and -x, --proxy. Added in 7.52.0.
3011
3012 --proxy-key <key>
3013 Same as --key but used in HTTPS proxy context.
3014
3015 Example:
3016 curl --proxy-key here -x https://proxy https://example.com
3017
3018 See also --proxy-key-type and -x, --proxy. Added in 7.52.0.
3019
3020 --proxy-negotiate
3021 Tells curl to use HTTP Negotiate (SPNEGO) authentication when
3022 communicating with the given proxy. Use --negotiate for enabling
3023 HTTP Negotiate (SPNEGO) with a remote host.
3024
3025 Example:
3026 curl --proxy-negotiate --proxy-user user:passwd -x proxy https://example.com
3027
3028 See also --proxy-anyauth and --proxy-basic.
3029
3030 --proxy-ntlm
3031 Tells curl to use HTTP NTLM authentication when communicating
3032 with the given proxy. Use --ntlm for enabling NTLM with a remote
3033 host.
3034
3035 Example:
3036 curl --proxy-ntlm --proxy-user user:passwd -x http://proxy https://example.com
3037
3038 See also --proxy-negotiate and --proxy-anyauth.
3039
3040 --proxy-pass <phrase>
3041 Same as --pass but used in HTTPS proxy context.
3042
3043 Example:
3044 curl --proxy-pass secret --proxy-key here -x https://proxy https://example.com
3045
3046 See also -x, --proxy and --proxy-key. Added in 7.52.0.
3047
3048 --proxy-pinnedpubkey <hashes>
3049 (TLS) Tells curl to use the specified public key file (or
3050 hashes) to verify the proxy. This can be a path to a file which
3051 contains a single public key in PEM or DER format, or any number
3052 of base64 encoded sha256 hashes preceded by 'sha256//' and sepa‐
3053 rated by ';'.
3054
3055 When negotiating a TLS or SSL connection, the server sends a
3056 certificate indicating its identity. A public key is extracted
3057 from this certificate and if it does not exactly match the pub‐
3058 lic key provided to this option, curl will abort the connection
3059 before sending or receiving any data.
3060
3061 If this option is used several times, the last one will be used.
3062
3063 Examples:
3064 curl --proxy-pinnedpubkey keyfile https://example.com
3065 curl --proxy-pinnedpubkey 'sha256//ce118b51897f4452dc' https://example.com
3066
3067 See also --pinnedpubkey and -x, --proxy. Added in 7.59.0.
3068
3069 --proxy-service-name <name>
3070 This option allows you to change the service name for proxy ne‐
3071 gotiation.
3072
3073 Example:
3074 curl --proxy-service-name "shrubbery" -x proxy https://example.com
3075
3076 See also --service-name and -x, --proxy. Added in 7.43.0.
3077
3078 --proxy-ssl-allow-beast
3079 Same as --ssl-allow-beast but used in HTTPS proxy context.
3080
3081 Example:
3082 curl --proxy-ssl-allow-beast -x https://proxy https://example.com
3083
3084 See also --ssl-allow-beast and -x, --proxy. Added in 7.52.0.
3085
3086 --proxy-ssl-auto-client-cert
3087 Same as --ssl-auto-client-cert but used in HTTPS proxy context.
3088
3089 Example:
3090 curl --proxy-ssl-auto-client-cert -x https://proxy https://example.com
3091
3092 See also --ssl-auto-client-cert and -x, --proxy. Added in
3093 7.77.0.
3094
3095 --proxy-tls13-ciphers <ciphersuite list>
3096 (TLS) Specifies which cipher suites to use in the connection to
3097 your HTTPS proxy when it negotiates TLS 1.3. The list of ciphers
3098 suites must specify valid ciphers. Read up on TLS 1.3 cipher
3099 suite details on this URL:
3100
3101 https://curl.se/docs/ssl-ciphers.html
3102
3103 This option is currently used only when curl is built to use
3104 OpenSSL 1.1.1 or later. If you are using a different SSL backend
3105 you can try setting TLS 1.3 cipher suites by using the --proxy-
3106 ciphers option.
3107
3108 If this option is used several times, the last one will be used.
3109
3110 Example:
3111 curl --proxy-tls13-ciphers TLS_AES_128_GCM_SHA256 -x proxy https://example.com
3112
3113 See also --tls13-ciphers and --curves. Added in 7.61.0.
3114
3115 --proxy-tlsauthtype <type>
3116 Same as --tlsauthtype but used in HTTPS proxy context.
3117
3118 Example:
3119 curl --proxy-tlsauthtype SRP -x https://proxy https://example.com
3120
3121 See also -x, --proxy and --proxy-tlsuser. Added in 7.52.0.
3122
3123 --proxy-tlspassword <string>
3124 Same as --tlspassword but used in HTTPS proxy context.
3125
3126 Example:
3127 curl --proxy-tlspassword passwd -x https://proxy https://example.com
3128
3129 See also -x, --proxy and --proxy-tlsuser. Added in 7.52.0.
3130
3131 --proxy-tlsuser <name>
3132 Same as --tlsuser but used in HTTPS proxy context.
3133
3134 Example:
3135 curl --proxy-tlsuser smith -x https://proxy https://example.com
3136
3137 See also -x, --proxy and --proxy-tlspassword. Added in 7.52.0.
3138
3139 --proxy-tlsv1
3140 Same as --tlsv1 but used in HTTPS proxy context.
3141
3142 Example:
3143 curl --proxy-tlsv1 -x https://proxy https://example.com
3144
3145 See also -x, --proxy. Added in 7.52.0.
3146
3147 -U, --proxy-user <user:password>
3148 Specify the user name and password to use for proxy authentica‐
3149 tion.
3150
3151 If you use a Windows SSPI-enabled curl binary and do either Ne‐
3152 gotiate or NTLM authentication then you can tell curl to select
3153 the user name and password from your environment by specifying a
3154 single colon with this option: "-U :".
3155
3156 On systems where it works, curl will hide the given option argu‐
3157 ment from process listings. This is not enough to protect cre‐
3158 dentials from possibly getting seen by other users on the same
3159 system as they will still be visible for a moment before
3160 cleared. Such sensitive data should be retrieved from a file in‐
3161 stead or similar and never used in clear text in a command line.
3162
3163 If this option is used several times, the last one will be used.
3164
3165 Example:
3166 curl --proxy-user name:pwd -x proxy https://example.com
3167
3168 See also --proxy-pass.
3169
3170 -x, --proxy [protocol://]host[:port]
3171 Use the specified proxy.
3172
3173 The proxy string can be specified with a protocol:// prefix. No
3174 protocol specified or http:// will be treated as HTTP proxy. Use
3175 socks4://, socks4a://, socks5:// or socks5h:// to request a spe‐
3176 cific SOCKS version to be used.
3177
3178
3179 Unix domain sockets are supported for socks proxy. Set localhost
3180 for the host part. e.g. socks5h://localhost/path/to/socket.sock
3181
3182 HTTPS proxy support via https:// protocol prefix was added in
3183 7.52.0 for OpenSSL, GnuTLS and NSS.
3184
3185 Unrecognized and unsupported proxy protocols cause an error
3186 since 7.52.0. Prior versions may ignore the protocol and use
3187 http:// instead.
3188
3189 If the port number is not specified in the proxy string, it is
3190 assumed to be 1080.
3191
3192 This option overrides existing environment variables that set
3193 the proxy to use. If there's an environment variable setting a
3194 proxy, you can set proxy to "" to override it.
3195
3196 All operations that are performed over an HTTP proxy will trans‐
3197 parently be converted to HTTP. It means that certain protocol
3198 specific operations might not be available. This is not the case
3199 if you can tunnel through the proxy, as one with the --proxytun‐
3200 nel option.
3201
3202 User and password that might be provided in the proxy string are
3203 URL decoded by curl. This allows you to pass in special charac‐
3204 ters such as @ by using %40 or pass in a colon with %3a.
3205
3206 The proxy host can be specified the same way as the proxy envi‐
3207 ronment variables, including the protocol prefix (http://) and
3208 the embedded user + password.
3209
3210 If this option is used several times, the last one will be used.
3211
3212 Example:
3213 curl --proxy http://proxy.example https://example.com
3214
3215 See also --socks5 and --proxy-basic.
3216
3217 --proxy1.0 <host[:port]>
3218 Use the specified HTTP 1.0 proxy. If the port number is not
3219 specified, it is assumed at port 1080.
3220
3221 The only difference between this and the HTTP proxy option -x,
3222 --proxy, is that attempts to use CONNECT through the proxy will
3223 specify an HTTP 1.0 protocol instead of the default HTTP 1.1.
3224
3225 Example:
3226 curl --proxy1.0 -x http://proxy https://example.com
3227
3228 See also -x, --proxy, --socks5 and --preproxy.
3229
3230 -p, --proxytunnel
3231 When an HTTP proxy is used -x, --proxy, this option will make
3232 curl tunnel through the proxy. The tunnel approach is made with
3233 the HTTP proxy CONNECT request and requires that the proxy al‐
3234 lows direct connect to the remote port number curl wants to tun‐
3235 nel through to.
3236
3237 To suppress proxy CONNECT response headers when curl is set to
3238 output headers use --suppress-connect-headers.
3239
3240 Example:
3241 curl --proxytunnel -x http://proxy https://example.com
3242
3243 See also -x, --proxy.
3244
3245 --pubkey <key>
3246 (SFTP SCP) Public key file name. Allows you to provide your pub‐
3247 lic key in this separate file.
3248
3249 If this option is used several times, the last one will be used.
3250
3251 (As of 7.39.0, curl attempts to automatically extract the public
3252 key from the private key file, so passing this option is gener‐
3253 ally not required. Note that this public key extraction requires
3254 libcurl to be linked against a copy of libssh2 1.2.8 or higher
3255 that is itself linked against OpenSSL.)
3256
3257 Example:
3258 curl --pubkey file.pub sftp://example.com/
3259
3260 See also --pass.
3261
3262 -Q, --quote <command>
3263 (FTP SFTP) Send an arbitrary command to the remote FTP or SFTP
3264 server. Quote commands are sent BEFORE the transfer takes place
3265 (just after the initial PWD command in an FTP transfer, to be
3266 exact). To make commands take place after a successful transfer,
3267 prefix them with a dash '-'.
3268
3269 (FTP only) To make commands be sent after curl has changed the
3270 working directory, just before the file transfer command(s),
3271 prefix the command with a '+'. This is not performed when a di‐
3272 rectory listing is performed.
3273
3274 You may specify any number of commands.
3275
3276 By default curl will stop at first failure. To make curl con‐
3277 tinue even if the command fails, prefix the command with an as‐
3278 terisk (*). Otherwise, if the server returns failure for one of
3279 the commands, the entire operation will be aborted.
3280
3281 You must send syntactically correct FTP commands as RFC 959 de‐
3282 fines to FTP servers, or one of the commands listed below to
3283 SFTP servers.
3284
3285 This option can be used multiple times.
3286
3287 SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP
3288 quote commands itself before sending them to the server. File
3289 names may be quoted shell-style to embed spaces or special char‐
3290 acters. Following is the list of all supported SFTP quote com‐
3291 mands:
3292
3293 atime date file
3294 The atime command sets the last access time of the file
3295 named by the file operand. The <date expression> can be
3296 all sorts of date strings, see the curl_getdate(3) man
3297 page for date expression details. (Added in 7.73.0)
3298
3299 chgrp group file
3300 The chgrp command sets the group ID of the file named by
3301 the file operand to the group ID specified by the group
3302 operand. The group operand is a decimal integer group ID.
3303
3304 chmod mode file
3305 The chmod command modifies the file mode bits of the
3306 specified file. The mode operand is an octal integer mode
3307 number.
3308
3309 chown user file
3310 The chown command sets the owner of the file named by the
3311 file operand to the user ID specified by the user oper‐
3312 and. The user operand is a decimal integer user ID.
3313
3314 ln source_file target_file
3315 The ln and symlink commands create a symbolic link at the
3316 target_file location pointing to the source_file loca‐
3317 tion.
3318
3319 mkdir directory_name
3320 The mkdir command creates the directory named by the di‐
3321 rectory_name operand.
3322
3323 mtime date file
3324 The mtime command sets the last modification time of the
3325 file named by the file operand. The <date expression> can
3326 be all sorts of date strings, see the curl_getdate(3) man
3327 page for date expression details. (Added in 7.73.0)
3328
3329 pwd The pwd command returns the absolute pathname of the cur‐
3330 rent working directory.
3331
3332 rename source target
3333 The rename command renames the file or directory named by
3334 the source operand to the destination path named by the
3335 target operand.
3336
3337 rm file
3338 The rm command removes the file specified by the file op‐
3339 erand.
3340
3341 rmdir directory
3342 The rmdir command removes the directory entry specified
3343 by the directory operand, provided it is empty.
3344
3345 symlink source_file target_file
3346 See ln.
3347
3348 Example:
3349 curl --quote "DELE file" ftp://example.com/foo
3350
3351 See also -X, --request.
3352
3353 --random-file <file>
3354 Deprecated option. This option is ignored by curl since 7.84.0.
3355 Prior to that it only had an effect on curl if built to use old
3356 versions of OpenSSL.
3357
3358 Specify the path name to file containing what will be considered
3359 as random data. The data may be used to seed the random engine
3360 for SSL connections.
3361
3362 Example:
3363 curl --random-file rubbish https://example.com
3364
3365 See also --egd-file.
3366
3367 -r, --range <range>
3368 (HTTP FTP SFTP FILE) Retrieve a byte range (i.e. a partial docu‐
3369 ment) from an HTTP/1.1, FTP or SFTP server or a local FILE.
3370 Ranges can be specified in a number of ways.
3371
3372 0-499 specifies the first 500 bytes
3373
3374 500-999 specifies the second 500 bytes
3375
3376 -500 specifies the last 500 bytes
3377
3378 9500- specifies the bytes from offset 9500 and forward
3379
3380 0-0,-1 specifies the first and last byte only(*)(HTTP)
3381
3382 100-199,500-599
3383 specifies two separate 100-byte ranges(*) (HTTP)
3384
3385 (*) = NOTE that this will cause the server to reply with a mul‐
3386 tipart response, which will be returned as-is by curl! Parsing
3387 or otherwise transforming this response is the responsibility of
3388 the caller.
3389
3390 Only digit characters (0-9) are valid in the 'start' and 'stop'
3391 fields of the 'start-stop' range syntax. If a non-digit charac‐
3392 ter is given in the range, the server's response will be unspec‐
3393 ified, depending on the server's configuration.
3394
3395 You should also be aware that many HTTP/1.1 servers do not have
3396 this feature enabled, so that when you attempt to get a range,
3397 you will instead get the whole document.
3398
3399 FTP and SFTP range downloads only support the simple 'start-
3400 stop' syntax (optionally with one of the numbers omitted). FTP
3401 use depends on the extended FTP command SIZE.
3402
3403 If this option is used several times, the last one will be used.
3404
3405 Example:
3406 curl --range 22-44 https://example.com
3407
3408 See also -C, --continue-at and -a, --append.
3409
3410 --rate <max request rate>
3411 Specify the maximum transfer frequency you allow curl to use -
3412 in number of transfer starts per time unit (sometimes called re‐
3413 quest rate). Without this option, curl will start the next
3414 transfer as fast as possible.
3415
3416 If given several URLs and a transfer completes faster than the
3417 allowed rate, curl will wait until the next transfer is started
3418 to maintain the requested rate. This option has no effect when
3419 --parallel is used.
3420
3421 The request rate is provided as "N/U" where N is an integer num‐
3422 ber and U is a time unit. Supported units are 's' (second), 'm'
3423 (minute), 'h' (hour) and 'd' /(day, as in a 24 hour unit). The
3424 default time unit, if no "/U" is provided, is number of trans‐
3425 fers per hour.
3426
3427 If curl is told to allow 10 requests per minute, it will not
3428 start the next request until 6 seconds have elapsed since the
3429 previous transfer was started.
3430
3431 This function uses millisecond resolution. If the allowed fre‐
3432 quency is set more than 1000 per second, it will instead run un‐
3433 restricted.
3434
3435 When retrying transfers, enabled with --retry, the separate
3436 retry delay logic is used and not this setting.
3437
3438 If this option is used several times, the last one will be used.
3439
3440 Examples:
3441 curl --rate 2/s https://example.com
3442 curl --rate 3/h https://example.com
3443 curl --rate 14/m https://example.com
3444
3445 See also --limit-rate and --retry-delay. Added in 7.84.0.
3446
3447 --raw (HTTP) When used, it disables all internal HTTP decoding of con‐
3448 tent or transfer encodings and instead makes them passed on un‐
3449 altered, raw.
3450
3451 Example:
3452 curl --raw https://example.com
3453
3454 See also --tr-encoding.
3455
3456 -e, --referer <URL>
3457 (HTTP) Sends the "Referrer Page" information to the HTTP server.
3458 This can also be set with the --header flag of course. When used
3459 with --location you can append ";auto" to the --referer URL to
3460 make curl automatically set the previous URL when it follows a
3461 Location: header. The ";auto" string can be used alone, even if
3462 you do not set an initial -e, --referer.
3463
3464 If this option is used several times, the last one will be used.
3465
3466 Examples:
3467 curl --referer "https://fake.example" https://example.com
3468 curl --referer "https://fake.example;auto" -L https://example.com
3469 curl --referer ";auto" -L https://example.com
3470
3471 See also -A, --user-agent and -H, --header.
3472
3473 -J, --remote-header-name
3474 (HTTP) This option tells the --remote-name option to use the
3475 server-specified Content-Disposition filename instead of ex‐
3476 tracting a filename from the URL. If the server-provided file
3477 name contains a path, that will be stripped off before the file
3478 name is used.
3479
3480 The file is saved in the current directory, or in the directory
3481 specified with --output-dir.
3482
3483 If the server specifies a file name and a file with that name
3484 already exists in the destination directory, it will not be
3485 overwritten and an error will occur. If the server does not
3486 specify a file name then this option has no effect.
3487
3488 There's no attempt to decode %-sequences (yet) in the provided
3489 file name, so this option may provide you with rather unexpected
3490 file names.
3491
3492 WARNING: Exercise judicious use of this option, especially on
3493 Windows. A rogue server could send you the name of a DLL or
3494 other file that could be loaded automatically by Windows or some
3495 third party software.
3496
3497 Example:
3498 curl -OJ https://example.com/file
3499
3500 See also -O, --remote-name.
3501
3502 --remote-name-all
3503 This option changes the default action for all given URLs to be
3504 dealt with as if --remote-name were used for each one. So if you
3505 want to disable that for a specific URL after --remote-name-all
3506 has been used, you must use "-o -" or --no-remote-name.
3507
3508 Example:
3509 curl --remote-name-all ftp://example.com/file1 ftp://example.com/file2
3510
3511 See also -O, --remote-name.
3512
3513 -O, --remote-name
3514 Write output to a local file named like the remote file we get.
3515 (Only the file part of the remote file is used, the path is cut
3516 off.)
3517
3518 The file will be saved in the current working directory. If you
3519 want the file saved in a different directory, make sure you
3520 change the current working directory before invoking curl with
3521 this option or use --output-dir.
3522
3523 The remote file name to use for saving is extracted from the
3524 given URL, nothing else, and if it already exists it will be
3525 overwritten. If you want the server to be able to choose the
3526 file name refer to --remote-header-name which can be used in ad‐
3527 dition to this option. If the server chooses a file name and
3528 that name already exists it will not be overwritten.
3529
3530 There is no URL decoding done on the file name. If it has %20 or
3531 other URL encoded parts of the name, they will end up as-is as
3532 file name.
3533
3534 You may use this option as many times as the number of URLs you
3535 have.
3536
3537 Example:
3538 curl -O https://example.com/filename
3539
3540 See also --remote-name-all, --output-dir and -J, --remote-
3541 header-name.
3542
3543 -R, --remote-time
3544 When used, this will make curl attempt to figure out the time‐
3545 stamp of the remote file, and if that is available make the lo‐
3546 cal file get that same timestamp.
3547
3548 Example:
3549 curl --remote-time -o foo https://example.com
3550
3551 See also -O, --remote-name and -z, --time-cond.
3552
3553 --remove-on-error
3554 When curl returns an error when told to save output in a local
3555 file, this option removes that saved file before exiting. This
3556 prevents curl from leaving a partial file in the case of an er‐
3557 ror during transfer.
3558
3559 If the output is not a file, this option has no effect.
3560
3561 Example:
3562 curl --remove-on-error -o output https://example.com
3563
3564 See also -f, --fail. Added in 7.83.0.
3565
3566 --request-target <path>
3567 (HTTP) Tells curl to use an alternative "target" (path) instead
3568 of using the path as provided in the URL. Particularly useful
3569 when wanting to issue HTTP requests without leading slash or
3570 other data that does not follow the regular URL pattern, like
3571 "OPTIONS *".
3572
3573 Example:
3574 curl --request-target "*" -X OPTIONS https://example.com
3575
3576 See also -X, --request. Added in 7.55.0.
3577
3578 -X, --request <method>
3579 (HTTP) Specifies a custom request method to use when communicat‐
3580 ing with the HTTP server. The specified request method will be
3581 used instead of the method otherwise used (which defaults to
3582 GET). Read the HTTP 1.1 specification for details and explana‐
3583 tions. Common additional HTTP requests include PUT and DELETE,
3584 but related technologies like WebDAV offers PROPFIND, COPY, MOVE
3585 and more.
3586
3587 Normally you do not need this option. All sorts of GET, HEAD,
3588 POST and PUT requests are rather invoked by using dedicated com‐
3589 mand line options.
3590
3591 This option only changes the actual word used in the HTTP re‐
3592 quest, it does not alter the way curl behaves. So for example if
3593 you want to make a proper HEAD request, using -X HEAD will not
3594 suffice. You need to use the --head option.
3595
3596 The method string you set with --request will be used for all
3597 requests, which if you for example use --location may cause un‐
3598 intended side-effects when curl does not change request method
3599 according to the HTTP 30x response codes - and similar.
3600
3601 (FTP) Specifies a custom FTP command to use instead of LIST when
3602 doing file lists with FTP.
3603
3604 (POP3) Specifies a custom POP3 command to use instead of LIST or
3605 RETR.
3606
3607
3608 (IMAP) Specifies a custom IMAP command to use instead of LIST.
3609 (Added in 7.30.0)
3610
3611 (SMTP) Specifies a custom SMTP command to use instead of HELP or
3612 VRFY. (Added in 7.34.0)
3613
3614 If this option is used several times, the last one will be used.
3615
3616 Examples:
3617 curl -X "DELETE" https://example.com
3618 curl -X NLST ftp://example.com/
3619
3620 See also --request-target.
3621
3622 --resolve <[+]host:port:addr[,addr]...>
3623 Provide a custom address for a specific host and port pair. Us‐
3624 ing this, you can make the curl requests(s) use a specified ad‐
3625 dress and prevent the otherwise normally resolved address to be
3626 used. Consider it a sort of /etc/hosts alternative provided on
3627 the command line. The port number should be the number used for
3628 the specific protocol the host will be used for. It means you
3629 need several entries if you want to provide address for the same
3630 host but different ports.
3631
3632 By specifying '*' as host you can tell curl to resolve any host
3633 and specific port pair to the specified address. Wildcard is re‐
3634 solved last so any --resolve with a specific host and port will
3635 be used first.
3636
3637 The provided address set by this option will be used even if
3638 --ipv4 or --ipv6 is set to make curl use another IP version.
3639
3640 By prefixing the host with a '+' you can make the entry time out
3641 after curl's default timeout (1 minute). Note that this will
3642 only make sense for long running parallel transfers with a lot
3643 of files. In such cases, if this option is used curl will try to
3644 resolve the host as it normally would once the timeout has ex‐
3645 pired.
3646
3647 Support for providing the IP address within [brackets] was added
3648 in 7.57.0.
3649
3650 Support for providing multiple IP addresses per entry was added
3651 in 7.59.0.
3652
3653 Support for resolving with wildcard was added in 7.64.0.
3654
3655 Support for the '+' prefix was was added in 7.75.0.
3656
3657 This option can be used many times to add many host names to re‐
3658 solve.
3659
3660 Example:
3661 curl --resolve example.com:443:127.0.0.1 https://example.com
3662
3663 See also --connect-to and --alt-svc.
3664
3665 --retry-all-errors
3666 Retry on any error. This option is used together with --retry.
3667
3668 This option is the "sledgehammer" of retrying. Do not use this
3669 option by default (eg in curlrc), there may be unintended conse‐
3670 quences such as sending or receiving duplicate data. Do not use
3671 with redirected input or output. You'd be much better off han‐
3672 dling your unique problems in shell script. Please read the ex‐
3673 ample below.
3674
3675 WARNING: For server compatibility curl attempts to retry failed
3676 flaky transfers as close as possible to how they were started,
3677 but this is not possible with redirected input or output. For
3678 example, before retrying it removes output data from a failed
3679 partial transfer that was written to an output file. However
3680 this is not true of data redirected to a | pipe or > file, which
3681 are not reset. We strongly suggest you do not parse or record
3682 output via redirect in combination with this option, since you
3683 may receive duplicate data.
3684
3685 By default curl will not error on an HTTP response code that in‐
3686 dicates an HTTP error, if the transfer was successful. For exam‐
3687 ple, if a server replies 404 Not Found and the reply is fully
3688 received then that is not an error. When --retry is used then
3689 curl will retry on some HTTP response codes that indicate tran‐
3690 sient HTTP errors, but that does not include most 4xx response
3691 codes such as 404. If you want to retry on all response codes
3692 that indicate HTTP errors (4xx and 5xx) then combine with -f,
3693 --fail.
3694
3695 Example:
3696 curl --retry 5 --retry-all-errors https://example.com
3697
3698 See also --retry. Added in 7.71.0.
3699
3700 --retry-connrefused
3701 In addition to the other conditions, consider ECONNREFUSED as a
3702 transient error too for --retry. This option is used together
3703 with --retry.
3704
3705 Example:
3706 curl --retry-connrefused --retry https://example.com
3707
3708 See also --retry and --retry-all-errors. Added in 7.52.0.
3709
3710 --retry-delay <seconds>
3711 Make curl sleep this amount of time before each retry when a
3712 transfer has failed with a transient error (it changes the de‐
3713 fault backoff time algorithm between retries). This option is
3714 only interesting if --retry is also used. Setting this delay to
3715 zero will make curl use the default backoff time.
3716
3717 If this option is used several times, the last one will be used.
3718
3719 Example:
3720 curl --retry-delay 5 --retry https://example.com
3721
3722 See also --retry.
3723
3724 --retry-max-time <seconds>
3725 The retry timer is reset before the first transfer attempt. Re‐
3726 tries will be done as usual (see --retry) as long as the timer
3727 has not reached this given limit. Notice that if the timer has
3728 not reached the limit, the request will be made and while per‐
3729 forming, it may take longer than this given time period. To
3730 limit a single request's maximum time, use -m, --max-time. Set
3731 this option to zero to not timeout retries.
3732
3733 If this option is used several times, the last one will be used.
3734
3735 Example:
3736 curl --retry-max-time 30 --retry 10 https://example.com
3737
3738 See also --retry.
3739
3740 --retry <num>
3741 If a transient error is returned when curl tries to perform a
3742 transfer, it will retry this number of times before giving up.
3743 Setting the number to 0 makes curl do no retries (which is the
3744 default). Transient error means either: a timeout, an FTP 4xx
3745 response code or an HTTP 408, 429, 500, 502, 503 or 504 response
3746 code.
3747
3748 When curl is about to retry a transfer, it will first wait one
3749 second and then for all forthcoming retries it will double the
3750 waiting time until it reaches 10 minutes which then will be the
3751 delay between the rest of the retries. By using --retry-delay
3752 you disable this exponential backoff algorithm. See also
3753 --retry-max-time to limit the total time allowed for retries.
3754
3755 Since curl 7.66.0, curl will comply with the Retry-After: re‐
3756 sponse header if one was present to know when to issue the next
3757 retry.
3758
3759 If this option is used several times, the last one will be used.
3760
3761 Example:
3762 curl --retry 7 https://example.com
3763
3764 See also --retry-max-time.
3765
3766 --sasl-authzid <identity>
3767 Use this authorization identity (authzid), during SASL PLAIN au‐
3768 thentication, in addition to the authentication identity (auth‐
3769 cid) as specified by -u, --user.
3770
3771 If the option is not specified, the server will derive the au‐
3772 thzid from the authcid, but if specified, and depending on the
3773 server implementation, it may be used to access another user's
3774 inbox, that the user has been granted access to, or a shared
3775 mailbox for example.
3776
3777 Example:
3778 curl --sasl-authzid zid imap://example.com/
3779
3780 See also --login-options. Added in 7.66.0.
3781
3782 --sasl-ir
3783 Enable initial response in SASL authentication.
3784
3785 Example:
3786 curl --sasl-ir imap://example.com/
3787
3788 See also --sasl-authzid. Added in 7.31.0.
3789
3790 --service-name <name>
3791 This option allows you to change the service name for SPNEGO.
3792
3793 Examples: --negotiate --service-name sockd would use
3794 sockd/server-name.
3795
3796 Example:
3797 curl --service-name sockd/server https://example.com
3798
3799 See also --negotiate and --proxy-service-name. Added in 7.43.0.
3800
3801 -S, --show-error
3802 When used with -s, --silent, it makes curl show an error message
3803 if it fails.
3804
3805 This option is global and does not need to be specified for each
3806 use of -:, --next.
3807
3808 Example:
3809 curl --show-error --silent https://example.com
3810
3811 See also --no-progress-meter.
3812
3813 -s, --silent
3814 Silent or quiet mode. Do not show progress meter or error mes‐
3815 sages. Makes Curl mute. It will still output the data you ask
3816 for, potentially even to the terminal/stdout unless you redirect
3817 it.
3818
3819 Use --show-error in addition to this option to disable progress
3820 meter but still show error messages.
3821
3822 Example:
3823 curl -s https://example.com
3824
3825 See also -v, --verbose, --stderr and --no-progress-meter.
3826
3827 --socks4 <host[:port]>
3828 Use the specified SOCKS4 proxy. If the port number is not speci‐
3829 fied, it is assumed at port 1080. Using this socket type make
3830 curl resolve the host name and passing the address on to the
3831 proxy.
3832
3833 To specify proxy on a unix domain socket, use localhost for
3834 host, e.g. socks4://localhost/path/to/socket.sock
3835
3836 This option overrides any previous use of -x, --proxy, as they
3837 are mutually exclusive.
3838
3839 This option is superfluous since you can specify a socks4 proxy
3840 with --proxy using a socks4:// protocol prefix.
3841
3842 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
3843 the same time --proxy is used with an HTTP/HTTPS proxy. In such
3844 a case curl first connects to the SOCKS proxy and then connects
3845 (through SOCKS) to the HTTP or HTTPS proxy.
3846
3847 If this option is used several times, the last one will be used.
3848
3849 Example:
3850 curl --socks4 hostname:4096 https://example.com
3851
3852 See also --socks4a, --socks5 and --socks5-hostname.
3853
3854 --socks4a <host[:port]>
3855 Use the specified SOCKS4a proxy. If the port number is not spec‐
3856 ified, it is assumed at port 1080. This asks the proxy to re‐
3857 solve the host name.
3858
3859 To specify proxy on a unix domain socket, use localhost for
3860 host, e.g. socks4a://localhost/path/to/socket.sock
3861
3862 This option overrides any previous use of -x, --proxy, as they
3863 are mutually exclusive.
3864
3865 This option is superfluous since you can specify a socks4a proxy
3866 with --proxy using a socks4a:// protocol prefix.
3867
3868 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
3869 the same time --proxy is used with an HTTP/HTTPS proxy. In such
3870 a case curl first connects to the SOCKS proxy and then connects
3871 (through SOCKS) to the HTTP or HTTPS proxy.
3872
3873 If this option is used several times, the last one will be used.
3874
3875 Example:
3876 curl --socks4a hostname:4096 https://example.com
3877
3878 See also --socks4, --socks5 and --socks5-hostname.
3879
3880 --socks5-basic
3881 Tells curl to use username/password authentication when connect‐
3882 ing to a SOCKS5 proxy. The username/password authentication is
3883 enabled by default. Use --socks5-gssapi to force GSS-API au‐
3884 thentication to SOCKS5 proxies.
3885
3886 Example:
3887 curl --socks5-basic --socks5 hostname:4096 https://example.com
3888
3889 See also --socks5. Added in 7.55.0.
3890
3891 --socks5-gssapi-nec
3892 As part of the GSS-API negotiation a protection mode is negoti‐
3893 ated. RFC 1961 says in section 4.3/4.4 it should be protected,
3894 but the NEC reference implementation does not. The option
3895 --socks5-gssapi-nec allows the unprotected exchange of the pro‐
3896 tection mode negotiation.
3897
3898 Example:
3899 curl --socks5-gssapi-nec --socks5 hostname:4096 https://example.com
3900
3901 See also --socks5.
3902
3903 --socks5-gssapi-service <name>
3904 The default service name for a socks server is rcmd/server-fqdn.
3905 This option allows you to change it.
3906
3907 Examples: --socks5 proxy-name --socks5-gssapi-service sockd
3908 would use sockd/proxy-name --socks5 proxy-name --socks5-gssapi-
3909 service sockd/real-name would use sockd/real-name for cases
3910 where the proxy-name does not match the principal name.
3911
3912 Example:
3913 curl --socks5-gssapi-service sockd --socks5 hostname:4096 https://example.com
3914
3915 See also --socks5.
3916
3917 --socks5-gssapi
3918 Tells curl to use GSS-API authentication when connecting to a
3919 SOCKS5 proxy. The GSS-API authentication is enabled by default
3920 (if curl is compiled with GSS-API support). Use --socks5-basic
3921 to force username/password authentication to SOCKS5 proxies.
3922
3923 Example:
3924 curl --socks5-gssapi --socks5 hostname:4096 https://example.com
3925
3926 See also --socks5. Added in 7.55.0.
3927
3928 --socks5-hostname <host[:port]>
3929 Use the specified SOCKS5 proxy (and let the proxy resolve the
3930 host name). If the port number is not specified, it is assumed
3931 at port 1080.
3932
3933 To specify proxy on a unix domain socket, use localhost for
3934 host, e.g. socks5h://localhost/path/to/socket.sock
3935
3936 This option overrides any previous use of -x, --proxy, as they
3937 are mutually exclusive.
3938
3939 This option is superfluous since you can specify a socks5 host‐
3940 name proxy with --proxy using a socks5h:// protocol prefix.
3941
3942 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
3943 the same time --proxy is used with an HTTP/HTTPS proxy. In such
3944 a case curl first connects to the SOCKS proxy and then connects
3945 (through SOCKS) to the HTTP or HTTPS proxy.
3946
3947 If this option is used several times, the last one will be used.
3948
3949 Example:
3950 curl --socks5-hostname proxy.example:7000 https://example.com
3951
3952 See also --socks5 and --socks4a.
3953
3954 --socks5 <host[:port]>
3955 Use the specified SOCKS5 proxy - but resolve the host name lo‐
3956 cally. If the port number is not specified, it is assumed at
3957 port 1080.
3958
3959 To specify proxy on a unix domain socket, use localhost for
3960 host, e.g. socks5://localhost/path/to/socket.sock
3961
3962 This option overrides any previous use of -x, --proxy, as they
3963 are mutually exclusive.
3964
3965 This option is superfluous since you can specify a socks5 proxy
3966 with --proxy using a socks5:// protocol prefix.
3967
3968 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
3969 the same time --proxy is used with an HTTP/HTTPS proxy. In such
3970 a case curl first connects to the SOCKS proxy and then connects
3971 (through SOCKS) to the HTTP or HTTPS proxy.
3972
3973 If this option is used several times, the last one will be used.
3974
3975 This option (as well as --socks4) does not work with IPV6, FTPS
3976 or LDAP.
3977
3978 Example:
3979 curl --socks5 proxy.example:7000 https://example.com
3980
3981 See also --socks5-hostname and --socks4a.
3982
3983 -Y, --speed-limit <speed>
3984 If a transfer is slower than this given speed (in bytes per sec‐
3985 ond) for speed-time seconds it gets aborted. speed-time is set
3986 with --speed-time and is 30 if not set.
3987
3988 If this option is used several times, the last one will be used.
3989
3990 Example:
3991 curl --speed-limit 300 --speed-time 10 https://example.com
3992
3993 See also -y, --speed-time, --limit-rate and -m, --max-time.
3994
3995 -y, --speed-time <seconds>
3996 If a transfer runs slower than speed-limit bytes per second dur‐
3997 ing a speed-time period, the transfer is aborted. If speed-time
3998 is used, the default speed-limit will be 1 unless set with -Y,
3999 --speed-limit.
4000
4001 This option controls transfers (in both directions) but will not
4002 affect slow connects etc. If this is a concern for you, try the
4003 --connect-timeout option.
4004
4005 If this option is used several times, the last one will be used.
4006
4007 Example:
4008 curl --speed-limit 300 --speed-time 10 https://example.com
4009
4010 See also -Y, --speed-limit and --limit-rate.
4011
4012 --ssl-allow-beast
4013 This option tells curl to not work around a security flaw in the
4014 SSL3 and TLS1.0 protocols known as BEAST. If this option is not
4015 used, the SSL layer may use workarounds known to cause interop‐
4016 erability problems with some older SSL implementations.
4017
4018 WARNING: this option loosens the SSL security, and by using this
4019 flag you ask for exactly that.
4020
4021 Example:
4022 curl --ssl-allow-beast https://example.com
4023
4024 See also --proxy-ssl-allow-beast and -k, --insecure.
4025
4026 --ssl-auto-client-cert
4027 Tell libcurl to automatically locate and use a client certifi‐
4028 cate for authentication, when requested by the server. This op‐
4029 tion is only supported for Schannel (the native Windows SSL li‐
4030 brary). Prior to 7.77.0 this was the default behavior in libcurl
4031 with Schannel. Since the server can request any certificate that
4032 supports client authentication in the OS certificate store it
4033 could be a privacy violation and unexpected.
4034
4035 Example:
4036 curl --ssl-auto-client-cert https://example.com
4037
4038 See also --proxy-ssl-auto-client-cert. Added in 7.77.0.
4039
4040 --ssl-no-revoke
4041 (Schannel) This option tells curl to disable certificate revoca‐
4042 tion checks. WARNING: this option loosens the SSL security, and
4043 by using this flag you ask for exactly that.
4044
4045 Example:
4046 curl --ssl-no-revoke https://example.com
4047
4048 See also --crlfile. Added in 7.44.0.
4049
4050 --ssl-reqd
4051 (FTP IMAP POP3 SMTP LDAP) Require SSL/TLS for the connection.
4052 Terminates the connection if the server does not support
4053 SSL/TLS.
4054
4055 This option is handled in LDAP since version 7.81.0. It is fully
4056 supported by the openldap backend and rejected by the generic
4057 ldap backend if explicit TLS is required.
4058
4059 This option was formerly known as --ftp-ssl-reqd.
4060
4061 Example:
4062 curl --ssl-reqd ftp://example.com
4063
4064 See also --ssl and -k, --insecure.
4065
4066 --ssl-revoke-best-effort
4067 (Schannel) This option tells curl to ignore certificate revoca‐
4068 tion checks when they failed due to missing/offline distribution
4069 points for the revocation check lists.
4070
4071 Example:
4072 curl --ssl-revoke-best-effort https://example.com
4073
4074 See also --crlfile and -k, --insecure. Added in 7.70.0.
4075
4076 --ssl (FTP IMAP POP3 SMTP LDAP) Try to use SSL/TLS for the connection.
4077 Reverts to a non-secure connection if the server does not sup‐
4078 port SSL/TLS. See also --ftp-ssl-control and --ssl-reqd for dif‐
4079 ferent levels of encryption required.
4080
4081 This option is handled in LDAP since version 7.81.0. It is fully
4082 supported by the openldap backend and ignored by the generic
4083 ldap backend.
4084
4085 Please note that a server may close the connection if the nego‐
4086 tiation does not succeed.
4087
4088 This option was formerly known as --ftp-ssl. That option name
4089 can still be used but will be removed in a future version.
4090
4091 Example:
4092 curl --ssl pop3://example.com/
4093
4094 See also -k, --insecure and --ciphers.
4095
4096 -2, --sslv2
4097 (SSL) This option previously asked curl to use SSLv2, but start‐
4098 ing in curl 7.77.0 this instruction is ignored. SSLv2 is widely
4099 considered insecure (see RFC 6176).
4100
4101 Example:
4102 curl --sslv2 https://example.com
4103
4104 See also --http1.1 and --http2. -2, --sslv2 requires that the
4105 underlying libcurl was built to support TLS. This option is mu‐
4106 tually exclusive to -3, --sslv3 and -1, --tlsv1 and --tlsv1.1
4107 and --tlsv1.2.
4108
4109 -3, --sslv3
4110 (SSL) This option previously asked curl to use SSLv3, but start‐
4111 ing in curl 7.77.0 this instruction is ignored. SSLv3 is widely
4112 considered insecure (see RFC 7568).
4113
4114 Example:
4115 curl --sslv3 https://example.com
4116
4117 See also --http1.1 and --http2. -3, --sslv3 requires that the
4118 underlying libcurl was built to support TLS. This option is mu‐
4119 tually exclusive to -2, --sslv2 and -1, --tlsv1 and --tlsv1.1
4120 and --tlsv1.2.
4121
4122 --stderr <file>
4123 Redirect all writes to stderr to the specified file instead. If
4124 the file name is a plain '-', it is instead written to stdout.
4125
4126 This option is global and does not need to be specified for each
4127 use of -:, --next.
4128
4129 If this option is used several times, the last one will be used.
4130
4131 Example:
4132 curl --stderr output.txt https://example.com
4133
4134 See also -v, --verbose and -s, --silent.
4135
4136 --styled-output
4137 Enables the automatic use of bold font styles when writing HTTP
4138 headers to the terminal. Use --no-styled-output to switch them
4139 off.
4140
4141 This option is global and does not need to be specified for each
4142 use of -:, --next.
4143
4144 Example:
4145 curl --styled-output -I https://example.com
4146
4147 See also -I, --head and -v, --verbose. Added in 7.61.0.
4148
4149 --suppress-connect-headers
4150 When --proxytunnel is used and a CONNECT request is made do not
4151 output proxy CONNECT response headers. This option is meant to
4152 be used with --dump-header or --include which are used to show
4153 protocol headers in the output. It has no effect on debug op‐
4154 tions such as --verbose or --trace, or any statistics.
4155
4156 Example:
4157 curl --suppress-connect-headers --include -x proxy https://example.com
4158
4159 See also -D, --dump-header, -i, --include and -p, --proxytunnel.
4160 Added in 7.54.0.
4161
4162 --tcp-fastopen
4163 Enable use of TCP Fast Open (RFC7413).
4164
4165 Example:
4166 curl --tcp-fastopen https://example.com
4167
4168 See also --false-start. Added in 7.49.0.
4169
4170 --tcp-nodelay
4171 Turn on the TCP_NODELAY option. See the curl_easy_setopt(3) man
4172 page for details about this option.
4173
4174 Since 7.50.2, curl sets this option by default and you need to
4175 explicitly switch it off if you do not want it on.
4176
4177 Example:
4178 curl --tcp-nodelay https://example.com
4179
4180 See also -N, --no-buffer.
4181
4182 -t, --telnet-option <opt=val>
4183 Pass options to the telnet protocol. Supported options are:
4184
4185 TTYPE=<term> Sets the terminal type.
4186
4187 XDISPLOC=<X display> Sets the X display location.
4188
4189 NEW_ENV=<var,val> Sets an environment variable.
4190
4191 Example:
4192 curl -t TTYPE=vt100 telnet://example.com/
4193
4194 See also -K, --config.
4195
4196 --tftp-blksize <value>
4197 (TFTP) Set TFTP BLKSIZE option (must be >512). This is the block
4198 size that curl will try to use when transferring data to or from
4199 a TFTP server. By default 512 bytes will be used.
4200
4201 If this option is used several times, the last one will be used.
4202
4203 Example:
4204 curl --tftp-blksize 1024 tftp://example.com/file
4205
4206 See also --tftp-no-options.
4207
4208 --tftp-no-options
4209 (TFTP) Tells curl not to send TFTP options requests.
4210
4211 This option improves interop with some legacy servers that do
4212 not acknowledge or properly implement TFTP options. When this
4213 option is used --tftp-blksize is ignored.
4214
4215 Example:
4216 curl --tftp-no-options tftp://192.168.0.1/
4217
4218 See also --tftp-blksize. Added in 7.48.0.
4219
4220 -z, --time-cond <time>
4221 (HTTP FTP) Request a file that has been modified later than the
4222 given time and date, or one that has been modified before that
4223 time. The <date expression> can be all sorts of date strings or
4224 if it does not match any internal ones, it is taken as a file‐
4225 name and tries to get the modification date (mtime) from <file>
4226 instead. See the curl_getdate(3) man pages for date expression
4227 details.
4228
4229 Start the date expression with a dash (-) to make it request for
4230 a document that is older than the given date/time, default is a
4231 document that is newer than the specified date/time.
4232
4233 If this option is used several times, the last one will be used.
4234
4235 Examples:
4236 curl -z "Wed 01 Sep 2021 12:18:00" https://example.com
4237 curl -z "-Wed 01 Sep 2021 12:18:00" https://example.com
4238 curl -z file https://example.com
4239
4240 See also --etag-compare and -R, --remote-time.
4241
4242 --tls-max <VERSION>
4243 (SSL) VERSION defines maximum supported TLS version. The minimum
4244 acceptable version is set by tlsv1.0, tlsv1.1, tlsv1.2 or
4245 tlsv1.3.
4246
4247 If the connection is done without TLS, this option has no ef‐
4248 fect. This includes QUIC-using (HTTP/3) transfers.
4249
4250
4251 default
4252 Use up to recommended TLS version.
4253
4254 1.0 Use up to TLSv1.0.
4255
4256 1.1 Use up to TLSv1.1.
4257
4258 1.2 Use up to TLSv1.2.
4259
4260 1.3 Use up to TLSv1.3.
4261
4262 Examples:
4263 curl --tls-max 1.2 https://example.com
4264 curl --tls-max 1.3 --tlsv1.2 https://example.com
4265
4266 See also --tlsv1.0, --tlsv1.1, --tlsv1.2 and --tlsv1.3. --tls-max re‐
4267 quires that the underlying libcurl was built to support TLS. Added in
4268 7.54.0.
4269
4270 --tls13-ciphers <ciphersuite list>
4271 (TLS) Specifies which cipher suites to use in the connection if
4272 it negotiates TLS 1.3. The list of ciphers suites must specify
4273 valid ciphers. Read up on TLS 1.3 cipher suite details on this
4274 URL:
4275
4276 https://curl.se/docs/ssl-ciphers.html
4277
4278 This option is currently used only when curl is built to use
4279 OpenSSL 1.1.1 or later. If you are using a different SSL backend
4280 you can try setting TLS 1.3 cipher suites by using the --ciphers
4281 option.
4282
4283 If this option is used several times, the last one will be used.
4284
4285 Example:
4286 curl --tls13-ciphers TLS_AES_128_GCM_SHA256 https://example.com
4287
4288 See also --ciphers and --curves. Added in 7.61.0.
4289
4290 --tlsauthtype <type>
4291 Set TLS authentication type. Currently, the only supported op‐
4292 tion is "SRP", for TLS-SRP (RFC 5054). If --tlsuser and
4293 --tlspassword are specified but --tlsauthtype is not, then this
4294 option defaults to "SRP". This option works only if the underly‐
4295 ing libcurl is built with TLS-SRP support, which requires
4296 OpenSSL or GnuTLS with TLS-SRP support.
4297
4298 Example:
4299 curl --tlsauthtype SRP https://example.com
4300
4301 See also --tlsuser.
4302
4303 --tlspassword <string>
4304 Set password for use with the TLS authentication method speci‐
4305 fied with --tlsauthtype. Requires that --tlsuser also be set.
4306
4307 This option does not work with TLS 1.3.
4308
4309 Example:
4310 curl --tlspassword pwd --tlsuser user https://example.com
4311
4312 See also --tlsuser.
4313
4314 --tlsuser <name>
4315 Set username for use with the TLS authentication method speci‐
4316 fied with --tlsauthtype. Requires that --tlspassword also is
4317 set.
4318
4319 This option does not work with TLS 1.3.
4320
4321 Example:
4322 curl --tlspassword pwd --tlsuser user https://example.com
4323
4324 See also --tlspassword.
4325
4326 --tlsv1.0
4327 (TLS) Forces curl to use TLS version 1.0 or later when connect‐
4328 ing to a remote TLS server.
4329
4330 In old versions of curl this option was documented to allow
4331 _only_ TLS 1.0. That behavior was inconsistent depending on the
4332 TLS library. Use --tls-max if you want to set a maximum TLS ver‐
4333 sion.
4334
4335 Example:
4336 curl --tlsv1.0 https://example.com
4337
4338 See also --tlsv1.3. Added in 7.34.0.
4339
4340 --tlsv1.1
4341 (TLS) Forces curl to use TLS version 1.1 or later when connect‐
4342 ing to a remote TLS server.
4343
4344 In old versions of curl this option was documented to allow
4345 _only_ TLS 1.1. That behavior was inconsistent depending on the
4346 TLS library. Use --tls-max if you want to set a maximum TLS ver‐
4347 sion.
4348
4349 Example:
4350 curl --tlsv1.1 https://example.com
4351
4352 See also --tlsv1.3 and --tls-max. Added in 7.34.0.
4353
4354 --tlsv1.2
4355 (TLS) Forces curl to use TLS version 1.2 or later when connect‐
4356 ing to a remote TLS server.
4357
4358 In old versions of curl this option was documented to allow
4359 _only_ TLS 1.2. That behavior was inconsistent depending on the
4360 TLS library. Use --tls-max if you want to set a maximum TLS ver‐
4361 sion.
4362
4363 Example:
4364 curl --tlsv1.2 https://example.com
4365
4366 See also --tlsv1.3 and --tls-max. Added in 7.34.0.
4367
4368 --tlsv1.3
4369 (TLS) Forces curl to use TLS version 1.3 or later when connect‐
4370 ing to a remote TLS server.
4371
4372 If the connection is done without TLS, this option has no ef‐
4373 fect. This includes QUIC-using (HTTP/3) transfers.
4374
4375 Note that TLS 1.3 is not supported by all TLS backends.
4376
4377 Example:
4378 curl --tlsv1.3 https://example.com
4379
4380 See also --tlsv1.2 and --tls-max. Added in 7.52.0.
4381
4382 -1, --tlsv1
4383 (SSL) Tells curl to use at least TLS version 1.x when negotiat‐
4384 ing with a remote TLS server. That means TLS version 1.0 or
4385 higher
4386
4387 Example:
4388 curl --tlsv1 https://example.com
4389
4390 See also --http1.1 and --http2. -1, --tlsv1 requires that the
4391 underlying libcurl was built to support TLS. This option is mu‐
4392 tually exclusive to --tlsv1.1 and --tlsv1.2 and --tlsv1.3.
4393
4394 --tr-encoding
4395 (HTTP) Request a compressed Transfer-Encoding response using one
4396 of the algorithms curl supports, and uncompress the data while
4397 receiving it.
4398
4399 Example:
4400 curl --tr-encoding https://example.com
4401
4402 See also --compressed.
4403
4404 --trace-ascii <file>
4405 Enables a full trace dump of all incoming and outgoing data, in‐
4406 cluding descriptive information, to the given output file. Use
4407 "-" as filename to have the output sent to stdout.
4408
4409 This is similar to --trace, but leaves out the hex part and only
4410 shows the ASCII part of the dump. It makes smaller output that
4411 might be easier to read for untrained humans.
4412
4413 This option is global and does not need to be specified for each
4414 use of -:, --next.
4415
4416 If this option is used several times, the last one will be used.
4417
4418 Example:
4419 curl --trace-ascii log.txt https://example.com
4420
4421 See also -v, --verbose and --trace. This option is mutually ex‐
4422 clusive to --trace and -v, --verbose.
4423
4424 --trace-time
4425 Prepends a time stamp to each trace or verbose line that curl
4426 displays.
4427
4428 This option is global and does not need to be specified for each
4429 use of -:, --next.
4430
4431 Example:
4432 curl --trace-time --trace-ascii output https://example.com
4433
4434 See also --trace and -v, --verbose.
4435
4436 --trace <file>
4437 Enables a full trace dump of all incoming and outgoing data, in‐
4438 cluding descriptive information, to the given output file. Use
4439 "-" as filename to have the output sent to stdout. Use "%" as
4440 filename to have the output sent to stderr.
4441
4442 This option is global and does not need to be specified for each
4443 use of -:, --next.
4444
4445 If this option is used several times, the last one will be used.
4446
4447 Example:
4448 curl --trace log.txt https://example.com
4449
4450 See also --trace-ascii and --trace-time. This option is mutually
4451 exclusive to -v, --verbose and --trace-ascii.
4452
4453 --unix-socket <path>
4454 (HTTP) Connect through this Unix domain socket, instead of using
4455 the network.
4456
4457 Example:
4458 curl --unix-socket socket-path https://example.com
4459
4460 See also --abstract-unix-socket. Added in 7.40.0.
4461
4462 -T, --upload-file <file>
4463 This transfers the specified local file to the remote URL. If
4464 there is no file part in the specified URL, curl will append the
4465 local file name. NOTE that you must use a trailing / on the last
4466 directory to really prove to Curl that there is no file name or
4467 curl will think that your last directory name is the remote file
4468 name to use. That will most likely cause the upload operation to
4469 fail. If this is used on an HTTP(S) server, the PUT command will
4470 be used.
4471
4472 Use the file name "-" (a single dash) to use stdin instead of a
4473 given file. Alternately, the file name "." (a single period)
4474 may be specified instead of "-" to use stdin in non-blocking
4475 mode to allow reading server output while stdin is being up‐
4476 loaded.
4477
4478 You can specify one --upload-file for each URL on the command
4479 line. Each -T, --upload-file + URL pair specifies what to upload
4480 and to where. curl also supports "globbing" of the --upload-file
4481 argument, meaning that you can upload multiple files to a single
4482 URL by using the same URL globbing style supported in the URL.
4483
4484 When uploading to an SMTP server: the uploaded data is assumed
4485 to be RFC 5322 formatted. It has to feature the necessary set of
4486 headers and mail body formatted correctly by the user as curl
4487 will not transcode nor encode it further in any way.
4488
4489 Examples:
4490 curl -T file https://example.com
4491 curl -T "img[1-1000].png" ftp://ftp.example.com/
4492 curl --upload-file "{file1,file2}" https://example.com
4493
4494 See also -G, --get and -I, --head.
4495
4496 --url <url>
4497 Specify a URL to fetch. This option is mostly handy when you
4498 want to specify URL(s) in a config file.
4499
4500 If the given URL is missing a scheme name (such as "http://" or
4501 "ftp://" etc) then curl will make a guess based on the host. If
4502 the outermost sub-domain name matches DICT, FTP, IMAP, LDAP,
4503 POP3 or SMTP then that protocol will be used, otherwise HTTP
4504 will be used. Since 7.45.0 guessing can be disabled by setting a
4505 default protocol, see --proto-default for details.
4506
4507 This option may be used any number of times. To control where
4508 this URL is written, use the --output or the --remote-name op‐
4509 tions.
4510
4511 WARNING: On Windows, particular file:// accesses can be con‐
4512 verted to network accesses by the operating system. Beware!
4513
4514 Example:
4515 curl --url https://example.com
4516
4517 See also -:, --next and -K, --config.
4518
4519 -B, --use-ascii
4520 (FTP LDAP) Enable ASCII transfer. For FTP, this can also be en‐
4521 forced by using a URL that ends with ";type=A". This option
4522 causes data sent to stdout to be in text mode for win32 systems.
4523
4524 Example:
4525 curl -B ftp://example.com/README
4526
4527 See also --crlf and --data-ascii.
4528
4529 -A, --user-agent <name>
4530 (HTTP) Specify the User-Agent string to send to the HTTP server.
4531 To encode blanks in the string, surround the string with single
4532 quote marks. This header can also be set with the --header or
4533 the --proxy-header options.
4534
4535 If you give an empty argument to -A, --user-agent (""), it will
4536 remove the header completely from the request. If you prefer a
4537 blank header, you can set it to a single space (" ").
4538
4539 If this option is used several times, the last one will be used.
4540
4541 Example:
4542 curl -A "Agent 007" https://example.com
4543
4544 See also -H, --header and --proxy-header.
4545
4546 -u, --user <user:password>
4547 Specify the user name and password to use for server authentica‐
4548 tion. Overrides --netrc and --netrc-optional.
4549
4550 If you simply specify the user name, curl will prompt for a
4551 password.
4552
4553 The user name and passwords are split up on the first colon,
4554 which makes it impossible to use a colon in the user name with
4555 this option. The password can, still.
4556
4557 On systems where it works, curl will hide the given option argu‐
4558 ment from process listings. This is not enough to protect cre‐
4559 dentials from possibly getting seen by other users on the same
4560 system as they will still be visible for a moment before
4561 cleared. Such sensitive data should be retrieved from a file in‐
4562 stead or similar and never used in clear text in a command line.
4563
4564 When using Kerberos V5 with a Windows based server you should
4565 include the Windows domain name in the user name, in order for
4566 the server to successfully obtain a Kerberos Ticket. If you do
4567 not, then the initial authentication handshake may fail.
4568
4569 When using NTLM, the user name can be specified simply as the
4570 user name, without the domain, if there is a single domain and
4571 forest in your setup for example.
4572
4573 To specify the domain name use either Down-Level Logon Name or
4574 UPN (User Principal Name) formats. For example, EXAMPLE\user and
4575 user@example.com respectively.
4576
4577 If you use a Windows SSPI-enabled curl binary and perform Ker‐
4578 beros V5, Negotiate, NTLM or Digest authentication then you can
4579 tell curl to select the user name and password from your envi‐
4580 ronment by specifying a single colon with this option: "-u :".
4581
4582 If this option is used several times, the last one will be used.
4583
4584 Example:
4585 curl -u user:secret https://example.com
4586
4587 See also -n, --netrc and -K, --config.
4588
4589 -v, --verbose
4590 Makes curl verbose during the operation. Useful for debugging
4591 and seeing what's going on "under the hood". A line starting
4592 with '>' means "header data" sent by curl, '<' means "header
4593 data" received by curl that is hidden in normal cases, and a
4594 line starting with '*' means additional info provided by curl.
4595
4596 If you only want HTTP headers in the output, --include might be
4597 the option you are looking for.
4598
4599 If you think this option still does not give you enough details,
4600 consider using --trace or --trace-ascii instead.
4601
4602 This option is global and does not need to be specified for each
4603 use of -:, --next.
4604
4605 Use --silent to make curl really quiet.
4606
4607 Example:
4608 curl --verbose https://example.com
4609
4610 See also -i, --include. This option is mutually exclusive to
4611 --trace and --trace-ascii.
4612
4613 -V, --version
4614 Displays information about curl and the libcurl version it uses.
4615
4616 The first line includes the full version of curl, libcurl and
4617 other 3rd party libraries linked with the executable.
4618
4619 The second line (starts with "Protocols:") shows all protocols
4620 that libcurl reports to support.
4621
4622 The third line (starts with "Features:") shows specific features
4623 libcurl reports to offer. Available features include:
4624
4625 alt-svc
4626 Support for the Alt-Svc: header is provided.
4627
4628 AsynchDNS
4629 This curl uses asynchronous name resolves. Asynchronous
4630 name resolves can be done using either the c-ares or the
4631 threaded resolver backends.
4632
4633 brotli Support for automatic brotli compression over HTTP(S).
4634
4635 CharConv
4636 curl was built with support for character set conversions
4637 (like EBCDIC)
4638
4639 Debug This curl uses a libcurl built with Debug. This enables
4640 more error-tracking and memory debugging etc. For curl-
4641 developers only!
4642
4643 gsasl The built-in SASL authentication includes extensions to
4644 support SCRAM because libcurl was built with libgsasl.
4645
4646 GSS-API
4647 GSS-API is supported.
4648
4649 HSTS HSTS support is present.
4650
4651 HTTP2 HTTP/2 support has been built-in.
4652
4653 HTTP3 HTTP/3 support has been built-in.
4654
4655 HTTPS-proxy
4656 This curl is built to support HTTPS proxy.
4657
4658 IDN This curl supports IDN - international domain names.
4659
4660 IPv6 You can use IPv6 with this.
4661
4662 Kerberos
4663 Kerberos V5 authentication is supported.
4664
4665 Largefile
4666 This curl supports transfers of large files, files larger
4667 than 2GB.
4668
4669 libz Automatic decompression (via gzip, deflate) of compressed
4670 files over HTTP is supported.
4671
4672 MultiSSL
4673 This curl supports multiple TLS backends.
4674
4675 NTLM NTLM authentication is supported.
4676
4677 NTLM_WB
4678 NTLM delegation to winbind helper is supported.
4679
4680 PSL PSL is short for Public Suffix List and means that this
4681 curl has been built with knowledge about "public suf‐
4682 fixes".
4683
4684 SPNEGO SPNEGO authentication is supported.
4685
4686 SSL SSL versions of various protocols are supported, such as
4687 HTTPS, FTPS, POP3S and so on.
4688
4689 SSPI SSPI is supported.
4690
4691 TLS-SRP
4692 SRP (Secure Remote Password) authentication is supported
4693 for TLS.
4694
4695 TrackMemory
4696 Debug memory tracking is supported.
4697
4698 Unicode
4699 Unicode support on Windows.
4700
4701 UnixSockets
4702 Unix sockets support is provided.
4703
4704 zstd Automatic decompression (via zstd) of compressed files
4705 over HTTP is supported.
4706
4707 Example:
4708 curl --version
4709
4710 See also -h, --help and -M, --manual.
4711
4712 -w, --write-out <format>
4713 Make curl display information on stdout after a completed trans‐
4714 fer. The format is a string that may contain plain text mixed
4715 with any number of variables. The format can be specified as a
4716 literal "string", or you can have curl read the format from a
4717 file with "@filename" and to tell curl to read the format from
4718 stdin you write "@-".
4719
4720 The variables present in the output format will be substituted
4721 by the value or text that curl thinks fit, as described below.
4722 All variables are specified as %{variable_name} and to output a
4723 normal % you just write them as %%. You can output a newline by
4724 using \n, a carriage return with \r and a tab space with \t.
4725
4726 The output will be written to standard output, but this can be
4727 switched to standard error by using %{stderr}.
4728
4729 Output HTTP headers from the most recent request by using
4730 %header{name} where name is the case insensitive name of the
4731 header (without the trailing colon). The header contents are ex‐
4732 actly as sent over the network, with leading and trailing white‐
4733 space trimmed. Added in curl 7.84.0.
4734
4735 NOTE: The %-symbol is a special symbol in the win32-environment,
4736 where all occurrences of % must be doubled when using this op‐
4737 tion.
4738
4739 The variables available are:
4740
4741 content_type The Content-Type of the requested document, if
4742 there was any.
4743
4744 errormsg The error message. (Added in 7.75.0)
4745
4746 exitcode The numerical exitcode of the transfer. (Added in
4747 7.75.0)
4748
4749 filename_effective
4750 The ultimate filename that curl writes out to.
4751 This is only meaningful if curl is told to write
4752 to a file with the --remote-name or --output op‐
4753 tion. It's most useful in combination with the
4754 --remote-header-name option.
4755
4756 ftp_entry_path The initial path curl ended up in when logging on
4757 to the remote FTP server.
4758
4759 header_json A JSON object with all HTTP response headers from
4760 the recent transfer. Values are provided as ar‐
4761 rays, since in the case of multiple headers there
4762 can be multiple values.
4763
4764 The header names provided in lowercase, listed in
4765 order of appearance over the wire. Except for du‐
4766 plicated headers. They are grouped on the first
4767 occurrence of that header, each value is pre‐
4768 sented in the JSON array.
4769
4770 http_code The numerical response code that was found in the
4771 last retrieved HTTP(S) or FTP(s) transfer.
4772
4773 http_connect The numerical code that was found in the last re‐
4774 sponse (from a proxy) to a curl CONNECT request.
4775
4776 http_version The http version that was effectively used.
4777 (Added in 7.50.0)
4778
4779 json A JSON object with all available keys.
4780
4781 local_ip The IP address of the local end of the most re‐
4782 cently done connection - can be either IPv4 or
4783 IPv6.
4784
4785 local_port The local port number of the most recently done
4786 connection.
4787
4788 method The http method used in the most recent HTTP re‐
4789 quest. (Added in 7.72.0)
4790
4791 num_connects Number of new connects made in the recent trans‐
4792 fer.
4793
4794 num_headers The number of response headers in the most recent
4795 request (restarted at each redirect). Note that
4796 the status line IS NOT a header. (Added in
4797 7.73.0)
4798
4799 num_redirects Number of redirects that were followed in the re‐
4800 quest.
4801
4802 onerror The rest of the output is only shown if the
4803 transfer returned a non-zero error (Added in
4804 7.75.0)
4805
4806 proxy_ssl_verify_result
4807 The result of the HTTPS proxy's SSL peer certifi‐
4808 cate verification that was requested. 0 means the
4809 verification was successful. (Added in 7.52.0)
4810
4811 redirect_url When an HTTP request was made without --location
4812 to follow redirects (or when --max-redirs is
4813 met), this variable will show the actual URL a
4814 redirect would have gone to.
4815
4816 referer The Referer: header, if there was any. (Added in
4817 7.76.0)
4818
4819 remote_ip The remote IP address of the most recently done
4820 connection - can be either IPv4 or IPv6.
4821
4822 remote_port The remote port number of the most recently done
4823 connection.
4824
4825 response_code The numerical response code that was found in the
4826 last transfer (formerly known as "http_code").
4827
4828 scheme The URL scheme (sometimes called protocol) that
4829 was effectively used. (Added in 7.52.0)
4830
4831 size_download The total amount of bytes that were downloaded.
4832 This is the size of the body/data that was trans‐
4833 ferred, excluding headers.
4834
4835 size_header The total amount of bytes of the downloaded head‐
4836 ers.
4837
4838 size_request The total amount of bytes that were sent in the
4839 HTTP request.
4840
4841 size_upload The total amount of bytes that were uploaded.
4842 This is the size of the body/data that was trans‐
4843 ferred, excluding headers.
4844
4845 speed_download The average download speed that curl measured for
4846 the complete download. Bytes per second.
4847
4848 speed_upload The average upload speed that curl measured for
4849 the complete upload. Bytes per second.
4850
4851 ssl_verify_result
4852 The result of the SSL peer certificate verifica‐
4853 tion that was requested. 0 means the verification
4854 was successful.
4855
4856 stderr From this point on, the --write-out output will
4857 be written to standard error. (Added in 7.63.0)
4858
4859 stdout From this point on, the --write-out output will
4860 be written to standard output. This is the de‐
4861 fault, but can be used to switch back after
4862 switching to stderr. (Added in 7.63.0)
4863
4864 time_appconnect
4865 The time, in seconds, it took from the start un‐
4866 til the SSL/SSH/etc connect/handshake to the re‐
4867 mote host was completed.
4868
4869 time_connect The time, in seconds, it took from the start un‐
4870 til the TCP connect to the remote host (or proxy)
4871 was completed.
4872
4873 time_namelookup
4874 The time, in seconds, it took from the start un‐
4875 til the name resolving was completed.
4876
4877 time_pretransfer
4878 The time, in seconds, it took from the start un‐
4879 til the file transfer was just about to begin.
4880 This includes all pre-transfer commands and nego‐
4881 tiations that are specific to the particular pro‐
4882 tocol(s) involved.
4883
4884 time_redirect The time, in seconds, it took for all redirection
4885 steps including name lookup, connect, pretransfer
4886 and transfer before the final transaction was
4887 started. time_redirect shows the complete execu‐
4888 tion time for multiple redirections.
4889
4890 time_starttransfer
4891 The time, in seconds, it took from the start un‐
4892 til the first byte was just about to be trans‐
4893 ferred. This includes time_pretransfer and also
4894 the time the server needed to calculate the re‐
4895 sult.
4896
4897 time_total The total time, in seconds, that the full opera‐
4898 tion lasted.
4899
4900 url The URL that was fetched. (Added in 7.75.0)
4901
4902 urlnum The URL index number of this transfer, 0-indexed.
4903 De-globbed URLs share the same index number as
4904 the origin globbed URL. (Added in 7.75.0)
4905
4906 url_effective The URL that was fetched last. This is most mean‐
4907 ingful if you have told curl to follow location:
4908 headers.
4909
4910 If this option is used several times, the last one will be used.
4911
4912 Example:
4913 curl -w '%{http_code}\n' https://example.com
4914
4915 See also -v, --verbose and -I, --head.
4916
4917 --xattr
4918 When saving output to a file, this option tells curl to store
4919 certain file metadata in extended file attributes. Currently,
4920 the URL is stored in the xdg.origin.url attribute and, for HTTP,
4921 the content type is stored in the mime_type attribute. If the
4922 file system does not support extended attributes, a warning is
4923 issued.
4924
4925 Example:
4926 curl --xattr -o storage https://example.com
4927
4928 See also -R, --remote-time, -w, --write-out and -v, --verbose.
4929
4931 ~/.curlrc
4932 Default config file, see --config for details.
4933
4935 The environment variables can be specified in lower case or upper case.
4936 The lower case version has precedence. http_proxy is an exception as it
4937 is only available in lower case.
4938
4939 Using an environment variable to set the proxy has the same effect as
4940 using the --proxy option.
4941
4942
4943 http_proxy [protocol://]<host>[:port]
4944 Sets the proxy server to use for HTTP.
4945
4946 HTTPS_PROXY [protocol://]<host>[:port]
4947 Sets the proxy server to use for HTTPS.
4948
4949 [url-protocol]_PROXY [protocol://]<host>[:port]
4950 Sets the proxy server to use for [url-protocol], where the pro‐
4951 tocol is a protocol that curl supports and as specified in a
4952 URL. FTP, FTPS, POP3, IMAP, SMTP, LDAP, etc.
4953
4954 ALL_PROXY [protocol://]<host>[:port]
4955 Sets the proxy server to use if no protocol-specific proxy is
4956 set.
4957
4958 NO_PROXY <comma-separated list of hosts/domains>
4959 list of host names that should not go through any proxy. If set
4960 to an asterisk '*' only, it matches all hosts. Each name in this
4961 list is matched as either a domain name which contains the host‐
4962 name, or the hostname itself.
4963
4964 This environment variable disables use of the proxy even when
4965 specified with the --proxy option. That is NO_PROXY=direct.exam‐
4966 ple.com curl -x http://proxy.example.com http://direct.exam‐
4967 ple.com accesses the target URL directly, and NO_PROXY=di‐
4968 rect.example.com curl -x http://proxy.example.com http://some‐
4969 where.example.com accesses the target URL through the proxy.
4970
4971 The list of host names can also be include numerical IP ad‐
4972 dresses, and IPv6 versions should then be given without enclos‐
4973 ing brackets.
4974
4975 IPv6 numerical addresses are compared as strings, so they will
4976 only match if the representations are the same: "::1" is the
4977 same as "::0:1" but they do not match.
4978
4979 APPDATA <dir>
4980 On Windows, this variable is used when trying to find the home
4981 directory. If the primary home variable are all unset.
4982
4983 COLUMNS <terminal width>
4984 If set, the specified number of characters will be used as the
4985 terminal width when the alternative progress-bar is shown. If
4986 not set, curl will try to figure it out using other ways.
4987
4988 CURL_CA_BUNDLE <file>
4989 If set, will be used as the --cacert value.
4990
4991 CURL_HOME <dir>
4992 If set, is the first variable curl checks when trying to find
4993 its home directory. If not set, it continues to check XDG_CON‐
4994 FIG_HOME.
4995
4996 CURL_SSL_BACKEND <TLS backend>
4997 If curl was built with support for "MultiSSL", meaning that it
4998 has built-in support for more than one TLS backend, this envi‐
4999 ronment variable can be set to the case insensitive name of the
5000 particular backend to use when curl is invoked. Setting a name
5001 that is not a built-in alternative will make curl stay with the
5002 default.
5003
5004 SSL backend names (case-insensitive): bearssl, gnutls, gskit,
5005 mbedtls, nss, openssl, rustls, schannel, secure-transport, wolf‐
5006 ssl
5007
5008 HOME <dir>
5009 If set, this is used to find the home directory when that is
5010 needed. Like when looking for the default .curlrc. CURL_HOME and
5011 XDG_CONFIG_HOME have preference.
5012
5013 QLOGDIR <directory name>
5014 If curl was built with HTTP/3 support, setting this environment
5015 variable to a local directory will make curl produce qlogs in
5016 that directory, using file names named after the destination
5017 connection id (in hex). Do note that these files can become
5018 rather large. Works with both QUIC backends.
5019
5020 SHELL Used on VMS when trying to detect if using a DCL or a "unix"
5021 shell.
5022
5023 SSL_CERT_DIR <dir>
5024 If set, will be used as the --capath value.
5025
5026 SSL_CERT_FILE <path>
5027 If set, will be used as the --cacert value.
5028
5029 SSLKEYLOGFILE <file name>
5030 If you set this environment variable to a file name, curl will
5031 store TLS secrets from its connections in that file when invoked
5032 to enable you to analyze the TLS traffic in real time using net‐
5033 work analyzing tools such as Wireshark. This works with the fol‐
5034 lowing TLS backends: OpenSSL, libressl, BoringSSL, GnuTLS, NSS
5035 and wolfSSL.
5036
5037 USERPROFILE <dir>
5038 On Windows, this variable is used when trying to find the home
5039 directory. If the other, primary, variable are all unset. If
5040 set, curl will use the path "$USERPROFILE\Application Data".
5041
5042 XDG_CONFIG_HOME <dir>
5043 If CURL_HOME is not set, this variable is checked when looking
5044 for a default .curlrc file.
5045
5047 The proxy string may be specified with a protocol:// prefix to specify
5048 alternative proxy protocols.
5049
5050 If no protocol is specified in the proxy string or if the string does
5051 not match a supported one, the proxy will be treated as an HTTP proxy.
5052
5053 The supported proxy protocol prefixes are as follows:
5054
5055 http://
5056 Makes it use it as an HTTP proxy. The default if no scheme pre‐
5057 fix is used.
5058
5059 https://
5060 Makes it treated as an HTTPS proxy.
5061
5062 socks4://
5063 Makes it the equivalent of --socks4
5064
5065 socks4a://
5066 Makes it the equivalent of --socks4a
5067
5068 socks5://
5069 Makes it the equivalent of --socks5
5070
5071 socks5h://
5072 Makes it the equivalent of --socks5-hostname
5073
5075 There are a bunch of different error codes and their corresponding er‐
5076 ror messages that may appear under error conditions. At the time of
5077 this writing, the exit codes are:
5078
5079 0 Success. The operation completed successfully according to the
5080 instructions.
5081
5082 1 Unsupported protocol. This build of curl has no support for this
5083 protocol.
5084
5085 2 Failed to initialize.
5086
5087 3 URL malformed. The syntax was not correct.
5088
5089 4 A feature or option that was needed to perform the desired re‐
5090 quest was not enabled or was explicitly disabled at build-time.
5091 To make curl able to do this, you probably need another build of
5092 libcurl.
5093
5094 5 Could not resolve proxy. The given proxy host could not be re‐
5095 solved.
5096
5097 6 Could not resolve host. The given remote host could not be re‐
5098 solved.
5099
5100 7 Failed to connect to host.
5101
5102 8 Weird server reply. The server sent data curl could not parse.
5103
5104 9 FTP access denied. The server denied login or denied access to
5105 the particular resource or directory you wanted to reach. Most
5106 often you tried to change to a directory that does not exist on
5107 the server.
5108
5109 10 FTP accept failed. While waiting for the server to connect back
5110 when an active FTP session is used, an error code was sent over
5111 the control connection or similar.
5112
5113 11 FTP weird PASS reply. Curl could not parse the reply sent to the
5114 PASS request.
5115
5116 12 During an active FTP session while waiting for the server to
5117 connect back to curl, the timeout expired.
5118
5119 13 FTP weird PASV reply, Curl could not parse the reply sent to the
5120 PASV request.
5121
5122 14 FTP weird 227 format. Curl could not parse the 227-line the
5123 server sent.
5124
5125 15 FTP cannot use host. Could not resolve the host IP we got in the
5126 227-line.
5127
5128 16 HTTP/2 error. A problem was detected in the HTTP2 framing layer.
5129 This is somewhat generic and can be one out of several problems,
5130 see the error message for details.
5131
5132 17 FTP could not set binary. Could not change transfer method to
5133 binary.
5134
5135 18 Partial file. Only a part of the file was transferred.
5136
5137 19 FTP could not download/access the given file, the RETR (or simi‐
5138 lar) command failed.
5139
5140 21 FTP quote error. A quote command returned error from the server.
5141
5142 22 HTTP page not retrieved. The requested URL was not found or re‐
5143 turned another error with the HTTP error code being 400 or
5144 above. This return code only appears if --fail is used.
5145
5146 23 Write error. Curl could not write data to a local filesystem or
5147 similar.
5148
5149 25 FTP could not STOR file. The server denied the STOR operation,
5150 used for FTP uploading.
5151
5152 26 Read error. Various reading problems.
5153
5154 27 Out of memory. A memory allocation request failed.
5155
5156 28 Operation timeout. The specified time-out period was reached ac‐
5157 cording to the conditions.
5158
5159 30 FTP PORT failed. The PORT command failed. Not all FTP servers
5160 support the PORT command, try doing a transfer using PASV in‐
5161 stead!
5162
5163 31 FTP could not use REST. The REST command failed. This command is
5164 used for resumed FTP transfers.
5165
5166 33 HTTP range error. The range "command" did not work.
5167
5168 34 HTTP post error. Internal post-request generation error.
5169
5170 35 SSL connect error. The SSL handshaking failed.
5171
5172 36 Bad download resume. Could not continue an earlier aborted down‐
5173 load.
5174
5175 37 FILE could not read file. Failed to open the file. Permissions?
5176
5177 38 LDAP cannot bind. LDAP bind operation failed.
5178
5179 39 LDAP search failed.
5180
5181 41 Function not found. A required LDAP function was not found.
5182
5183 42 Aborted by callback. An application told curl to abort the oper‐
5184 ation.
5185
5186 43 Internal error. A function was called with a bad parameter.
5187
5188 45 Interface error. A specified outgoing interface could not be
5189 used.
5190
5191 47 Too many redirects. When following redirects, curl hit the maxi‐
5192 mum amount.
5193
5194 48 Unknown option specified to libcurl. This indicates that you
5195 passed a weird option to curl that was passed on to libcurl and
5196 rejected. Read up in the manual!
5197
5198 49 Malformed telnet option.
5199
5200 52 The server did not reply anything, which here is considered an
5201 error.
5202
5203 53 SSL crypto engine not found.
5204
5205 54 Cannot set SSL crypto engine as default.
5206
5207 55 Failed sending network data.
5208
5209 56 Failure in receiving network data.
5210
5211 58 Problem with the local certificate.
5212
5213 59 Could not use specified SSL cipher.
5214
5215 60 Peer certificate cannot be authenticated with known CA certifi‐
5216 cates.
5217
5218 61 Unrecognized transfer encoding.
5219
5220 63 Maximum file size exceeded.
5221
5222 64 Requested FTP SSL level failed.
5223
5224 65 Sending the data requires a rewind that failed.
5225
5226 66 Failed to initialise SSL Engine.
5227
5228 67 The user name, password, or similar was not accepted and curl
5229 failed to log in.
5230
5231 68 File not found on TFTP server.
5232
5233 69 Permission problem on TFTP server.
5234
5235 70 Out of disk space on TFTP server.
5236
5237 71 Illegal TFTP operation.
5238
5239 72 Unknown TFTP transfer ID.
5240
5241 73 File already exists (TFTP).
5242
5243 74 No such user (TFTP).
5244
5245 77 Problem reading the SSL CA cert (path? access rights?).
5246
5247 78 The resource referenced in the URL does not exist.
5248
5249 79 An unspecified error occurred during the SSH session.
5250
5251 80 Failed to shut down the SSL connection.
5252
5253 82 Could not load CRL file, missing or wrong format.
5254
5255 83 Issuer check failed.
5256
5257 84 The FTP PRET command failed.
5258
5259 85 Mismatch of RTSP CSeq numbers.
5260
5261 86 Mismatch of RTSP Session Identifiers.
5262
5263 87 Unable to parse FTP file list.
5264
5265 88 FTP chunk callback reported error.
5266
5267 89 No connection available, the session will be queued.
5268
5269 90 SSL public key does not matched pinned public key.
5270
5271 91 Invalid SSL certificate status.
5272
5273 92 Stream error in HTTP/2 framing layer.
5274
5275 93 An API function was called from inside a callback.
5276
5277 94 An authentication function returned an error.
5278
5279 95 A problem was detected in the HTTP/3 layer. This is somewhat
5280 generic and can be one out of several problems, see the error
5281 message for details.
5282
5283 96 QUIC connection error. This error may be caused by an SSL li‐
5284 brary error. QUIC is the protocol used for HTTP/3 transfers.
5285
5286 XX More error codes will appear here in future releases. The exist‐
5287 ing ones are meant to never change.
5288
5290 If you experience any problems with curl, submit an issue in the
5291 project's bug tracker on GitHub: https://github.com/curl/curl/issues
5292
5294 Daniel Stenberg is the main author, but the whole list of contributors
5295 is found in the separate THANKS file.
5296
5298 https://curl.se
5299
5301 ftp(1), wget(1)
5302
5303
5304
5305curl 7.85.0 August 30 2022 curl(1)