FETCH(1)

📦

version 15.1 · 2 versions

15.1 · freebsd 15.1 (latest)
14.5 · freebsd 14.5

💅 FETCH(1) — the `fetch` manual page, bestie edition 🎀

okay so you opened the General Commands Manual and landed on fetch — welcome, you're gonna love her, she's iconic. this is the part-one girlie of a two-parter, so buckle up and don't go anywhere. ✨

🌸 NAME 🌸

fetch — retrieve a file by Uniform Resource Locator

like, you give her a URL and she goes and gets the thing. that's the whole vibe. no cap.

🦋 SYNOPSIS 🦋

fetch [-146AadFlMmnPpqRrsUv] [-B bytes] [--bind-address=host]
      [--ca-cert=file] [--ca-path=dir] [--cert=file] [--crl=file]
      [-i file] [--key=file] [-N file] [--no-passive] [--no-proxy=list]
      [--no-sslv3] [--no-tlsv1] [--no-verify-hostname]
      [--no-verify-peer] [-o file] [--referer=URL] [-S bytes]
      [-T seconds] [--user-agent=agent-string] [-w seconds] URL ...
fetch [-146AadFlMmnPpqRrsUv] [-B bytes] [--bind-address=host]
      [--ca-cert=file] [--ca-path=dir] [--cert=file] [--crl=file]
      [-i file] [--key=file] [-N file] [--no-passive] [--no-proxy=list]
      [--no-sslv3] [--no-tlsv1] [--no-verify-hostname]
      [--no-verify-peer] [-o file] [--referer=URL] [-S bytes]
      [-T seconds] [--user-agent=agent-string] [-w seconds] -h host -f
      file [-c dir]

two whole modes, bestie — the normal "here's a URL" era and the old-school "here's a host and a file" era. both valid. both slay. 💅

✨ DESCRIPTION ✨

The fetch utility is literally just a command-line bestie for the fetch(3) library. her whole purpose? retrieve the file(s) that the URL(s) on the command line are pointing at. that's it. that's the job. 🫶

The following options are available — and yes, we're doing all of them, no skips:

-1, --one-file — Stop and return exit code 0 at the first successfully retrieved file. like, first win and she's out. 🏁
-4, --ipv4-only — Forces fetch to use IPv4 addresses only. v4 girlies only, sorry to the v6 girlies.
-6, --ipv6-only — Forces fetch to use IPv6 addresses only. the v6 girlies get their turn now. 💜
-A, --no-redirect — Do not automatically follow "temporary" (302) redirects. some broken Web sites will return a redirect instead of a not-found error when the requested object does not exist — which is giving very much gaslighting, honestly. 🙈
-a, --retry — Automatically retry the transfer upon soft failures. she gets back up. main character energy. 💪
-B bytes, --buffer-size=bytes — Specify the read buffer size in bytes. The default is 16,384 bytes. Attempts to set a buffer size lower than this will be silently ignored (she's not gonna argue with you, she'll just ignore you 💀). The number of reads actually performed is reported at verbosity level two or higher (see the -v flag).
--bind-address=host — Specifies a hostname or IP address to which sockets used for outgoing connections will be bound. tying the socket down to one address. committed. 🎀
-c dir — The file to retrieve is in directory dir on the remote host. This option is deprecated and is provided for backward compatibility only. old money, but still money. ⭐
--ca-cert=file — [SSL] Path to certificate bundle containing trusted CA certificates. Otherwise, OpenSSL's default CA cert and path settings apply. she'll trust the bundle you hand her.
--ca-path=dir — [SSL] The directory dir contains trusted CA hashes. hashes, not vibes. 🌈
--cert=file — [SSL] file is a PEM encoded client certificate/key which will be used in client certificate authentication. your lil ID card, glowing. 👑
--crl=file — [SSL] Points to certificate revocation list file, which has to be in PEM format and may contain peer certificates that have been revoked. the block list, fr fr. 💀
-d, --direct — Use a direct connection even if a proxy is configured. no middleman, just her and the destination. ✨
-F, --force-restart — In combination with the -r flag, forces a restart even if the local and remote files have different modification times. Implies -R. 🔥
-f file — The file to retrieve is named file on the remote host. This option is deprecated and is provided for backward compatibility only. yes, deprecated again, we know. 💅
-h host — The file to retrieve is located on the host host. This option is deprecated and is provided for backward compatibility only. the old guard. 🫶
-i file, --if-modified-since=file — If-Modified-Since mode: the remote file will only be retrieved if it is newer than file on the local host. (HTTP only) like, if it's not new, she's not interested. 🍓
--key=file — [SSL] file is a PEM encoded client key that will be used in client certificate authentication in case key and client certificate are stored separately. separate storage, still soulmates. 🔑
-l, --symlink — If the target is a file-scheme URL, make a symbolic link to the target rather than trying to copy it. link, don't copy — lowkey efficient. 🦋
-M — (that's it. she's just -M. mystery icon. no explanation given. we respect her privacy. 🤫)
-m, --mirror — Mirror mode: if the file already exists locally and has the same size and modification time as the remote file, it will not be fetched. Note that the -m and -r flags are mutually exclusive — they literally cannot both be in the group chat. 😭
-N file, --netrc=file — Use file instead of ~/.netrc to look up login names and passwords for FTP sites. See ftp(1) for a description of the file format. This feature is experimental — handle with care, bestie. 🙈
-n, --no-mtime — Do not preserve the modification time of the transferred file. let it be reborn with a new timestamp. 🌸
--no-passive — Forces the FTP code to use active mode. she's taking initiative. 🔥
--no-proxy=list — Either a single asterisk, which disables the use of proxies altogether, or a comma- or whitespace-separated list of hosts for which proxies should not be used. one * and it's over for proxies. ✋
--no-sslv3 — [SSL] Do not allow SSL version 3 when negotiating the connection. This option is deprecated and is provided for backward compatibility only. SSLv3 is disabled by default. Set SSL_ALLOW_SSL3 to change this behavior. (SSLv3 is ancient, we do not stan. 💀)
--no-tlsv1 — [SSL] Do not allow TLS version 1 when negotiating the connection. nope, not that one either. 🚫
--no-verify-hostname — [SSL] Do not verify that the hostname matches the subject of the certificate presented by the server. ⚠️ like, you're choosing to not check, so. yeah. know what you're doing.
--no-verify-peer — [SSL] Do not verify the peer certificate against trusted CAs. same energy, different check. ⚠️
-o file, --output=file — Set the output file name to file. By default, a "pathname" is extracted from the specified URI, and its basename is used as the name of the output file. A file argument of - indicates that results are to be directed to the standard output. If the file argument is a directory, fetched file(s) will be placed within the directory, with name(s) selected as in the default behaviour. so: name it, or pipe it to stdout with -, or drop it in a dir. she's flexible. 🎀
-P — (another lone icon. she's just here. hi -P, we love you. 💜)
-p, --passive — Use passive FTP. These flags have no effect, since passive FTP is the default, but are provided for compatibility with earlier versions where active FTP was the default. To force active mode, use the --no-passive flag or set the FTP_PASSIVE_MODE environment variable to NO. so -p is basically a decorative flag at this point. aesthetic. ✨
--referer=URL — Specifies the referrer URL to use for HTTP requests. If URL is set to auto, the document URL will be used as referrer URL. tell them where you came from, or let auto handle it. 🌈
-q, --quiet — Quiet mode. she's not gonna narrate. shhh. 🤫
-R, --keep-output — The output files are precious, and should not be deleted under any circumstances, even if the transfer failed or was incomplete. protect them at all costs. 👑
-r, --restart — Restart a previously interrupted transfer. Note that the -m and -r flags are mutually exclusive. again — cannot share a group chat. 😭
-S bytes, --require-size=bytes — Require the file size reported by the server to match the specified value. If it does not, a message is printed and the file is not fetched. If the server does not support reporting file sizes, this option is ignored and the file is fetched unconditionally — no size info? she's fetching anyway, bestie. 🍓
-s, --print-size — Print the size in bytes of each requested file, without fetching it. just the numbers, no download. a little peek. 👀
-T seconds, --timeout=seconds — Set timeout value to seconds. Overrides the environment variables FTP_TIMEOUT for FTP transfers or HTTP_TIMEOUT for HTTP transfers if set. your clock, your rules. ⏰
-U, --passive-portrange-default — When using passive FTP, allocate the port for the data connection from the low (default) port range. See ip(4) for details on how to specify which port range this corresponds to. low ports, high drama. 🔥
--user-agent=agent-string — Specifies the User-Agent string to use for HTTP requests. This can be useful when working with HTTP origin or proxy servers that differentiate between user agents. dress her up in whatever UA you want. 💅
-v, --verbose — Increase verbosity level. she talks more. and more. and more. 🗣️
-w seconds, --retry-delay=seconds — When the -a flag is specified, wait this many seconds between successive retries. patience, bestie. 🧘

If fetch receives a SIGINFO signal (see the status argument for stty(1)), the current transfer rate statistics will be written to the standard error output, in the same format as the standard completion message. so you can poke her mid-transfer and she'll tell you how it's going. 🫶

💖 ENVIRONMENT 💖

FTP_TIMEOUT — Maximum time, in seconds, to wait before aborting an FTP connection. ⏳
HTTP_TIMEOUT — Maximum time, in seconds, to wait before aborting an HTTP connection. ⏳

See fetch(3) for a description of additional environment variables, including FETCH_BIND_ADDRESS, FTP_LOGIN, FTP_PASSIVE_MODE, FTP_PASSWORD, FTP_PROXY, ftp_proxy, HTTP_ACCEPT, HTTP_AUTH, HTTP_PROXY, http_proxy, HTTP_PROXY_AUTH, HTTP_REFERER, HTTP_USER_AGENT, NETRC, NO_PROXY, no_proxy, SSL_CA_CERT_FILE, SSL_CA_CERT_PATH, SSL_CLIENT_CERT_FILE, SSL_CLIENT_KEY_FILE, SSL_CRL_FILE, SSL_ALLOW_SSL3, SSL_NO_TLS1, SSL_NO_TLS1_1, SSL_NO_TLS1_2, SSL_NO_VERIFY_HOSTNAME and SSL_NO_VERIFY_PEER. that's a whole lot of env vars, and every single one of them is invited to the party. 🎉

⭐ EXIT STATUS ⭐

The fetch command returns zero on success, or one on failure. If multiple URLs are listed on the command line, fetch will attempt to retrieve each one of them in turn, and will return zero only if they were all successfully retrieved. all or nothing, group project rules. 😤

If the -i argument is used and the remote file is not newer than the specified file then the command will still return success, although no file is transferred. so like — nothing happened, but she's still winning. iconic. 👑

🎀 EXAMPLES 🎀

Okay bestie, real talk — this is where it all clicks. Watch and learn 💅

💖 Silently try to fetch the URLs passed as parameters 💖

So the vibe here is: the first one will fail (rip 💀). But if the second URL succeeds, the third one will not be tried at all — that's the -1 doing its thing ✨

$ fetch -1 -q https://www.freebsd.org/bad.html \
        ftp.freebsd.org/pub/FreeBSD/README.TXT \
        https://www.fake.url
fetch: https://www.freebsd.org/bad.html: Not Found

🌸 Be verbose when retrieving the README.TXT file 🌸

-v is giving main character energy — it tells you everything that's happening 🫶

$ fetch -v ftp.freebsd.org/pub/FreeBSD/README.TXT
resolving server address: ftp.freebsd.org:80
requesting http://ftp.freebsd.org/pub/FreeBSD/README.TXT
local size / mtime: 4259 / 1431015519
remote size / mtime: 4259 / 1431015519
README.TXT                                            4259  B   44 MBps    00s

🦋 Quietly save the README.TXT file as myreadme.txt 🦋

And -R means do not delete the output file under any circumstances — like, ever, periodt 👑

fetch -o myreadme.txt -q -R ftp.freebsd.org/pub/FreeBSD/README.TXT

⭐ Print the size of the requested file ⭐

Bonus: identify the request with a custom user agent string, because why be anonymous when you can have personality 😌

$ fetch -s ftp.freebsd.org/pub/FreeBSD/README.TXT
--user-agent="Mozilla/5.0 (X11; FreeBSD x86_64; rv:78.0) Gecko/20100101"
3513231

🔥 Restart the transfer and retry on soft failures 🔥

-a restarts, -r retries — the duo we didn't know we needed fr fr 💜

$ fetch -a -r http://ftp.freebsd.org/pub/FreeBSD/README.TXT

👀 SEE ALSO 👀

fetch(3)
phttpget(8)

🧚 HISTORY 🧚

The fetch command appeared in FreeBSD 2.1.5. This implementation first appeared in FreeBSD 4.1. Literally iconic behavior, no cap 🌈

👑 AUTHORS 👑

The original implementation of fetch was done by Jean-Marc Zucconi <jmz@FreeBSD.org>. Then it was extensively re-worked for FreeBSD 2.2 by Garrett Wollman <wollman@FreeBSD.org>, and later completely rewritten to use the fetch(3) library by Dag-Erling Smørgrav <des@FreeBSD.org> and Michael Gmelin <freebsd@grem.de>. A whole glow-up arc, honestly ✨🫶

💀 NOTES 💀

Heads up bestie, some important tea ☕

The -b and -t options are no longer supported and will generate warnings ⚠️ They were workarounds for bugs in other OSes which this implementation does not trigger — so like, not our problem anymore 🙈

Also, one cannot both use the -h, -c and -f options and specify URLs on the command line. Pick a lane, babe 💅

Debian · October 7, 2023 · FETCH(1) — that's the whole page, bestie! Go forth and fetch responsibly, mwah 🎀💖🦋

📦 where this page comes from

freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms