GNURL(1)

📦 version 7.72.0, in nixos 26.05, nixpkgs unstable

okay bestie, welcome to gnurl(1) from the General Commands Manual — yep, the manual name is folded in right here at the top instead of being copy-pasted as its own line. let’s get into it 💅

💖 NAME 💖

gnurl — transfer a URL. that’s the whole name section and honestly it ate.

✨ SYNOPSIS ✨

the synopsis is giving “every flag at once” energy, so here it is verbatim, no cap:

gnurl [--abstract-unix-socket <path>] [--alt-svc <file name>]
      [--anyauth] [-a | --append] [--basic] [--cacert <file>]
      [--capath <dir>] [--cert-status] [--cert-type <type>]
      [-E <certificate[:password]> | --cert <certificate[:password]>]
      [--ciphers <list of ciphers>] [--compressed-ssh] [--compressed]
      [-K <file> | -config <file>] [--connect-timeout <seconds>]
      [--connect-to <HOST1:PORT1:HOST2:PORT2>]
      [-C <offset> | --continue-at <offset>]
      [-c <filename> | --cookie-jar <filename>]
      [-b <data|filename> | --cookie <data|filename>] [--create-dirs]
      [--crlf] [--crlfile <file>] [--data-binary <data>]
      [--data-raw <data>] [--data-urlencode <data>]
      [-d data | --data data] [--delegation LEVEL] [--digest]
      [--disable-eprt] [--disable-epsv] [-q | --disable]
      [--dns-interface <interface>] [--dns-ipv4-addr <address>]
      [--dns-ipv6-addr <address>] [--dns-servers <addresses>]
      [--doh-url -<URL>] [-D <filename> | --dump-header <filename>]
      [--egd-file <file>] [--engine <name>]
      [--expect100-timeout <seconds>] [--fail-early] [-f | --fail]
      [--false-start] [--form-string <name=string>]
      [-F <name=content> | -form <name=content>] [--ftp-account <data>]
      [--ftp-alternative-to-user <command>] [--ftp-create-dirs]
      [--ftp-method <method>] [--ftp-pasv]
      [-P <address> | -ftp-port <address>] [--ftp-pret]
      [--ftp-skip-pasv-ip] [--ftp-ssl-ccc-mode <active/passive>]
      [--ftp-ssl-ccc] [--ftp-ssl-control] [-G | --get] [-g | --globoff]
      [--happy-eyeballs-timeout-ms milliseconds] [--haproxy-protocol]
      [-I | --head] [-h | --help] [--hostpubmd5 <md5>] [--http0.9]
      [-0 | --http1.0] [--http1.1] [--http2-prior-knowledge] [--http2]
      [--ignore-content-length] [-i | --include] [-k | --insecure]
      [--interface <name>] [-4 | --ipv4] [-6 | --ipv6]
      [-j | --junk-session-cookies] [--key-type <type>] [--key <key>]
      [--krb <level>] [--libcurl <file>] [--limit-rate <speed>]
      [-l | --list-only] [--location-trusted] [-L | --location]
      [--login-options <options>] [--mail-auth <address>]
      [--mail-from <address>] [--mail-rcpt <address>] [-M | --manual]
      [--max-filesize <bytes>] [--max-redirs <num>] [--metalink]
      [--negotiate] [--netrc-file filename] [--netrc-optional]
      [-n | --netrc] [-: | --next] [--no-alpn] [-N | --no-buffer]
      [--no-keepalive] [--no-npn] [--no-sessionid]
      [--noproxy no-proxy-list] [--ntlm-wb] [--ntlm]
      [--oauth2-bearer token] [-o FILE | --output FILE] [--pass phrase]
      [--path-as-is] [--pinnedpubkey <hashes>] [--post301] [--post302]
      [--post303] [--preproxy [protocol://]host[:port]]
      [-# | --progress-bar] [--proto-default <protocol>]
      [--proto-redir <protocols>] [--proto <protocols>]
      [--proxy-anyauth] [--proxy-basic] [--proxy-cacert <file>]
      [--proxy-capath <dir>] [--proxy-cert-type <type>]
      [--proxy-cert <cert[:passwd]>] [--proxy-ciphers <list>]
      [--proxy-crlfile <file>] [--proxy-digest]
      [--proxy-header <header/@file>] [--proxy-insecure]
      [--proxy-key-type <type>] [--proxy-key <key>] [--proxy-negotiate]
      [--proxy-ntlm] [--proxy-pass <phrase>]
      [--proxy-pinnedpubkey <hashes>] [--proxy-service-name <name>]
      [--proxy-ssl-allow-beast]
      [--proxy-tls13-ciphers <ciphersuite list>]
      [--proxy-tlsauthtype <type>] [--proxy-tlspassword <string>]
      [--proxy-tlsuser <name>] [--proxy-tlsv1]
      [-U <user:password> | --proxy-user <user:password>]
      [-x [protocol://]host[:port] | -proxy [protocol://]host[:port]]
      [--proxy1.0 <host[:port]>] [-p | --proxytunnel] [--pubkey <key>]
      [-Q | --quote] [--random-file <file>]
      [-r <range> | --range <range>] [--raw] [-e | --referer <URL>]
      [-J | --remote-header-name] [--remote-name-all]
      [-O | --remote-name] [-R | --remote-time] [--request-target]
      [-X command | -request <command>]
      [--resolve <host:port:address[,address]...>] [--retry-connrefused]
      [--retry-delay <seconds>] [--retry-max-time <seconds>]
      [--retry <num>] [--sasl-ir] [--service-name <name>]
      [-S | --show-error] [-s | --silent] [--socks4 <host[:port]>]
      [--socks4a <host[:port]>] [--socks5-basic] [--socks5-gssapi-nec]
      [--socks5-gssapi-service <name>] [--socks5-gssapi]
      [--socks5-hostname <host[:port]>] [--socks5 <host[:port]>]
      [-Y speed | --speed-limit <speed>]
      [--y seconds | -speed-time <seconds>] [--ssl-allow-beast]
      [--ssl-no-revoke] [--ssl-reqd] [--ssl] [-2 | --sslv2]
      [-3 | --sslv3] [--stderr] [--styled-output]
      [--suppress-connect-headers] [--tcp-fastopen] [--tcp-nodelay]
      [-t opt=val | --telnet-option <opt=val>] [--tftp-blksize <value>]
      [--tftp-no-options] [-z -time | --time-cond <time>]
      [--tls-max <VERSION>]
      [--tls13-ciphers <list of TLS 1.3 ciphersuites>]
      [--tlsauthtype <type>] [--tlspassword] [--tlsuser <name>]
      [--tlsv1.0] [--tlsv1.1] [--tlsv1.2] [--tlsv1.3] [-1 | --tlsv1]
      [--tr-encoding] [--trace-ascii <file>] [--trace-time]
      [--trace <file>] [-T file | --upload-file <file>] [--url <url>]
      [-B | --use-ascii] [-A <name> | --user-agent <name>]
      [-u <user:password> | --user <user:password>] [-v | --verbose]
      [-V | --version] [-w <format> | --write-out <format>] [--xattr]
      ⟨URLs⟩

🦋 DESCRIPTION 🦋

okay so gnurl is a tool to transfer data from or to a server, using one of the supported protocols: DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET and TFTP. the command is designed to work without user interaction. main character energy: it just does the thing.

gnurl offers a busload of useful tricks like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume, Metalink, and more. as you will see below, the number of features will make your head spin! literally, there are so many.

gnurl is powered by libgnurl for all transfer-related features. see libcurl(3) for details. 🫶

🌈 URL 🌈

the URL syntax is protocol-dependent. you’ll find a detailed description in RFC 3986.

you can specify multiple URLs or parts of URLs by writing part sets within braces as in:

http://site.{one,two,three}.com

or you can get sequences of alphanumeric series by using [] as in:

ftp://ftp.example.com/file[1-100].txt

ftp://ftp.example.com/file[001-100].txt (with leading zeros)

ftp://ftp.example.com/file[a-z].txt

nested sequences are not supported, but you can use several ones next to each other:

http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html

you can specify any amount of URLs on the command line. they will be fetched in a sequential manner in the specified order. you can specify command line options and URLs mixed and in any order on the command line. iconic behavior, honestly.

you can specify a step counter for the ranges to get every Nth number or letter:

http://example.com/file[1-100:10].txt

http://example.com/file[a-z:2].txt

when using [] or {} sequences when invoked from a command line prompt, you probably have to put the full URL within double quotes to avoid the shell from interfering with it. this also goes for other characters treated special, like for example '&', '?' and '*'.

provide the IPv6 zone index in the URL with an escaped percentage sign and the interface name. like in:

http://[fe80::3%25eth0]/

if you specify URL without protocol:// prefix, curl will attempt to guess what protocol you might want. it will then default to HTTP but try other protocols based on often-used host name prefixes. for example, for host names starting with "ftp." curl will assume you want to speak FTP.

curl will do its best to use what you pass to it as a URL. it is not trying to validate it as a syntactically correct URL by any means but is instead very liberal with what it accepts.

curl will attempt to re-use connections for multiple file transfers, so that getting many files from the same server will not do multiple connects / handshakes. this improves speed. of course this is only done on files specified on a single command line and cannot be used between separate curl invokes.

⏳ PROGRESS METER ⏳

gnurl normally displays a progress meter during operations, indicating the amount of transferred data, transfer speeds and estimated time left, etc. the progress meter displays number of bytes and the speeds are in bytes per second. the suffixes (k, M, G, T, P) are 1024 based. for example 1k is 1024 bytes. 1M is 1048576 bytes.

curl displays this data to the terminal by default, so if you invoke curl to do an operation and it is about to write data to the terminal, it disables the progress meter as otherwise it would mess up the output mixing progress meter and response data.

if you want a progress meter for HTTP POST or PUT requests, you need to redirect the response output to a file, using shell redirect (>), -o | --output or similar.

it is not the same case for FTP upload as that operation does not spit out any response data to the terminal.

if you prefer a progress “bar” instead of the regular meter, -# | --progress-bar is your friend. you can also disable the progress meter completely with the -s | --silent option.

✨ OPTIONS ✨

options start with one or two dashes. many of the options require an additional value next to them.

the short “single-dash” form of the options, -d for example, may be used with or without a space between it and its value, although a space is a recommended separator. the long “double-dash” form, -d | --data for example, requires a space between it and its value.

short version options that don’t need any additional values can be used immediately next to each other, like for example you can specify all the options -O, -L and -v at once as -OLv.

in general, all boolean options are enabled with --option and yet again disabled with --no-option. that is, you use the exact same option name but prefix it with "no-". however, in this list we mostly only list and show the --option version of them. (this concept with --no options was added in 7.19.0. previously most options were toggled on/off on repeated use of the same command line option.)

--abstract-unix-socket <path> — (HTTP) connect through an abstract Unix domain socket, instead of using the network. Note: netstat shows the path of an abstract socket prefixed with '@', however the <path> argument should not have this leading character.

Added in 7.53.0.

✨ OPTIONS ✨

--alt-svc <file name> — (HTTPS) ⚠️ okay so first thing: this option is experimental. Do not use in production. fr fr, not a drill.

It turns on the alt-svc parser in curl. If the file name you give points at an alt-svc cache file that already exists, curl uses it. Then after a transfer finishes, the cache gets saved back to that same file name — but only if it got modified. ✨

Wanna keep it all in memory and touch zero files? Hand it a "" file name (zero length, like literally empty) and curl skips loading and saving, just handling the cache in memory. 🧠

Use it a bunch of times and curl loads contents from every single file you listed — but the last one is the one used for saving.

Added in 7.64.1.

--anyauth — (HTTP) tells curl to figure out the authentication method all by its own self 👑 and then use the most secure one the remote site claims to support. The way it does this is: do a request first, check the response headers, and then pick — which means possibly an extra network round-trip. So it's the "instead of" option for setting a specific method yourself, which you'd do with --basic, --digest, --ntlm, and --negotiate.

🫶 Heads up bestie: --anyauth is not recommended if you do uploads from stdin. It may need the data sent twice, and then the client has to be able to rewind. If that need arises while uploading from stdin, the upload operation will fail.

Used together with -u | --user.

See also --proxy-anyauth, --basic and --digest.

-a | --append — (FTP SFTP) in an upload, this makes curl append to the target file instead of overwriting it. Slay. If the remote file doesn't exist, it gets created. Just know that some SFTP servers ignore this flag entirely (including OpenSSH) 😭.
--basic — (HTTP) tells curl to use HTTP Basic authentication with the remote host. This is the default, so honestly this option is usually pointless — unless you're using it to override a previously set option that set a different auth method (like --ntlm, --digest, or --negotiate). Then it's doing actual work 💅.

Used together with -u | --user.

🧦 `--socks5-gssapi`

Tells curl to use GSS-API authentication when connecting to a SOCKS5 proxy. The GSS-API authentication is enabled by default (if curl is compiled with GSS-API support). Use --socks5-basic to force username/password authentication to SOCKS5 proxies.

Added in 7.55.0.

🦋 `--socks5-hostname <host[:port]>`

Use the specified SOCKS5 proxy — and let the proxy resolve the host name, which is the whole point. If the port number is not specified, it is assumed at port 1080.

This option overrides any previous use of -x, --proxy, as they are mutually exclusive. (they cannot both be the main character, iykyk)

Since 7.21.7, this option is superfluous since you can specify a socks5 hostname proxy with -x, --proxy using a socks5h:// protocol prefix.

If this option is used several times, the last one will be used.

Added in 7.18.0.

🧚 `--socks5 <host[:port]>`

Use the specified SOCKS5 proxy — but resolve the host name locally. If the port number is not specified, it is assumed at port 1080.

This option overrides any previous use of -x, --proxy, as they are mutually exclusive.

Since 7.21.7, this option is superfluous since you can specify a socks5 proxy with -x, --proxy using a socks5:// protocol prefix.

If this option is used several times, the last one will be used.

Heads up bestie, this one has a whole list of things it doesn't vibe with: this option (as well as --socks4) does not work with IPV6, FTPS or LDAP. 😭

Added in 7.18.0.

🏎️ `-Y speed`, `--speed-limit <speed>`

If a download is slower than this given speed (in bytes per second) for speed-time seconds it gets aborted. speed-time is set with -y, --speed-time and is 30 if not set. So like, curl will literally give up on a slug-speed download. iconique.

If this option is used several times, the last one will be used.

⏱️ `--y seconds`, `-speed-time <seconds>`

(ok so the manpage literally prints it as --y seconds | -speed-time <seconds> and i'm not about to "fix" it, that's not my job, i'm just the messenger 💀)

If a download is slower than speed-limit bytes per second during a speed-time period, the download gets aborted. If speed-time is used, the default speed-limit will be 1 unless set with -Y, --speed-limit.

This option controls transfers and thus will not affect slow connects etc. If this is a concern for you, try the --connect-timeout option.

If this option is used several times, the last one will be used.

🦁 `--ssl-allow-beast`

This option tells curl to not work around a security flaw in the SSL3 and TLS1.0 protocols known as BEAST. If this option isn't used, the SSL layer may use workarounds known to cause interoperability problems with some older SSL implementations.

WARNING: this option loosens the SSL security, and by using this flag you ask for exactly that. Like, you are literally requesting the insecure thing. no cap. 🙈

Added in 7.25.0.

🚫 `--ssl-no-revoke`

(Schannel) This option tells curl to disable certificate revocation checks.

WARNING: this option loosens the SSL security, and by using this flag you ask for exactly that. same energy as above bestie, pls be careful. 💀

Added in 7.44.0.

🔒 `--ssl-reqd`

(FTP IMAP POP3 SMTP) Require SSL/TLS for the connection. Terminates the connection if the server doesn't support SSL/TLS. it's giving "my way or the highway" and honestly? respect.

This option was formerly known as --ftp-ssl-reqd.

Added in 7.20.0.

🌸 `--ssl`

(FTP IMAP POP3 SMTP) Try to use SSL/TLS for the connection. Reverts to a non-secure connection if the server doesn't support SSL/TLS. See also --ftp-ssl-control and --ssl-reqd for different levels of encryption required. (soft launch security, basically)

This option was formerly known as --ftp-ssl (Added in 7.11.0). That option name can still be used but will be removed in a future version.

Added in 7.20.0.

💀 `-2`, `--sslv2`

(SSL) Forces curl to use SSL version 2 when negotiating with a remote SSL server. Sometimes curl is built without SSLv2 support. SSLv2 is widely considered insecure (see RFC 6176). seriously bestie, RFC 6176 exists specifically to say this is bad news.

See also --http1.1 and --http2. -2, --sslv2 requires that the underlying libgnurl was built to support TLS. This option overrides -3, --sslv3 and -1, --tlsv1 and --tlsv1.1 and --tlsv1.2.

🫠 `-3`, `--sslv3`

(SSL) Forces curl to use SSL version 3 when negotiating with a remote SSL server. Sometimes curl is built without SSLv3 support. SSLv3 is widely considered insecure (see RFC 7568). yes another RFC saying nope.

See also --http1.1 and --http2. -3, --sslv3 requires that the underlying libgnurl was built to support TLS. This option overrides -2, --sslv2 and -1, --tlsv1 and --tlsv1.1 and --tlsv1.2.

📝 `--stderr`

Redirect all writes to stderr to the specified file instead. If the file name is a plain -, it is instead written to stdout. sneaky little trick, love that for you.

If this option is used several times, the last one will be used.

See also -v, --verbose and -s, --silent.

✨ `--styled-output`

Enables the automatic use of bold font styles when writing HTTP headers to the terminal. Use --no-styled-output to switch them off. yes it literally just makes your headers bold. aesthetic. 🎀

Added in 7.61.0.

🙈 `--suppress-connect-headers`

When -p, --proxytunnel is used and a CONNECT request is made don't output proxy CONNECT response headers. This option is meant to be used with -D, --dump-header or -i, --include which are used to show protocol headers in the output. It has no effect on debug options such as -v, --verbose or --trace, or any statistics.

See also -D, --dump-header and -i, --include and -p, --proxytunnel.

⚡ `--tcp-fastopen`

Enable use of TCP Fast Open (RFC7413). zoom zoom. 🔥

Added in 7.49.0.

🚀 `--tcp-nodelay`

Turn on the TCP_NODELAY option. See the curl_easy_setopt(3) man page for details about this option.

Since 7.50.2, curl sets this option by default and you need to explicitly switch it off if you don't want it on.

Added in 7.11.2.

📺 `-t opt=val`, `--telnet-option <opt=val>`

Pass options to the telnet protocol. Supported options are:

TTYPE=<term> — Sets the terminal type.
XDISPLOC=<X display> — Sets the X display location.
NEW_ENV=<var,val> — Sets an environment variable.

🍓 `--tftp-blksize <value>`

(TFTP) Set TFTP BLKSIZE option (must be >512). This is the block size that curl will try to use when transferring data to or from a TFTP server. By default 512 bytes will be used.

If this option is used several times, the last one will be used.

Added in 7.20.0.

🧊 `--tftp-no-options`

(TFTP) Tells curl not to send TFTP options requests.

This option improves interop with some legacy servers that do not acknowledge or properly implement TFTP options. When this option is used --tftp-blksize is ignored. (yes, fully ignored, so don't bother setting it 💅)

Added in 7.48.0.

🕰️ `-z -time`, `--time-cond <time>`

(again, verbatim from the page: -z -time | --time-cond <time> — i just report, i don't editorialize. ok maybe a little.)

(HTTP FTP) Request a file that has been modified later than the given time and date, or one that has been modified before that time. The <date expression> can be all sorts of date strings or if it doesn't match any internal ones, it is taken as a filename and tries to get the modification date (mtime) from <file> instead. See the curl_getdate(3) man pages for date expression details.

Start the date expression with a dash (-) to make it request for a document that is older than the given date/time, default is a document that is newer than the specified date/time.

If this option is used several times, the last one will be used.

👑 `--tls-max <VERSION>`

(SSL) VERSION defines maximum supported TLS version. The minimum acceptable version is set by tlsv1.0, tlsv1.1, tlsv1.2 or tlsv1.3.

default — Use up to recommended TLS version.
1.0 — Use up to TLSv1.0.
1.1 — Use up to TLSv1.1.
1.2 — Use up to TLSv1.2.
1.3 — Use up to TLSv1.3.

See also --tlsv1.0 and --tlsv1.1 and --tlsv1.2 and --tlsv1.3. --tls-max requires that the underlying libgnurl was built to support TLS. Added in 7.54.0.

🔐 `--tls13-ciphers <list of TLS 1.3 ciphersuites>`

(TLS) Specifies which cipher suites to use in the connection if it negotiates TLS 1.3. The list of ciphers suites must specify valid ciphers. Read up on TLS 1.3 cipher suite details on this URL: https://curl.haxx.se/docs/ssl-ciphers.html

This option is currently used only when curl is built to use OpenSSL 1.1.1 or later. If you are using a different SSL backend you can try setting TLS 1.3 cipher suites by using the --ciphers option.

If this option is used several times, the last one will be used.

🎀 `--tlsauthtype <type>`

Set TLS authentication type. Currently, the only supported option is "SRP", for TLS-SRP (RFC 5054). If --tlsuser and --tlspassword are specified but --tlsauthtype is not, then this option defaults to "SRP". This option works only if the underlying libcurl is built with TLS-SRP support, which requires OpenSSL or GnuTLS with TLS-SRP support.

Added in 7.21.4.

🗝️ `--tlspassword`

Set password for use with the TLS authentication method specified with --tlsauthtype. Requires that --tlsuser also be set. (they're a package deal, fr fr)

Added in 7.21.4.

🌈 `--tlsuser <name>`

Set username for use with the TLS authentication method specified with --tlsauthtype. Requires that --tlspassword also is set.

Added in 7.21.4.

⭐ `--tlsv1.0`

(TLS) Forces curl to use TLS version 1.0 or later when connecting to a remote TLS server.

--tlsv1.1 — bestie, this one forces curl to speak TLS version 1.1 or later when it's connecting to a remote TLS server. Like, no downgrading, we're not doing that today. ✨

Added in 7.34.0.

--tlsv1.2 — same deal but for TLS version 1.2 or later. curl said "we're negotiating, but we're negotiating upward." 💅

Added in 7.34.0.

--tlsv1.3 — forces TLS version 1.3 or later. Iconic, secure, modern. 👑

Note that TLS 1.3 is only supported by a subset of TLS backends. At the time of this writing, they are BoringSSL, NSS, and Secure Transport (on iOS 11 or later, and macOS 10.13 or later).

Added in 7.52.0.

-1, --tlsv1 — (SSL) tells curl to use at least TLS version 1.x when negotiating with a remote TLS server. That means TLS version 1.0 or higher, periodt.

See also --http1.1 and --http2. -1, --tlsv1 requires that the underlying libgnurl was built to support TLS. This option overrides --tlsv1.1 and --tlsv1.2 and --tlsv1.3. So yeah, it's the bossy one in the TLS friend group. 😌

--tr-encoding — (HTTP) requests a compressed Transfer-Encoding response using one of the algorithms curl supports, and uncompresses the data while receiving it. Like getting a gift wrapped in compression and curl unwraps it for you in real time. 🎁

Added in 7.21.6.

--trace-ascii <file> — enables a full trace dump of all incoming and outgoing data, including descriptive information, to the given output file. Use "-" as filename to have the output sent to stdout.

This is very similar to --trace, but leaves out the hex part and only shows the ASCII part of the dump. It makes smaller output that might be easier to read for untrained humans. (No shade, we were all untrained humans once. 🫶)

If this option is used several times, the last one will be used.

This option overrides --trace and -v, --verbose.

--trace-time — prepends a time stamp to each trace or verbose line that curl displays. Timestamps on everything, because chronology is the moment. ⏰

Added in 7.14.0.

--trace <file> — enables a full trace dump of all incoming and outgoing data, including descriptive information, to the given output file. Use "-" as filename to have the output sent to stdout. Use "%" as filename to have the output sent to stderr.

If this option is used several times, the last one will be used.

This option overrides -v, --verbose and --trace-ascii.

--unix-socket <path> — (HTTP) connects through this Unix domain socket, instead of using the network. Lowkey networking but not networking. 🦋

Added in 7.40.0.

-T file, --upload-file <file> — this transfers the specified local file to the remote URL. If there is no file part in the specified URL, curl will append the local file name. NOTE that you must use a trailing / on the last directory to really prove to Curl that there is no file name or curl will think that your last directory name is the remote file name to use. That will most likely cause the upload operation to fail. So please, bestie, give it the slash. 🙏 If this is used on an HTTP(S) server, the PUT command will be used.

Use the file name "-" (a single dash) to use stdin instead of a given file. Alternately, the file name "." (a single period) may be specified instead of "-" to use stdin in non-blocking mode to allow reading server output while stdin is being uploaded.

You can specify one -T, --upload-file for each URL on the command line. Each -T, --upload-file + URL pair specifies what to upload and to where. curl also supports "globbing" of the -T, --upload-file argument, meaning that you can upload multiple files to a single URL by using the same URL globbing style supported in the URL, like this:

curl --upload-file {file1,file2} http://www.example.com

or even

curl -T img[1-1000].png ftp://ftp.example.com/upload/

When uploading to an SMTP server: the uploaded data is assumed to be RFC 5322 formatted. It has to feature the necessary set of headers and mail body formatted correctly by the user as curl will not transcode nor encode it further in any way. So curl is literally just the messenger. 💌

--url <url> — specify a URL to fetch. This option is mostly handy when you want to specify URL(s) in a config file. Config file girlies rise up. 🎀

If the given URL is missing a scheme name (such as "http://" or "ftp://" etc) then curl will make a guess based on the host. If the outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be used, otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by setting a default protocol, see --proto-default for details.

This option may be used any number of times. To control where this URL is written, use the -o, --output or the -O, --remote-name options.

-B, --use-ascii — (FTP LDAP) enable ASCII transfer. For FTP, this can also be enforced by using a URL that ends with ";type=A". This option causes data sent to stdout to be in text mode for win32 systems. Plain text supremacy, I guess. 📝
-A <name>, --user-agent <name> — (HTTP) specify the User-Agent string to send to the HTTP server. To encode blanks in the string, surround the string with single quote marks. This header can also be set with the -H, --header or the --proxy-header options.

If this option is used several times, the last one will be used.

-u <user:password>, --user <user:password> — specify the user name and password to use for server authentication. Overrides -n, --netrc and --netrc-optional.

If you simply specify the user name, curl will prompt for a password.

The user name and passwords are split up on the first colon, which makes it impossible to use a colon in the user name with this option. The password can, still. So colons are welcome in the password but absolutely not in the username. Rules are rules. 💅

On systems where it works, curl will hide the given option argument from process listings. This is not enough to protect credentials from possibly getting seen by other users on the same system as they will still be visible for a brief moment before cleared. Such sensitive data should be retrieved from a file instead or similar and never used in clear text in a command line.

Okay bestie, real talk: do not put your passwords in a command line and think you're safe. curl can hide it for a sec but other users may still glimpse it. Files are the move. 🔐

When using Kerberos V5 with a Windows based server you should include the Windows domain name in the user name, in order for the server to successfully obtain a Kerberos Ticket. If you don't then the initial authentication handshake may fail.

When using NTLM, the user name can be specified simply as the user name, without the domain, if there is a single domain and forest in your setup for example.

To specify the domain name use either Down-Level Logon Name or UPN (User Principal Name) formats. For example, EXAMPLE\user and user@example.com respectively.

If you use a Windows SSPI-enabled curl binary and perform Kerberos V5, Negotiate, NTLM or Digest authentication then you can tell curl to select the user name and password from your environment by specifying a single colon with this option: "-u :".

If this option is used several times, the last one will be used.

-v, --verbose — makes curl verbose during the operation. Useful for debugging and seeing what's going on "under the hood". A line starting with '>' means "header data" sent by curl, '<' means "header data" received by curl that is hidden in normal cases, and a line starting with '*' means additional info provided by curl. It's giving detective mode. 🔍

If you only want HTTP headers in the output, -i | --include might be the option you're looking for.

If you think this option still doesn't give you enough details, consider using --trace or --trace-ascii instead.

Use -s | --silent to make curl really quiet.

See also -i | --include. This option overrides --trace and --trace-ascii.

-V, --version — displays information about curl and the libcurl version it uses. Receipts on receipts. 🧾

The first line includes the full version of curl, libcurl and other 3rd party libraries linked with the executable.

The second line (starts with "Protocols:") shows all protocols that libcurl reports to support.

The third line (starts with "Features:") shows specific features libcurl reports to offer. Available features include:

IPv6 — you can use IPv6 with this.
krb4 — Krb4 for FTP is supported.
SSL — SSL versions of various protocols are supported, such as HTTPS, FTPS, POP3S and so on.
libz — automatic decompression of compressed files over HTTP is supported.
NTLM — NTLM authentication is supported.
Debug — this curl uses a libcurl built with Debug. This enables more error-tracking and memory debugging etc. For curl-developers only! 👀
AsynchDNS — this curl uses asynchronous name resolves. Asynchronous name resolves can be done using either the c-ares or the threaded resolver backends.
SPNEGO — SPNEGO authentication is supported.
Largefile — this curl supports transfers of large files, files larger than 2GB.
IDN — this curl supports IDN - international domain names.
GSS-API — GSS-API is supported.
SSPI — SSPI is supported.
TLS-SRP — SRP (Secure Remote Password) authentication is supported for TLS.
HTTP2 — HTTP/2 support has been built-in.
UnixSockets — Unix sockets support is provided.
HTTPS-proxy — this curl is built to support HTTPS proxy.
Metalink — this curl supports Metalink (both version 3 and 4 (RFC 5854)), which describes mirrors and hashes. curl will use mirrors for failover if there are errors (such as the file or server not being available).
PSL — PSL is short for Public Suffix List and means that this curl has been built with knowledge about "public suffixes".
MultiSSL — this gnurl supports multiple TLS backends.

-w <format>, --write-out <format> — ok so this one is the ✨aesthetic✨ option: it makes curl print a little info dump on stdout after a transfer finishes. The <format> is a string, and it can be plain text mixed with as many variables as you want. You can hand it a literal "string", or make curl read the format out of a file with @filename, or — and this is so cute — write @- to have it read the format from stdin. 💅

Every variable in the output format gets swapped for whatever value or text curl thinks fits, as listed below. All variables are written as %{variable_name}, and if you want a normal literal % you just double it up: %%. Newline? \n. Carriage return? \r. Tab space? \t. Obsessed with the control over here. 🎀

Output goes to standard output by default, but you can flip it to standard error with %{stderr}.

NOTE: the %-symbol is a special symbol in the win32-environment, where all occurrences of % must be doubled when you're using this option. Not me warning you twice 💀

The variables available are:

content_type — the Content-Type of the requested document, if there was any.
filename_effective — the ultimate filename that curl writes out to. This is only meaningful if curl is told to write to a file with the -O, --remote-name or -o, --output option. It's most useful in combination with the -J, --remote-header-name option. (Added in 7.26.0)
ftp_entry_path — the initial path curl ended up in when logging on to the remote FTP server. (Added in 7.15.4)
http_code — the numerical response code that was found in the last retrieved HTTP(S) or FTP(s) transfer. In 7.18.2 the alias response_code was added to show the same info.
http_connect — the numerical code that was found in the last response (from a proxy) to a curl CONNECT request. (Added in 7.12.4)
http_version — the http version that was effectively used. (Added in 7.50.0)
local_ip — the IP address of the local end of the most recently done connection — can be either IPv4 or IPv6 (Added in 7.29.0)
local_port — the local port number of the most recently done connection (Added in 7.29.0)
num_connects — number of new connects made in the recent transfer. (Added in 7.12.3)
num_redirects — number of redirects that were followed in the request. (Added in 7.12.3)
proxy_ssl_verify_result — the result of the HTTPS proxy's SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.52.0)
redirect_url — when an HTTP request was made without -L, --location to follow redirects (or when --max-redir is met), this variable will show the actual URL a redirect would have gone to. (Added in 7.18.2)
remote_ip — the remote IP address of the most recently done connection — can be either IPv4 or IPv6 (Added in 7.29.0)
remote_port — the remote port number of the most recently done connection (Added in 7.29.0)
scheme — the URL scheme (sometimes called protocol) that was effectively used (Added in 7.52.0)
size_download — the total amount of bytes that were downloaded.
size_header — the total amount of bytes of the downloaded headers.
size_request — the total amount of bytes that were sent in the HTTP request.
size_upload — the total amount of bytes that were uploaded.
speed_download — the average download speed that curl measured for the complete download. Bytes per second.
speed_upload — the average upload speed that curl measured for the complete upload. Bytes per second.
ssl_verify_result — the result of the SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.19.0)
stderr — from this point on, the -w, --write-out output will be written to standard error. (Added in 7.63.0)
stdout — from this point on, the -w, --write-out output will be written to standard output. This is the default, but can be used to switch back after switching to stderr. (Added in 7.63.0)
time_appconnect — the time, in seconds, it took from the start until the SSL/SSH/etc connect/handshake to the remote host was completed. (Added in 7.19.0)
time_connect — the time, in seconds, it took from the start until the TCP connect to the remote host (or proxy) was completed.
time_namelookup — the time, in seconds, it took from the start until the name resolving was completed.
time_pretransfer — the time, in seconds, it took from the start until the file transfer was just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved.
time_redirect — the time, in seconds, it took for all redirection steps including name lookup, connect, pretransfer and transfer before the final transaction was started. time_redirect shows the complete execution time for multiple redirections. (Added in 7.12.3)
time_starttransfer — the time, in seconds, it took from the start until the first byte was just about to be transferred. This includes time_pretransfer and also the time the server needed to calculate the result.
time_total — the total time, in seconds, that the full operation lasted.
url_effective — the URL that was fetched last. This is most meaningful if you've told curl to follow location: headers.

If this option is used several times, the last one will be used. (Classic last-one-wins energy, we love consistency 💖)

--xattr — when you're saving output to a file, this option tells curl to store certain file metadata in extended file attributes. Currently, the URL is stored in the xdg.origin.url attribute and, for HTTP, the content type is stored in the mime_type attribute. If the file system does not support extended attributes, a warning is issued. 🫶

🎀 FILES 🎀

~/.curlrc — the default config file, see --config for details. Your little home-base vibe file 💜

💖 ENVIRONMENT 💖

Ok so the environment variables can be specified in lower case or upper case — either is fine, bestie. The lower case version has precedence. http_proxy is the exception though, because it's only available in lower case. 🙈

Using an environment variable to set the proxy has the same effect as using the --proxy option.

http_proxy [protocol://]<host>[:port] — sets the proxy server to use for HTTP.
HTTPS_PROXY [protocol://]<host>[:port] — sets the proxy server to use for HTTPS.
[url-protocol]_PROXY [protocol://]<host>[:port] — sets the proxy server to use for [url-protocol], where the protocol is a protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP, SMTP, LDAP etc. Like, the whole roster 🦋
ALL_PROXY [protocol://]<host>[:port] — sets the proxy server to use if no protocol-specific proxy is set.
NO_PROXY <comma-separated list of hosts/domains> — a list of host names that shouldn't go through any proxy. If set to an asterisk '*' only, it matches all hosts. Each name in this list is matched as either a domain name which contains the hostname, or the hostname itself.

This environment variable disables use of the proxy even when specified with the -x, --proxy option. Like, that is:

NO_PROXY=direct.example.com curl -x http://proxy.example.com
http://direct.example.com

accesses the target URL directly, and

NO_PROXY=direct.example.com curl -x http://proxy.example.com
http://somewhere.example.com

accesses the target URL through the proxy. Same command, different outcome — the way NO_PROXY just casually overrides everything is giving main character energy, honestly 😭

The list of host names can also be include numerical IP addresses, and IPv6 versions should then be given without enclosing brackets. (Yes, the original says "can also be include" — we're keeping it, character for character, that's the rule 💅)

🧚 PROXY PROTOCOL PREFIXES 🧚

Since curl version 7.21.7, the proxy string may be specified with a protocol:// prefix to specify alternative proxy protocols. Iconic upgrade, no cap.

If no protocol is specified in the proxy string or if the string doesn't match a supported one, the proxy will be treated as an HTTP proxy.

The supported proxy protocol prefixes are as follows:

http:// — makes it use it as an HTTP proxy. The default if no scheme prefix is used.
https:// — makes it treated as an HTTPS proxy.
socks4:// — makes it the equivalent of --socks4
socks4a:// — makes it the equivalent of --socks4a
socks5:// — makes it the equivalent of --socks5
socks5h:// — makes it the equivalent of --socks5-hostname

Slay, that's the whole prefix menu 🌸

💀 EXIT STATUS 💀

okay bestie so when stuff goes sideways, curl (and gnurl, hi) bails out with one of these numbered codes. Each one comes with its own little error message, and ngl the numbers are kind of a whole personality. Here's the whole lineup as of this writing:

1 — Unsupported protocol. This particular build of curl just straight up has no support for that protocol. Not today, bestie. 😭
2 — Failed to initialize. It couldn't even get out of bed. 😴
3 — URL malformed. The syntax was not it. 💅
4 — A feature or option that was needed to do the request you wanted was not enabled, or was explicitly disabled at build-time. To fix this you probably need a whole other build of libcurl! Sorry babe.
5 — Couldn't resolve proxy. That proxy host you gave? Unresolvable, ghosted fr.
6 — Couldn't resolve host. The remote host you wanted was not resolved. no cap.
7 — Failed to connect to host. It tried, it really did. 🫶
8 — Weird server reply. The server sent data curl couldn't parse. it's giving chaos.
9 — FTP access denied. The server denied login, or denied access to the particular resource or directory you were trying to reach. Most often this means you tried to change to a directory that doesn't exist on the server. 🙈
10 — FTP accept failed. While waiting for the server to connect back during an active FTP session, an error code got sent over the control connection or something similar. 💀
11 — FTP weird PASS reply. Curl couldn't parse the reply to the PASS request.
12 — During an active FTP session, while waiting for the server to connect back to curl, the timeout expired. clock ran out, bestie. ⏰
13 — FTP weird PASV reply. Curl couldn't parse the reply to the PASV request.
14 — FTP weird 227 format. Curl couldn't parse the 227-line the server sent. like why is it formatted like that 😭
15 — FTP can't get host. Couldn't resolve the host IP we got in the 227-line.
16 — HTTP/2 error. A problem was detected in the HTTP2 framing layer. This one's somewhat generic and can be any one of several problems — check the error message for the details, iykyk.
17 — FTP couldn't set binary. Couldn't switch the transfer method to binary.
18 — Partial file. Only a part of the file was transferred. half a snack 🍓
19 — FTP couldn't download/access the given file; the RETR (or similar) command failed.
21 — FTP quote error. A quote command came back with an error from the server.
22 — HTTP page not retrieved. The requested url was not found, or returned another error with the HTTP error code being 400 or above. This return code only shows up if -f | --fail is used. 🔥
23 — Write error. Curl couldn't write data to a local filesystem or similar. permission vibes? 😬
25 — FTP couldn't STOR file. The server denied the STOR operation, which is used for FTP uploading.
26 — Read error. Various reading problems. vague on purpose, honestly.
27 — Out of memory. A memory allocation request failed. 😵‍💫
28 — Operation timeout. The specified time-out period was reached according to the conditions.
30 — FTP PORT failed. The PORT command failed. Not all FTP servers support the PORT command — try doing the transfer using PASV instead! ✨
31 — FTP couldn't use REST. The REST command failed. That command is used for resumed FTP transfers.
33 — HTTP range error. The range "command" didn't work. 💀
34 — HTTP post error. Internal post-request generation error.
35 — SSL connect error. The SSL handshaking failed. awkward handshake, we've all been there. 🫠
36 — Bad download resume. Couldn't continue an earlier aborted download.
37 — FILE couldn't read file. Failed to open the file. Permissions, maybe?
38 — LDAP cannot bind. The LDAP bind operation failed.
39 — LDAP search failed.
41 — Function not found. A required LDAP function was not found.
42 — Aborted by callback. An application told curl to abort the operation.
43 — Internal error. A function was called with a bad parameter.
45 — Interface error. A specified outgoing interface could not be used.
47 — Too many redirects. When following redirects, curl hit the maximum amount. girl got lost in the loop 💫
48 — Unknown option specified to libcurl. This means you passed a weird option to curl that got passed on to libcurl and rejected. Read up in the manual! 📖
49 — Malformed telnet option.
51 — The peer's SSL certificate or SSH MD5 fingerprint was not OK. 🚩
52 — The server didn't reply anything, which here counts as an error. silent treatment, rude.
53 — SSL crypto engine not found.
54 — Cannot set SSL crypto engine as default.
55 — Failed sending network data.
56 — Failure in receiving network data.
58 — Problem with the local certificate.
59 — Couldn't use specified SSL cipher.
60 — Peer certificate cannot be authenticated with known CA certificates. trust issues, literally.
61 — Unrecognized transfer encoding.
62 — Invalid LDAP URL.
63 — Maximum file size exceeded.
64 — Requested FTP SSL level failed.
65 — Sending the data requires a rewind that failed.
66 — Failed to initialise SSL Engine.
67 — The user name, password, or similar was not accepted and curl failed to log in. 🙈
68 — File not found on TFTP server.
69 — Permission problem on TFTP server.
70 — Out of disk space on TFTP server. 🍽️
71 — Illegal TFTP operation.
72 — Unknown TFTP transfer ID.
73 — File already exists (TFTP).
74 — No such user (TFTP).
75 — Character conversion failed.
76 — Character conversion functions required.
77 — Problem with reading the SSL CA cert (path? access rights?).
78 — The resource referenced in the URL does not exist.
79 — An unspecified error occurred during the SSH session.
80 — Failed to shut down the SSL connection.
82 — Could not load CRL file, missing or wrong format (added in 7.19.0).
83 — Issuer check failed (added in 7.19.0).
84 — The FTP PRET command failed
85 — RTSP: mismatch of CSeq numbers
86 — RTSP: mismatch of Session Identifiers
87 — unable to parse FTP file list
88 — FTP chunk callback reported error
89 — No connection available, the session will be queued
90 — SSL public key does not matched pinned public key
91 — Invalid SSL certificate status.
92 — Stream error in HTTP/2 framing layer.
XX — More error codes will appear here in future releases. The existing ones are meant to never change. 👑

👑 AUTHORS 👑

Daniel Stenberg is the main author of curl, but the whole list of contributors lives over in the separate THANKS file. give them their flowers 💐

gnurl is based on curl and is maintained by ng0 <ng0@n0.is>. This mdoc man page was derived from the curl automated groff page generation output and is slowly being adjusted to reflect the smaller feature set found in gnurl. we love a work in progress 🎀

🦋 SEE ALSO 🦋

and that's the whole page bestie, we did it 🫶💖 this is the Debian build, dated May 22, 2019, and you were reading GNURL(1) — iconic, honestly. go forth and curl responsibly ✨👑

📦 where this page comes from

nixos 26.05: libgnurl 7.72.0
nixpkgs unstable: libgnurl 7.72.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

GNURL(1)

💖 NAME 💖

✨ SYNOPSIS ✨

🦋 DESCRIPTION 🦋

🌈 URL 🌈

⏳ PROGRESS METER ⏳

✨ OPTIONS ✨

✨ OPTIONS ✨

🧦 --socks5-gssapi

🦋 --socks5-hostname <host[:port]>

🧚 --socks5 <host[:port]>

🏎️ -Y speed, --speed-limit <speed>

⏱️ --y seconds, -speed-time <seconds>

🦁 --ssl-allow-beast

🚫 --ssl-no-revoke

🔒 --ssl-reqd

🌸 --ssl

💀 -2, --sslv2

🫠 -3, --sslv3

📝 --stderr

✨ --styled-output

🙈 --suppress-connect-headers

⚡ --tcp-fastopen

🚀 --tcp-nodelay

📺 -t opt=val, --telnet-option <opt=val>

🍓 --tftp-blksize <value>

🧊 --tftp-no-options

🕰️ -z -time, --time-cond <time>

👑 --tls-max <VERSION>

🔐 --tls13-ciphers <list of TLS 1.3 ciphersuites>

🎀 --tlsauthtype <type>

🗝️ --tlspassword

🌈 --tlsuser <name>

⭐ --tlsv1.0

🎀 FILES 🎀

💖 ENVIRONMENT 💖

🧚 PROXY PROTOCOL PREFIXES 🧚

💀 EXIT STATUS 💀

👑 AUTHORS 👑

🦋 SEE ALSO 🦋

🧦 `--socks5-gssapi`

🦋 `--socks5-hostname <host[:port]>`

🧚 `--socks5 <host[:port]>`

🏎️ `-Y speed`, `--speed-limit <speed>`

⏱️ `--y seconds`, `-speed-time <seconds>`

🦁 `--ssl-allow-beast`

🚫 `--ssl-no-revoke`

🔒 `--ssl-reqd`

🌸 `--ssl`

💀 `-2`, `--sslv2`

🫠 `-3`, `--sslv3`

📝 `--stderr`

✨ `--styled-output`

🙈 `--suppress-connect-headers`

⚡ `--tcp-fastopen`

🚀 `--tcp-nodelay`

📺 `-t opt=val`, `--telnet-option <opt=val>`

🍓 `--tftp-blksize <value>`

🧊 `--tftp-no-options`

🕰️ `-z -time`, `--time-cond <time>`

👑 `--tls-max <VERSION>`

🔐 `--tls13-ciphers <list of TLS 1.3 ciphersuites>`

🎀 `--tlsauthtype <type>`

🗝️ `--tlspassword`

🌈 `--tlsuser <name>`

⭐ `--tlsv1.0`