1curl(1) curl Manual curl(1)
2
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, TFTP, WS and WSS. The command is
16 designed to work without user interaction.
17 curl offers a busload of useful tricks like proxy support, user authen‐
19 tication, FTP upload, HTTP post, SSL connections, cookies, file trans‐
20 fer resume and more. As you will see below, the number of features will
21 make your head spin.
22 curl is powered by libcurl for all transfer-related features. See
24 libcurl(3) for details.
25
27 The URL syntax is protocol-dependent. You find a detailed description
28 in RFC 3986.
29 You can specify multiple URLs or parts of URLs by writing part sets
31 within braces and quoting the URL as in:
32 "http://site.{one,two,three}.com"
34 or you can get sequences of alphanumeric series by using [] as in:
36 "ftp://ftp.example.com/file[1-100].txt"
38 "ftp://ftp.example.com/file[001-100].txt" (with leading zeros)
40 "ftp://ftp.example.com/file[a-z].txt"
42 Nested sequences are not supported, but you can use several ones next
44 to each other:
45 "http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html"
47 You can specify any amount of URLs on the command line. They will be
49 fetched in a sequential manner in the specified order unless you use
50 -Z, --parallel. You can specify command line options and URLs mixed and
51 in any order on the command line.
52 You can specify a step counter for the ranges to get every Nth number
54 or letter:
55 "http://example.com/file[1-100:10].txt"
57 "http://example.com/file[a-z:2].txt"
59 When using [] or {} sequences when invoked from a command line prompt,
61 you probably have to put the full URL within double quotes to avoid the
62 shell from interfering with it. This also goes for other characters
63 treated special, like for example '&', '?' and '*'.
64 Provide the IPv6 zone index in the URL with an escaped percentage sign
66 and the interface name. Like in
67 "http://[fe80::3%25eth0]/"
69 If you specify a URL without a protocol:// scheme, curl guesses what
71 protocol you want. It then defaults to HTTP but assumes others based on
72 often-used host name prefixes. For example, for host names starting
73 with "ftp." curl assumes you want FTP.
74 curl attempts to re-use connections when doing multiple file transfers,
76 so that getting many files from the same server do not use multiple
77 connects / handshakes. This improves speed. Connection re-use can only
78 be done for URLs specified for a single command line invocation and
79 cannot be performed between separate curl runs.
80
82 If not told otherwise, curl writes the received data to stdout. It can
83 be instructed to instead save that data into a local file, using the
84 -o, --output or -O, --remote-name options. If curl is given multiple
85 URLs to transfer on the command line, it similarly needs multiple op‐
86 tions for where to save them.
87 curl does not parse or otherwise "understand" the content it gets or
89 writes as output. It does no encoding or decoding, unless explicitly
90 asked to with dedicated command line options.
91
93 curl supports numerous protocols, or put in URL terms: schemes. Your
94 particular build may not support them all.
95 DICT Lets you lookup words using online dictionaries.
97 FILE Read or write local files. curl does not support accessing
99 file:// URL remotely, but when running on Microsoft Windows us‐
100 ing the native UNC approach will work.
101 FTP(S) curl supports the File Transfer Protocol with a lot of tweaks
103 and levers. With or without using TLS.
104 GOPHER(S)
106 Retrieve files.
107 HTTP(S)
109 curl supports HTTP with numerous options and variations. It can
110 speak HTTP version 0.9, 1.0, 1.1, 2 and 3 depending on build op‐
111 tions and the correct command line options.
112 IMAP(S)
114 Using the mail reading protocol, curl can "download" emails for
115 you. With or without using TLS.
116 LDAP(S)
118 curl can do directory lookups for you, with or without TLS.
119 MQTT curl supports MQTT version 3. Downloading over MQTT equals "sub‐
121 scribe" to a topic while uploading/posting equals "publish" on a
122 topic. MQTT over TLS is not supported (yet).
123 POP3(S)
125 Downloading from a pop3 server means getting a mail. With or
126 without using TLS.
127 RTMP(S)
129 The Realtime Messaging Protocol is primarily used to server
130 streaming media and curl can download it.
131 RTSP curl supports RTSP 1.0 downloads.
133 SCP curl supports SSH version 2 scp transfers.
135 SFTP curl supports SFTP (draft 5) done over SSH version 2.
137 SMB(S) curl supports SMB version 1 for upload and download.
139 SMTP(S)
141 Uploading contents to an SMTP server means sending an email.
142 With or without TLS.
143 TELNET Telling curl to fetch a telnet URL starts an interactive session
145 where it sends what it reads on stdin and outputs what the
146 server sends it.
147 TFTP curl can do TFTP downloads and uploads.
149
151 curl normally displays a progress meter during operations, indicating
152 the amount of transferred data, transfer speeds and estimated time
153 left, etc. The progress meter displays the transfer rate in bytes per
154 second. The suffixes (k, M, G, T, P) are 1024 based. For example 1k is
155 1024 bytes. 1M is 1048576 bytes.
156 curl displays this data to the terminal by default, so if you invoke
158 curl to do an operation and it is about to write data to the terminal,
159 it disables the progress meter as otherwise it would mess up the output
160 mixing progress meter and response data.
161 If you want a progress meter for HTTP POST or PUT requests, you need to
163 redirect the response output to a file, using shell redirect (>), -o,
164 --output or similar.
165 This does not apply to FTP upload as that operation does not spit out
167 any response data to the terminal.
168 If you prefer a progress "bar" instead of the regular meter, -#,
170 --progress-bar is your friend. You can also disable the progress meter
171 completely with the -s, --silent option.
172
174 This man page describes curl 8.2.1. If you use a later version, chances
175 are this man page does not fully document it. If you use an earlier
176 version, this document tries to include version information about which
177 specific version that introduced changes.
178 You can always learn which the latest curl version is by running
180 curl https://curl.se/info
181
183 Options start with one or two dashes. Many of the options require an
184 additional value next to them.
185 The short "single-dash" form of the options, -d for example, may be
187 used with or without a space between it and its value, although a space
188 is a recommended separator. The long "double-dash" form, -d, --data for
189 example, requires a space between it and its value.
190 Short version options that do not need any additional values can be
192 used immediately next to each other, like for example you can specify
193 all the options -O, -L and -v at once as -OLv.
194 In general, all boolean options are enabled with --option and yet again
196 disabled with --no-option. That is, you use the same option name but
197 prefix it with "no-". However, in this list we mostly only list and
198 show the --option version of them.
199 When -:, --next is used, it resets the parser state and you start again
201 with a clean option state, except for the options that are "global".
202 Global options will retain their values and meaning even after -:,
203 --next.
204 The following options are global: --fail-early, --libcurl, --parallel-
206 immediate, -Z, --parallel, -#, --progress-bar, --rate, -S, --show-er‐
207 ror, --stderr, --styled-output, --trace-ascii, --trace-ids, --trace-
208 time, --trace and -v, --verbose.
209 --abstract-unix-socket <path>
211 (HTTP) Connect through an abstract Unix domain socket, instead
212 of using the network. Note: netstat shows the path of an ab‐
213 stract socket prefixed with '@', however the <path> argument
214 should not have this leading character.
215 If --abstract-unix-socket is provided several times, the last
217 set value will be used.
218 Example:
220 curl --abstract-unix-socket socketpath https://example.com
221 See also --unix-socket. Added in 7.53.0.
223 --alt-svc <file name>
225 (HTTPS) This option enables the alt-svc parser in curl. If the
226 file name points to an existing alt-svc cache file, that will be
227 used. After a completed transfer, the cache will be saved to the
228 file name again if it has been modified.
229 Specify a "" file name (zero length) to avoid loading/saving and
231 make curl just handle the cache in memory.
232 If this option is used several times, curl will load contents
234 from all the files but the last one will be used for saving.
235 --alt-svc can be used several times in a command line
237 Example:
239 curl --alt-svc svc.txt https://example.com
240 See also --resolve and --connect-to. Added in 7.64.1.
242 --anyauth
244 (HTTP) Tells curl to figure out authentication method by itself,
245 and use the most secure one the remote site claims to support.
246 This is done by first doing a request and checking the response-
247 headers, thus possibly inducing an extra network round-trip.
248 This is used instead of setting a specific authentication
249 method, which you can do with --basic, --digest, --ntlm, and
250 --negotiate.
251 Using --anyauth is not recommended if you do uploads from stdin,
253 since it may require data to be sent twice and then the client
254 must be able to rewind. If the need should arise when uploading
255 from stdin, the upload operation will fail.
256 Used together with -u, --user.
258 Providing --anyauth multiple times has no extra effect.
260 Example:
262 curl --anyauth --user me:pwd https://example.com
263 See also --proxy-anyauth, --basic and --digest.
265 -a, --append
267 (FTP SFTP) When used in an upload, this makes curl append to the
268 target file instead of overwriting it. If the remote file does
269 not exist, it will be created. Note that this flag is ignored by
270 some SFTP servers (including OpenSSH).
271 Providing -a, --append multiple times has no extra effect. Dis‐
273 able it again with --no-append.
274 Example:
276 curl --upload-file local --append ftp://example.com/
277 See also -r, --range and -C, --continue-at.
279 --aws-sigv4 <provider1[:provider2[:region[:service]]]>
281 Use AWS V4 signature authentication in the transfer.
282 The provider argument is a string that is used by the algorithm
284 when creating outgoing authentication headers.
285 The region argument is a string that points to a geographic area
287 of a resources collection (region-code) when the region name is
288 omitted from the endpoint.
289 The service argument is a string that points to a function pro‐
291 vided by a cloud (service-code) when the service name is omitted
292 from the endpoint.
293 If --aws-sigv4 is provided several times, the last set value
295 will be used.
296 Example:
298 curl --aws-sigv4 "aws:amz:us-east-2:es" --user "key:secret" https://example.com
299 See also --basic and -u, --user. Added in 7.75.0.
301 --basic
303 (HTTP) Tells curl to use HTTP Basic authentication with the re‐
304 mote host. This is the default and this option is usually point‐
305 less, unless you use it to override a previously set option that
306 sets a different authentication method (such as --ntlm, --di‐
307 gest, or --negotiate).
308 Used together with -u, --user.
310 Providing --basic multiple times has no extra effect.
312 Example:
314 curl -u name:password --basic https://example.com
315 See also --proxy-basic.
317 --ca-native
319 (TLS) Tells curl to use the CA store from the native operating
320 system to verify the peer. By default, curl will otherwise use a
321 CA store provided in a single file or directory, but when using
322 this option it will interface the operating system's own vault.
323 This option only works for curl on Windows when built to use
325 OpenSSL. When curl on Windows is built to use Schannel, this
326 feature is implied and curl then only uses the native CA store.
327 Providing --ca-native multiple times has no extra effect. Dis‐
329 able it again with --no-ca-native.
330 Example:
332 curl --ca-native https://example.com
333 See also --cacert, --capath and -k, --insecure. Added in 8.2.0.
335 --cacert <file>
337 (TLS) Tells curl to use the specified certificate file to verify
338 the peer. The file may contain multiple CA certificates. The
339 certificate(s) must be in PEM format. Normally curl is built to
340 use a default file for this, so this option is typically used to
341 alter that default file.
342 curl recognizes the environment variable named 'CURL_CA_BUNDLE'
344 if it is set, and uses the given path as a path to a CA cert
345 bundle. This option overrides that variable.
346 The windows version of curl will automatically look for a CA
348 certs file named 'curl-ca-bundle.crt', either in the same direc‐
349 tory as curl.exe, or in the Current Working Directory, or in any
350 folder along your PATH.
351 If curl is built against the NSS SSL library, the NSS PEM
353 PKCS#11 module (libnsspem.so) needs to be available for this op‐
354 tion to work properly.
355 (iOS and macOS only) If curl is built against Secure Transport,
357 then this option is supported for backward compatibility with
358 other SSL engines, but it should not be set. If the option is
359 not set, then curl will use the certificates in the system and
360 user Keychain to verify the peer, which is the preferred method
361 of verifying the peer's certificate chain.
362 (Schannel only) This option is supported for Schannel in Windows
364 7 or later with libcurl 7.60 or later. This option is supported
365 for backward compatibility with other SSL engines; instead it is
366 recommended to use Windows' store of root certificates (the de‐
367 fault for Schannel).
368 If --cacert is provided several times, the last set value will
370 be used.
371 Example:
373 curl --cacert CA-file.txt https://example.com
374 See also --capath and -k, --insecure.
376 --capath <dir>
378 (TLS) Tells curl to use the specified certificate directory to
379 verify the peer. Multiple paths can be provided by separating
380 them with ":" (e.g. "path1:path2:path3"). The certificates must
381 be in PEM format, and if curl is built against OpenSSL, the di‐
382 rectory must have been processed using the c_rehash utility sup‐
383 plied with OpenSSL. Using --capath can allow OpenSSL-powered
384 curl to make SSL-connections much more efficiently than using
385 --cacert if the --cacert file contains many CA certificates.
386 If this option is set, the default capath value will be ignored.
388 If --capath is provided several times, the last set value will
390 be used.
391 Example:
393 curl --capath /local/directory https://example.com
394 See also --cacert and -k, --insecure.
396 --cert-status
398 (TLS) Tells curl to verify the status of the server certificate
399 by using the Certificate Status Request (aka. OCSP stapling) TLS
400 extension.
401 If this option is enabled and the server sends an invalid (e.g.
403 expired) response, if the response suggests that the server cer‐
404 tificate has been revoked, or no response at all is received,
405 the verification fails.
406 This is currently only implemented in the OpenSSL, GnuTLS and
408 NSS backends.
409 Providing --cert-status multiple times has no extra effect.
411 Disable it again with --no-cert-status.
412 Example:
414 curl --cert-status https://example.com
415 See also --pinnedpubkey. Added in 7.41.0.
417 --cert-type <type>
419 (TLS) Tells curl what type the provided client certificate is
420 using. PEM, DER, ENG and P12 are recognized types.
421 The default type depends on the TLS backend and is usually PEM,
423 however for Secure Transport and Schannel it is P12. If -E,
424 --cert is a pkcs11: URI then ENG is the default type.
425 If --cert-type is provided several times, the last set value
427 will be used.
428 Example:
430 curl --cert-type PEM --cert file https://example.com
431 See also -E, --cert, --key and --key-type.
433 -E, --cert <certificate[:password]>
435 (TLS) Tells curl to use the specified client certificate file
436 when getting a file with HTTPS, FTPS or another SSL-based proto‐
437 col. The certificate must be in PKCS#12 format if using Secure
438 Transport, or PEM format if using any other engine. If the op‐
439 tional password is not specified, it will be queried for on the
440 terminal. Note that this option assumes a certificate file that
441 is the private key and the client certificate concatenated. See
442 -E, --cert and --key to specify them independently.
443 In the <certificate> portion of the argument, you must escape
445 the character ":" as "\:" so that it is not recognized as the
446 password delimiter. Similarly, you must escape the character "\"
447 as "\\" so that it is not recognized as an escape character.
448 If curl is built against the NSS SSL library then this option
450 can tell curl the nickname of the certificate to use within the
451 NSS database defined by the environment variable SSL_DIR (or by
452 default /etc/pki/nssdb). If the NSS PEM PKCS#11 module (lib‐
453 nsspem.so) is available then PEM files may be loaded.
454 If you provide a path relative to the current directory, you
456 must prefix the path with "./" in order to avoid confusion with
457 an NSS database nickname.
458 If curl is built against OpenSSL library, and the engine pkcs11
460 is available, then a PKCS#11 URI (RFC 7512) can be used to spec‐
461 ify a certificate located in a PKCS#11 device. A string begin‐
462 ning with "pkcs11:" will be interpreted as a PKCS#11 URI. If a
463 PKCS#11 URI is provided, then the --engine option will be set as
464 "pkcs11" if none was provided and the --cert-type option will be
465 set as "ENG" if none was provided.
466 (iOS and macOS only) If curl is built against Secure Transport,
468 then the certificate string can either be the name of a certifi‐
469 cate/private key in the system or user keychain, or the path to
470 a PKCS#12-encoded certificate and private key. If you want to
471 use a file from the current directory, please precede it with
472 "./" prefix, in order to avoid confusion with a nickname.
473 (Schannel only) Client certificates must be specified by a path
475 expression to a certificate store. (Loading PFX is not sup‐
476 ported; you can import it to a store first). You can use "<store
477 location>\<store name>\<thumbprint>" to refer to a certificate
478 in the system certificates store, for example, "Curren‐
479 tUser\MY\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a". Thumbprint
480 is usually a SHA-1 hex string which you can see in certificate
481 details. Following store locations are supported: CurrentUser,
482 LocalMachine, CurrentService, Services, CurrentUserGroupPolicy,
483 LocalMachineGroupPolicy, LocalMachineEnterprise.
484 If -E, --cert is provided several times, the last set value will
486 be used.
487 Example:
489 curl --cert certfile --key keyfile https://example.com
490 See also --cert-type, --key and --key-type.
492 --ciphers <list of ciphers>
494 (TLS) Specifies which ciphers to use in the connection. The list
495 of ciphers must specify valid ciphers. Read up on SSL cipher
496 list details on this URL:
497 https://curl.se/docs/ssl-ciphers.html
499 If --ciphers is provided several times, the last set value will
501 be used.
502 Example:
504 curl --ciphers ECDHE-ECDSA-AES256-CCM8 https://example.com
505 See also --tlsv1.3, --tls13-ciphers and --proxy-ciphers.
507 --compressed-ssh
509 (SCP SFTP) Enables built-in SSH compression. This is a request,
510 not an order; the server may or may not do it.
511 Providing --compressed-ssh multiple times has no extra effect.
513 Disable it again with --no-compressed-ssh.
514 Example:
516 curl --compressed-ssh sftp://example.com/
517 See also --compressed. Added in 7.56.0.
519 --compressed
521 (HTTP) Request a compressed response using one of the algorithms
522 curl supports, and automatically decompress the content.
523 Response headers are not modified when saved, so if they are
525 "interpreted" separately again at a later point they might ap‐
526 pear to be saying that the content is (still) compressed; while
527 in fact it has already been decompressed.
528 If this option is used and the server sends an unsupported en‐
530 coding, curl will report an error. This is a request, not an or‐
531 der; the server may or may not deliver data compressed.
532 Providing --compressed multiple times has no extra effect. Dis‐
534 able it again with --no-compressed.
535 Example:
537 curl --compressed https://example.com
538 See also --compressed-ssh.
540 -K, --config <file>
542 Specify a text file to read curl arguments from. The command
543 line arguments found in the text file will be used as if they
544 were provided on the command line.
545 Options and their parameters must be specified on the same line
547 in the file, separated by whitespace, colon, or the equals sign.
548 Long option names can optionally be given in the config file
549 without the initial double dashes and if so, the colon or equals
550 characters can be used as separators. If the option is specified
551 with one or two dashes, there can be no colon or equals charac‐
552 ter between the option and its parameter.
553 If the parameter contains whitespace (or starts with : or =),
555 the parameter must be enclosed within quotes. Within double
556 quotes, the following escape sequences are available: \\, \",
557 \t, \n, \r and \v. A backslash preceding any other letter is ig‐
558 nored.
559 If the first column of a config line is a '#' character, the
561 rest of the line will be treated as a comment.
562 Only write one option per physical line in the config file. A
564 single line is required to be no more than 10 megabytes (since
565 8.2.0).
566 Specify the filename to -K, --config as '-' to make curl read
568 the file from stdin.
569 Note that to be able to specify a URL in the config file, you
571 need to specify it using the --url option, and not by simply
572 writing the URL on its own line. So, it could look similar to
573 this:
574 url = "https://curl.se/docs/"
576 # --- Example file ---
578 # this is a comment
579 url = "example.com"
580 output = "curlhere.html"
581 user-agent = "superagent/1.0"
582 # and fetch another URL too
584 url = "example.com/docs/manpage.html"
585 -O
586 referer = "http://nowhereatall.example.com/"
587 # --- End of example file ---
588 When curl is invoked, it (unless -q, --disable is used) checks
590 for a default config file and uses it if found, even when -K,
591 --config is used. The default config file is checked for in the
592 following places in this order:
593 1) "$CURL_HOME/.curlrc"
595 2) "$XDG_CONFIG_HOME/curlrc" (Added in 7.73.0)
597 3) "$HOME/.curlrc"
599 4) Windows: "%USERPROFILE%\.curlrc"
601 5) Windows: "%APPDATA%\.curlrc"
603 6) Windows: "%USERPROFILE%\Application Data\.curlrc"
605 7) Non-Windows: use getpwuid to find the home directory
607 8) On Windows, if it finds no .curlrc file in the sequence de‐
609 scribed above, it checks for one in the same dir the curl exe‐
610 cutable is placed.
611 On Windows two filenames are checked per location: .curlrc and
613 _curlrc, preferring the former. Older versions on Windows
614 checked for _curlrc only.
615 -K, --config can be used several times in a command line
617 Example:
619 curl --config file.txt https://example.com
620 See also -q, --disable.
622 --connect-timeout <fractional seconds>
624 Maximum time in seconds that you allow curl's connection to
625 take. This only limits the connection phase, so if curl con‐
626 nects within the given period it will continue - if not it will
627 exit. Since version 7.32.0, this option accepts decimal values.
628 The "connection phase" is considered complete when the DNS
630 lookup and requested TCP, TLS or QUIC handshakes are done.
631 The decimal value needs to provided using a dot (.) as decimal
633 separator - not the local version even if it might be using an‐
634 other separator.
635 If --connect-timeout is provided several times, the last set
637 value will be used.
638 Examples:
640 curl --connect-timeout 20 https://example.com
641 curl --connect-timeout 3.14 https://example.com
642 See also -m, --max-time.
644 --connect-to <HOST1:PORT1:HOST2:PORT2>
646 For a request to the given HOST1:PORT1 pair, connect to
648 HOST2:PORT2 instead. This option is suitable to direct requests
649 at a specific server, e.g. at a specific cluster node in a clus‐
650 ter of servers. This option is only used to establish the net‐
651 work connection. It does NOT affect the hostname/port that is
652 used for TLS/SSL (e.g. SNI, certificate verification) or for the
653 application protocols. "HOST1" and "PORT1" may be the empty
654 string, meaning "any host/port". "HOST2" and "PORT2" may also be
655 the empty string, meaning "use the request's original
656 host/port".
657 A "host" specified to this option is compared as a string, so it
659 needs to match the name used in request URL. It can be either
660 numerical such as "127.0.0.1" or the full host name such as "ex‐
661 ample.org".
662 --connect-to can be used several times in a command line
664 Example:
666 curl --connect-to example.com:443:example.net:8443 https://example.com
667 See also --resolve and -H, --header. Added in 7.49.0.
669 -C, --continue-at <offset>
671 Continue/Resume a previous file transfer at the given offset.
672 The given offset is the exact number of bytes that will be
673 skipped, counting from the beginning of the source file before
674 it is transferred to the destination. If used with uploads, the
675 FTP server command SIZE will not be used by curl.
676 Use "-C -" to tell curl to automatically find out where/how to
678 resume the transfer. It then uses the given output/input files
679 to figure that out.
680 If -C, --continue-at is provided several times, the last set
682 value will be used.
683 Examples:
685 curl -C - https://example.com
686 curl -C 400 https://example.com
687 See also -r, --range.
689 -c, --cookie-jar <filename>
691 (HTTP) Specify to which file you want curl to write all cookies
692 after a completed operation. Curl writes all cookies from its
693 in-memory cookie storage to the given file at the end of opera‐
694 tions. If no cookies are known, no data will be written. The
695 file will be written using the Netscape cookie file format. If
696 you set the file name to a single dash, "-", the cookies will be
697 written to stdout.
698 This command line option will activate the cookie engine that
700 makes curl record and use cookies. Another way to activate it is
701 to use the -b, --cookie option.
702 If the cookie jar cannot be created or written to, the whole
704 curl operation will not fail or even report an error clearly.
705 Using -v, --verbose will get a warning displayed, but that is
706 the only visible feedback you get about this possibly lethal
707 situation.
708 If -c, --cookie-jar is provided several times, the last set
710 value will be used.
711 Examples:
713 curl -c store-here.txt https://example.com
714 curl -c store-here.txt -b read-these https://example.com
715 See also -b, --cookie.
717 -b, --cookie <data|filename>
719 (HTTP) Pass the data to the HTTP server in the Cookie header. It
720 is supposedly the data previously received from the server in a
721 "Set-Cookie:" line. The data should be in the format
722 "NAME1=VALUE1; NAME2=VALUE2". This makes curl use the cookie
723 header with this content explicitly in all outgoing request(s).
724 If multiple requests are done due to authentication, followed
725 redirects or similar, they will all get this cookie passed on.
726 If no '=' symbol is used in the argument, it is instead treated
728 as a filename to read previously stored cookie from. This option
729 also activates the cookie engine which will make curl record in‐
730 coming cookies, which may be handy if you are using this in com‐
731 bination with the -L, --location option or do multiple URL
732 transfers on the same invoke. If the file name is exactly a mi‐
733 nus ("-"), curl will instead read the contents from stdin.
734 The file format of the file to read cookies from should be plain
736 HTTP headers (Set-Cookie style) or the Netscape/Mozilla cookie
737 file format.
738 The file specified with -b, --cookie is only used as input. No
740 cookies will be written to the file. To store cookies, use the
741 -c, --cookie-jar option.
742 If you use the Set-Cookie file format and do not specify a do‐
744 main then the cookie is not sent since the domain will never
745 match. To address this, set a domain in Set-Cookie line (doing
746 that will include sub-domains) or preferably: use the Netscape
747 format.
748 Users often want to both read cookies from a file and write up‐
750 dated cookies back to a file, so using both -b, --cookie and -c,
751 --cookie-jar in the same command line is common.
752 -b, --cookie can be used several times in a command line
754 Examples:
756 curl -b cookiefile https://example.com
757 curl -b cookiefile -c cookiefile https://example.com
758 See also -c, --cookie-jar and -j, --junk-session-cookies.
760 --create-dirs
762 When used in conjunction with the -o, --output option, curl will
763 create the necessary local directory hierarchy as needed. This
764 option creates the directories mentioned with the -o, --output
765 option, nothing else. If the -o, --output file name uses no di‐
766 rectory, or if the directories it mentions already exist, no di‐
767 rectories will be created.
768 Created dirs are made with mode 0750 on unix style file systems.
770 To create remote directories when using FTP or SFTP, try --ftp-
772 create-dirs.
773 Providing --create-dirs multiple times has no extra effect.
775 Disable it again with --no-create-dirs.
776 Example:
778 curl --create-dirs --output local/dir/file https://example.com
779 See also --ftp-create-dirs and --output-dir.
781 --create-file-mode <mode>
783 (SFTP SCP FILE) When curl is used to create files remotely using
784 one of the supported protocols, this option allows the user to
785 set which 'mode' to set on the file at creation time, instead of
786 the default 0644.
787 This option takes an octal number as argument.
789 If --create-file-mode is provided several times, the last set
791 value will be used.
792 Example:
794 curl --create-file-mode 0777 -T localfile sftp://example.com/new
795 See also --ftp-create-dirs. Added in 7.75.0.
797 --crlf (FTP SMTP) Convert LF to CRLF in upload. Useful for MVS
799 (OS/390).
800 (SMTP added in 7.40.0)
802 Providing --crlf multiple times has no extra effect. Disable it
804 again with --no-crlf.
805 Example:
807 curl --crlf -T file ftp://example.com/
808 See also -B, --use-ascii.
810 --crlfile <file>
812 (TLS) Provide a file using PEM format with a Certificate Revoca‐
813 tion List that may specify peer certificates that are to be con‐
814 sidered revoked.
815 If --crlfile is provided several times, the last set value will
817 be used.
818 Example:
820 curl --crlfile rejects.txt https://example.com
821 See also --cacert and --capath.
823 --curves <algorithm list>
825 (TLS) Tells curl to request specific curves to use during SSL
826 session establishment according to RFC 8422, 5.1. Multiple al‐
827 gorithms can be provided by separating them with ":" (e.g.
828 "X25519:P-521"). The parameter is available identically in the
829 "openssl s_client/s_server" utilities.
830 --curves allows a OpenSSL powered curl to make SSL-connections
832 with exactly the (EC) curve requested by the client, avoiding
833 nontransparent client/server negotiations.
834 If this option is set, the default curves list built into
836 openssl will be ignored.
837 If --curves is provided several times, the last set value will
839 be used.
840 Example:
842 curl --curves X25519 https://example.com
843 See also --ciphers. Added in 7.73.0.
845 --data-ascii <data>
847 (HTTP) This is just an alias for -d, --data.
848 --data-ascii can be used several times in a command line
850 Example:
852 curl --data-ascii @file https://example.com
853 See also --data-binary, --data-raw and --data-urlencode.
855 --data-binary <data>
857 (HTTP) This posts data exactly as specified with no extra pro‐
858 cessing whatsoever.
859 If you start the data with the letter @, the rest should be a
861 filename. Data is posted in a similar manner as -d, --data does,
862 except that newlines and carriage returns are preserved and con‐
863 versions are never done.
864 Like -d, --data the default content-type sent to the server is
866 application/x-www-form-urlencoded. If you want the data to be
867 treated as arbitrary binary data by the server then set the con‐
868 tent-type to octet-stream: -H "Content-Type: application/octet-
869 stream".
870 If this option is used several times, the ones following the
872 first will append data as described in -d, --data.
873 --data-binary can be used several times in a command line
875 Example:
877 curl --data-binary @filename https://example.com
878 See also --data-ascii.
880 --data-raw <data>
882 (HTTP) This posts data similarly to -d, --data but without the
883 special interpretation of the @ character.
884 --data-raw can be used several times in a command line
886 Examples:
888 curl --data-raw "hello" https://example.com
889 curl --data-raw "@at@at@" https://example.com
890 See also -d, --data. Added in 7.43.0.
892 --data-urlencode <data>
894 (HTTP) This posts data, similar to the other -d, --data options
895 with the exception that this performs URL-encoding.
896 To be CGI-compliant, the <data> part should begin with a name
898 followed by a separator and a content specification. The <data>
899 part can be passed to curl using one of the following syntaxes:
900 content
902 This will make curl URL-encode the content and pass that
903 on. Just be careful so that the content does not contain
904 any = or @ symbols, as that will then make the syntax
905 match one of the other cases below!
906 =content
908 This will make curl URL-encode the content and pass that
909 on. The preceding = symbol is not included in the data.
910 name=content
912 This will make curl URL-encode the content part and pass
913 that on. Note that the name part is expected to be URL-
914 encoded already.
915 @filename
917 This will make curl load data from the given file (in‐
918 cluding any newlines), URL-encode that data and pass it
919 on in the POST.
920 name@filename
922 This will make curl load data from the given file (in‐
923 cluding any newlines), URL-encode that data and pass it
924 on in the POST. The name part gets an equal sign ap‐
925 pended, resulting in name=urlencoded-file-content. Note
926 that the name is expected to be URL-encoded already.
927 --data-urlencode can be used several times in a command line
929 Examples:
931 curl --data-urlencode name=val https://example.com
932 curl --data-urlencode =encodethis https://example.com
933 curl --data-urlencode name@file https://example.com
934 curl --data-urlencode @fileonly https://example.com
935 See also -d, --data and --data-raw.
937 -d, --data <data>
939 (HTTP MQTT) Sends the specified data in a POST request to the
940 HTTP server, in the same way that a browser does when a user has
941 filled in an HTML form and presses the submit button. This will
942 cause curl to pass the data to the server using the content-type
943 application/x-www-form-urlencoded. Compare to -F, --form.
944 --data-raw is almost the same but does not have a special inter‐
946 pretation of the @ character. To post data purely binary, you
947 should instead use the --data-binary option. To URL-encode the
948 value of a form field you may use --data-urlencode.
949 If any of these options is used more than once on the same com‐
951 mand line, the data pieces specified will be merged with a sepa‐
952 rating &-symbol. Thus, using '-d name=daniel -d skill=lousy'
953 would generate a post chunk that looks like
954 'name=daniel&skill=lousy'.
955 If you start the data with the letter @, the rest should be a
957 file name to read the data from, or - if you want curl to read
958 the data from stdin. Posting data from a file named 'foobar'
959 would thus be done with -d, --data @foobar. When -d, --data is
960 told to read from a file like that, carriage returns and new‐
961 lines will be stripped out. If you do not want the @ character
962 to have a special interpretation use --data-raw instead.
963 The data for this option is passed on to the server exactly as
965 provided on the command line. curl will not convert it, change
966 it or improve it. It is up to the user to provide the data in
967 the correct form.
968 -d, --data can be used several times in a command line
970 Examples:
972 curl -d "name=curl" https://example.com
973 curl -d "name=curl" -d "tool=cmdline" https://example.com
974 curl -d @filename https://example.com
975 See also --data-binary, --data-urlencode and --data-raw. This
977 option is mutually exclusive to -F, --form and -I, --head and
978 -T, --upload-file.
979 --delegation <LEVEL>
981 (GSS/kerberos) Set LEVEL to tell the server what it is allowed
982 to delegate when it comes to user credentials.
983 none Do not allow any delegation.
985 policy Delegates if and only if the OK-AS-DELEGATE flag is set
987 in the Kerberos service ticket, which is a matter of
988 realm policy.
989 always Unconditionally allow the server to delegate.
991 If --delegation is provided several times, the last set value
993 will be used.
994 Example:
996 curl --delegation "none" https://example.com
997 See also -k, --insecure and --ssl.
999 --digest
1001 (HTTP) Enables HTTP Digest authentication. This is an authenti‐
1002 cation scheme that prevents the password from being sent over
1003 the wire in clear text. Use this in combination with the normal
1004 -u, --user option to set user name and password.
1005 Providing --digest multiple times has no extra effect. Disable
1007 it again with --no-digest.
1008 Example:
1010 curl -u name:password --digest https://example.com
1011 See also -u, --user, --proxy-digest and --anyauth. This option
1013 is mutually exclusive to --basic and --ntlm and --negotiate.
1014 --disable-eprt
1016 (FTP) Tell curl to disable the use of the EPRT and LPRT commands
1017 when doing active FTP transfers. Curl will normally always first
1018 attempt to use EPRT, then LPRT before using PORT, but with this
1019 option, it will use PORT right away. EPRT and LPRT are exten‐
1020 sions to the original FTP protocol, and may not work on all
1021 servers, but they enable more functionality in a better way than
1022 the traditional PORT command.
1023 --eprt can be used to explicitly enable EPRT again and --no-eprt
1025 is an alias for --disable-eprt.
1026 If the server is accessed using IPv6, this option will have no
1028 effect as EPRT is necessary then.
1029 Disabling EPRT only changes the active behavior. If you want to
1031 switch to passive mode you need to not use -P, --ftp-port or
1032 force it with --ftp-pasv.
1033 Providing --disable-eprt multiple times has no extra effect.
1035 Disable it again with --no-disable-eprt.
1036 Example:
1038 curl --disable-eprt ftp://example.com/
1039 See also --disable-epsv and -P, --ftp-port.
1041 --disable-epsv
1043 (FTP) Tell curl to disable the use of the EPSV command when do‐
1044 ing passive FTP transfers. Curl will normally always first at‐
1045 tempt to use EPSV before PASV, but with this option, it will not
1046 try using EPSV.
1047 --epsv can be used to explicitly enable EPSV again and --no-epsv
1049 is an alias for --disable-epsv.
1050 If the server is an IPv6 host, this option will have no effect
1052 as EPSV is necessary then.
1053 Disabling EPSV only changes the passive behavior. If you want to
1055 switch to active mode you need to use -P, --ftp-port.
1056 Providing --disable-epsv multiple times has no extra effect.
1058 Disable it again with --no-disable-epsv.
1059 Example:
1061 curl --disable-epsv ftp://example.com/
1062 See also --disable-eprt and -P, --ftp-port.
1064 -q, --disable
1066 If used as the first parameter on the command line, the curlrc
1067 config file will not be read and used. See the -K, --config for
1068 details on the default config file search path.
1069 Providing -q, --disable multiple times has no extra effect.
1071 Disable it again with --no-disable.
1072 Example:
1074 curl -q https://example.com
1075 See also -K, --config.
1077 --disallow-username-in-url
1079 (HTTP) This tells curl to exit if passed a URL containing a
1080 username. This is probably most useful when the URL is being
1081 provided at runtime or similar.
1082 Providing --disallow-username-in-url multiple times has no extra
1084 effect. Disable it again with --no-disallow-username-in-url.
1085 Example:
1087 curl --disallow-username-in-url https://example.com
1088 See also --proto. Added in 7.61.0.
1090 --dns-interface <interface>
1092 (DNS) Tell curl to send outgoing DNS requests through <inter‐
1093 face>. This option is a counterpart to --interface (which does
1094 not affect DNS). The supplied string must be an interface name
1095 (not an address).
1096 If --dns-interface is provided several times, the last set value
1098 will be used.
1099 Example:
1101 curl --dns-interface eth0 https://example.com
1102 See also --dns-ipv4-addr and --dns-ipv6-addr. --dns-interface
1104 requires that the underlying libcurl was built to support c-
1105 ares. Added in 7.33.0.
1106 --dns-ipv4-addr <address>
1108 (DNS) Tell curl to bind to <ip-address> when making IPv4 DNS re‐
1109 quests, so that the DNS requests originate from this address.
1110 The argument should be a single IPv4 address.
1111 If --dns-ipv4-addr is provided several times, the last set value
1113 will be used.
1114 Example:
1116 curl --dns-ipv4-addr 10.1.2.3 https://example.com
1117 See also --dns-interface and --dns-ipv6-addr. --dns-ipv4-addr
1119 requires that the underlying libcurl was built to support c-
1120 ares. Added in 7.33.0.
1121 --dns-ipv6-addr <address>
1123 (DNS) Tell curl to bind to <ip-address> when making IPv6 DNS re‐
1124 quests, so that the DNS requests originate from this address.
1125 The argument should be a single IPv6 address.
1126 If --dns-ipv6-addr is provided several times, the last set value
1128 will be used.
1129 Example:
1131 curl --dns-ipv6-addr 2a04:4e42::561 https://example.com
1132 See also --dns-interface and --dns-ipv4-addr. --dns-ipv6-addr
1134 requires that the underlying libcurl was built to support c-
1135 ares. Added in 7.33.0.
1136 --dns-servers <addresses>
1138 Set the list of DNS servers to be used instead of the system de‐
1139 fault. The list of IP addresses should be separated with com‐
1140 mas. Port numbers may also optionally be given as :<port-number>
1141 after each IP address.
1142 If --dns-servers is provided several times, the last set value
1144 will be used.
1145 Example:
1147 curl --dns-servers 192.168.0.1,192.168.0.2 https://example.com
1148 See also --dns-interface and --dns-ipv4-addr. --dns-servers re‐
1150 quires that the underlying libcurl was built to support c-ares.
1151 Added in 7.33.0.
1152 --doh-cert-status
1154 Same as --cert-status but used for DoH (DNS-over-HTTPS).
1155 Providing --doh-cert-status multiple times has no extra effect.
1157 Disable it again with --no-doh-cert-status.
1158 Example:
1160 curl --doh-cert-status --doh-url https://doh.example https://example.com
1161 See also --doh-insecure. Added in 7.76.0.
1163 --doh-insecure
1165 Same as -k, --insecure but used for DoH (DNS-over-HTTPS).
1166 Providing --doh-insecure multiple times has no extra effect.
1168 Disable it again with --no-doh-insecure.
1169 Example:
1171 curl --doh-insecure --doh-url https://doh.example https://example.com
1172 See also --doh-url. Added in 7.76.0.
1174 --doh-url <URL>
1176 Specifies which DNS-over-HTTPS (DoH) server to use to resolve
1177 hostnames, instead of using the default name resolver mechanism.
1178 The URL must be HTTPS.
1179 Some SSL options that you set for your transfer will apply to
1181 DoH since the name lookups take place over SSL. However, the
1182 certificate verification settings are not inherited and can be
1183 controlled separately via --doh-insecure and --doh-cert-status.
1184 This option is unset if an empty string "" is used as the URL.
1186 (Added in 7.85.0)
1187 If --doh-url is provided several times, the last set value will
1189 be used.
1190 Example:
1192 curl --doh-url https://doh.example https://example.com
1193 See also --doh-insecure. Added in 7.62.0.
1195 -D, --dump-header <filename>
1197 (HTTP FTP) Write the received protocol headers to the specified
1198 file. If no headers are received, the use of this option will
1199 create an empty file.
1200 When used in FTP, the FTP server response lines are considered
1202 being "headers" and thus are saved there.
1203 Having multiple transfers in one set of operations (i.e. the
1205 URLs in one -:, --next clause), will append them to the same
1206 file, separated by a blank line.
1207 If -D, --dump-header is provided several times, the last set
1209 value will be used.
1210 Example:
1212 curl --dump-header store.txt https://example.com
1213 See also -o, --output.
1215 --egd-file <file>
1217 (TLS) Deprecated option. This option is ignored by curl since
1218 7.84.0. Prior to that it only had an effect on curl if built to
1219 use old versions of OpenSSL.
1220 Specify the path name to the Entropy Gathering Daemon socket.
1222 The socket is used to seed the random engine for SSL connec‐
1223 tions.
1224 If --egd-file is provided several times, the last set value will
1226 be used.
1227 Example:
1229 curl --egd-file /random/here https://example.com
1230 See also --random-file.
1232 --engine <name>
1234 (TLS) Select the OpenSSL crypto engine to use for cipher opera‐
1235 tions. Use --engine list to print a list of build-time supported
1236 engines. Note that not all (and possibly none) of the engines
1237 may be available at runtime.
1238 If --engine is provided several times, the last set value will
1240 be used.
1241 Example:
1243 curl --engine flavor https://example.com
1244 See also --ciphers and --curves.
1246 --etag-compare <file>
1248 (HTTP) This option makes a conditional HTTP request for the spe‐
1249 cific ETag read from the given file by sending a custom If-None-
1250 Match header using the stored ETag.
1251 For correct results, make sure that the specified file contains
1253 only a single line with the desired ETag. An empty file is
1254 parsed as an empty ETag.
1255 Use the option --etag-save to first save the ETag from a re‐
1257 sponse, and then use this option to compare against the saved
1258 ETag in a subsequent request.
1259 If --etag-compare is provided several times, the last set value
1261 will be used.
1262 Example:
1264 curl --etag-compare etag.txt https://example.com
1265 See also --etag-save and -z, --time-cond. Added in 7.68.0.
1267 --etag-save <file>
1269 (HTTP) This option saves an HTTP ETag to the specified file. An
1270 ETag is a caching related header, usually returned in a re‐
1271 sponse.
1272 If no ETag is sent by the server, an empty file is created.
1274 If --etag-save is provided several times, the last set value
1276 will be used.
1277 Example:
1279 curl --etag-save storetag.txt https://example.com
1280 See also --etag-compare. Added in 7.68.0.
1282 --expect100-timeout <seconds>
1284 (HTTP) Maximum time in seconds that you allow curl to wait for a
1285 100-continue response when curl emits an Expects: 100-continue
1286 header in its request. By default curl will wait one second.
1287 This option accepts decimal values! When curl stops waiting, it
1288 will continue as if the response has been received.
1289 The decimal value needs to provided using a dot (.) as decimal
1291 separator - not the local version even if it might be using an‐
1292 other separator.
1293 If --expect100-timeout is provided several times, the last set
1295 value will be used.
1296 Example:
1298 curl --expect100-timeout 2.5 -T file https://example.com
1299 See also --connect-timeout. Added in 7.47.0.
1301 --fail-early
1303 Fail and exit on the first detected transfer error.
1304 When curl is used to do multiple transfers on the command line,
1306 it will attempt to operate on each given URL, one by one. By de‐
1307 fault, it will ignore errors if there are more URLs given and
1308 the last URL's success will determine the error code curl re‐
1309 turns. So early failures will be "hidden" by subsequent success‐
1310 ful transfers.
1311 Using this option, curl will instead return an error on the
1313 first transfer that fails, independent of the amount of URLs
1314 that are given on the command line. This way, no transfer fail‐
1315 ures go undetected by scripts and similar.
1316 This option does not imply -f, --fail, which causes transfers to
1318 fail due to the server's HTTP status code. You can combine the
1319 two options, however note -f, --fail is not global and is there‐
1320 fore contained by -:, --next.
1321 This option is global and does not need to be specified for each
1323 use of --next.
1324 Providing --fail-early multiple times has no extra effect. Dis‐
1326 able it again with --no-fail-early.
1327 Example:
1329 curl --fail-early https://example.com https://two.example
1330 See also -f, --fail and --fail-with-body. Added in 7.52.0.
1332 --fail-with-body
1334 (HTTP) Return an error on server errors where the HTTP response
1335 code is 400 or greater). In normal cases when an HTTP server
1336 fails to deliver a document, it returns an HTML document stating
1337 so (which often also describes why and more). This flag will
1338 still allow curl to output and save that content but also to re‐
1339 turn error 22.
1340 This is an alternative option to -f, --fail which makes curl
1342 fail for the same circumstances but without saving the content.
1343 Providing --fail-with-body multiple times has no extra effect.
1345 Disable it again with --no-fail-with-body.
1346 Example:
1348 curl --fail-with-body https://example.com
1349 See also -f, --fail. This option is mutually exclusive to -f,
1351 --fail. Added in 7.76.0.
1352 -f, --fail
1354 (HTTP) Fail fast with no output at all on server errors. This is
1355 useful to enable scripts and users to better deal with failed
1356 attempts. In normal cases when an HTTP server fails to deliver a
1357 document, it returns an HTML document stating so (which often
1358 also describes why and more). This flag will prevent curl from
1359 outputting that and return error 22.
1360 This method is not fail-safe and there are occasions where non-
1362 successful response codes will slip through, especially when au‐
1363 thentication is involved (response codes 401 and 407).
1364 Providing -f, --fail multiple times has no extra effect. Dis‐
1366 able it again with --no-fail.
1367 Example:
1369 curl --fail https://example.com
1370 See also --fail-with-body. This option is mutually exclusive to
1372 --fail-with-body.
1373 --false-start
1375 (TLS) Tells curl to use false start during the TLS handshake.
1376 False start is a mode where a TLS client will start sending ap‐
1377 plication data before verifying the server's Finished message,
1378 thus saving a round trip when performing a full handshake.
1379 This is currently only implemented in the NSS and Secure Trans‐
1381 port (on iOS 7.0 or later, or OS X 10.9 or later) backends.
1382 Providing --false-start multiple times has no extra effect.
1384 Disable it again with --no-false-start.
1385 Example:
1387 curl --false-start https://example.com
1388 See also --tcp-fastopen. Added in 7.42.0.
1390 --form-escape
1392 (HTTP) Tells curl to pass on names of multipart form fields and
1393 files using backslash-escaping instead of percent-encoding.
1394 If --form-escape is provided several times, the last set value
1396 will be used.
1397 Example:
1399 curl --form-escape -F 'field\name=curl' -F 'file=@load"this' https://example.com
1400 See also -F, --form. Added in 7.81.0.
1402 --form-string <name=string>
1404 (HTTP SMTP IMAP) Similar to -F, --form except that the value
1405 string for the named parameter is used literally. Leading '@'
1406 and '<' characters, and the ';type=' string in the value have no
1407 special meaning. Use this in preference to -F, --form if there's
1408 any possibility that the string value may accidentally trigger
1409 the '@' or '<' features of -F, --form.
1410 --form-string can be used several times in a command line
1412 Example:
1414 curl --form-string "data" https://example.com
1415 See also -F, --form.
1417 -F, --form <name=content>
1419 (HTTP SMTP IMAP) For HTTP protocol family, this lets curl emu‐
1420 late a filled-in form in which a user has pressed the submit
1421 button. This causes curl to POST data using the Content-Type
1422 multipart/form-data according to RFC 2388.
1423 For SMTP and IMAP protocols, this is the means to compose a mul‐
1425 tipart mail message to transmit.
1426 This enables uploading of binary files etc. To force the 'con‐
1428 tent' part to be a file, prefix the file name with an @ sign. To
1429 just get the content part from a file, prefix the file name with
1430 the symbol <. The difference between @ and < is then that @
1431 makes a file get attached in the post as a file upload, while
1432 the < makes a text field and just get the contents for that text
1433 field from a file.
1434 Tell curl to read content from stdin instead of a file by using
1436 - as filename. This goes for both @ and < constructs. When stdin
1437 is used, the contents is buffered in memory first by curl to de‐
1438 termine its size and allow a possible resend. Defining a part's
1439 data from a named non-regular file (such as a named pipe or sim‐
1440 ilar) is unfortunately not subject to buffering and will be ef‐
1441 fectively read at transmission time; since the full size is un‐
1442 known before the transfer starts, such data is sent as chunks by
1443 HTTP and rejected by IMAP.
1444 Example: send an image to an HTTP server, where 'profile' is the
1446 name of the form-field to which the file portrait.jpg will be
1447 the input:
1448 curl -F profile=@portrait.jpg https://example.com/upload.cgi
1450 Example: send your name and shoe size in two text fields to the
1452 server:
1453 curl -F name=John -F shoesize=11 https://example.com/
1455 Example: send your essay in a text field to the server. Send it
1457 as a plain text field, but get the contents for it from a local
1458 file:
1459 curl -F "story=<hugefile.txt" https://example.com/
1461 You can also tell curl what Content-Type to use by using
1463 'type=', in a manner similar to:
1464 curl -F "web=@index.html;type=text/html" example.com
1466 or
1468 curl -F "name=daniel;type=text/foo" example.com
1470 You can also explicitly change the name field of a file upload
1472 part by setting filename=, like this:
1473 curl -F "file=@localfile;filename=nameinpost" example.com
1475 If filename/path contains ',' or ';', it must be quoted by dou‐
1477 ble-quotes like:
1478 curl -F "file=@\"local,file\";filename=\"name;in;post\"" example.com
1480 or
1482 curl -F 'file=@"local,file";filename="name;in;post"' example.com
1484 Note that if a filename/path is quoted by double-quotes, any
1486 double-quote or backslash within the filename must be escaped by
1487 backslash.
1488 Quoting must also be applied to non-file data if it contains
1490 semicolons, leading/trailing spaces or leading double quotes:
1491 curl -F 'colors="red; green; blue";type=text/x-myapp' example.com
1493 You can add custom headers to the field by setting headers=,
1495 like
1496 curl -F "submit=OK;headers=\"X-submit-type: OK\"" example.com
1498 or
1500 curl -F "submit=OK;headers=@headerfile" example.com
1502 The headers= keyword may appear more that once and above notes
1504 about quoting apply. When headers are read from a file, Empty
1505 lines and lines starting with '#' are comments and ignored; each
1506 header can be folded by splitting between two words and starting
1507 the continuation line with a space; embedded carriage-returns
1508 and trailing spaces are stripped. Here is an example of a
1509 header file contents:
1510 # This file contain two headers.
1512 X-header-1: this is a header
1513 # The following header is folded.
1515 X-header-2: this is
1516 another header
1517 To support sending multipart mail messages, the syntax is ex‐
1519 tended as follows:
1520 - name can be omitted: the equal sign is the first character of
1521 the argument,
1522 - if data starts with '(', this signals to start a new multi‐
1523 part: it can be followed by a content type specification.
1524 - a multipart can be terminated with a '=)' argument.
1525 Example: the following command sends an SMTP mime email consist‐
1527 ing in an inline part in two alternative formats: plain text and
1528 HTML. It attaches a text file:
1529 curl -F '=(;type=multipart/alternative' \
1531 -F '=plain text message' \
1532 -F '= <body>HTML message</body>;type=text/html' \
1533 -F '=)' -F '=@textfile.txt' ... smtp://example.com
1534 Data can be encoded for transfer using encoder=. Available en‐
1536 codings are binary and 8bit that do nothing else than adding the
1537 corresponding Content-Transfer-Encoding header, 7bit that only
1538 rejects 8-bit characters with a transfer error, quoted-printable
1539 and base64 that encodes data according to the corresponding
1540 schemes, limiting lines length to 76 characters.
1541 Example: send multipart mail with a quoted-printable text mes‐
1543 sage and a base64 attached file:
1544 curl -F '=text message;encoder=quoted-printable' \
1546 -F '=@localfile;encoder=base64' ... smtp://example.com
1547 See further examples and details in the MANUAL.
1549 -F, --form can be used several times in a command line
1551 Example:
1553 curl --form "name=curl" --form "file=@loadthis" https://example.com
1554 See also -d, --data, --form-string and --form-escape. This op‐
1556 tion is mutually exclusive to -d, --data and -I, --head and -T,
1557 --upload-file.
1558 --ftp-account <data>
1560 (FTP) When an FTP server asks for "account data" after user name
1561 and password has been provided, this data is sent off using the
1562 ACCT command.
1563 If --ftp-account is provided several times, the last set value
1565 will be used.
1566 Example:
1568 curl --ftp-account "mr.robot" ftp://example.com/
1569 See also -u, --user.
1571 --ftp-alternative-to-user <command>
1573 (FTP) If authenticating with the USER and PASS commands fails,
1574 send this command. When connecting to Tumbleweed's Secure
1575 Transport server over FTPS using a client certificate, using
1576 "SITE AUTH" will tell the server to retrieve the username from
1577 the certificate.
1578 If --ftp-alternative-to-user is provided several times, the last
1580 set value will be used.
1581 Example:
1583 curl --ftp-alternative-to-user "U53r" ftp://example.com
1584 See also --ftp-account and -u, --user.
1586 --ftp-create-dirs
1588 (FTP SFTP) When an FTP or SFTP URL/operation uses a path that
1589 does not currently exist on the server, the standard behavior of
1590 curl is to fail. Using this option, curl will instead attempt to
1591 create missing directories.
1592 Providing --ftp-create-dirs multiple times has no extra effect.
1594 Disable it again with --no-ftp-create-dirs.
1595 Example:
1597 curl --ftp-create-dirs -T file ftp://example.com/remote/path/file
1598 See also --create-dirs.
1600 --ftp-method <method>
1602 (FTP) Control what method curl should use to reach a file on an
1603 FTP(S) server. The method argument should be one of the follow‐
1604 ing alternatives:
1605 multicwd
1607 curl does a single CWD operation for each path part in
1608 the given URL. For deep hierarchies this means many com‐
1609 mands. This is how RFC 1738 says it should be done. This
1610 is the default but the slowest behavior.
1611 nocwd curl does no CWD at all. curl will do SIZE, RETR, STOR
1613 etc and give a full path to the server for all these com‐
1614 mands. This is the fastest behavior.
1615 singlecwd
1617 curl does one CWD with the full target directory and then
1618 operates on the file "normally" (like in the multicwd
1619 case). This is somewhat more standards compliant than
1620 'nocwd' but without the full penalty of 'multicwd'.
1621 If --ftp-method is provided several times, the last set value
1623 will be used.
1624 Examples:
1626 curl --ftp-method multicwd ftp://example.com/dir1/dir2/file
1627 curl --ftp-method nocwd ftp://example.com/dir1/dir2/file
1628 curl --ftp-method singlecwd ftp://example.com/dir1/dir2/file
1629 See also -l, --list-only.
1631 --ftp-pasv
1633 (FTP) Use passive mode for the data connection. Passive is the
1634 internal default behavior, but using this option can be used to
1635 override a previous -P, --ftp-port option.
1636 Reversing an enforced passive really is not doable but you must
1638 then instead enforce the correct -P, --ftp-port again.
1639 Passive mode means that curl will try the EPSV command first and
1641 then PASV, unless --disable-epsv is used.
1642 Providing --ftp-pasv multiple times has no extra effect. Dis‐
1644 able it again with --no-ftp-pasv.
1645 Example:
1647 curl --ftp-pasv ftp://example.com/
1648 See also --disable-epsv.
1650 -P, --ftp-port <address>
1652 (FTP) Reverses the default initiator/listener roles when con‐
1653 necting with FTP. This option makes curl use active mode. curl
1654 then tells the server to connect back to the client's specified
1655 address and port, while passive mode asks the server to setup an
1656 IP address and port for it to connect to. <address> should be
1657 one of:
1658 interface
1660 e.g. "eth0" to specify which interface's IP address you
1661 want to use (Unix only)
1662 IP address
1664 e.g. "192.168.10.1" to specify the exact IP address
1665 host name
1667 e.g. "my.host.domain" to specify the machine
1668 - make curl pick the same IP address that is already used
1670 for the control connection
1671 Disable the use of PORT with --ftp-pasv. Disable the attempt to
1673 use the EPRT command instead of PORT by using --disable-eprt.
1674 EPRT is really PORT++.
1675 You can also append ":[start]-[end]" to the right of the ad‐
1677 dress, to tell curl what TCP port range to use. That means you
1678 specify a port range, from a lower to a higher number. A single
1679 number works as well, but do note that it increases the risk of
1680 failure since the port may not be available.
1681 If -P, --ftp-port is provided several times, the last set value
1684 will be used.
1685 Examples:
1687 curl -P - ftp:/example.com
1688 curl -P eth0 ftp:/example.com
1689 curl -P 192.168.0.2 ftp:/example.com
1690 See also --ftp-pasv and --disable-eprt.
1692 --ftp-pret
1694 (FTP) Tell curl to send a PRET command before PASV (and EPSV).
1695 Certain FTP servers, mainly drftpd, require this non-standard
1696 command for directory listings as well as up and downloads in
1697 PASV mode.
1698 Providing --ftp-pret multiple times has no extra effect. Dis‐
1700 able it again with --no-ftp-pret.
1701 Example:
1703 curl --ftp-pret ftp://example.com/
1704 See also -P, --ftp-port and --ftp-pasv.
1706 --ftp-skip-pasv-ip
1708 (FTP) Tell curl to not use the IP address the server suggests in
1709 its response to curl's PASV command when curl connects the data
1710 connection. Instead curl will re-use the same IP address it al‐
1711 ready uses for the control connection.
1712 Since curl 7.74.0 this option is enabled by default.
1714 This option has no effect if PORT, EPRT or EPSV is used instead
1716 of PASV.
1717 Providing --ftp-skip-pasv-ip multiple times has no extra effect.
1719 Disable it again with --no-ftp-skip-pasv-ip.
1720 Example:
1722 curl --ftp-skip-pasv-ip ftp://example.com/
1723 See also --ftp-pasv.
1725 --ftp-ssl-ccc-mode <active/passive>
1727 (FTP) Sets the CCC mode. The passive mode will not initiate the
1728 shutdown, but instead wait for the server to do it, and will not
1729 reply to the shutdown from the server. The active mode initiates
1730 the shutdown and waits for a reply from the server.
1731 Providing --ftp-ssl-ccc-mode multiple times has no extra effect.
1733 Disable it again with --no-ftp-ssl-ccc-mode.
1734 Example:
1736 curl --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/
1737 See also --ftp-ssl-ccc.
1739 --ftp-ssl-ccc
1741 (FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS
1742 layer after authenticating. The rest of the control channel com‐
1743 munication will be unencrypted. This allows NAT routers to fol‐
1744 low the FTP transaction. The default mode is passive.
1745 Providing --ftp-ssl-ccc multiple times has no extra effect.
1747 Disable it again with --no-ftp-ssl-ccc.
1748 Example:
1750 curl --ftp-ssl-ccc ftps://example.com/
1751 See also --ssl and --ftp-ssl-ccc-mode.
1753 --ftp-ssl-control
1755 (FTP) Require SSL/TLS for the FTP login, clear for transfer.
1756 Allows secure authentication, but non-encrypted data transfers
1757 for efficiency. Fails the transfer if the server does not sup‐
1758 port SSL/TLS.
1759 Providing --ftp-ssl-control multiple times has no extra effect.
1761 Disable it again with --no-ftp-ssl-control.
1762 Example:
1764 curl --ftp-ssl-control ftp://example.com
1765 See also --ssl.
1767 -G, --get
1769 When used, this option will make all data specified with -d,
1770 --data, --data-binary or --data-urlencode to be used in an HTTP
1771 GET request instead of the POST request that otherwise would be
1772 used. The data will be appended to the URL with a '?' separator.
1773 If used in combination with -I, --head, the POST data will in‐
1775 stead be appended to the URL with a HEAD request.
1776 Providing -G, --get multiple times has no extra effect. Disable
1778 it again with --no-get.
1779 Examples:
1781 curl --get https://example.com
1782 curl --get -d "tool=curl" -d "age=old" https://example.com
1783 curl --get -I -d "tool=curl" https://example.com
1784 See also -d, --data and -X, --request.
1786 -g, --globoff
1788 This option switches off the "URL globbing parser". When you set
1789 this option, you can specify URLs that contain the letters {}[]
1790 without having curl itself interpret them. Note that these let‐
1791 ters are not normal legal URL contents but they should be en‐
1792 coded according to the URI standard.
1793 Providing -g, --globoff multiple times has no extra effect.
1795 Disable it again with --no-globoff.
1796 Example:
1798 curl -g "https://example.com/{[]}}}}"
1799 See also -K, --config and -q, --disable.
1801 --happy-eyeballs-timeout-ms <milliseconds>
1803 Happy Eyeballs is an algorithm that attempts to connect to both
1804 IPv4 and IPv6 addresses for dual-stack hosts, giving IPv6 a
1805 head-start of the specified number of milliseconds. If the IPv6
1806 address cannot be connected to within that time, then a connec‐
1807 tion attempt is made to the IPv4 address in parallel. The first
1808 connection to be established is the one that is used.
1809 The range of suggested useful values is limited. Happy Eyeballs
1811 RFC 6555 says "It is RECOMMENDED that connection attempts be
1812 paced 150-250 ms apart to balance human factors against network
1813 load." libcurl currently defaults to 200 ms. Firefox and Chrome
1814 currently default to 300 ms.
1815 If --happy-eyeballs-timeout-ms is provided several times, the
1817 last set value will be used.
1818 Example:
1820 curl --happy-eyeballs-timeout-ms 500 https://example.com
1821 See also -m, --max-time and --connect-timeout. Added in 7.59.0.
1823 --haproxy-clientip
1825 (HTTP) Sets a client IP in HAProxy PROXY protocol v1 header at
1826 the beginning of the connection.
1827 For valid requests, IPv4 addresses must be indicated as a series
1829 of exactly 4 integers in the range [0..255] inclusive written in
1830 decimal representation separated by exactly one dot between each
1831 other. Heading zeroes are not permitted in front of numbers in
1832 order to avoid any possible confusion with octal numbers. IPv6
1833 addresses must be indicated as series of 4 hexadecimal digits
1834 (upper or lower case) delimited by colons between each other,
1835 with the acceptance of one double colon sequence to replace the
1836 largest acceptable range of consecutive zeroes. The total number
1837 of decoded bits must exactly be 128.
1838 Otherwise, any string can be accepted for the client IP and will
1840 be sent.
1841 It replaces `--haproxy-protocol` if used, it is not necessary to
1843 specify both flags.
1844 This option is primarily useful when sending test requests to
1846 verify a service is working as intended.
1847 If --haproxy-clientip is provided several times, the last set
1849 value will be used.
1850 Example:
1852 curl --haproxy-clientip $IP
1853 See also -x, --proxy. Added in 8.2.0.
1855 --haproxy-protocol
1857 (HTTP) Send a HAProxy PROXY protocol v1 header at the beginning
1858 of the connection. This is used by some load balancers and re‐
1859 verse proxies to indicate the client's true IP address and port.
1860 This option is primarily useful when sending test requests to a
1862 service that expects this header.
1863 Providing --haproxy-protocol multiple times has no extra effect.
1865 Disable it again with --no-haproxy-protocol.
1866 Example:
1868 curl --haproxy-protocol https://example.com
1869 See also -x, --proxy. Added in 7.60.0.
1871 -I, --head
1873 (HTTP FTP FILE) Fetch the headers only! HTTP-servers feature the
1874 command HEAD which this uses to get nothing but the header of a
1875 document. When used on an FTP or FILE file, curl displays the
1876 file size and last modification time only.
1877 Providing -I, --head multiple times has no extra effect. Dis‐
1879 able it again with --no-head.
1880 Example:
1882 curl -I https://example.com
1883 See also -G, --get, -v, --verbose and --trace-ascii.
1885 -H, --header <header/@file>
1887 (HTTP IMAP SMTP) Extra header to include in information sent.
1888 When used within an HTTP request, it is added to the regular re‐
1889 quest headers.
1890 For an IMAP or SMTP MIME uploaded mail built with -F, --form op‐
1892 tions, it is prepended to the resulting MIME document, effec‐
1893 tively including it at the mail global level. It does not affect
1894 raw uploaded mails (Added in 7.56.0).
1895 You may specify any number of extra headers. Note that if you
1897 should add a custom header that has the same name as one of the
1898 internal ones curl would use, your externally set header will be
1899 used instead of the internal one. This allows you to make even
1900 trickier stuff than curl would normally do. You should not re‐
1901 place internally set headers without knowing perfectly well what
1902 you are doing. Remove an internal header by giving a replacement
1903 without content on the right side of the colon, as in: -H
1904 "Host:". If you send the custom header with no-value then its
1905 header must be terminated with a semicolon, such as -H "X-Cus‐
1906 tom-Header;" to send "X-Custom-Header:".
1907 curl will make sure that each header you add/replace is sent
1909 with the proper end-of-line marker, you should thus not add that
1910 as a part of the header content: do not add newlines or carriage
1911 returns, they will only mess things up for you.
1912 This option can take an argument in @filename style, which then
1914 adds a header for each line in the input file. Using @- will
1915 make curl read the header file from stdin. Added in 7.55.0.
1916 Please note that most anti-spam utilities check the presence and
1918 value of several MIME mail headers: these are "From:", "To:",
1919 "Date:" and "Subject:" among others and should be added with
1920 this option.
1921 You need --proxy-header to send custom headers intended for an
1923 HTTP proxy. Added in 7.37.0.
1924 Passing on a "Transfer-Encoding: chunked" header when doing an
1926 HTTP request with a request body, will make curl send the data
1927 using chunked encoding.
1928 WARNING: headers set with this option will be set in all HTTP
1930 requests - even after redirects are followed, like when told
1931 with -L, --location. This can lead to the header being sent to
1932 other hosts than the original host, so sensitive headers should
1933 be used with caution combined with following redirects.
1934 -H, --header can be used several times in a command line
1936 Examples:
1938 curl -H "X-First-Name: Joe" https://example.com
1939 curl -H "User-Agent: yes-please/2000" https://example.com
1940 curl -H "Host:" https://example.com
1941 curl -H @headers.txt https://example.com
1942 See also -A, --user-agent and -e, --referer.
1944 -h, --help <category>
1946 Usage help. This lists all commands of the <category>. If no
1947 arg was provided, curl will display the most important command
1948 line arguments. If the argument "all" was provided, curl will
1949 display all options available. If the argument "category" was
1950 provided, curl will display all categories and their meanings.
1951 Example:
1953 curl --help all
1954 See also -v, --verbose.
1956 --hostpubmd5 <md5>
1958 (SFTP SCP) Pass a string containing 32 hexadecimal digits. The
1959 string should be the 128 bit MD5 checksum of the remote host's
1960 public key, curl will refuse the connection with the host unless
1961 the md5sums match.
1962 If --hostpubmd5 is provided several times, the last set value
1964 will be used.
1965 Example:
1967 curl --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/
1968 See also --hostpubsha256.
1970 --hostpubsha256 <sha256>
1972 (SFTP SCP) Pass a string containing a Base64-encoded SHA256 hash
1973 of the remote host's public key. Curl will refuse the connection
1974 with the host unless the hashes match.
1975 This feature requires libcurl to be built with libssh2 and does
1977 not work with other SSH backends.
1978 If --hostpubsha256 is provided several times, the last set value
1980 will be used.
1981 Example:
1983 curl --hostpubsha256 NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ= sftp://example.com/
1984 See also --hostpubmd5. Added in 7.80.0.
1986 --hsts <file name>
1988 (HTTPS) This option enables HSTS for the transfer. If the file
1989 name points to an existing HSTS cache file, that will be used.
1990 After a completed transfer, the cache will be saved to the file
1991 name again if it has been modified.
1992 If curl is told to use HTTP:// for a transfer involving a host
1994 name that exists in the HSTS cache, it upgrades the transfer to
1995 use HTTPS. Each HSTS cache entry has an individual life time af‐
1996 ter which the upgrade is no longer performed.
1997 Specify a "" file name (zero length) to avoid loading/saving and
1999 make curl just handle HSTS in memory.
2000 If this option is used several times, curl will load contents
2002 from all the files but the last one will be used for saving.
2003 --hsts can be used several times in a command line
2005 Example:
2007 curl --hsts cache.txt https://example.com
2008 See also --proto. Added in 7.74.0.
2010 --http0.9
2012 (HTTP) Tells curl to be fine with HTTP version 0.9 response.
2013 HTTP/0.9 is a completely headerless response and therefore you
2015 can also connect with this to non-HTTP servers and still get a
2016 response since curl will simply transparently downgrade - if al‐
2017 lowed.
2018 Since curl 7.66.0, HTTP/0.9 is disabled by default.
2020 Providing --http0.9 multiple times has no extra effect. Disable
2022 it again with --no-http0.9.
2023 Example:
2025 curl --http0.9 https://example.com
2026 See also --http1.1, --http2 and --http3. Added in 7.64.0.
2028 -0, --http1.0
2030 (HTTP) Tells curl to use HTTP version 1.0 instead of using its
2031 internally preferred HTTP version.
2032 Providing -0, --http1.0 multiple times has no extra effect.
2034 Example:
2036 curl --http1.0 https://example.com
2037 See also --http0.9 and --http1.1. This option is mutually exclu‐
2039 sive to --http1.1 and --http2 and --http2-prior-knowledge and
2040 --http3.
2041 --http1.1
2043 (HTTP) Tells curl to use HTTP version 1.1.
2044 Providing --http1.1 multiple times has no extra effect.
2046 Example:
2048 curl --http1.1 https://example.com
2049 See also -0, --http1.0 and --http0.9. This option is mutually
2051 exclusive to -0, --http1.0 and --http2 and --http2-prior-knowl‐
2052 edge and --http3. Added in 7.33.0.
2053 --http2-prior-knowledge
2055 (HTTP) Tells curl to issue its non-TLS HTTP requests using
2056 HTTP/2 without HTTP/1.1 Upgrade. It requires prior knowledge
2057 that the server supports HTTP/2 straight away. HTTPS requests
2058 will still do HTTP/2 the standard way with negotiated protocol
2059 version in the TLS handshake.
2060 Providing --http2-prior-knowledge multiple times has no extra
2062 effect. Disable it again with --no-http2-prior-knowledge.
2063 Example:
2065 curl --http2-prior-knowledge https://example.com
2066 See also --http2 and --http3. --http2-prior-knowledge requires
2068 that the underlying libcurl was built to support HTTP/2. This
2069 option is mutually exclusive to --http1.1 and -0, --http1.0 and
2070 --http2 and --http3. Added in 7.49.0.
2071 --http2
2073 (HTTP) Tells curl to use HTTP version 2.
2074 For HTTPS, this means curl will attempt to negotiate HTTP/2 in
2076 the TLS handshake. curl does this by default.
2077 For HTTP, this means curl will attempt to upgrade the request to
2079 HTTP/2 using the Upgrade: request header.
2080 When curl uses HTTP/2 over HTTPS, it does not itself insist on
2082 TLS 1.2 or higher even though that is required by the specifica‐
2083 tion. A user can add this version requirement with --tlsv1.2.
2084 Providing --http2 multiple times has no extra effect.
2086 Example:
2088 curl --http2 https://example.com
2089 See also --http1.1, --http3 and --no-alpn. --http2 requires that
2091 the underlying libcurl was built to support HTTP/2. This option
2092 is mutually exclusive to --http1.1 and -0, --http1.0 and
2093 --http2-prior-knowledge and --http3. Added in 7.33.0.
2094 --http3-only
2096 (HTTP) **WARNING**: this option is experimental. Do not use in
2097 production.
2098 Instructs curl to use HTTP/3 to the host in the URL, with no
2100 fallback to earlier HTTP versions. HTTP/3 can only be used for
2101 HTTPS and not for HTTP URLs. For HTTP, this option will trigger
2102 an error.
2103 This option allows a user to avoid using the Alt-Svc method of
2105 upgrading to HTTP/3 when you know that the target speaks HTTP/3
2106 on the given host and port.
2107 This option will make curl fail if a QUIC connection cannot be
2109 established, it will not attempt any other HTTP version on its
2110 own. Use --http3 for similar functionality with a fallback.
2111 Providing --http3-only multiple times has no extra effect.
2113 Example:
2115 curl --http3-only https://example.com
2116 See also --http1.1, --http2 and --http3. --http3-only requires
2118 that the underlying libcurl was built to support HTTP/3. This
2119 option is mutually exclusive to --http1.1 and -0, --http1.0 and
2120 --http2 and --http2-prior-knowledge and --http3. Added in
2121 7.88.0.
2122 --http3
2124 (HTTP) **WARNING**: this option is experimental. Do not use in
2125 production.
2126 Tells curl to try HTTP/3 to the host in the URL, but fallback to
2128 earlier HTTP versions if the HTTP/3 connection establishment
2129 fails. HTTP/3 is only available for HTTPS and not for HTTP URLs.
2130 This option allows a user to avoid using the Alt-Svc method of
2132 upgrading to HTTP/3 when you know that the target speaks HTTP/3
2133 on the given host and port.
2134 When asked to use HTTP/3, curl will issue a separate attempt to
2136 use older HTTP versions with a slight delay, so if the HTTP/3
2137 transfer fails or is very slow, curl will still try to proceed
2138 with an older HTTP version.
2139 Use --http3-only for similar functionality without a fallback.
2141 Providing --http3 multiple times has no extra effect.
2143 Example:
2145 curl --http3 https://example.com
2146 See also --http1.1 and --http2. --http3 requires that the under‐
2148 lying libcurl was built to support HTTP/3. This option is mutu‐
2149 ally exclusive to --http1.1 and -0, --http1.0 and --http2 and
2150 --http2-prior-knowledge and --http3-only. Added in 7.66.0.
2151 --ignore-content-length
2153 (FTP HTTP) For HTTP, Ignore the Content-Length header. This is
2154 particularly useful for servers running Apache 1.x, which will
2155 report incorrect Content-Length for files larger than 2 giga‐
2156 bytes.
2157 For FTP (since 7.46.0), skip the RETR command to figure out the
2159 size before downloading a file.
2160 This option does not work for HTTP if libcurl was built to use
2162 hyper.
2163 Providing --ignore-content-length multiple times has no extra
2165 effect. Disable it again with --no-ignore-content-length.
2166 Example:
2168 curl --ignore-content-length https://example.com
2169 See also --ftp-skip-pasv-ip.
2171 -i, --include
2173 Include the HTTP response headers in the output. The HTTP re‐
2174 sponse headers can include things like server name, cookies,
2175 date of the document, HTTP version and more...
2176 To view the request headers, consider the -v, --verbose option.
2178 Providing -i, --include multiple times has no extra effect.
2180 Disable it again with --no-include.
2181 Example:
2183 curl -i https://example.com
2184 See also -v, --verbose.
2186 -k, --insecure
2188 (TLS SFTP SCP) By default, every secure connection curl makes is
2189 verified to be secure before the transfer takes place. This op‐
2190 tion makes curl skip the verification step and proceed without
2191 checking.
2192 When this option is not used for protocols using TLS, curl veri‐
2194 fies the server's TLS certificate before it continues: that the
2195 certificate contains the right name which matches the host name
2196 used in the URL and that the certificate has been signed by a CA
2197 certificate present in the cert store. See this online resource
2198 for further details:
2199 https://curl.se/docs/sslcerts.html
2200 For SFTP and SCP, this option makes curl skip the known_hosts
2202 verification. known_hosts is a file normally stored in the
2203 user's home directory in the ".ssh" subdirectory, which contains
2204 host names and their public keys.
2205 WARNING: using this option makes the transfer insecure.
2207 When curl uses secure protocols it trusts responses and allows
2209 for example HSTS and Alt-Svc information to be stored and used
2210 subsequently. Using -k, --insecure can make curl trust and use
2211 such information from malicious servers.
2212 Providing -k, --insecure multiple times has no extra effect.
2214 Disable it again with --no-insecure.
2215 Example:
2217 curl --insecure https://example.com
2218 See also --proxy-insecure, --cacert and --capath.
2220 --interface <name>
2222 Perform an operation using a specified interface. You can enter
2223 interface name, IP address or host name. An example could look
2224 like:
2225 curl --interface eth0:1 https://www.example.com/
2227 On Linux it can be used to specify a VRF, but the binary needs
2229 to either have CAP_NET_RAW or to be run as root. More informa‐
2230 tion about Linux VRF: https://www.kernel.org/doc/Documenta‐
2231 tion/networking/vrf.txt
2232 If --interface is provided several times, the last set value
2234 will be used.
2235 Example:
2237 curl --interface eth0 https://example.com
2238 See also --dns-interface.
2240 -4, --ipv4
2242 This option tells curl to use IPv4 addresses only when resolving
2243 host names, and not for example try IPv6.
2244 Providing -4, --ipv4 multiple times has no extra effect.
2246 Example:
2248 curl --ipv4 https://example.com
2249 See also --http1.1 and --http2. This option is mutually exclu‐
2251 sive to -6, --ipv6.
2252 -6, --ipv6
2254 This option tells curl to use IPv6 addresses only when resolving
2255 host names, and not for example try IPv4.
2256 Providing -6, --ipv6 multiple times has no extra effect.
2258 Example:
2260 curl --ipv6 https://example.com
2261 See also --http1.1 and --http2. This option is mutually exclu‐
2263 sive to -4, --ipv4.
2264 --json <data>
2266 (HTTP) Sends the specified JSON data in a POST request to the
2267 HTTP server. --json works as a shortcut for passing on these
2268 three options:
2269 --data [arg]
2271 --header "Content-Type: application/json"
2272 --header "Accept: application/json"
2273 There is no verification that the passed in data is actual JSON
2275 or that the syntax is correct.
2276 If you start the data with the letter @, the rest should be a
2278 file name to read the data from, or a single dash (-) if you
2279 want curl to read the data from stdin. Posting data from a file
2280 named 'foobar' would thus be done with --json @foobar and to in‐
2281 stead read the data from stdin, use --json @-.
2282 If this option is used more than once on the same command line,
2284 the additional data pieces will be concatenated to the previous
2285 before sending.
2286 The headers this option sets can be overridden with -H, --header
2288 as usual.
2289 --json can be used several times in a command line
2291 Examples:
2293 curl --json '{ "drink": "coffe" }' https://example.com
2294 curl --json '{ "drink":' --json ' "coffe" }' https://example.com
2295 curl --json @prepared https://example.com
2296 curl --json @- https://example.com < json.txt
2297 See also --data-binary and --data-raw. This option is mutually
2299 exclusive to -F, --form and -I, --head and -T, --upload-file.
2300 Added in 7.82.0.
2301 -j, --junk-session-cookies
2303 (HTTP) When curl is told to read cookies from a given file, this
2304 option will make it discard all "session cookies". This will ba‐
2305 sically have the same effect as if a new session is started.
2306 Typical browsers always discard session cookies when they are
2307 closed down.
2308 Providing -j, --junk-session-cookies multiple times has no extra
2310 effect. Disable it again with --no-junk-session-cookies.
2311 Example:
2313 curl --junk-session-cookies -b cookies.txt https://example.com
2314 See also -b, --cookie and -c, --cookie-jar.
2316 --keepalive-time <seconds>
2318 This option sets the time a connection needs to remain idle be‐
2319 fore sending keepalive probes and the time between individual
2320 keepalive probes. It is currently effective on operating systems
2321 offering the TCP_KEEPIDLE and TCP_KEEPINTVL socket options
2322 (meaning Linux, recent AIX, HP-UX and more). Keepalives are
2323 used by the TCP stack to detect broken networks on idle connec‐
2324 tions. The number of missed keepalive probes before declaring
2325 the connection down is OS dependent and is commonly 9 or 10.
2326 This option has no effect if --no-keepalive is used.
2327 If unspecified, the option defaults to 60 seconds.
2329 If --keepalive-time is provided several times, the last set
2331 value will be used.
2332 Example:
2334 curl --keepalive-time 20 https://example.com
2335 See also --no-keepalive and -m, --max-time.
2337 --key-type <type>
2339 (TLS) Private key file type. Specify which type your --key pro‐
2340 vided private key is. DER, PEM, and ENG are supported. If not
2341 specified, PEM is assumed.
2342 If --key-type is provided several times, the last set value will
2344 be used.
2345 Example:
2347 curl --key-type DER --key here https://example.com
2348 See also --key.
2350 --key <key>
2352 (TLS SSH) Private key file name. Allows you to provide your pri‐
2353 vate key in this separate file. For SSH, if not specified, curl
2354 tries the following candidates in order: '~/.ssh/id_rsa',
2355 '~/.ssh/id_dsa', './id_rsa', './id_dsa'.
2356 If curl is built against OpenSSL library, and the engine pkcs11
2358 is available, then a PKCS#11 URI (RFC 7512) can be used to spec‐
2359 ify a private key located in a PKCS#11 device. A string begin‐
2360 ning with "pkcs11:" will be interpreted as a PKCS#11 URI. If a
2361 PKCS#11 URI is provided, then the --engine option will be set as
2362 "pkcs11" if none was provided and the --key-type option will be
2363 set as "ENG" if none was provided.
2364 If curl is built against Secure Transport or Schannel then this
2366 option is ignored for TLS protocols (HTTPS, etc). Those backends
2367 expect the private key to be already present in the keychain or
2368 PKCS#12 file containing the certificate.
2369 If --key is provided several times, the last set value will be
2371 used.
2372 Example:
2374 curl --cert certificate --key here https://example.com
2375 See also --key-type and -E, --cert.
2377 --krb <level>
2379 (FTP) Enable Kerberos authentication and use. The level must be
2380 entered and should be one of 'clear', 'safe', 'confidential', or
2381 'private'. Should you use a level that is not one of these,
2382 'private' will instead be used.
2383 If --krb is provided several times, the last set value will be
2385 used.
2386 Example:
2388 curl --krb clear ftp://example.com/
2389 See also --delegation and --ssl. --krb requires that the under‐
2391 lying libcurl was built to support Kerberos.
2392 --libcurl <file>
2394 Append this option to any ordinary curl command line, and you
2395 will get libcurl-using C source code written to the file that
2396 does the equivalent of what your command-line operation does!
2397 This option is global and does not need to be specified for each
2399 use of --next.
2400 If --libcurl is provided several times, the last set value will
2402 be used.
2403 Example:
2405 curl --libcurl client.c https://example.com
2406 See also -v, --verbose.
2408 --limit-rate <speed>
2410 Specify the maximum transfer rate you want curl to use - for
2411 both downloads and uploads. This feature is useful if you have a
2412 limited pipe and you would like your transfer not to use your
2413 entire bandwidth. To make it slower than it otherwise would be.
2414 The given speed is measured in bytes/second, unless a suffix is
2416 appended. Appending 'k' or 'K' will count the number as kilo‐
2417 bytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it
2418 gigabytes. The suffixes (k, M, G, T, P) are 1024 based. For ex‐
2419 ample 1k is 1024. Examples: 200K, 3m and 1G.
2420 The rate limiting logic works on averaging the transfer speed to
2422 no more than the set threshold over a period of multiple sec‐
2423 onds.
2424 If you also use the -Y, --speed-limit option, that option will
2426 take precedence and might cripple the rate-limiting slightly, to
2427 help keeping the speed-limit logic working.
2428 If --limit-rate is provided several times, the last set value
2430 will be used.
2431 Examples:
2433 curl --limit-rate 100K https://example.com
2434 curl --limit-rate 1000 https://example.com
2435 curl --limit-rate 10M https://example.com
2436 See also --rate, -Y, --speed-limit and -y, --speed-time.
2438 -l, --list-only
2440 (FTP POP3) (FTP) When listing an FTP directory, this switch
2441 forces a name-only view. This is especially useful if the user
2442 wants to machine-parse the contents of an FTP directory since
2443 the normal directory view does not use a standard look or for‐
2444 mat. When used like this, the option causes an NLST command to
2445 be sent to the server instead of LIST.
2446 Note: Some FTP servers list only files in their response to
2448 NLST; they do not include sub-directories and symbolic links.
2449 (POP3) When retrieving a specific email from POP3, this switch
2451 forces a LIST command to be performed instead of RETR. This is
2452 particularly useful if the user wants to see if a specific mes‐
2453 sage-id exists on the server and what size it is.
2454 Note: When combined with -X, --request, this option can be used
2456 to send a UIDL command instead, so the user may use the email's
2457 unique identifier rather than its message-id to make the re‐
2458 quest.
2459 Providing -l, --list-only multiple times has no extra effect.
2461 Disable it again with --no-list-only.
2462 Example:
2464 curl --list-only ftp://example.com/dir/
2465 See also -Q, --quote and -X, --request.
2467 --local-port <num/range>
2469 Set a preferred single number or range (FROM-TO) of local port
2470 numbers to use for the connection(s). Note that port numbers by
2471 nature are a scarce resource that will be busy at times so set‐
2472 ting this range to something too narrow might cause unnecessary
2473 connection setup failures.
2474 If --local-port is provided several times, the last set value
2476 will be used.
2477 Example:
2479 curl --local-port 1000-3000 https://example.com
2480 See also -g, --globoff.
2482 --location-trusted
2484 (HTTP) Like -L, --location, but will allow sending the name +
2485 password to all hosts that the site may redirect to. This may or
2486 may not introduce a security breach if the site redirects you to
2487 a site to which you will send your authentication info (which is
2488 plaintext in the case of HTTP Basic authentication).
2489 Providing --location-trusted multiple times has no extra effect.
2491 Disable it again with --no-location-trusted.
2492 Example:
2494 curl --location-trusted -u user:password https://example.com
2495 See also -u, --user.
2497 -L, --location
2499 (HTTP) If the server reports that the requested page has moved
2500 to a different location (indicated with a Location: header and a
2501 3XX response code), this option will make curl redo the request
2502 on the new place. If used together with -i, --include or -I,
2503 --head, headers from all requested pages will be shown. When au‐
2504 thentication is used, curl only sends its credentials to the
2505 initial host. If a redirect takes curl to a different host, it
2506 will not be able to intercept the user+password. See also --lo‐
2507 cation-trusted on how to change this. You can limit the amount
2508 of redirects to follow by using the --max-redirs option.
2509 When curl follows a redirect and if the request is a POST, it
2511 will send the following request with a GET if the HTTP response
2512 was 301, 302, or 303. If the response code was any other 3xx
2513 code, curl will re-send the following request using the same un‐
2514 modified method.
2515 You can tell curl to not change POST requests to GET after a 30x
2517 response by using the dedicated options for that: --post301,
2518 --post302 and --post303.
2519 The method set with -X, --request overrides the method curl
2521 would otherwise select to use.
2522 Providing -L, --location multiple times has no extra effect.
2524 Disable it again with --no-location.
2525 Example:
2527 curl -L https://example.com
2528 See also --resolve and --alt-svc.
2530 --login-options <options>
2532 (IMAP LDAP POP3 SMTP) Specify the login options to use during
2533 server authentication.
2534 You can use login options to specify protocol specific options
2536 that may be used during authentication. At present only IMAP,
2537 POP3 and SMTP support login options. For more information about
2538 login options please see RFC 2384, RFC 5092 and IETF draft
2539 draft-earhart-url-smtp-00.txt
2540 Since 8.2.0, IMAP supports the login option "AUTH=+LOGIN". With
2542 this option, curl uses the plain (not SASL) LOGIN IMAP command
2543 even if the server advertises SASL authentication. Care should
2544 be taken in using this option, as it will send out your password
2545 in plain text. This will not work if the IMAP server disables
2546 the plain LOGIN (e.g. to prevent password snooping).
2547 If --login-options is provided several times, the last set value
2549 will be used.
2550 Example:
2552 curl --login-options 'AUTH=*' imap://example.com
2553 See also -u, --user. Added in 7.34.0.
2555 --mail-auth <address>
2557 (SMTP) Specify a single address. This will be used to specify
2558 the authentication address (identity) of a submitted message
2559 that is being relayed to another server.
2560 If --mail-auth is provided several times, the last set value
2562 will be used.
2563 Example:
2565 curl --mail-auth user@example.come -T mail smtp://example.com/
2566 See also --mail-rcpt and --mail-from.
2568 --mail-from <address>
2570 (SMTP) Specify a single address that the given mail should get
2571 sent from.
2572 If --mail-from is provided several times, the last set value
2574 will be used.
2575 Example:
2577 curl --mail-from user@example.com -T mail smtp://example.com/
2578 See also --mail-rcpt and --mail-auth.
2580 --mail-rcpt-allowfails
2582 (SMTP) When sending data to multiple recipients, by default curl
2583 will abort SMTP conversation if at least one of the recipients
2584 causes RCPT TO command to return an error.
2585 The default behavior can be changed by passing --mail-rcpt-al‐
2587 lowfails command-line option which will make curl ignore errors
2588 and proceed with the remaining valid recipients.
2589 If all recipients trigger RCPT TO failures and this flag is
2591 specified, curl will still abort the SMTP conversation and re‐
2592 turn the error received from to the last RCPT TO command.
2593 Providing --mail-rcpt-allowfails multiple times has no extra ef‐
2595 fect. Disable it again with --no-mail-rcpt-allowfails.
2596 Example:
2598 curl --mail-rcpt-allowfails --mail-rcpt dest@example.com smtp://example.com
2599 See also --mail-rcpt. Added in 7.69.0.
2601 --mail-rcpt <address>
2603 (SMTP) Specify a single email address, user name or mailing list
2604 name. Repeat this option several times to send to multiple re‐
2605 cipients.
2606 When performing an address verification (VRFY command), the re‐
2608 cipient should be specified as the user name or user name and
2609 domain (as per Section 3.5 of RFC 5321). (Added in 7.34.0)
2610 When performing a mailing list expand (EXPN command), the recip‐
2612 ient should be specified using the mailing list name, such as
2613 "Friends" or "London-Office". (Added in 7.34.0)
2614 --mail-rcpt can be used several times in a command line
2616 Example:
2618 curl --mail-rcpt user@example.net smtp://example.com
2619 See also --mail-rcpt-allowfails.
2621 -M, --manual
2623 Manual. Display the huge help text.
2624 Example:
2626 curl --manual
2627 See also -v, --verbose, --libcurl and --trace.
2629 --max-filesize <bytes>
2631 (FTP HTTP MQTT) Specify the maximum size (in bytes) of a file to
2632 download. If the file requested is larger than this value, the
2633 transfer will not start and curl will return with exit code 63.
2634 A size modifier may be used. For example, Appending 'k' or 'K'
2636 will count the number as kilobytes, 'm' or 'M' makes it
2637 megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K,
2638 3m and 1G. (Added in 7.58.0)
2639 NOTE: The file size is not always known prior to download, and
2641 for such files this option has no effect even if the file trans‐
2642 fer ends up being larger than this given limit. If --max-file‐
2643 size is provided several times, the last set value will be used.
2644 Example:
2646 curl --max-filesize 100K https://example.com
2647 See also --limit-rate.
2649 --max-redirs <num>
2651 (HTTP) Set maximum number of redirections to follow. When -L,
2652 --location is used, to prevent curl from following too many
2653 redirects, by default, the limit is set to 50 redirects. Set
2654 this option to -1 to make it unlimited.
2655 If --max-redirs is provided several times, the last set value
2657 will be used.
2658 Example:
2660 curl --max-redirs 3 --location https://example.com
2661 See also -L, --location.
2663 -m, --max-time <fractional seconds>
2665 Maximum time in seconds that you allow each transfer to take.
2666 This is useful for preventing your batch jobs from hanging for
2667 hours due to slow networks or links going down. Since 7.32.0,
2668 this option accepts decimal values, but the actual timeout will
2669 decrease in accuracy as the specified timeout increases in deci‐
2670 mal precision.
2671 If you enable retrying the transfer (--retry) then the maximum
2673 time counter is reset each time the transfer is retried. You can
2674 use --retry-max-time to limit the retry time.
2675 The decimal value needs to provided using a dot (.) as decimal
2677 separator - not the local version even if it might be using an‐
2678 other separator.
2679 If -m, --max-time is provided several times, the last set value
2681 will be used.
2682 Examples:
2684 curl --max-time 10 https://example.com
2685 curl --max-time 2.92 https://example.com
2686 See also --connect-timeout and --retry-max-time.
2688 --metalink
2690 This option was previously used to specify a metalink resource.
2691 Metalink support has been disabled in curl since 7.78.0 for se‐
2692 curity reasons.
2693 If --metalink is provided several times, the last set value will
2695 be used.
2696 Example:
2698 curl --metalink file https://example.com
2699 See also -Z, --parallel.
2701 --negotiate
2703 (HTTP) Enables Negotiate (SPNEGO) authentication.
2704 This option requires a library built with GSS-API or SSPI sup‐
2706 port. Use -V, --version to see if your curl supports GSS-
2707 API/SSPI or SPNEGO.
2708 When using this option, you must also provide a fake -u, --user
2710 option to activate the authentication code properly. Sending a
2711 '-u :' is enough as the user name and password from the -u,
2712 --user option are not actually used.
2713 If this option is used several times, only the first one is
2715 used.
2716 Providing --negotiate multiple times has no extra effect.
2718 Example:
2720 curl --negotiate -u : https://example.com
2721 See also --basic, --ntlm, --anyauth and --proxy-negotiate.
2723 --netrc-file <filename>
2725 This option is similar to -n, --netrc, except that you provide
2726 the path (absolute or relative) to the netrc file that curl
2727 should use. You can only specify one netrc file per invocation.
2728 It will abide by --netrc-optional if specified.
2730 If --netrc-file is provided several times, the last set value
2732 will be used.
2733 Example:
2735 curl --netrc-file netrc https://example.com
2736 See also -n, --netrc, -u, --user and -K, --config. This option
2738 is mutually exclusive to -n, --netrc.
2739 --netrc-optional
2741 Similar to -n, --netrc, but this option makes the .netrc usage
2742 optional and not mandatory as the -n, --netrc option does.
2743 Providing --netrc-optional multiple times has no extra effect.
2745 Disable it again with --no-netrc-optional.
2746 Example:
2748 curl --netrc-optional https://example.com
2749 See also --netrc-file. This option is mutually exclusive to -n,
2751 --netrc.
2752 -n, --netrc
2754 Makes curl scan the .netrc (_netrc on Windows) file in the
2755 user's home directory for login name and password. This is typi‐
2756 cally used for FTP on Unix. If used with HTTP, curl will enable
2757 user authentication. See netrc(5) and ftp(1) for details on the
2758 file format. Curl will not complain if that file does not have
2759 the right permissions (it should be neither world- nor group-
2760 readable). The environment variable "HOME" is used to find the
2761 home directory.
2762 A quick and simple example of how to setup a .netrc to allow
2764 curl to FTP to the machine host.domain.com with user name 'my‐
2765 self' and password 'secret' could look similar to:
2766 machine host.domain.com
2768 login myself
2769 password secret
2770 Providing -n, --netrc multiple times has no extra effect. Dis‐
2772 able it again with --no-netrc.
2773 Example:
2775 curl --netrc https://example.com
2776 See also --netrc-file, -K, --config and -u, --user. This option
2778 is mutually exclusive to --netrc-file and --netrc-optional.
2779 -:, --next
2781 Tells curl to use a separate operation for the following URL and
2782 associated options. This allows you to send several URL re‐
2783 quests, each with their own specific options, for example, such
2784 as different user names or custom requests for each.
2785 -:, --next will reset all local options and only global ones
2787 will have their values survive over to the operation following
2788 the -:, --next instruction. Global options include -v, --ver‐
2789 bose, --trace, --trace-ascii and --fail-early.
2790 For example, you can do both a GET and a POST in a single com‐
2792 mand line:
2793 curl www1.example.com --next -d postthis www2.example.com
2795 -:, --next can be used several times in a command line
2797 Examples:
2799 curl https://example.com --next -d postthis www2.example.com
2800 curl -I https://example.com --next https://example.net/
2801 See also -Z, --parallel and -K, --config. Added in 7.36.0.
2803 --no-alpn
2805 (HTTPS) Disable the ALPN TLS extension. ALPN is enabled by de‐
2806 fault if libcurl was built with an SSL library that supports
2807 ALPN. ALPN is used by a libcurl that supports HTTP/2 to negoti‐
2808 ate HTTP/2 support with the server during https sessions.
2809 Providing --no-alpn multiple times has no extra effect. Disable
2811 it again with --alpn.
2812 Example:
2814 curl --no-alpn https://example.com
2815 See also --no-npn and --http2. --no-alpn requires that the un‐
2817 derlying libcurl was built to support TLS. Added in 7.36.0.
2818 -N, --no-buffer
2820 Disables the buffering of the output stream. In normal work sit‐
2821 uations, curl will use a standard buffered output stream that
2822 will have the effect that it will output the data in chunks, not
2823 necessarily exactly when the data arrives. Using this option
2824 will disable that buffering.
2825 Providing -N, --no-buffer multiple times has no extra effect.
2827 Disable it again with --buffer.
2828 Example:
2830 curl --no-buffer https://example.com
2831 See also -#, --progress-bar.
2833 --no-clobber
2835 When used in conjunction with the -o, --output, -J, --remote-
2836 header-name, -O, --remote-name, or --remote-name-all options,
2837 curl avoids overwriting files that already exist. Instead, a dot
2838 and a number gets appended to the name of the file that would be
2839 created, up to filename.100 after which it will not create any
2840 file.
2841 Note that this is the negated option name documented. You can
2843 thus use --clobber to enforce the clobbering, even if -J, --re‐
2844 mote-header-name is specified.
2845 Providing --no-clobber multiple times has no extra effect. Dis‐
2847 able it again with --clobber.
2848 Example:
2850 curl --no-clobber --output local/dir/file https://example.com
2851 See also -o, --output and -O, --remote-name. Added in 7.83.0.
2853 --no-keepalive
2855 Disables the use of keepalive messages on the TCP connection.
2856 curl otherwise enables them by default.
2857 Note that this is the negated option name documented. You can
2859 thus use --keepalive to enforce keepalive.
2860 Providing --no-keepalive multiple times has no extra effect.
2862 Disable it again with --keepalive.
2863 Example:
2865 curl --no-keepalive https://example.com
2866 See also --keepalive-time.
2868 --no-npn
2870 (HTTPS) In curl 7.86.0 and later, curl never uses NPN.
2871 Disable the NPN TLS extension. NPN is enabled by default if
2873 libcurl was built with an SSL library that supports NPN. NPN is
2874 used by a libcurl that supports HTTP/2 to negotiate HTTP/2 sup‐
2875 port with the server during https sessions.
2876 Providing --no-npn multiple times has no extra effect. Disable
2878 it again with --npn.
2879 Example:
2881 curl --no-npn https://example.com
2882 See also --no-alpn and --http2. --no-npn requires that the un‐
2884 derlying libcurl was built to support TLS. Added in 7.36.0.
2885 --no-progress-meter
2887 Option to switch off the progress meter output without muting or
2888 otherwise affecting warning and informational messages like -s,
2889 --silent does.
2890 Note that this is the negated option name documented. You can
2892 thus use --progress-meter to enable the progress meter again.
2893 Providing --no-progress-meter multiple times has no extra ef‐
2895 fect. Disable it again with --progress-meter.
2896 Example:
2898 curl --no-progress-meter -o store https://example.com
2899 See also -v, --verbose and -s, --silent. Added in 7.67.0.
2901 --no-sessionid
2903 (TLS) Disable curl's use of SSL session-ID caching. By default
2904 all transfers are done using the cache. Note that while nothing
2905 should ever get hurt by attempting to reuse SSL session-IDs,
2906 there seem to be broken SSL implementations in the wild that may
2907 require you to disable this in order for you to succeed.
2908 Note that this is the negated option name documented. You can
2910 thus use --sessionid to enforce session-ID caching.
2911 Providing --no-sessionid multiple times has no extra effect.
2913 Disable it again with --sessionid.
2914 Example:
2916 curl --no-sessionid https://example.com
2917 See also -k, --insecure.
2919 --noproxy <no-proxy-list>
2921 Comma-separated list of hosts for which not to use a proxy, if
2922 one is specified. The only wildcard is a single * character,
2923 which matches all hosts, and effectively disables the proxy.
2924 Each name in this list is matched as either a domain which con‐
2925 tains the hostname, or the hostname itself. For example, lo‐
2926 cal.com would match local.com, local.com:80, and www.local.com,
2927 but not www.notlocal.com.
2928 Since 7.53.0, This option overrides the environment variables
2930 that disable the proxy ('no_proxy' and 'NO_PROXY'). If there's
2931 an environment variable disabling a proxy, you can set the no‐
2932 proxy list to "" to override it.
2933 Since 7.86.0, IP addresses specified to this option can be pro‐
2935 vided using CIDR notation: an appended slash and number speci‐
2936 fies the number of "network bits" out of the address to use in
2937 the comparison. For example "192.168.0.0/16" would match all ad‐
2938 dresses starting with "192.168".
2939 If --noproxy is provided several times, the last set value will
2941 be used.
2942 Example:
2944 curl --noproxy "www.example" https://example.com
2945 See also -x, --proxy.
2947 --ntlm-wb
2949 (HTTP) Enables NTLM much in the style --ntlm does, but hand over
2950 the authentication to the separate binary ntlmauth application
2951 that is executed when needed.
2952 Providing --ntlm-wb multiple times has no extra effect.
2954 Example:
2956 curl --ntlm-wb -u user:password https://example.com
2957 See also --ntlm and --proxy-ntlm.
2959 --ntlm (HTTP) Enables NTLM authentication. The NTLM authentication
2961 method was designed by Microsoft and is used by IIS web servers.
2962 It is a proprietary protocol, reverse-engineered by clever peo‐
2963 ple and implemented in curl based on their efforts. This kind of
2964 behavior should not be endorsed, you should encourage everyone
2965 who uses NTLM to switch to a public and documented authentica‐
2966 tion method instead, such as Digest.
2967 If you want to enable NTLM for your proxy authentication, then
2969 use --proxy-ntlm.
2970 If this option is used several times, only the first one is
2972 used.
2973 Providing --ntlm multiple times has no extra effect.
2975 Example:
2977 curl --ntlm -u user:password https://example.com
2978 See also --proxy-ntlm. --ntlm requires that the underlying
2980 libcurl was built to support TLS. This option is mutually exclu‐
2981 sive to --basic and --negotiate and --digest and --anyauth.
2982 --oauth2-bearer <token>
2984 (IMAP LDAP POP3 SMTP HTTP) Specify the Bearer Token for OAUTH
2985 2.0 server authentication. The Bearer Token is used in conjunc‐
2986 tion with the user name which can be specified as part of the
2987 --url or -u, --user options.
2988 The Bearer Token and user name are formatted according to RFC
2990 6750.
2991 If --oauth2-bearer is provided several times, the last set value
2993 will be used.
2994 Example:
2996 curl --oauth2-bearer "mF_9.B5f-4.1JqM" https://example.com
2997 See also --basic, --ntlm and --digest. Added in 7.33.0.
2999 --output-dir <dir>
3001 This option specifies the directory in which files should be
3002 stored, when -O, --remote-name or -o, --output are used.
3003 The given output directory is used for all URLs and output op‐
3005 tions on the command line, up until the first -:, --next.
3006 If the specified target directory does not exist, the operation
3008 will fail unless --create-dirs is also used.
3009 If --output-dir is provided several times, the last set value
3011 will be used.
3012 Example:
3014 curl --output-dir "tmp" -O https://example.com
3015 See also -O, --remote-name and -J, --remote-header-name. Added
3017 in 7.73.0.
3018 -o, --output <file>
3020 Write output to <file> instead of stdout. If you are using {} or
3021 [] to fetch multiple documents, you should quote the URL and you
3022 can use '#' followed by a number in the <file> specifier. That
3023 variable will be replaced with the current string for the URL
3024 being fetched. Like in:
3025 curl "http://{one,two}.example.com" -o "file_#1.txt"
3027 or use several variables like:
3029 curl "http://{site,host}.host[1-5].com" -o "#1_#2"
3031 You may use this option as many times as the number of URLs you
3033 have. For example, if you specify two URLs on the same command
3034 line, you can use it like this:
3035 curl -o aa example.com -o bb example.net
3037 and the order of the -o options and the URLs does not matter,
3039 just that the first -o is for the first URL and so on, so the
3040 above command line can also be written as
3041 curl example.com example.net -o aa -o bb
3043 See also the --create-dirs option to create the local directo‐
3045 ries dynamically. Specifying the output as '-' (a single dash)
3046 will force the output to be done to stdout.
3047 To suppress response bodies, you can redirect output to
3049 /dev/null:
3050 curl example.com -o /dev/null
3052 Or for Windows use nul:
3054 curl example.com -o nul
3056 -o, --output can be used several times in a command line
3058 Examples:
3060 curl -o file https://example.com
3061 curl "http://{one,two}.example.com" -o "file_#1.txt"
3062 curl "http://{site,host}.host[1-5].com" -o "#1_#2"
3063 curl -o file https://example.com -o file2 https://example.net
3064 See also -O, --remote-name, --remote-name-all and -J, --remote-
3066 header-name.
3067 --parallel-immediate
3069 When doing parallel transfers, this option will instruct curl
3070 that it should rather prefer opening up more connections in par‐
3071 allel at once rather than waiting to see if new transfers can be
3072 added as multiplexed streams on another connection.
3073 This option is global and does not need to be specified for each
3075 use of --next.
3076 Providing --parallel-immediate multiple times has no extra ef‐
3078 fect. Disable it again with --no-parallel-immediate.
3079 Example:
3081 curl --parallel-immediate -Z https://example.com -o file1 https://example.com -o file2
3082 See also -Z, --parallel and --parallel-max. Added in 7.68.0.
3084 --parallel-max <num>
3086 When asked to do parallel transfers, using -Z, --parallel, this
3087 option controls the maximum amount of transfers to do simultane‐
3088 ously.
3089 This option is global and does not need to be specified for each
3091 use of -:, --next.
3092 The default is 50.
3094 If --parallel-max is provided several times, the last set value
3096 will be used.
3097 Example:
3099 curl --parallel-max 100 -Z https://example.com ftp://example.com/
3100 See also -Z, --parallel. Added in 7.66.0.
3102 -Z, --parallel
3104 Makes curl perform its transfers in parallel as compared to the
3105 regular serial manner.
3106 This option is global and does not need to be specified for each
3108 use of --next.
3109 Providing -Z, --parallel multiple times has no extra effect.
3111 Disable it again with --no-parallel.
3112 Example:
3114 curl --parallel https://example.com -o file1 https://example.com -o file2
3115 See also -:, --next and -v, --verbose. Added in 7.66.0.
3117 --pass <phrase>
3119 (SSH TLS) Passphrase for the private key.
3120 If --pass is provided several times, the last set value will be
3122 used.
3123 Example:
3125 curl --pass secret --key file https://example.com
3126 See also --key and -u, --user.
3128 --path-as-is
3130 Tell curl to not handle sequences of /../ or /./ in the given
3131 URL path. Normally curl will squash or merge them according to
3132 standards but with this option set you tell it not to do that.
3133 Providing --path-as-is multiple times has no extra effect. Dis‐
3135 able it again with --no-path-as-is.
3136 Example:
3138 curl --path-as-is https://example.com/../../etc/passwd
3139 See also --request-target. Added in 7.42.0.
3141 --pinnedpubkey <hashes>
3143 (TLS) Tells curl to use the specified public key file (or
3144 hashes) to verify the peer. This can be a path to a file which
3145 contains a single public key in PEM or DER format, or any number
3146 of base64 encoded sha256 hashes preceded by 'sha256//' and sepa‐
3147 rated by ';'.
3148 When negotiating a TLS or SSL connection, the server sends a
3150 certificate indicating its identity. A public key is extracted
3151 from this certificate and if it does not exactly match the pub‐
3152 lic key provided to this option, curl will abort the connection
3153 before sending or receiving any data.
3154 PEM/DER support:
3156 7.39.0: OpenSSL, GnuTLS and GSKit
3158 7.43.0: NSS and wolfSSL
3160 7.47.0: mbedtls
3162 sha256 support:
3164 7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL
3166 7.47.0: mbedtls
3168 Other SSL backends not supported.
3170 If --pinnedpubkey is provided several times, the last set value
3172 will be used.
3173 Examples:
3175 curl --pinnedpubkey keyfile https://example.com
3176 curl --pinnedpubkey 'sha256//ce118b51897f4452dc' https://example.com
3177 See also --hostpubsha256. Added in 7.39.0.
3179 --post301
3181 (HTTP) Tells curl to respect RFC 7231/6.4.2 and not convert POST
3182 requests into GET requests when following a 301 redirection. The
3183 non-RFC behavior is ubiquitous in web browsers, so curl does the
3184 conversion by default to maintain consistency. However, a server
3185 may require a POST to remain a POST after such a redirection.
3186 This option is meaningful only when using -L, --location.
3187 Providing --post301 multiple times has no extra effect. Disable
3189 it again with --no-post301.
3190 Example:
3192 curl --post301 --location -d "data" https://example.com
3193 See also --post302, --post303 and -L, --location.
3195 --post302
3197 (HTTP) Tells curl to respect RFC 7231/6.4.3 and not convert POST
3198 requests into GET requests when following a 302 redirection. The
3199 non-RFC behavior is ubiquitous in web browsers, so curl does the
3200 conversion by default to maintain consistency. However, a server
3201 may require a POST to remain a POST after such a redirection.
3202 This option is meaningful only when using -L, --location.
3203 Providing --post302 multiple times has no extra effect. Disable
3205 it again with --no-post302.
3206 Example:
3208 curl --post302 --location -d "data" https://example.com
3209 See also --post301, --post303 and -L, --location.
3211 --post303
3213 (HTTP) Tells curl to violate RFC 7231/6.4.4 and not convert POST
3214 requests into GET requests when following 303 redirections. A
3215 server may require a POST to remain a POST after a 303 redirect‐
3216 ion. This option is meaningful only when using -L, --location.
3217 Providing --post303 multiple times has no extra effect. Disable
3219 it again with --no-post303.
3220 Example:
3222 curl --post303 --location -d "data" https://example.com
3223 See also --post302, --post301 and -L, --location.
3225 --preproxy [protocol://]host[:port]
3227 Use the specified SOCKS proxy before connecting to an HTTP or
3228 HTTPS -x, --proxy. In such a case curl first connects to the
3229 SOCKS proxy and then connects (through SOCKS) to the HTTP or
3230 HTTPS proxy. Hence pre proxy.
3231 The pre proxy string should be specified with a protocol:// pre‐
3233 fix to specify alternative proxy protocols. Use socks4://,
3234 socks4a://, socks5:// or socks5h:// to request the specific
3235 SOCKS version to be used. No protocol specified will make curl
3236 default to SOCKS4.
3237 If the port number is not specified in the proxy string, it is
3239 assumed to be 1080.
3240 User and password that might be provided in the proxy string are
3242 URL decoded by curl. This allows you to pass in special charac‐
3243 ters such as @ by using %40 or pass in a colon with %3a.
3244 If --preproxy is provided several times, the last set value will
3246 be used.
3247 Example:
3249 curl --preproxy socks5://proxy.example -x http://http.example https://example.com
3250 See also -x, --proxy and --socks5. Added in 7.52.0.
3252 -#, --progress-bar
3254 Make curl display transfer progress as a simple progress bar in‐
3255 stead of the standard, more informational, meter.
3256 This progress bar draws a single line of '#' characters across
3258 the screen and shows a percentage if the transfer size is known.
3259 For transfers without a known size, there will be space ship
3260 (-=o=-) that moves back and forth but only while data is being
3261 transferred, with a set of flying hash sign symbols on top.
3262 This option is global and does not need to be specified for each
3264 use of --next.
3265 Providing -#, --progress-bar multiple times has no extra effect.
3267 Disable it again with --no-progress-bar.
3268 Example:
3270 curl -# -O https://example.com
3271 See also --styled-output.
3273 --proto-default <protocol>
3275 Tells curl to use protocol for any URL missing a scheme name.
3276 An unknown or unsupported protocol causes error CURLE_UNSUP‐
3278 PORTED_PROTOCOL (1).
3279 This option does not change the default proxy protocol (http).
3281 Without this option set, curl guesses protocol based on the host
3283 name, see --url for details.
3284 If --proto-default is provided several times, the last set value
3286 will be used.
3287 Example:
3289 curl --proto-default https ftp.example.com
3290 See also --proto and --proto-redir. Added in 7.45.0.
3292 --proto-redir <protocols>
3294 Tells curl to limit what protocols it may use on redirect. Pro‐
3295 tocols denied by --proto are not overridden by this option. See
3296 --proto for how protocols are represented.
3297 Example, allow only HTTP and HTTPS on redirect:
3299 curl --proto-redir -all,http,https http://example.com
3301 By default curl will only allow HTTP, HTTPS, FTP and FTPS on re‐
3303 direct (since 7.65.2). Specifying all or +all enables all proto‐
3304 cols on redirects, which is not good for security.
3305 If --proto-redir is provided several times, the last set value
3307 will be used.
3308 Example:
3310 curl --proto-redir =http,https https://example.com
3311 See also --proto.
3313 --proto <protocols>
3315 Tells curl to limit what protocols it may use for transfers.
3316 Protocols are evaluated left to right, are comma separated, and
3317 are each a protocol name or 'all', optionally prefixed by zero
3318 or more modifiers. Available modifiers are:
3319 + Permit this protocol in addition to protocols already permit‐
3321 ted (this is the default if no modifier is used).
3322 - Deny this protocol, removing it from the list of protocols
3324 already permitted.
3325 = Permit only this protocol (ignoring the list already permit‐
3327 ted), though subject to later modification by subsequent en‐
3328 tries in the comma separated list.
3329 For example:
3331 --proto -ftps uses the default protocols, but disables ftps
3333 --proto -all,https,+http
3335 only enables http and https
3336 --proto =http,https
3338 also only enables http and https
3339 Unknown and disabled protocols produce a warning. This allows
3341 scripts to safely rely on being able to disable potentially dan‐
3342 gerous protocols, without relying upon support for that protocol
3343 being built into curl to avoid an error.
3344 This option can be used multiple times, in which case the effect
3346 is the same as concatenating the protocols into one instance of
3347 the option.
3348 If --proto is provided several times, the last set value will be
3350 used.
3351 Example:
3353 curl --proto =http,https,sftp https://example.com
3354 See also --proto-redir and --proto-default.
3356 --proxy-anyauth
3358 Tells curl to pick a suitable authentication method when commu‐
3359 nicating with the given HTTP proxy. This might cause an extra
3360 request/response round-trip.
3361 Providing --proxy-anyauth multiple times has no extra effect.
3363 Example:
3365 curl --proxy-anyauth --proxy-user user:passwd -x proxy https://example.com
3366 See also -x, --proxy, --proxy-basic and --proxy-digest.
3368 --proxy-basic
3370 Tells curl to use HTTP Basic authentication when communicating
3371 with the given proxy. Use --basic for enabling HTTP Basic with a
3372 remote host. Basic is the default authentication method curl
3373 uses with proxies.
3374 Providing --proxy-basic multiple times has no extra effect.
3376 Example:
3378 curl --proxy-basic --proxy-user user:passwd -x proxy https://example.com
3379 See also -x, --proxy, --proxy-anyauth and --proxy-digest.
3381 --proxy-ca-native
3383 (TLS) Tells curl to use the CA store from the native operating
3384 system to verify the HTTPS proxy. By default, curl will other‐
3385 wise use a CA store provided in a single file or directory, but
3386 when using this option it will interface the operating system's
3387 own vault.
3388 This option only works for curl on Windows when built to use
3390 OpenSSL. When curl on Windows is built to use Schannel, this
3391 feature is implied and curl then only uses the native CA store.
3392 Providing --proxy-ca-native multiple times has no extra effect.
3394 Disable it again with --no-proxy-ca-native.
3395 Example:
3397 curl --ca-native https://example.com
3398 See also --cacert, --capath and -k, --insecure. Added in 8.2.0.
3400 --proxy-cacert <file>
3402 Same as --cacert but used in HTTPS proxy context.
3403 If --proxy-cacert is provided several times, the last set value
3405 will be used.
3406 Example:
3408 curl --proxy-cacert CA-file.txt -x https://proxy https://example.com
3409 See also --proxy-capath, --cacert, --capath and -x, --proxy.
3411 Added in 7.52.0.
3412 --proxy-capath <dir>
3414 Same as --capath but used in HTTPS proxy context.
3415 If --proxy-capath is provided several times, the last set value
3417 will be used.
3418 Example:
3420 curl --proxy-capath /local/directory -x https://proxy https://example.com
3421 See also --proxy-cacert, -x, --proxy and --capath. Added in
3423 7.52.0.
3424 --proxy-cert-type <type>
3426 Same as --cert-type but used in HTTPS proxy context.
3427 If --proxy-cert-type is provided several times, the last set
3429 value will be used.
3430 Example:
3432 curl --proxy-cert-type PEM --proxy-cert file -x https://proxy https://example.com
3433 See also --proxy-cert. Added in 7.52.0.
3435 --proxy-cert <cert[:passwd]>
3437 Same as -E, --cert but used in HTTPS proxy context.
3438 If --proxy-cert is provided several times, the last set value
3440 will be used.
3441 Example:
3443 curl --proxy-cert file -x https://proxy https://example.com
3444 See also --proxy-cert-type. Added in 7.52.0.
3446 --proxy-ciphers <list>
3448 Same as --ciphers but used in HTTPS proxy context.
3449 Specifies which ciphers to use in the connection to the HTTPS
3451 proxy. The list of ciphers must specify valid ciphers. Read up
3452 on SSL cipher list details on this URL:
3453 https://curl.se/docs/ssl-ciphers.html
3455 If --proxy-ciphers is provided several times, the last set value
3457 will be used.
3458 Example:
3460 curl --proxy-ciphers ECDHE-ECDSA-AES256-CCM8 -x https://proxy https://example.com
3461 See also --ciphers, --curves and -x, --proxy. Added in 7.52.0.
3463 --proxy-crlfile <file>
3465 Same as --crlfile but used in HTTPS proxy context.
3466 If --proxy-crlfile is provided several times, the last set value
3468 will be used.
3469 Example:
3471 curl --proxy-crlfile rejects.txt -x https://proxy https://example.com
3472 See also --crlfile and -x, --proxy. Added in 7.52.0.
3474 --proxy-digest
3476 Tells curl to use HTTP Digest authentication when communicating
3477 with the given proxy. Use --digest for enabling HTTP Digest with
3478 a remote host.
3479 Providing --proxy-digest multiple times has no extra effect.
3481 Example:
3483 curl --proxy-digest --proxy-user user:passwd -x proxy https://example.com
3484 See also -x, --proxy, --proxy-anyauth and --proxy-basic.
3486 --proxy-header <header/@file>
3488 (HTTP) Extra header to include in the request when sending HTTP
3489 to a proxy. You may specify any number of extra headers. This is
3490 the equivalent option to -H, --header but is for proxy communi‐
3491 cation only like in CONNECT requests when you want a separate
3492 header sent to the proxy to what is sent to the actual remote
3493 host.
3494 curl will make sure that each header you add/replace is sent
3496 with the proper end-of-line marker, you should thus not add that
3497 as a part of the header content: do not add newlines or carriage
3498 returns, they will only mess things up for you.
3499 Headers specified with this option will not be included in re‐
3501 quests that curl knows will not be sent to a proxy.
3502 Starting in 7.55.0, this option can take an argument in @file‐
3504 name style, which then adds a header for each line in the input
3505 file. Using @- will make curl read the header file from stdin.
3506 This option can be used multiple times to add/replace/remove
3508 multiple headers.
3509 --proxy-header can be used several times in a command line
3511 Examples:
3513 curl --proxy-header "X-First-Name: Joe" -x http://proxy https://example.com
3514 curl --proxy-header "User-Agent: surprise" -x http://proxy https://example.com
3515 curl --proxy-header "Host:" -x http://proxy https://example.com
3516 See also -x, --proxy. Added in 7.37.0.
3518 --proxy-http2
3520 (HTTP) Tells curl to try negotiate HTTP version 2 with an HTTPS
3521 proxy. The proxy might still only offer HTTP/1 and then curl
3522 will stick to using that version.
3523 This has no effect for any other kinds of proxies.
3525 Providing --proxy-http2 multiple times has no extra effect.
3527 Disable it again with --no-proxy-http2.
3528 Example:
3530 curl --proxy-http2 -x proxy https://example.com
3531 See also -x, --proxy. --proxy-http2 requires that the underlying
3533 libcurl was built to support HTTP/2. Added in 8.1.0.
3534 --proxy-insecure
3536 Same as -k, --insecure but used in HTTPS proxy context.
3537 Providing --proxy-insecure multiple times has no extra effect.
3539 Disable it again with --no-proxy-insecure.
3540 Example:
3542 curl --proxy-insecure -x https://proxy https://example.com
3543 See also -x, --proxy and -k, --insecure. Added in 7.52.0.
3545 --proxy-key-type <type>
3547 Same as --key-type but used in HTTPS proxy context.
3548 If --proxy-key-type is provided several times, the last set
3550 value will be used.
3551 Example:
3553 curl --proxy-key-type DER --proxy-key here -x https://proxy https://example.com
3554 See also --proxy-key and -x, --proxy. Added in 7.52.0.
3556 --proxy-key <key>
3558 Same as --key but used in HTTPS proxy context.
3559 If --proxy-key is provided several times, the last set value
3561 will be used.
3562 Example:
3564 curl --proxy-key here -x https://proxy https://example.com
3565 See also --proxy-key-type and -x, --proxy. Added in 7.52.0.
3567 --proxy-negotiate
3569 Tells curl to use HTTP Negotiate (SPNEGO) authentication when
3570 communicating with the given proxy. Use --negotiate for enabling
3571 HTTP Negotiate (SPNEGO) with a remote host.
3572 Providing --proxy-negotiate multiple times has no extra effect.
3574 Example:
3576 curl --proxy-negotiate --proxy-user user:passwd -x proxy https://example.com
3577 See also --proxy-anyauth and --proxy-basic.
3579 --proxy-ntlm
3581 Tells curl to use HTTP NTLM authentication when communicating
3582 with the given proxy. Use --ntlm for enabling NTLM with a remote
3583 host.
3584 Providing --proxy-ntlm multiple times has no extra effect.
3586 Example:
3588 curl --proxy-ntlm --proxy-user user:passwd -x http://proxy https://example.com
3589 See also --proxy-negotiate and --proxy-anyauth.
3591 --proxy-pass <phrase>
3593 Same as --pass but used in HTTPS proxy context.
3594 If --proxy-pass is provided several times, the last set value
3596 will be used.
3597 Example:
3599 curl --proxy-pass secret --proxy-key here -x https://proxy https://example.com
3600 See also -x, --proxy and --proxy-key. Added in 7.52.0.
3602 --proxy-pinnedpubkey <hashes>
3604 (TLS) Tells curl to use the specified public key file (or
3605 hashes) to verify the proxy. This can be a path to a file which
3606 contains a single public key in PEM or DER format, or any number
3607 of base64 encoded sha256 hashes preceded by 'sha256//' and sepa‐
3608 rated by ';'.
3609 When negotiating a TLS or SSL connection, the server sends a
3611 certificate indicating its identity. A public key is extracted
3612 from this certificate and if it does not exactly match the pub‐
3613 lic key provided to this option, curl will abort the connection
3614 before sending or receiving any data.
3615 If --proxy-pinnedpubkey is provided several times, the last set
3617 value will be used.
3618 Examples:
3620 curl --proxy-pinnedpubkey keyfile https://example.com
3621 curl --proxy-pinnedpubkey 'sha256//ce118b51897f4452dc' https://example.com
3622 See also --pinnedpubkey and -x, --proxy. Added in 7.59.0.
3624 --proxy-service-name <name>
3626 This option allows you to change the service name for proxy ne‐
3627 gotiation.
3628 If --proxy-service-name is provided several times, the last set
3630 value will be used.
3631 Example:
3633 curl --proxy-service-name "shrubbery" -x proxy https://example.com
3634 See also --service-name and -x, --proxy. Added in 7.43.0.
3636 --proxy-ssl-allow-beast
3638 Same as --ssl-allow-beast but used in HTTPS proxy context.
3639 Providing --proxy-ssl-allow-beast multiple times has no extra
3641 effect. Disable it again with --no-proxy-ssl-allow-beast.
3642 Example:
3644 curl --proxy-ssl-allow-beast -x https://proxy https://example.com
3645 See also --ssl-allow-beast and -x, --proxy. Added in 7.52.0.
3647 --proxy-ssl-auto-client-cert
3649 Same as --ssl-auto-client-cert but used in HTTPS proxy context.
3650 Providing --proxy-ssl-auto-client-cert multiple times has no ex‐
3652 tra effect. Disable it again with --no-proxy-ssl-auto-client-
3653 cert.
3654 Example:
3656 curl --proxy-ssl-auto-client-cert -x https://proxy https://example.com
3657 See also --ssl-auto-client-cert and -x, --proxy. Added in
3659 7.77.0.
3660 --proxy-tls13-ciphers <ciphersuite list>
3662 (TLS) Specifies which cipher suites to use in the connection to
3663 your HTTPS proxy when it negotiates TLS 1.3. The list of ciphers
3664 suites must specify valid ciphers. Read up on TLS 1.3 cipher
3665 suite details on this URL:
3666 https://curl.se/docs/ssl-ciphers.html
3668 This option is currently used only when curl is built to use
3670 OpenSSL 1.1.1 or later. If you are using a different SSL backend
3671 you can try setting TLS 1.3 cipher suites by using the --proxy-
3672 ciphers option.
3673 If --proxy-tls13-ciphers is provided several times, the last set
3675 value will be used.
3676 Example:
3678 curl --proxy-tls13-ciphers TLS_AES_128_GCM_SHA256 -x proxy https://example.com
3679 See also --tls13-ciphers, --curves and --proxy-ciphers. Added in
3681 7.61.0.
3682 --proxy-tlsauthtype <type>
3684 Same as --tlsauthtype but used in HTTPS proxy context.
3685 If --proxy-tlsauthtype is provided several times, the last set
3687 value will be used.
3688 Example:
3690 curl --proxy-tlsauthtype SRP -x https://proxy https://example.com
3691 See also -x, --proxy and --proxy-tlsuser. Added in 7.52.0.
3693 --proxy-tlspassword <string>
3695 Same as --tlspassword but used in HTTPS proxy context.
3696 If --proxy-tlspassword is provided several times, the last set
3698 value will be used.
3699 Example:
3701 curl --proxy-tlspassword passwd -x https://proxy https://example.com
3702 See also -x, --proxy and --proxy-tlsuser. Added in 7.52.0.
3704 --proxy-tlsuser <name>
3706 Same as --tlsuser but used in HTTPS proxy context.
3707 If --proxy-tlsuser is provided several times, the last set value
3709 will be used.
3710 Example:
3712 curl --proxy-tlsuser smith -x https://proxy https://example.com
3713 See also -x, --proxy and --proxy-tlspassword. Added in 7.52.0.
3715 --proxy-tlsv1
3717 Same as -1, --tlsv1 but used in HTTPS proxy context.
3718 Providing --proxy-tlsv1 multiple times has no extra effect.
3720 Example:
3722 curl --proxy-tlsv1 -x https://proxy https://example.com
3723 See also -x, --proxy. Added in 7.52.0.
3725 -U, --proxy-user <user:password>
3727 Specify the user name and password to use for proxy authentica‐
3728 tion.
3729 If you use a Windows SSPI-enabled curl binary and do either Ne‐
3731 gotiate or NTLM authentication then you can tell curl to select
3732 the user name and password from your environment by specifying a
3733 single colon with this option: "-U :".
3734 On systems where it works, curl will hide the given option argu‐
3736 ment from process listings. This is not enough to protect cre‐
3737 dentials from possibly getting seen by other users on the same
3738 system as they will still be visible for a moment before
3739 cleared. Such sensitive data should be retrieved from a file in‐
3740 stead or similar and never used in clear text in a command line.
3741 If -U, --proxy-user is provided several times, the last set
3743 value will be used.
3744 Example:
3746 curl --proxy-user name:pwd -x proxy https://example.com
3747 See also --proxy-pass.
3749 -x, --proxy [protocol://]host[:port]
3751 Use the specified proxy.
3752 The proxy string can be specified with a protocol:// prefix. No
3754 protocol specified or http:// will be treated as HTTP proxy. Use
3755 socks4://, socks4a://, socks5:// or socks5h:// to request a spe‐
3756 cific SOCKS version to be used.
3757 Unix domain sockets are supported for socks proxy. Set localhost
3760 for the host part. e.g. socks5h://localhost/path/to/socket.sock
3761 HTTPS proxy support via https:// protocol prefix was added in
3763 7.52.0 for OpenSSL, GnuTLS and NSS. Since 7.87.0, it also works
3764 for BearSSL, mbedTLS, rustls, Schannel, Secure Transport and
3765 wolfSSL.
3766 Unrecognized and unsupported proxy protocols cause an error
3768 since 7.52.0. Prior versions may ignore the protocol and use
3769 http:// instead.
3770 If the port number is not specified in the proxy string, it is
3772 assumed to be 1080.
3773 This option overrides existing environment variables that set
3775 the proxy to use. If there's an environment variable setting a
3776 proxy, you can set proxy to "" to override it.
3777 All operations that are performed over an HTTP proxy will trans‐
3779 parently be converted to HTTP. It means that certain protocol
3780 specific operations might not be available. This is not the case
3781 if you can tunnel through the proxy, as one with the -p, --prox‐
3782 ytunnel option.
3783 User and password that might be provided in the proxy string are
3785 URL decoded by curl. This allows you to pass in special charac‐
3786 ters such as @ by using %40 or pass in a colon with %3a.
3787 The proxy host can be specified the same way as the proxy envi‐
3789 ronment variables, including the protocol prefix (http://) and
3790 the embedded user + password.
3791 When a proxy is used, the active FTP mode as set with -P, --ftp-
3793 port, cannot be used.
3794 If -x, --proxy is provided several times, the last set value
3796 will be used.
3797 Example:
3799 curl --proxy http://proxy.example https://example.com
3800 See also --socks5 and --proxy-basic.
3802 --proxy1.0 <host[:port]>
3804 Use the specified HTTP 1.0 proxy. If the port number is not
3805 specified, it is assumed at port 1080.
3806 The only difference between this and the HTTP proxy option -x,
3808 --proxy, is that attempts to use CONNECT through the proxy will
3809 specify an HTTP 1.0 protocol instead of the default HTTP 1.1.
3810 Providing --proxy1.0 multiple times has no extra effect.
3812 Example:
3814 curl --proxy1.0 -x http://proxy https://example.com
3815 See also -x, --proxy, --socks5 and --preproxy.
3817 -p, --proxytunnel
3819 When an HTTP proxy is used -x, --proxy, this option will make
3820 curl tunnel through the proxy. The tunnel approach is made with
3821 the HTTP proxy CONNECT request and requires that the proxy al‐
3822 lows direct connect to the remote port number curl wants to tun‐
3823 nel through to.
3824 To suppress proxy CONNECT response headers when curl is set to
3826 output headers use --suppress-connect-headers.
3827 Providing -p, --proxytunnel multiple times has no extra effect.
3829 Disable it again with --no-proxytunnel.
3830 Example:
3832 curl --proxytunnel -x http://proxy https://example.com
3833 See also -x, --proxy.
3835 --pubkey <key>
3837 (SFTP SCP) Public key file name. Allows you to provide your pub‐
3838 lic key in this separate file.
3839 (As of 7.39.0, curl attempts to automatically extract the public
3841 key from the private key file, so passing this option is gener‐
3842 ally not required. Note that this public key extraction requires
3843 libcurl to be linked against a copy of libssh2 1.2.8 or higher
3844 that is itself linked against OpenSSL.)
3845 If --pubkey is provided several times, the last set value will
3847 be used.
3848 Example:
3850 curl --pubkey file.pub sftp://example.com/
3851 See also --pass.
3853 -Q, --quote <command>
3855 (FTP SFTP) Send an arbitrary command to the remote FTP or SFTP
3856 server. Quote commands are sent BEFORE the transfer takes place
3857 (just after the initial PWD command in an FTP transfer, to be
3858 exact). To make commands take place after a successful transfer,
3859 prefix them with a dash '-'.
3860 (FTP only) To make commands be sent after curl has changed the
3862 working directory, just before the file transfer command(s),
3863 prefix the command with a '+'. This is not performed when a di‐
3864 rectory listing is performed.
3865 You may specify any number of commands.
3867 By default curl will stop at first failure. To make curl con‐
3869 tinue even if the command fails, prefix the command with an as‐
3870 terisk (*). Otherwise, if the server returns failure for one of
3871 the commands, the entire operation will be aborted.
3872 You must send syntactically correct FTP commands as RFC 959 de‐
3874 fines to FTP servers, or one of the commands listed below to
3875 SFTP servers.
3876 SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP
3878 quote commands itself before sending them to the server. File
3879 names may be quoted shell-style to embed spaces or special char‐
3880 acters. Following is the list of all supported SFTP quote com‐
3881 mands:
3882 atime date file
3884 The atime command sets the last access time of the file
3885 named by the file operand. The <date expression> can be
3886 all sorts of date strings, see the curl_getdate(3) man
3887 page for date expression details. (Added in 7.73.0)
3888 chgrp group file
3890 The chgrp command sets the group ID of the file named by
3891 the file operand to the group ID specified by the group
3892 operand. The group operand is a decimal integer group ID.
3893 chmod mode file
3895 The chmod command modifies the file mode bits of the
3896 specified file. The mode operand is an octal integer mode
3897 number.
3898 chown user file
3900 The chown command sets the owner of the file named by the
3901 file operand to the user ID specified by the user oper‐
3902 and. The user operand is a decimal integer user ID.
3903 ln source_file target_file
3905 The ln and symlink commands create a symbolic link at the
3906 target_file location pointing to the source_file loca‐
3907 tion.
3908 mkdir directory_name
3910 The mkdir command creates the directory named by the di‐
3911 rectory_name operand.
3912 mtime date file
3914 The mtime command sets the last modification time of the
3915 file named by the file operand. The <date expression> can
3916 be all sorts of date strings, see the curl_getdate(3) man
3917 page for date expression details. (Added in 7.73.0)
3918 pwd The pwd command returns the absolute pathname of the cur‐
3920 rent working directory.
3921 rename source target
3923 The rename command renames the file or directory named by
3924 the source operand to the destination path named by the
3925 target operand.
3926 rm file
3928 The rm command removes the file specified by the file op‐
3929 erand.
3930 rmdir directory
3932 The rmdir command removes the directory entry specified
3933 by the directory operand, provided it is empty.
3934 symlink source_file target_file
3936 See ln.
3937 -Q, --quote can be used several times in a command line
3939 Example:
3941 curl --quote "DELE file" ftp://example.com/foo
3942 See also -X, --request.
3944 --random-file <file>
3946 Deprecated option. This option is ignored by curl since 7.84.0.
3947 Prior to that it only had an effect on curl if built to use old
3948 versions of OpenSSL.
3949 Specify the path name to file containing what will be considered
3951 as random data. The data may be used to seed the random engine
3952 for SSL connections.
3953 If --random-file is provided several times, the last set value
3955 will be used.
3956 Example:
3958 curl --random-file rubbish https://example.com
3959 See also --egd-file.
3961 -r, --range <range>
3963 (HTTP FTP SFTP FILE) Retrieve a byte range (i.e. a partial docu‐
3964 ment) from an HTTP/1.1, FTP or SFTP server or a local FILE.
3965 Ranges can be specified in a number of ways.
3966 0-499 specifies the first 500 bytes
3968 500-999 specifies the second 500 bytes
3970 -500 specifies the last 500 bytes
3972 9500- specifies the bytes from offset 9500 and forward
3974 0-0,-1 specifies the first and last byte only(*)(HTTP)
3976 100-199,500-599
3978 specifies two separate 100-byte ranges(*) (HTTP)
3979 (*) = NOTE that this will cause the server to reply with a mul‐
3981 tipart response, which will be returned as-is by curl! Parsing
3982 or otherwise transforming this response is the responsibility of
3983 the caller.
3984 Only digit characters (0-9) are valid in the 'start' and 'stop'
3986 fields of the 'start-stop' range syntax. If a non-digit charac‐
3987 ter is given in the range, the server's response will be unspec‐
3988 ified, depending on the server's configuration.
3989 You should also be aware that many HTTP/1.1 servers do not have
3991 this feature enabled, so that when you attempt to get a range,
3992 you will instead get the whole document.
3993 FTP and SFTP range downloads only support the simple 'start-
3995 stop' syntax (optionally with one of the numbers omitted). FTP
3996 use depends on the extended FTP command SIZE.
3997 If -r, --range is provided several times, the last set value
3999 will be used.
4000 Example:
4002 curl --range 22-44 https://example.com
4003 See also -C, --continue-at and -a, --append.
4005 --rate <max request rate>
4007 Specify the maximum transfer frequency you allow curl to use -
4008 in number of transfer starts per time unit (sometimes called re‐
4009 quest rate). Without this option, curl will start the next
4010 transfer as fast as possible.
4011 If given several URLs and a transfer completes faster than the
4013 allowed rate, curl will wait until the next transfer is started
4014 to maintain the requested rate. This option has no effect when
4015 -Z, --parallel is used.
4016 The request rate is provided as "N/U" where N is an integer num‐
4018 ber and U is a time unit. Supported units are 's' (second), 'm'
4019 (minute), 'h' (hour) and 'd' /(day, as in a 24 hour unit). The
4020 default time unit, if no "/U" is provided, is number of trans‐
4021 fers per hour.
4022 If curl is told to allow 10 requests per minute, it will not
4024 start the next request until 6 seconds have elapsed since the
4025 previous transfer was started.
4026 This function uses millisecond resolution. If the allowed fre‐
4028 quency is set more than 1000 per second, it will instead run un‐
4029 restricted.
4030 When retrying transfers, enabled with --retry, the separate
4032 retry delay logic is used and not this setting.
4033 This option is global and does not need to be specified for each
4035 use of --next.
4036 If --rate is provided several times, the last set value will be
4038 used.
4039 Examples:
4041 curl --rate 2/s https://example.com ...
4042 curl --rate 3/h https://example.com ...
4043 curl --rate 14/m https://example.com ...
4044 See also --limit-rate and --retry-delay. Added in 7.84.0.
4046 --raw (HTTP) When used, it disables all internal HTTP decoding of con‐
4048 tent or transfer encodings and instead makes them passed on un‐
4049 altered, raw.
4050 Providing --raw multiple times has no extra effect. Disable it
4052 again with --no-raw.
4053 Example:
4055 curl --raw https://example.com
4056 See also --tr-encoding.
4058 -e, --referer <URL>
4060 (HTTP) Sends the "Referrer Page" information to the HTTP server.
4061 This can also be set with the -H, --header flag of course. When
4062 used with -L, --location you can append ";auto" to the -e,
4063 --referer URL to make curl automatically set the previous URL
4064 when it follows a Location: header. The ";auto" string can be
4065 used alone, even if you do not set an initial -e, --referer.
4066 If -e, --referer is provided several times, the last set value
4068 will be used.
4069 Examples:
4071 curl --referer "https://fake.example" https://example.com
4072 curl --referer "https://fake.example;auto" -L https://example.com
4073 curl --referer ";auto" -L https://example.com
4074 See also -A, --user-agent and -H, --header.
4076 -J, --remote-header-name
4078 (HTTP) This option tells the -O, --remote-name option to use the
4079 server-specified Content-Disposition filename instead of ex‐
4080 tracting a filename from the URL. If the server-provided file
4081 name contains a path, that will be stripped off before the file
4082 name is used.
4083 The file is saved in the current directory, or in the directory
4085 specified with --output-dir.
4086 If the server specifies a file name and a file with that name
4088 already exists in the destination directory, it will not be
4089 overwritten and an error will occur - unless you allow it by us‐
4090 ing the --clobber option. If the server does not specify a file
4091 name then this option has no effect.
4092 There's no attempt to decode %-sequences (yet) in the provided
4094 file name, so this option may provide you with rather unexpected
4095 file names.
4096 This feature uses the name from the "filename" field, it does
4098 not yet support the "filename*" field (filenames with explicit
4099 character sets).
4100 WARNING: Exercise judicious use of this option, especially on
4102 Windows. A rogue server could send you the name of a DLL or
4103 other file that could be loaded automatically by Windows or some
4104 third party software.
4105 Providing -J, --remote-header-name multiple times has no extra
4107 effect. Disable it again with --no-remote-header-name.
4108 Example:
4110 curl -OJ https://example.com/file
4111 See also -O, --remote-name.
4113 --remote-name-all
4115 This option changes the default action for all given URLs to be
4116 dealt with as if -O, --remote-name were used for each one. So if
4117 you want to disable that for a specific URL after --remote-name-
4118 all has been used, you must use "-o -" or --no-remote-name.
4119 Providing --remote-name-all multiple times has no extra effect.
4121 Disable it again with --no-remote-name-all.
4122 Example:
4124 curl --remote-name-all ftp://example.com/file1 ftp://example.com/file2
4125 See also -O, --remote-name.
4127 -O, --remote-name
4129 Write output to a local file named like the remote file we get.
4130 (Only the file part of the remote file is used, the path is cut
4131 off.)
4132 The file will be saved in the current working directory. If you
4134 want the file saved in a different directory, make sure you
4135 change the current working directory before invoking curl with
4136 this option or use --output-dir.
4137 The remote file name to use for saving is extracted from the
4139 given URL, nothing else, and if it already exists it will be
4140 overwritten. If you want the server to be able to choose the
4141 file name refer to -J, --remote-header-name which can be used in
4142 addition to this option. If the server chooses a file name and
4143 that name already exists it will not be overwritten.
4144 There is no URL decoding done on the file name. If it has %20 or
4146 other URL encoded parts of the name, they will end up as-is as
4147 file name.
4148 You may use this option as many times as the number of URLs you
4150 have.
4151 -O, --remote-name can be used several times in a command line
4153 Example:
4155 curl -O https://example.com/filename
4156 See also --remote-name-all, --output-dir and -J, --remote-
4158 header-name.
4159 -R, --remote-time
4161 When used, this will make curl attempt to figure out the time‐
4162 stamp of the remote file, and if that is available make the lo‐
4163 cal file get that same timestamp.
4164 Providing -R, --remote-time multiple times has no extra effect.
4166 Disable it again with --no-remote-time.
4167 Example:
4169 curl --remote-time -o foo https://example.com
4170 See also -O, --remote-name and -z, --time-cond.
4172 --remove-on-error
4174 When curl returns an error when told to save output in a local
4175 file, this option removes that saved file before exiting. This
4176 prevents curl from leaving a partial file in the case of an er‐
4177 ror during transfer.
4178 If the output is not a file, this option has no effect.
4180 Providing --remove-on-error multiple times has no extra effect.
4182 Disable it again with --no-remove-on-error.
4183 Example:
4185 curl --remove-on-error -o output https://example.com
4186 See also -f, --fail. Added in 7.83.0.
4188 --request-target <path>
4190 (HTTP) Tells curl to use an alternative "target" (path) instead
4191 of using the path as provided in the URL. Particularly useful
4192 when wanting to issue HTTP requests without leading slash or
4193 other data that does not follow the regular URL pattern, like
4194 "OPTIONS *".
4195 If --request-target is provided several times, the last set
4197 value will be used.
4198 Example:
4200 curl --request-target "*" -X OPTIONS https://example.com
4201 See also -X, --request. Added in 7.55.0.
4203 -X, --request <method>
4205 (HTTP) Specifies a custom request method to use when communicat‐
4206 ing with the HTTP server. The specified request method will be
4207 used instead of the method otherwise used (which defaults to
4208 GET). Read the HTTP 1.1 specification for details and explana‐
4209 tions. Common additional HTTP requests include PUT and DELETE,
4210 but related technologies like WebDAV offers PROPFIND, COPY, MOVE
4211 and more.
4212 Normally you do not need this option. All sorts of GET, HEAD,
4214 POST and PUT requests are rather invoked by using dedicated com‐
4215 mand line options.
4216 This option only changes the actual word used in the HTTP re‐
4218 quest, it does not alter the way curl behaves. So for example if
4219 you want to make a proper HEAD request, using -X HEAD will not
4220 suffice. You need to use the -I, --head option.
4221 The method string you set with -X, --request will be used for
4223 all requests, which if you for example use -L, --location may
4224 cause unintended side-effects when curl does not change request
4225 method according to the HTTP 30x response codes - and similar.
4226 (FTP) Specifies a custom FTP command to use instead of LIST when
4228 doing file lists with FTP.
4229 (POP3) Specifies a custom POP3 command to use instead of LIST or
4231 RETR.
4232 (IMAP) Specifies a custom IMAP command to use instead of LIST.
4235 (Added in 7.30.0)
4236 (SMTP) Specifies a custom SMTP command to use instead of HELP or
4238 VRFY. (Added in 7.34.0)
4239 If -X, --request is provided several times, the last set value
4241 will be used.
4242 Examples:
4244 curl -X "DELETE" https://example.com
4245 curl -X NLST ftp://example.com/
4246 See also --request-target.
4248 --resolve <[+]host:port:addr[,addr]...>
4250 Provide a custom address for a specific host and port pair. Us‐
4251 ing this, you can make the curl requests(s) use a specified ad‐
4252 dress and prevent the otherwise normally resolved address to be
4253 used. Consider it a sort of /etc/hosts alternative provided on
4254 the command line. The port number should be the number used for
4255 the specific protocol the host will be used for. It means you
4256 need several entries if you want to provide address for the same
4257 host but different ports.
4258 By specifying '*' as host you can tell curl to resolve any host
4260 and specific port pair to the specified address. Wildcard is re‐
4261 solved last so any --resolve with a specific host and port will
4262 be used first.
4263 The provided address set by this option will be used even if -4,
4265 --ipv4 or -6, --ipv6 is set to make curl use another IP version.
4266 By prefixing the host with a '+' you can make the entry time out
4268 after curl's default timeout (1 minute). Note that this will
4269 only make sense for long running parallel transfers with a lot
4270 of files. In such cases, if this option is used curl will try to
4271 resolve the host as it normally would once the timeout has ex‐
4272 pired.
4273 Support for providing the IP address within [brackets] was added
4275 in 7.57.0.
4276 Support for providing multiple IP addresses per entry was added
4278 in 7.59.0.
4279 Support for resolving with wildcard was added in 7.64.0.
4281 Support for the '+' prefix was was added in 7.75.0.
4283 This option can be used many times to add many host names to re‐
4285 solve.
4286 --resolve can be used several times in a command line
4288 Example:
4290 curl --resolve example.com:443:127.0.0.1 https://example.com
4291 See also --connect-to and --alt-svc.
4293 --retry-all-errors
4295 Retry on any error. This option is used together with --retry.
4296 This option is the "sledgehammer" of retrying. Do not use this
4298 option by default (eg in curlrc), there may be unintended conse‐
4299 quences such as sending or receiving duplicate data. Do not use
4300 with redirected input or output. You'd be much better off han‐
4301 dling your unique problems in shell script. Please read the ex‐
4302 ample below.
4303 WARNING: For server compatibility curl attempts to retry failed
4305 flaky transfers as close as possible to how they were started,
4306 but this is not possible with redirected input or output. For
4307 example, before retrying it removes output data from a failed
4308 partial transfer that was written to an output file. However
4309 this is not true of data redirected to a | pipe or > file, which
4310 are not reset. We strongly suggest you do not parse or record
4311 output via redirect in combination with this option, since you
4312 may receive duplicate data.
4313 By default curl will not error on an HTTP response code that in‐
4315 dicates an HTTP error, if the transfer was successful. For exam‐
4316 ple, if a server replies 404 Not Found and the reply is fully
4317 received then that is not an error. When --retry is used then
4318 curl will retry on some HTTP response codes that indicate tran‐
4319 sient HTTP errors, but that does not include most 4xx response
4320 codes such as 404. If you want to retry on all response codes
4321 that indicate HTTP errors (4xx and 5xx) then combine with -f,
4322 --fail.
4323 Providing --retry-all-errors multiple times has no extra effect.
4325 Disable it again with --no-retry-all-errors.
4326 Example:
4328 curl --retry 5 --retry-all-errors https://example.com
4329 See also --retry. Added in 7.71.0.
4331 --retry-connrefused
4333 In addition to the other conditions, consider ECONNREFUSED as a
4334 transient error too for --retry. This option is used together
4335 with --retry.
4336 Providing --retry-connrefused multiple times has no extra ef‐
4338 fect. Disable it again with --no-retry-connrefused.
4339 Example:
4341 curl --retry-connrefused --retry 7 https://example.com
4342 See also --retry and --retry-all-errors. Added in 7.52.0.
4344 --retry-delay <seconds>
4346 Make curl sleep this amount of time before each retry when a
4347 transfer has failed with a transient error (it changes the de‐
4348 fault backoff time algorithm between retries). This option is
4349 only interesting if --retry is also used. Setting this delay to
4350 zero will make curl use the default backoff time.
4351 If --retry-delay is provided several times, the last set value
4353 will be used.
4354 Example:
4356 curl --retry-delay 5 --retry 7 https://example.com
4357 See also --retry.
4359 --retry-max-time <seconds>
4361 The retry timer is reset before the first transfer attempt. Re‐
4362 tries will be done as usual (see --retry) as long as the timer
4363 has not reached this given limit. Notice that if the timer has
4364 not reached the limit, the request will be made and while per‐
4365 forming, it may take longer than this given time period. To
4366 limit a single request's maximum time, use -m, --max-time. Set
4367 this option to zero to not timeout retries.
4368 If --retry-max-time is provided several times, the last set
4370 value will be used.
4371 Example:
4373 curl --retry-max-time 30 --retry 10 https://example.com
4374 See also --retry.
4376 --retry <num>
4378 If a transient error is returned when curl tries to perform a
4379 transfer, it will retry this number of times before giving up.
4380 Setting the number to 0 makes curl do no retries (which is the
4381 default). Transient error means either: a timeout, an FTP 4xx
4382 response code or an HTTP 408, 429, 500, 502, 503 or 504 response
4383 code.
4384 When curl is about to retry a transfer, it will first wait one
4386 second and then for all forthcoming retries it will double the
4387 waiting time until it reaches 10 minutes which then will be the
4388 delay between the rest of the retries. By using --retry-delay
4389 you disable this exponential backoff algorithm. See also
4390 --retry-max-time to limit the total time allowed for retries.
4391 Since curl 7.66.0, curl will comply with the Retry-After: re‐
4393 sponse header if one was present to know when to issue the next
4394 retry.
4395 If --retry is provided several times, the last set value will be
4397 used.
4398 Example:
4400 curl --retry 7 https://example.com
4401 See also --retry-max-time.
4403 --sasl-authzid <identity>
4405 Use this authorization identity (authzid), during SASL PLAIN au‐
4406 thentication, in addition to the authentication identity (auth‐
4407 cid) as specified by -u, --user.
4408 If the option is not specified, the server will derive the au‐
4410 thzid from the authcid, but if specified, and depending on the
4411 server implementation, it may be used to access another user's
4412 inbox, that the user has been granted access to, or a shared
4413 mailbox for example.
4414 If --sasl-authzid is provided several times, the last set value
4416 will be used.
4417 Example:
4419 curl --sasl-authzid zid imap://example.com/
4420 See also --login-options. Added in 7.66.0.
4422 --sasl-ir
4424 Enable initial response in SASL authentication.
4425 Providing --sasl-ir multiple times has no extra effect. Disable
4427 it again with --no-sasl-ir.
4428 Example:
4430 curl --sasl-ir imap://example.com/
4431 See also --sasl-authzid. Added in 7.31.0.
4433 --service-name <name>
4435 This option allows you to change the service name for SPNEGO.
4436 Examples: --negotiate --service-name sockd would use
4438 sockd/server-name.
4439 If --service-name is provided several times, the last set value
4441 will be used.
4442 Example:
4444 curl --service-name sockd/server https://example.com
4445 See also --negotiate and --proxy-service-name. Added in 7.43.0.
4447 -S, --show-error
4449 When used with -s, --silent, it makes curl show an error message
4450 if it fails.
4451 This option is global and does not need to be specified for each
4453 use of --next.
4454 Providing -S, --show-error multiple times has no extra effect.
4456 Disable it again with --no-show-error.
4457 Example:
4459 curl --show-error --silent https://example.com
4460 See also --no-progress-meter.
4462 -s, --silent
4464 Silent or quiet mode. Do not show progress meter or error mes‐
4465 sages. Makes Curl mute. It will still output the data you ask
4466 for, potentially even to the terminal/stdout unless you redirect
4467 it.
4468 Use -S, --show-error in addition to this option to disable
4470 progress meter but still show error messages.
4471 Providing -s, --silent multiple times has no extra effect. Dis‐
4473 able it again with --no-silent.
4474 Example:
4476 curl -s https://example.com
4477 See also -v, --verbose, --stderr and --no-progress-meter.
4479 --socks4 <host[:port]>
4481 Use the specified SOCKS4 proxy. If the port number is not speci‐
4482 fied, it is assumed at port 1080. Using this socket type make
4483 curl resolve the host name and passing the address on to the
4484 proxy.
4485 To specify proxy on a unix domain socket, use localhost for
4487 host, e.g. socks4://localhost/path/to/socket.sock
4488 This option overrides any previous use of -x, --proxy, as they
4490 are mutually exclusive.
4491 This option is superfluous since you can specify a socks4 proxy
4493 with -x, --proxy using a socks4:// protocol prefix.
4494 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
4496 the same time -x, --proxy is used with an HTTP/HTTPS proxy. In
4497 such a case curl first connects to the SOCKS proxy and then con‐
4498 nects (through SOCKS) to the HTTP or HTTPS proxy.
4499 If --socks4 is provided several times, the last set value will
4501 be used.
4502 Example:
4504 curl --socks4 hostname:4096 https://example.com
4505 See also --socks4a, --socks5 and --socks5-hostname.
4507 --socks4a <host[:port]>
4509 Use the specified SOCKS4a proxy. If the port number is not spec‐
4510 ified, it is assumed at port 1080. This asks the proxy to re‐
4511 solve the host name.
4512 To specify proxy on a unix domain socket, use localhost for
4514 host, e.g. socks4a://localhost/path/to/socket.sock
4515 This option overrides any previous use of -x, --proxy, as they
4517 are mutually exclusive.
4518 This option is superfluous since you can specify a socks4a proxy
4520 with -x, --proxy using a socks4a:// protocol prefix.
4521 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
4523 the same time -x, --proxy is used with an HTTP/HTTPS proxy. In
4524 such a case curl first connects to the SOCKS proxy and then con‐
4525 nects (through SOCKS) to the HTTP or HTTPS proxy.
4526 If --socks4a is provided several times, the last set value will
4528 be used.
4529 Example:
4531 curl --socks4a hostname:4096 https://example.com
4532 See also --socks4, --socks5 and --socks5-hostname.
4534 --socks5-basic
4536 Tells curl to use username/password authentication when connect‐
4537 ing to a SOCKS5 proxy. The username/password authentication is
4538 enabled by default. Use --socks5-gssapi to force GSS-API au‐
4539 thentication to SOCKS5 proxies.
4540 Providing --socks5-basic multiple times has no extra effect.
4542 Example:
4544 curl --socks5-basic --socks5 hostname:4096 https://example.com
4545 See also --socks5. Added in 7.55.0.
4547 --socks5-gssapi-nec
4549 As part of the GSS-API negotiation a protection mode is negoti‐
4550 ated. RFC 1961 says in section 4.3/4.4 it should be protected,
4551 but the NEC reference implementation does not. The option
4552 --socks5-gssapi-nec allows the unprotected exchange of the pro‐
4553 tection mode negotiation.
4554 Providing --socks5-gssapi-nec multiple times has no extra ef‐
4556 fect. Disable it again with --no-socks5-gssapi-nec.
4557 Example:
4559 curl --socks5-gssapi-nec --socks5 hostname:4096 https://example.com
4560 See also --socks5.
4562 --socks5-gssapi-service <name>
4564 The default service name for a socks server is rcmd/server-fqdn.
4565 This option allows you to change it.
4566 Examples: --socks5 proxy-name --socks5-gssapi-service sockd
4568 would use sockd/proxy-name --socks5 proxy-name --socks5-gssapi-
4569 service sockd/real-name would use sockd/real-name for cases
4570 where the proxy-name does not match the principal name.
4571 If --socks5-gssapi-service is provided several times, the last
4573 set value will be used.
4574 Example:
4576 curl --socks5-gssapi-service sockd --socks5 hostname:4096 https://example.com
4577 See also --socks5.
4579 --socks5-gssapi
4581 Tells curl to use GSS-API authentication when connecting to a
4582 SOCKS5 proxy. The GSS-API authentication is enabled by default
4583 (if curl is compiled with GSS-API support). Use --socks5-basic
4584 to force username/password authentication to SOCKS5 proxies.
4585 Providing --socks5-gssapi multiple times has no extra effect.
4587 Disable it again with --no-socks5-gssapi.
4588 Example:
4590 curl --socks5-gssapi --socks5 hostname:4096 https://example.com
4591 See also --socks5. Added in 7.55.0.
4593 --socks5-hostname <host[:port]>
4595 Use the specified SOCKS5 proxy (and let the proxy resolve the
4596 host name). If the port number is not specified, it is assumed
4597 at port 1080.
4598 To specify proxy on a unix domain socket, use localhost for
4600 host, e.g. socks5h://localhost/path/to/socket.sock
4601 This option overrides any previous use of -x, --proxy, as they
4603 are mutually exclusive.
4604 This option is superfluous since you can specify a socks5 host‐
4606 name proxy with -x, --proxy using a socks5h:// protocol prefix.
4607 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
4609 the same time -x, --proxy is used with an HTTP/HTTPS proxy. In
4610 such a case curl first connects to the SOCKS proxy and then con‐
4611 nects (through SOCKS) to the HTTP or HTTPS proxy.
4612 If --socks5-hostname is provided several times, the last set
4614 value will be used.
4615 Example:
4617 curl --socks5-hostname proxy.example:7000 https://example.com
4618 See also --socks5 and --socks4a.
4620 --socks5 <host[:port]>
4622 Use the specified SOCKS5 proxy - but resolve the host name lo‐
4623 cally. If the port number is not specified, it is assumed at
4624 port 1080.
4625 To specify proxy on a unix domain socket, use localhost for
4627 host, e.g. socks5://localhost/path/to/socket.sock
4628 This option overrides any previous use of -x, --proxy, as they
4630 are mutually exclusive.
4631 This option is superfluous since you can specify a socks5 proxy
4633 with -x, --proxy using a socks5:// protocol prefix.
4634 Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at
4636 the same time -x, --proxy is used with an HTTP/HTTPS proxy. In
4637 such a case curl first connects to the SOCKS proxy and then con‐
4638 nects (through SOCKS) to the HTTP or HTTPS proxy.
4639 This option (as well as --socks4) does not work with IPV6, FTPS
4641 or LDAP.
4642 If --socks5 is provided several times, the last set value will
4644 be used.
4645 Example:
4647 curl --socks5 proxy.example:7000 https://example.com
4648 See also --socks5-hostname and --socks4a.
4650 -Y, --speed-limit <speed>
4652 If a transfer is slower than this given speed (in bytes per sec‐
4653 ond) for speed-time seconds it gets aborted. speed-time is set
4654 with -y, --speed-time and is 30 if not set.
4655 If -Y, --speed-limit is provided several times, the last set
4657 value will be used.
4658 Example:
4660 curl --speed-limit 300 --speed-time 10 https://example.com
4661 See also -y, --speed-time, --limit-rate and -m, --max-time.
4663 -y, --speed-time <seconds>
4665 If a transfer runs slower than speed-limit bytes per second dur‐
4666 ing a speed-time period, the transfer is aborted. If speed-time
4667 is used, the default speed-limit will be 1 unless set with -Y,
4668 --speed-limit.
4669 This option controls transfers (in both directions) but will not
4671 affect slow connects etc. If this is a concern for you, try the
4672 --connect-timeout option.
4673 If -y, --speed-time is provided several times, the last set
4675 value will be used.
4676 Example:
4678 curl --speed-limit 300 --speed-time 10 https://example.com
4679 See also -Y, --speed-limit and --limit-rate.
4681 --ssl-allow-beast
4683 This option tells curl to not work around a security flaw in the
4684 SSL3 and TLS1.0 protocols known as BEAST. If this option is not
4685 used, the SSL layer may use workarounds known to cause interop‐
4686 erability problems with some older SSL implementations.
4687 WARNING: this option loosens the SSL security, and by using this
4689 flag you ask for exactly that.
4690 Providing --ssl-allow-beast multiple times has no extra effect.
4692 Disable it again with --no-ssl-allow-beast.
4693 Example:
4695 curl --ssl-allow-beast https://example.com
4696 See also --proxy-ssl-allow-beast and -k, --insecure.
4698 --ssl-auto-client-cert
4700 Tell libcurl to automatically locate and use a client certifi‐
4701 cate for authentication, when requested by the server. This op‐
4702 tion is only supported for Schannel (the native Windows SSL li‐
4703 brary). Prior to 7.77.0 this was the default behavior in libcurl
4704 with Schannel. Since the server can request any certificate that
4705 supports client authentication in the OS certificate store it
4706 could be a privacy violation and unexpected.
4707 Providing --ssl-auto-client-cert multiple times has no extra ef‐
4709 fect. Disable it again with --no-ssl-auto-client-cert.
4710 Example:
4712 curl --ssl-auto-client-cert https://example.com
4713 See also --proxy-ssl-auto-client-cert. Added in 7.77.0.
4715 --ssl-no-revoke
4717 (Schannel) This option tells curl to disable certificate revoca‐
4718 tion checks. WARNING: this option loosens the SSL security, and
4719 by using this flag you ask for exactly that.
4720 Providing --ssl-no-revoke multiple times has no extra effect.
4722 Disable it again with --no-ssl-no-revoke.
4723 Example:
4725 curl --ssl-no-revoke https://example.com
4726 See also --crlfile. Added in 7.44.0.
4728 --ssl-reqd
4730 (FTP IMAP POP3 SMTP LDAP) Require SSL/TLS for the connection.
4731 Terminates the connection if the transfer cannot be upgraded to
4732 use SSL/TLS.
4733 This option is handled in LDAP since version 7.81.0. It is fully
4735 supported by the OpenLDAP backend and rejected by the generic
4736 ldap backend if explicit TLS is required.
4737 This option is unnecessary if you use a URL scheme that in it‐
4739 self implies immediate and implicit use of TLS, like for FTPS,
4740 IMAPS, POP3S, SMTPS and LDAPS. Such transfers will always fail
4741 if the TLS handshake does not work.
4742 This option was formerly known as --ftp-ssl-reqd.
4744 Providing --ssl-reqd multiple times has no extra effect. Dis‐
4746 able it again with --no-ssl-reqd.
4747 Example:
4749 curl --ssl-reqd ftp://example.com
4750 See also --ssl and -k, --insecure.
4752 --ssl-revoke-best-effort
4754 (Schannel) This option tells curl to ignore certificate revoca‐
4755 tion checks when they failed due to missing/offline distribution
4756 points for the revocation check lists.
4757 Providing --ssl-revoke-best-effort multiple times has no extra
4759 effect. Disable it again with --no-ssl-revoke-best-effort.
4760 Example:
4762 curl --ssl-revoke-best-effort https://example.com
4763 See also --crlfile and -k, --insecure. Added in 7.70.0.
4765 --ssl (FTP IMAP POP3 SMTP LDAP) Warning: this is considered an inse‐
4767 cure option. Consider using --ssl-reqd instead to be sure curl
4768 upgrades to a secure connection.
4769 Try to use SSL/TLS for the connection. Reverts to a non-secure
4771 connection if the server does not support SSL/TLS. See also
4772 --ftp-ssl-control and --ssl-reqd for different levels of encryp‐
4773 tion required.
4774 This option is handled in LDAP since version 7.81.0. It is fully
4776 supported by the OpenLDAP backend and ignored by the generic
4777 ldap backend.
4778 Please note that a server may close the connection if the nego‐
4780 tiation does not succeed.
4781 This option was formerly known as --ftp-ssl. That option name
4783 can still be used but will be removed in a future version.
4784 Providing --ssl multiple times has no extra effect. Disable it
4786 again with --no-ssl.
4787 Example:
4789 curl --ssl pop3://example.com/
4790 See also --ssl-reqd, -k, --insecure and --ciphers.
4792 -2, --sslv2
4794 (SSL) This option previously asked curl to use SSLv2, but start‐
4795 ing in curl 7.77.0 this instruction is ignored. SSLv2 is widely
4796 considered insecure (see RFC 6176).
4797 Providing -2, --sslv2 multiple times has no extra effect.
4799 Example:
4801 curl --sslv2 https://example.com
4802 See also --http1.1 and --http2. -2, --sslv2 requires that the
4804 underlying libcurl was built to support TLS. This option is mu‐
4805 tually exclusive to -3, --sslv3 and -1, --tlsv1 and --tlsv1.1
4806 and --tlsv1.2.
4807 -3, --sslv3
4809 (SSL) This option previously asked curl to use SSLv3, but start‐
4810 ing in curl 7.77.0 this instruction is ignored. SSLv3 is widely
4811 considered insecure (see RFC 7568).
4812 Providing -3, --sslv3 multiple times has no extra effect.
4814 Example:
4816 curl --sslv3 https://example.com
4817 See also --http1.1 and --http2. -3, --sslv3 requires that the
4819 underlying libcurl was built to support TLS. This option is mu‐
4820 tually exclusive to -2, --sslv2 and -1, --tlsv1 and --tlsv1.1
4821 and --tlsv1.2.
4822 --stderr <file>
4824 Redirect all writes to stderr to the specified file instead. If
4825 the file name is a plain '-', it is instead written to stdout.
4826 This option is global and does not need to be specified for each
4828 use of --next.
4829 If --stderr is provided several times, the last set value will
4831 be used.
4832 Example:
4834 curl --stderr output.txt https://example.com
4835 See also -v, --verbose and -s, --silent.
4837 --styled-output
4839 Enables the automatic use of bold font styles when writing HTTP
4840 headers to the terminal. Use --no-styled-output to switch them
4841 off.
4842 Styled output requires a terminal that supports bold fonts. This
4844 feature is not present on curl for Windows due to lack of this
4845 capability.
4846 This option is global and does not need to be specified for each
4848 use of --next.
4849 Providing --styled-output multiple times has no extra effect.
4851 Disable it again with --no-styled-output.
4852 Example:
4854 curl --styled-output -I https://example.com
4855 See also -I, --head and -v, --verbose. Added in 7.61.0.
4857 --suppress-connect-headers
4859 When -p, --proxytunnel is used and a CONNECT request is made do
4860 not output proxy CONNECT response headers. This option is meant
4861 to be used with -D, --dump-header or -i, --include which are
4862 used to show protocol headers in the output. It has no effect on
4863 debug options such as -v, --verbose or --trace, or any statis‐
4864 tics.
4865 Providing --suppress-connect-headers multiple times has no extra
4867 effect. Disable it again with --no-suppress-connect-headers.
4868 Example:
4870 curl --suppress-connect-headers --include -x proxy https://example.com
4871 See also -D, --dump-header, -i, --include and -p, --proxytunnel.
4873 Added in 7.54.0.
4874 --tcp-fastopen
4876 Enable use of TCP Fast Open (RFC 7413). TCP Fast Open is a TCP
4878 extension that allows data to get sent earlier over the connec‐
4879 tion (before the final handshake ACK) if the client and server
4880 have been connected previously.
4881 Providing --tcp-fastopen multiple times has no extra effect.
4883 Disable it again with --no-tcp-fastopen.
4884 Example:
4886 curl --tcp-fastopen https://example.com
4887 See also --false-start. Added in 7.49.0.
4889 --tcp-nodelay
4891 Turn on the TCP_NODELAY option. See the curl_easy_setopt(3) man
4892 page for details about this option.
4893 Since 7.50.2, curl sets this option by default and you need to
4895 explicitly switch it off if you do not want it on.
4896 Providing --tcp-nodelay multiple times has no extra effect.
4898 Disable it again with --no-tcp-nodelay.
4899 Example:
4901 curl --tcp-nodelay https://example.com
4902 See also -N, --no-buffer.
4904 -t, --telnet-option <opt=val>
4906 Pass options to the telnet protocol. Supported options are:
4907 TTYPE=<term> Sets the terminal type.
4909 XDISPLOC=<X display> Sets the X display location.
4911 NEW_ENV=<var,val> Sets an environment variable.
4913 -t, --telnet-option can be used several times in a command line
4915 Example:
4917 curl -t TTYPE=vt100 telnet://example.com/
4918 See also -K, --config.
4920 --tftp-blksize <value>
4922 (TFTP) Set TFTP BLKSIZE option (must be >512). This is the block
4923 size that curl will try to use when transferring data to or from
4924 a TFTP server. By default 512 bytes will be used.
4925 If --tftp-blksize is provided several times, the last set value
4927 will be used.
4928 Example:
4930 curl --tftp-blksize 1024 tftp://example.com/file
4931 See also --tftp-no-options.
4933 --tftp-no-options
4935 (TFTP) Tells curl not to send TFTP options requests.
4936 This option improves interop with some legacy servers that do
4938 not acknowledge or properly implement TFTP options. When this
4939 option is used --tftp-blksize is ignored.
4940 Providing --tftp-no-options multiple times has no extra effect.
4942 Disable it again with --no-tftp-no-options.
4943 Example:
4945 curl --tftp-no-options tftp://192.168.0.1/
4946 See also --tftp-blksize. Added in 7.48.0.
4948 -z, --time-cond <time>
4950 (HTTP FTP) Request a file that has been modified later than the
4951 given time and date, or one that has been modified before that
4952 time. The <date expression> can be all sorts of date strings or
4953 if it does not match any internal ones, it is taken as a file‐
4954 name and tries to get the modification date (mtime) from <file>
4955 instead. See the curl_getdate(3) man pages for date expression
4956 details.
4957 Start the date expression with a dash (-) to make it request for
4959 a document that is older than the given date/time, default is a
4960 document that is newer than the specified date/time.
4961 If -z, --time-cond is provided several times, the last set value
4963 will be used.
4964 Examples:
4966 curl -z "Wed 01 Sep 2021 12:18:00" https://example.com
4967 curl -z "-Wed 01 Sep 2021 12:18:00" https://example.com
4968 curl -z file https://example.com
4969 See also --etag-compare and -R, --remote-time.
4971 --tls-max <VERSION>
4973 (TLS) VERSION defines maximum supported TLS version. The minimum
4974 acceptable version is set by tlsv1.0, tlsv1.1, tlsv1.2 or
4975 tlsv1.3.
4976 If the connection is done without TLS, this option has no ef‐
4978 fect. This includes QUIC-using (HTTP/3) transfers.
4979 default
4982 Use up to recommended TLS version.
4983 1.0 Use up to TLSv1.0.
4985 1.1 Use up to TLSv1.1.
4987 1.2 Use up to TLSv1.2.
4989 1.3 Use up to TLSv1.3.
4991 If --tls-max is provided several times, the last set value will
4993 be used.
4994 Examples:
4996 curl --tls-max 1.2 https://example.com
4997 curl --tls-max 1.3 --tlsv1.2 https://example.com
4998 See also --tlsv1.0, --tlsv1.1, --tlsv1.2 and --tlsv1.3. --tls-
5000 max requires that the underlying libcurl was built to support
5001 TLS. Added in 7.54.0.
5002 --tls13-ciphers <ciphersuite list>
5004 (TLS) Specifies which cipher suites to use in the connection if
5005 it negotiates TLS 1.3. The list of ciphers suites must specify
5006 valid ciphers. Read up on TLS 1.3 cipher suite details on this
5007 URL:
5008 https://curl.se/docs/ssl-ciphers.html
5010 This option is currently used only when curl is built to use
5012 OpenSSL 1.1.1 or later or Schannel. If you are using a different
5013 SSL backend you can try setting TLS 1.3 cipher suites by using
5014 the --ciphers option.
5015 If --tls13-ciphers is provided several times, the last set value
5017 will be used.
5018 Example:
5020 curl --tls13-ciphers TLS_AES_128_GCM_SHA256 https://example.com
5021 See also --ciphers, --curves and --proxy-tls13-ciphers. Added in
5023 7.61.0.
5024 --tlsauthtype <type>
5026 Set TLS authentication type. Currently, the only supported op‐
5027 tion is "SRP", for TLS-SRP (RFC 5054). If --tlsuser and
5028 --tlspassword are specified but --tlsauthtype is not, then this
5029 option defaults to "SRP". This option works only if the underly‐
5030 ing libcurl is built with TLS-SRP support, which requires
5031 OpenSSL or GnuTLS with TLS-SRP support.
5032 If --tlsauthtype is provided several times, the last set value
5034 will be used.
5035 Example:
5037 curl --tlsauthtype SRP https://example.com
5038 See also --tlsuser.
5040 --tlspassword <string>
5042 Set password for use with the TLS authentication method speci‐
5043 fied with --tlsauthtype. Requires that --tlsuser also be set.
5044 This option does not work with TLS 1.3.
5046 If --tlspassword is provided several times, the last set value
5048 will be used.
5049 Example:
5051 curl --tlspassword pwd --tlsuser user https://example.com
5052 See also --tlsuser.
5054 --tlsuser <name>
5056 Set username for use with the TLS authentication method speci‐
5057 fied with --tlsauthtype. Requires that --tlspassword also is
5058 set.
5059 This option does not work with TLS 1.3.
5061 If --tlsuser is provided several times, the last set value will
5063 be used.
5064 Example:
5066 curl --tlspassword pwd --tlsuser user https://example.com
5067 See also --tlspassword.
5069 --tlsv1.0
5071 (TLS) Forces curl to use TLS version 1.0 or later when connect‐
5072 ing to a remote TLS server.
5073 In old versions of curl this option was documented to allow
5075 _only_ TLS 1.0. That behavior was inconsistent depending on the
5076 TLS library. Use --tls-max if you want to set a maximum TLS ver‐
5077 sion.
5078 Providing --tlsv1.0 multiple times has no extra effect.
5080 Example:
5082 curl --tlsv1.0 https://example.com
5083 See also --tlsv1.3. Added in 7.34.0.
5085 --tlsv1.1
5087 (TLS) Forces curl to use TLS version 1.1 or later when connect‐
5088 ing to a remote TLS server.
5089 In old versions of curl this option was documented to allow
5091 _only_ TLS 1.1. That behavior was inconsistent depending on the
5092 TLS library. Use --tls-max if you want to set a maximum TLS ver‐
5093 sion.
5094 Providing --tlsv1.1 multiple times has no extra effect.
5096 Example:
5098 curl --tlsv1.1 https://example.com
5099 See also --tlsv1.3 and --tls-max. Added in 7.34.0.
5101 --tlsv1.2
5103 (TLS) Forces curl to use TLS version 1.2 or later when connect‐
5104 ing to a remote TLS server.
5105 In old versions of curl this option was documented to allow
5107 _only_ TLS 1.2. That behavior was inconsistent depending on the
5108 TLS library. Use --tls-max if you want to set a maximum TLS ver‐
5109 sion.
5110 Providing --tlsv1.2 multiple times has no extra effect.
5112 Example:
5114 curl --tlsv1.2 https://example.com
5115 See also --tlsv1.3 and --tls-max. Added in 7.34.0.
5117 --tlsv1.3
5119 (TLS) Forces curl to use TLS version 1.3 or later when connect‐
5120 ing to a remote TLS server.
5121 If the connection is done without TLS, this option has no ef‐
5123 fect. This includes QUIC-using (HTTP/3) transfers.
5124 Note that TLS 1.3 is not supported by all TLS backends.
5126 Providing --tlsv1.3 multiple times has no extra effect.
5128 Example:
5130 curl --tlsv1.3 https://example.com
5131 See also --tlsv1.2 and --tls-max. Added in 7.52.0.
5133 -1, --tlsv1
5135 (TLS) Tells curl to use at least TLS version 1.x when negotiat‐
5136 ing with a remote TLS server. That means TLS version 1.0 or
5137 higher
5138 Providing -1, --tlsv1 multiple times has no extra effect.
5140 Example:
5142 curl --tlsv1 https://example.com
5143 See also --http1.1 and --http2. -1, --tlsv1 requires that the
5145 underlying libcurl was built to support TLS. This option is mu‐
5146 tually exclusive to --tlsv1.1 and --tlsv1.2 and --tlsv1.3.
5147 --tr-encoding
5149 (HTTP) Request a compressed Transfer-Encoding response using one
5150 of the algorithms curl supports, and uncompress the data while
5151 receiving it.
5152 Providing --tr-encoding multiple times has no extra effect.
5154 Disable it again with --no-tr-encoding.
5155 Example:
5157 curl --tr-encoding https://example.com
5158 See also --compressed.
5160 --trace-ascii <file>
5162 Enables a full trace dump of all incoming and outgoing data, in‐
5163 cluding descriptive information, to the given output file. Use
5164 "-" as filename to have the output sent to stdout.
5165 This is similar to --trace, but leaves out the hex part and only
5167 shows the ASCII part of the dump. It makes smaller output that
5168 might be easier to read for untrained humans.
5169 This option is global and does not need to be specified for each
5171 use of --next.
5172 If --trace-ascii is provided several times, the last set value
5174 will be used.
5175 Example:
5177 curl --trace-ascii log.txt https://example.com
5178 See also -v, --verbose and --trace. This option is mutually ex‐
5180 clusive to --trace and -v, --verbose.
5181 --trace-ids
5183 Prepends the transfer and connection identifiers to each trace
5184 or verbose line that curl displays.
5185 This option is global and does not need to be specified for each
5187 use of --next.
5188 Providing --trace-ids multiple times has no extra effect. Dis‐
5190 able it again with --no-trace-ids.
5191 Example:
5193 curl --trace-ids --trace-ascii output https://example.com
5194 See also --trace and -v, --verbose. Added in 8.2.0.
5196 --trace-time
5198 Prepends a time stamp to each trace or verbose line that curl
5199 displays.
5200 This option is global and does not need to be specified for each
5202 use of --next.
5203 Providing --trace-time multiple times has no extra effect. Dis‐
5205 able it again with --no-trace-time.
5206 Example:
5208 curl --trace-time --trace-ascii output https://example.com
5209 See also --trace and -v, --verbose.
5211 --trace <file>
5213 Enables a full trace dump of all incoming and outgoing data, in‐
5214 cluding descriptive information, to the given output file. Use
5215 "-" as filename to have the output sent to stdout. Use "%" as
5216 filename to have the output sent to stderr.
5217 This option is global and does not need to be specified for each
5219 use of --next.
5220 If --trace is provided several times, the last set value will be
5222 used.
5223 Example:
5225 curl --trace log.txt https://example.com
5226 See also --trace-ascii, --trace-ids and --trace-time. This op‐
5228 tion is mutually exclusive to -v, --verbose and --trace-ascii.
5229 --unix-socket <path>
5231 (HTTP) Connect through this Unix domain socket, instead of using
5232 the network.
5233 If --unix-socket is provided several times, the last set value
5235 will be used.
5236 Example:
5238 curl --unix-socket socket-path https://example.com
5239 See also --abstract-unix-socket. Added in 7.40.0.
5241 -T, --upload-file <file>
5243 This transfers the specified local file to the remote URL. If
5244 there is no file part in the specified URL, curl will append the
5245 local file name. NOTE that you must use a trailing / on the last
5246 directory to really prove to Curl that there is no file name or
5247 curl will think that your last directory name is the remote file
5248 name to use. That will most likely cause the upload operation to
5249 fail. If this is used on an HTTP(S) server, the PUT command will
5250 be used.
5251 Use the file name "-" (a single dash) to use stdin instead of a
5253 given file. Alternately, the file name "." (a single period)
5254 may be specified instead of "-" to use stdin in non-blocking
5255 mode to allow reading server output while stdin is being up‐
5256 loaded.
5257 You can specify one -T, --upload-file for each URL on the com‐
5259 mand line. Each -T, --upload-file + URL pair specifies what to
5260 upload and to where. curl also supports "globbing" of the -T,
5261 --upload-file argument, meaning that you can upload multiple
5262 files to a single URL by using the same URL globbing style sup‐
5263 ported in the URL.
5264 When uploading to an SMTP server: the uploaded data is assumed
5266 to be RFC 5322 formatted. It has to feature the necessary set of
5267 headers and mail body formatted correctly by the user as curl
5268 will not transcode nor encode it further in any way.
5269 -T, --upload-file can be used several times in a command line
5271 Examples:
5273 curl -T file https://example.com
5274 curl -T "img[1-1000].png" ftp://ftp.example.com/
5275 curl --upload-file "{file1,file2}" https://example.com
5276 See also -G, --get and -I, --head.
5278 --url-query <data>
5280 (all) This option adds a piece of data, usually a name + value
5281 pair, to the end of the URL query part. The syntax is identical
5282 to that used for --data-urlencode with one extension:
5283 If the argument starts with a '+' (plus), the rest of the string
5285 is provided as-is unencoded.
5286 The query part of a URL is the one following the question mark
5288 on the right end.
5289 --url-query can be used several times in a command line
5291 Examples:
5293 curl --url-query name=val https://example.com
5294 curl --url-query =encodethis http://example.net/foo
5295 curl --url-query name@file https://example.com
5296 curl --url-query @fileonly https://example.com
5297 curl --url-query "+name=%20foo" https://example.com
5298 See also --data-urlencode and -G, --get. Added in 7.87.0.
5300 --url <url>
5302 Specify a URL to fetch. This option is mostly handy when you
5303 want to specify URL(s) in a config file.
5304 If the given URL is missing a scheme name (such as "http://" or
5306 "ftp://" etc) then curl will make a guess based on the host. If
5307 the outermost sub-domain name matches DICT, FTP, IMAP, LDAP,
5308 POP3 or SMTP then that protocol will be used, otherwise HTTP
5309 will be used. Since 7.45.0 guessing can be disabled by setting a
5310 default protocol, see --proto-default for details.
5311 To control where this URL is written, use the -o, --output or
5313 the -O, --remote-name options.
5314 WARNING: On Windows, particular file:// accesses can be con‐
5316 verted to network accesses by the operating system. Beware!
5317 --url can be used several times in a command line
5319 Example:
5321 curl --url https://example.com
5322 See also -:, --next and -K, --config.
5324 -B, --use-ascii
5326 (FTP LDAP) Enable ASCII transfer. For FTP, this can also be en‐
5327 forced by using a URL that ends with ";type=A". This option
5328 causes data sent to stdout to be in text mode for win32 systems.
5329 Providing -B, --use-ascii multiple times has no extra effect.
5331 Disable it again with --no-use-ascii.
5332 Example:
5334 curl -B ftp://example.com/README
5335 See also --crlf and --data-ascii.
5337 -A, --user-agent <name>
5339 (HTTP) Specify the User-Agent string to send to the HTTP server.
5340 To encode blanks in the string, surround the string with single
5341 quote marks. This header can also be set with the -H, --header
5342 or the --proxy-header options.
5343 If you give an empty argument to -A, --user-agent (""), it will
5345 remove the header completely from the request. If you prefer a
5346 blank header, you can set it to a single space (" ").
5347 If -A, --user-agent is provided several times, the last set
5349 value will be used.
5350 Example:
5352 curl -A "Agent 007" https://example.com
5353 See also -H, --header and --proxy-header.
5355 -u, --user <user:password>
5357 Specify the user name and password to use for server authentica‐
5358 tion. Overrides -n, --netrc and --netrc-optional.
5359 If you simply specify the user name, curl will prompt for a
5361 password.
5362 The user name and passwords are split up on the first colon,
5364 which makes it impossible to use a colon in the user name with
5365 this option. The password can, still.
5366 On systems where it works, curl will hide the given option argu‐
5368 ment from process listings. This is not enough to protect cre‐
5369 dentials from possibly getting seen by other users on the same
5370 system as they will still be visible for a moment before
5371 cleared. Such sensitive data should be retrieved from a file in‐
5372 stead or similar and never used in clear text in a command line.
5373 When using Kerberos V5 with a Windows based server you should
5375 include the Windows domain name in the user name, in order for
5376 the server to successfully obtain a Kerberos Ticket. If you do
5377 not, then the initial authentication handshake may fail.
5378 When using NTLM, the user name can be specified simply as the
5380 user name, without the domain, if there is a single domain and
5381 forest in your setup for example.
5382 To specify the domain name use either Down-Level Logon Name or
5384 UPN (User Principal Name) formats. For example, EXAMPLE\user and
5385 user@example.com respectively.
5386 If you use a Windows SSPI-enabled curl binary and perform Ker‐
5388 beros V5, Negotiate, NTLM or Digest authentication then you can
5389 tell curl to select the user name and password from your envi‐
5390 ronment by specifying a single colon with this option: "-u :".
5391 If -u, --user is provided several times, the last set value will
5393 be used.
5394 Example:
5396 curl -u user:secret https://example.com
5397 See also -n, --netrc and -K, --config.
5399 -v, --verbose
5401 Makes curl verbose during the operation. Useful for debugging
5402 and seeing what's going on "under the hood". A line starting
5403 with '>' means "header data" sent by curl, '<' means "header
5404 data" received by curl that is hidden in normal cases, and a
5405 line starting with '*' means additional info provided by curl.
5406 If you only want HTTP headers in the output, -i, --include or
5408 -D, --dump-header might be more suitable options.
5409 If you think this option still does not give you enough details,
5411 consider using --trace or --trace-ascii instead.
5412 This option is global and does not need to be specified for each
5414 use of --next.
5415 Providing -v, --verbose multiple times has no extra effect.
5417 Disable it again with --no-verbose.
5418 Example:
5420 curl --verbose https://example.com
5421 See also -i, --include, -s, --silent, --trace and --trace-ascii.
5423 This option is mutually exclusive to --trace and --trace-ascii.
5424 -V, --version
5426 Displays information about curl and the libcurl version it uses.
5427 The first line includes the full version of curl, libcurl and
5429 other 3rd party libraries linked with the executable.
5430 The second line (starts with "Protocols:") shows all protocols
5432 that libcurl reports to support.
5433 The third line (starts with "Features:") shows specific features
5435 libcurl reports to offer. Available features include:
5436 alt-svc
5438 Support for the Alt-Svc: header is provided.
5439 AsynchDNS
5441 This curl uses asynchronous name resolves. Asynchronous
5442 name resolves can be done using either the c-ares or the
5443 threaded resolver backends.
5444 brotli Support for automatic brotli compression over HTTP(S).
5446 CharConv
5448 curl was built with support for character set conversions
5449 (like EBCDIC)
5450 Debug This curl uses a libcurl built with Debug. This enables
5452 more error-tracking and memory debugging etc. For curl-
5453 developers only!
5454 gsasl The built-in SASL authentication includes extensions to
5456 support SCRAM because libcurl was built with libgsasl.
5457 GSS-API
5459 GSS-API is supported.
5460 HSTS HSTS support is present.
5462 HTTP2 HTTP/2 support has been built-in.
5464 HTTP3 HTTP/3 support has been built-in.
5466 HTTPS-proxy
5468 This curl is built to support HTTPS proxy.
5469 IDN This curl supports IDN - international domain names.
5471 IPv6 You can use IPv6 with this.
5473 Kerberos
5475 Kerberos V5 authentication is supported.
5476 Largefile
5478 This curl supports transfers of large files, files larger
5479 than 2GB.
5480 libz Automatic decompression (via gzip, deflate) of compressed
5482 files over HTTP is supported.
5483 MultiSSL
5485 This curl supports multiple TLS backends.
5486 NTLM NTLM authentication is supported.
5488 NTLM_WB
5490 NTLM delegation to winbind helper is supported.
5491 PSL PSL is short for Public Suffix List and means that this
5493 curl has been built with knowledge about "public suf‐
5494 fixes".
5495 SPNEGO SPNEGO authentication is supported.
5497 SSL SSL versions of various protocols are supported, such as
5499 HTTPS, FTPS, POP3S and so on.
5500 SSPI SSPI is supported.
5502 TLS-SRP
5504 SRP (Secure Remote Password) authentication is supported
5505 for TLS.
5506 TrackMemory
5508 Debug memory tracking is supported.
5509 Unicode
5511 Unicode support on Windows.
5512 UnixSockets
5514 Unix sockets support is provided.
5515 zstd Automatic decompression (via zstd) of compressed files
5517 over HTTP is supported.
5518 Example:
5520 curl --version
5521 See also -h, --help and -M, --manual.
5523 -w, --write-out <format>
5525 Make curl display information on stdout after a completed trans‐
5526 fer. The format is a string that may contain plain text mixed
5527 with any number of variables. The format can be specified as a
5528 literal "string", or you can have curl read the format from a
5529 file with "@filename" and to tell curl to read the format from
5530 stdin you write "@-".
5531 The variables present in the output format will be substituted
5533 by the value or text that curl thinks fit, as described below.
5534 All variables are specified as %{variable_name} and to output a
5535 normal % you just write them as %%. You can output a newline by
5536 using \n, a carriage return with \r and a tab space with \t.
5537 The output will be written to standard output, but this can be
5539 switched to standard error by using %{stderr}.
5540 Output HTTP headers from the most recent request by using
5542 %header{name} where name is the case insensitive name of the
5543 header (without the trailing colon). The header contents are ex‐
5544 actly as sent over the network, with leading and trailing white‐
5545 space trimmed. Added in curl 7.84.0.
5546 NOTE: In Windows the %-symbol is a special symbol used to expand
5548 environment variables. In batch files all occurrences of % must
5549 be doubled when using this option to properly escape. If this
5550 option is used at the command prompt then the % cannot be es‐
5551 caped and unintended expansion is possible.
5552 The variables available are:
5554 certs Output the certificate chain with details. Sup‐
5556 ported only by the OpenSSL, GnuTLS, Schannel,
5557 NSS, GSKit and Secure Transport backends. (Added
5558 in 7.88.0)
5559 content_type The Content-Type of the requested document, if
5561 there was any.
5562 errormsg The error message. (Added in 7.75.0)
5564 exitcode The numerical exitcode of the transfer. (Added in
5566 7.75.0)
5567 filename_effective
5569 The ultimate filename that curl writes out to.
5570 This is only meaningful if curl is told to write
5571 to a file with the -O, --remote-name or -o,
5572 --output option. It's most useful in combination
5573 with the -J, --remote-header-name option.
5574 ftp_entry_path The initial path curl ended up in when logging on
5576 to the remote FTP server.
5577 header_json A JSON object with all HTTP response headers from
5579 the recent transfer. Values are provided as ar‐
5580 rays, since in the case of multiple headers there
5581 can be multiple values. (Added in 7.83.0)
5582 The header names provided in lowercase, listed in
5584 order of appearance over the wire. Except for du‐
5585 plicated headers. They are grouped on the first
5586 occurrence of that header, each value is pre‐
5587 sented in the JSON array.
5588 http_code The numerical response code that was found in the
5590 last retrieved HTTP(S) or FTP(s) transfer.
5591 http_connect The numerical code that was found in the last re‐
5593 sponse (from a proxy) to a curl CONNECT request.
5594 http_version The http version that was effectively used.
5596 (Added in 7.50.0)
5597 json A JSON object with all available keys.
5599 local_ip The IP address of the local end of the most re‐
5601 cently done connection - can be either IPv4 or
5602 IPv6.
5603 local_port The local port number of the most recently done
5605 connection.
5606 method The http method used in the most recent HTTP re‐
5608 quest. (Added in 7.72.0)
5609 num_certs Number of server certificates received in the TLS
5611 handshake. Supported only by the OpenSSL, GnuTLS,
5612 Schannel, NSS, GSKit and Secure Transport back‐
5613 ends. (Added in 7.88.0)
5614 num_connects Number of new connects made in the recent trans‐
5616 fer.
5617 num_headers The number of response headers in the most recent
5619 request (restarted at each redirect). Note that
5620 the status line IS NOT a header. (Added in
5621 7.73.0)
5622 num_redirects Number of redirects that were followed in the re‐
5624 quest.
5625 onerror The rest of the output is only shown if the
5627 transfer returned a non-zero error. (Added in
5628 7.75.0)
5629 proxy_ssl_verify_result
5631 The result of the HTTPS proxy's SSL peer certifi‐
5632 cate verification that was requested. 0 means the
5633 verification was successful. (Added in 7.52.0)
5634 redirect_url When an HTTP request was made without -L, --loca‐
5636 tion to follow redirects (or when --max-redirs is
5637 met), this variable will show the actual URL a
5638 redirect would have gone to.
5639 referer The Referer: header, if there was any. (Added in
5641 7.76.0)
5642 remote_ip The remote IP address of the most recently done
5644 connection - can be either IPv4 or IPv6.
5645 remote_port The remote port number of the most recently done
5647 connection.
5648 response_code The numerical response code that was found in the
5650 last transfer (formerly known as "http_code").
5651 scheme The URL scheme (sometimes called protocol) that
5653 was effectively used. (Added in 7.52.0)
5654 size_download The total amount of bytes that were downloaded.
5656 This is the size of the body/data that was trans‐
5657 ferred, excluding headers.
5658 size_header The total amount of bytes of the downloaded head‐
5660 ers.
5661 size_request The total amount of bytes that were sent in the
5663 HTTP request.
5664 size_upload The total amount of bytes that were uploaded.
5666 This is the size of the body/data that was trans‐
5667 ferred, excluding headers.
5668 speed_download The average download speed that curl measured for
5670 the complete download. Bytes per second.
5671 speed_upload The average upload speed that curl measured for
5673 the complete upload. Bytes per second.
5674 ssl_verify_result
5676 The result of the SSL peer certificate verifica‐
5677 tion that was requested. 0 means the verification
5678 was successful.
5679 stderr From this point on, the -w, --write-out output
5681 will be written to standard error. (Added in
5682 7.63.0)
5683 stdout From this point on, the -w, --write-out output
5685 will be written to standard output. This is the
5686 default, but can be used to switch back after
5687 switching to stderr. (Added in 7.63.0)
5688 time_appconnect
5690 The time, in seconds, it took from the start un‐
5691 til the SSL/SSH/etc connect/handshake to the re‐
5692 mote host was completed.
5693 time_connect The time, in seconds, it took from the start un‐
5695 til the TCP connect to the remote host (or proxy)
5696 was completed.
5697 time_namelookup
5699 The time, in seconds, it took from the start un‐
5700 til the name resolving was completed.
5701 time_pretransfer
5703 The time, in seconds, it took from the start un‐
5704 til the file transfer was just about to begin.
5705 This includes all pre-transfer commands and nego‐
5706 tiations that are specific to the particular pro‐
5707 tocol(s) involved.
5708 time_redirect The time, in seconds, it took for all redirection
5710 steps including name lookup, connect, pretransfer
5711 and transfer before the final transaction was
5712 started. time_redirect shows the complete execu‐
5713 tion time for multiple redirections.
5714 time_starttransfer
5716 The time, in seconds, it took from the start un‐
5717 til the first byte was just about to be trans‐
5718 ferred. This includes time_pretransfer and also
5719 the time the server needed to calculate the re‐
5720 sult.
5721 time_total The total time, in seconds, that the full opera‐
5723 tion lasted.
5724 url The URL that was fetched. (Added in 7.75.0)
5726 url.scheme The scheme part of the URL that was fetched.
5728 (Added in 8.1.0)
5729 url.user The user part of the URL that was fetched. (Added
5731 in 8.1.0)
5732 url.password The password part of the URL that was fetched.
5734 (Added in 8.1.0)
5735 url.options The options part of the URL that was fetched.
5737 (Added in 8.1.0)
5738 url.host The host part of the URL that was fetched. (Added
5740 in 8.1.0)
5741 url.port The port number of the URL that was fetched. If
5743 no port number was specified, but the URL scheme
5744 is known, that scheme's default port number is
5745 shown. (Added in 8.1.0)
5746 url.path The path part of the URL that was fetched. (Added
5748 in 8.1.0)
5749 url.query The query part of the URL that was fetched.
5751 (Added in 8.1.0)
5752 url.fragment The fragment part of the URL that was fetched.
5754 (Added in 8.1.0)
5755 url.zoneid The zoneid part of the URL that was fetched.
5757 (Added in 8.1.0)
5758 urle.scheme The scheme part of the effective (last) URL that
5760 was fetched. (Added in 8.1.0)
5761 urle.user The user part of the effective (last) URL that
5763 was fetched. (Added in 8.1.0)
5764 urle.password The password part of the effective (last) URL
5766 that was fetched. (Added in 8.1.0)
5767 urle.options The options part of the effective (last) URL that
5769 was fetched. (Added in 8.1.0)
5770 urle.host The host part of the effective (last) URL that
5772 was fetched. (Added in 8.1.0)
5773 urle.port The port number of the effective (last) URL that
5775 was fetched. If no port number was specified, but
5776 the URL scheme is known, that scheme's default
5777 port number is shown. (Added in 8.1.0)
5778 urle.path The path part of the effective (last) URL that
5780 was fetched. (Added in 8.1.0)
5781 urle.query The query part of the effective (last) URL that
5783 was fetched. (Added in 8.1.0)
5784 urle.fragment The fragment part of the effective (last) URL
5786 that was fetched. (Added in 8.1.0)
5787 urle.zoneid The zoneid part of the effective (last) URL that
5789 was fetched. (Added in 8.1.0)
5790 urlnum The URL index number of this transfer, 0-indexed.
5792 De-globbed URLs share the same index number as
5793 the origin globbed URL. (Added in 7.75.0)
5794 url_effective The URL that was fetched last. This is most mean‐
5796 ingful if you have told curl to follow location:
5797 headers.
5798 If -w, --write-out is provided several times, the last set value
5800 will be used.
5801 Example:
5803 curl -w '%{response_code}\n' https://example.com
5804 See also -v, --verbose and -I, --head.
5806 --xattr
5808 When saving output to a file, this option tells curl to store
5809 certain file metadata in extended file attributes. Currently,
5810 the URL is stored in the xdg.origin.url attribute and, for HTTP,
5811 the content type is stored in the mime_type attribute. If the
5812 file system does not support extended attributes, a warning is
5813 issued.
5814 Providing --xattr multiple times has no extra effect. Disable
5816 it again with --no-xattr.
5817 Example:
5819 curl --xattr -o storage https://example.com
5820 See also -R, --remote-time, -w, --write-out and -v, --verbose.
5822
5824 ~/.curlrc
5825 Default config file, see -K, --config for details.
5826
5828 The environment variables can be specified in lower case or upper case.
5829 The lower case version has precedence. http_proxy is an exception as it
5830 is only available in lower case.
5831 Using an environment variable to set the proxy has the same effect as
5833 using the -x, --proxy option.
5834 http_proxy [protocol://]<host>[:port]
5837 Sets the proxy server to use for HTTP.
5838 HTTPS_PROXY [protocol://]<host>[:port]
5840 Sets the proxy server to use for HTTPS.
5841 [url-protocol]_PROXY [protocol://]<host>[:port]
5843 Sets the proxy server to use for [url-protocol], where the pro‐
5844 tocol is a protocol that curl supports and as specified in a
5845 URL. FTP, FTPS, POP3, IMAP, SMTP, LDAP, etc.
5846 ALL_PROXY [protocol://]<host>[:port]
5848 Sets the proxy server to use if no protocol-specific proxy is
5849 set.
5850 NO_PROXY <comma-separated list of hosts/domains>
5852 list of host names that should not go through any proxy. If set
5853 to an asterisk '*' only, it matches all hosts. Each name in this
5854 list is matched as either a domain name which contains the host‐
5855 name, or the hostname itself.
5856 This environment variable disables use of the proxy even when
5858 specified with the -x, --proxy option. That is NO_PROXY=di‐
5859 rect.example.com curl -x http://proxy.example.com http://di‐
5860 rect.example.com accesses the target URL directly, and
5861 NO_PROXY=direct.example.com curl -x http://proxy.example.com
5862 http://somewhere.example.com accesses the target URL through the
5863 proxy.
5864 The list of host names can also be include numerical IP ad‐
5866 dresses, and IPv6 versions should then be given without enclos‐
5867 ing brackets.
5868 Since 7.86.0, IP addresses can be specified using CIDR notation:
5870 an appended slash and number specifies the number of "network
5871 bits" out of the address to use in the comparison. For example
5872 "192.168.0.0/16" would match all addresses starting with
5873 "192.168".
5874 APPDATA <dir>
5876 On Windows, this variable is used when trying to find the home
5877 directory. If the primary home variable are all unset.
5878 COLUMNS <terminal width>
5880 If set, the specified number of characters will be used as the
5881 terminal width when the alternative progress-bar is shown. If
5882 not set, curl will try to figure it out using other ways.
5883 CURL_CA_BUNDLE <file>
5885 If set, will be used as the --cacert value.
5886 CURL_HOME <dir>
5888 If set, is the first variable curl checks when trying to find
5889 its home directory. If not set, it continues to check XDG_CON‐
5890 FIG_HOME
5891 CURL_SSL_BACKEND <TLS backend>
5893 If curl was built with support for "MultiSSL", meaning that it
5894 has built-in support for more than one TLS backend, this envi‐
5895 ronment variable can be set to the case insensitive name of the
5896 particular backend to use when curl is invoked. Setting a name
5897 that is not a built-in alternative will make curl stay with the
5898 default.
5899 SSL backend names (case-insensitive): bearssl, gnutls, gskit,
5901 mbedtls, nss, openssl, rustls, schannel, secure-transport, wolf‐
5902 ssl
5903 HOME <dir>
5905 If set, this is used to find the home directory when that is
5906 needed. Like when looking for the default .curlrc. CURL_HOME and
5907 XDG_CONFIG_HOME have preference.
5908 QLOGDIR <directory name>
5910 If curl was built with HTTP/3 support, setting this environment
5911 variable to a local directory will make curl produce qlogs in
5912 that directory, using file names named after the destination
5913 connection id (in hex). Do note that these files can become
5914 rather large. Works with both QUIC backends.
5915 SHELL Used on VMS when trying to detect if using a DCL or a "unix"
5917 shell.
5918 SSL_CERT_DIR <dir>
5920 If set, will be used as the --capath value.
5921 SSL_CERT_FILE <path>
5923 If set, will be used as the --cacert value.
5924 SSLKEYLOGFILE <file name>
5926 If you set this environment variable to a file name, curl will
5927 store TLS secrets from its connections in that file when invoked
5928 to enable you to analyze the TLS traffic in real time using net‐
5929 work analyzing tools such as Wireshark. This works with the fol‐
5930 lowing TLS backends: OpenSSL, libressl, BoringSSL, GnuTLS, NSS
5931 and wolfSSL.
5932 USERPROFILE <dir>
5934 On Windows, this variable is used when trying to find the home
5935 directory. If the other, primary, variable are all unset. If
5936 set, curl will use the path "$USERPROFILE\Application Data".
5937 XDG_CONFIG_HOME <dir>
5939 If CURL_HOME is not set, this variable is checked when looking
5940 for a default .curlrc file.
5941
5943 The proxy string may be specified with a protocol:// prefix to specify
5944 alternative proxy protocols.
5945 If no protocol is specified in the proxy string or if the string does
5947 not match a supported one, the proxy will be treated as an HTTP proxy.
5948 The supported proxy protocol prefixes are as follows:
5950 http://
5952 Makes it use it as an HTTP proxy. The default if no scheme pre‐
5953 fix is used.
5954 https://
5956 Makes it treated as an HTTPS proxy.
5957 socks4://
5959 Makes it the equivalent of --socks4
5960 socks4a://
5962 Makes it the equivalent of --socks4a
5963 socks5://
5965 Makes it the equivalent of --socks5
5966 socks5h://
5968 Makes it the equivalent of --socks5-hostname
5969
5971 There are a bunch of different error codes and their corresponding er‐
5972 ror messages that may appear under error conditions. At the time of
5973 this writing, the exit codes are:
5974 0 Success. The operation completed successfully according to the
5976 instructions.
5977 1 Unsupported protocol. This build of curl has no support for this
5979 protocol.
5980 2 Failed to initialize.
5982 3 URL malformed. The syntax was not correct.
5984 4 A feature or option that was needed to perform the desired re‐
5986 quest was not enabled or was explicitly disabled at build-time.
5987 To make curl able to do this, you probably need another build of
5988 libcurl.
5989 5 Could not resolve proxy. The given proxy host could not be re‐
5991 solved.
5992 6 Could not resolve host. The given remote host could not be re‐
5994 solved.
5995 7 Failed to connect to host.
5997 8 Weird server reply. The server sent data curl could not parse.
5999 9 FTP access denied. The server denied login or denied access to
6001 the particular resource or directory you wanted to reach. Most
6002 often you tried to change to a directory that does not exist on
6003 the server.
6004 10 FTP accept failed. While waiting for the server to connect back
6006 when an active FTP session is used, an error code was sent over
6007 the control connection or similar.
6008 11 FTP weird PASS reply. Curl could not parse the reply sent to the
6010 PASS request.
6011 12 During an active FTP session while waiting for the server to
6013 connect back to curl, the timeout expired.
6014 13 FTP weird PASV reply, Curl could not parse the reply sent to the
6016 PASV request.
6017 14 FTP weird 227 format. Curl could not parse the 227-line the
6019 server sent.
6020 15 FTP cannot use host. Could not resolve the host IP we got in the
6022 227-line.
6023 16 HTTP/2 error. A problem was detected in the HTTP2 framing layer.
6025 This is somewhat generic and can be one out of several problems,
6026 see the error message for details.
6027 17 FTP could not set binary. Could not change transfer method to
6029 binary.
6030 18 Partial file. Only a part of the file was transferred.
6032 19 FTP could not download/access the given file, the RETR (or simi‐
6034 lar) command failed.
6035 21 FTP quote error. A quote command returned error from the server.
6037 22 HTTP page not retrieved. The requested URL was not found or re‐
6039 turned another error with the HTTP error code being 400 or
6040 above. This return code only appears if -f, --fail is used.
6041 23 Write error. Curl could not write data to a local filesystem or
6043 similar.
6044 25 FTP could not STOR file. The server denied the STOR operation,
6046 used for FTP uploading.
6047 26 Read error. Various reading problems.
6049 27 Out of memory. A memory allocation request failed.
6051 28 Operation timeout. The specified time-out period was reached ac‐
6053 cording to the conditions.
6054 30 FTP PORT failed. The PORT command failed. Not all FTP servers
6056 support the PORT command, try doing a transfer using PASV in‐
6057 stead!
6058 31 FTP could not use REST. The REST command failed. This command is
6060 used for resumed FTP transfers.
6061 33 HTTP range error. The range "command" did not work.
6063 34 HTTP post error. Internal post-request generation error.
6065 35 SSL connect error. The SSL handshaking failed.
6067 36 Bad download resume. Could not continue an earlier aborted down‐
6069 load.
6070 37 FILE could not read file. Failed to open the file. Permissions?
6072 38 LDAP cannot bind. LDAP bind operation failed.
6074 39 LDAP search failed.
6076 41 Function not found. A required LDAP function was not found.
6078 42 Aborted by callback. An application told curl to abort the oper‐
6080 ation.
6081 43 Internal error. A function was called with a bad parameter.
6083 45 Interface error. A specified outgoing interface could not be
6085 used.
6086 47 Too many redirects. When following redirects, curl hit the maxi‐
6088 mum amount.
6089 48 Unknown option specified to libcurl. This indicates that you
6091 passed a weird option to curl that was passed on to libcurl and
6092 rejected. Read up in the manual!
6093 49 Malformed telnet option.
6095 52 The server did not reply anything, which here is considered an
6097 error.
6098 53 SSL crypto engine not found.
6100 54 Cannot set SSL crypto engine as default.
6102 55 Failed sending network data.
6104 56 Failure in receiving network data.
6106 58 Problem with the local certificate.
6108 59 Could not use specified SSL cipher.
6110 60 Peer certificate cannot be authenticated with known CA certifi‐
6112 cates.
6113 61 Unrecognized transfer encoding.
6115 63 Maximum file size exceeded.
6117 64 Requested FTP SSL level failed.
6119 65 Sending the data requires a rewind that failed.
6121 66 Failed to initialise SSL Engine.
6123 67 The user name, password, or similar was not accepted and curl
6125 failed to log in.
6126 68 File not found on TFTP server.
6128 69 Permission problem on TFTP server.
6130 70 Out of disk space on TFTP server.
6132 71 Illegal TFTP operation.
6134 72 Unknown TFTP transfer ID.
6136 73 File already exists (TFTP).
6138 74 No such user (TFTP).
6140 77 Problem reading the SSL CA cert (path? access rights?).
6142 78 The resource referenced in the URL does not exist.
6144 79 An unspecified error occurred during the SSH session.
6146 80 Failed to shut down the SSL connection.
6148 82 Could not load CRL file, missing or wrong format.
6150 83 Issuer check failed.
6152 84 The FTP PRET command failed.
6154 85 Mismatch of RTSP CSeq numbers.
6156 86 Mismatch of RTSP Session Identifiers.
6158 87 Unable to parse FTP file list.
6160 88 FTP chunk callback reported error.
6162 89 No connection available, the session will be queued.
6164 90 SSL public key does not matched pinned public key.
6166 91 Invalid SSL certificate status.
6168 92 Stream error in HTTP/2 framing layer.
6170 93 An API function was called from inside a callback.
6172 94 An authentication function returned an error.
6174 95 A problem was detected in the HTTP/3 layer. This is somewhat
6176 generic and can be one out of several problems, see the error
6177 message for details.
6178 96 QUIC connection error. This error may be caused by an SSL li‐
6180 brary error. QUIC is the protocol used for HTTP/3 transfers.
6181 97 Proxy handshake error.
6183 98 A client-side certificate is required to complete the TLS hand‐
6185 shake.
6186 99 Poll or select returned fatal error.
6188 XX More error codes will appear here in future releases. The exist‐
6190 ing ones are meant to never change.
6191
6193 If you experience any problems with curl, submit an issue in the
6194 project's bug tracker on GitHub: https://github.com/curl/curl/issues
6195
6197 Daniel Stenberg is the main author, but the whole list of contributors
6198 is found in the separate THANKS file.
6199
6201 https://curl.se
6202
6204 ftp(1), wget(1)
6205curl 8.2.1 July 25 2023 curl(1)