RSURL(1)

NAME
rsurl - transfer a URL (a pure-Rust curl)

SYNOPSIS
rsurl [options] url...

DESCRIPTION
rsurl transfers data to or from a server using one of many supported protocols. It is a pure-Rust reimplementation of much of curl(1): no C toolchain and no *-sys crates are used, so there is no OpenSSL, GSSAPI/Kerberos, or c-ares dependency. The command line, semantics, and exit codes follow curl unless noted otherwise.

Supported URL schemes: http, https, ftp, ftps, sftp, scp, imap, imaps, pop3, pop3s, smtp, smtps, mqtt, mqtts, rtsp, tftp, ldap, ldaps, telnet, gopher, gophers, dict, file, ws, and wss. HTTP runs over HTTP/1.1, HTTP/2, or HTTP/3 (QUIC).

OPTIONS

  General

-h, --help
    Print the full option list and exit.

-V, --version
    Print the version and exit.

-v, --verbose
    Write a protocol trace to standard error.

-s, --silent
    Silent mode: suppress progress and error messages.

-S, --show-error
    Show errors even when -s is set.

--next, -:
    Begin a new request with its own independent options.

-K file, --config file
    Read further options from a curl-style config file.

  HTTP request

-X method, --request method
    Set the request method.

-H header, --header header
    Add a request header (repeatable).

-A ua, --user-agent ua
    Set the User-Agent header.

-e url, --referer url
    Set the Referer header; -e ';auto' sends it on each redirect.

-d data, --data data
    Send data as a urlencoded POST body; @file reads from disk. See also --data-raw, --data-binary, --data-urlencode.

--json data
    POST data as application/json and request a JSON response.

-F name=value, --form name=value
    Add a multipart/form-data part (@file uploads, <file inlines).

-G, --get
    Move -d data into the URL query and use GET.

-I, --head
    Fetch headers only (HEAD).

-L, --location
    Follow 3xx redirects. --location-trusted keeps credentials across hosts.

-b data, --cookie data
    Send cookies (a name=value string or a file to read).

-c file, --cookie-jar file
    Write the cookie jar to file after the transfer.

--compressed
    Request and transparently decode a compressed response.

  Authentication

-u user:password, --user user:password
    Server credentials (Basic by default).

--digest
    Use HTTP Digest authentication.

--oauth2-bearer token
    Send an OAuth 2 bearer token.

--aws-sigv4 provider
    Sign the request with AWS Signature V4 (use -u key:secret).

-n, --netrc
    Read credentials from ~/.netrc (or --netrc-file).

  TLS

-k, --insecure
    Do not verify the server certificate.

--cacert file
    Use file as the CA certificate bundle.

--tlsv1.2, --tlsv1.3, --tls-max <ver>
    Pin the minimum / maximum TLS version.

  Transfer and output

-o file, --output file
    Write output to file instead of standard output.

-O, --remote-name
    Save to a file named like the remote resource.

--create-dirs
    Create missing directories for -o.

--output-dir <dir>
    Prepend dir to -o/-O names.

--remove-on-error
    Delete a partial -o/-O file if the transfer fails.

--no-clobber
    Never overwrite an existing -o/-O file; pick .1, .2, ...

-r range, --range range
    Request a byte range.

--limit-rate speed
    Cap the download rate (e.g. 200k, 1M) on file downloads.

-Y bps, --speed-limit bps / -y s, --speed-time s
    Abort a file download averaging below bps bytes/sec over s seconds (exit 28).

--max-filesize bytes
    Refuse a download larger than bytes.

-#, --progress-bar
    Show progress on streamed file downloads.

-R, --remote-time
    Set the saved file's mtime from the response.

-w format, --write-out format
    After the transfer, print format with %{var} expanded: http_code, size_download, content_type, url_effective, time_total, time_connect, time_appconnect, time_pretransfer, time_starttransfer, ssl_verify_result, and %header{Name}. Phase timers are reported on HTTP/1.1 transfers.

  Connection and protocol

-4, --ipv4, -6, --ipv6
    Force IPv4 or IPv6.

-x proxy, --proxy proxy
    Route through a proxy. Schemes: http, https, socks4, socks4a, socks5, socks5h.

--resolve host:port:addr
    Provide a static address for host:port.

--connect-to spec
    Dial a different host:port while keeping the original Host:/SNI.

--unix-socket <path>
    Connect through a Unix-domain socket (Unix only).

--disable-epsv
    For FTP, skip EPSV and use PASV directly.

--http2, --http1.1, --http3, --http3-only
    Select the HTTP version.

--retry n
    Retry a failed transfer up to n times (with --retry-delay, --retry-max-time, --retry-connrefused, --retry-all-errors).

-Z, --parallel
    Run this invocation's transfers concurrently (--parallel-max caps them).

EXIT STATUS
rsurl uses curl's exit codes. The common ones:

0   Success.

1   Unsupported protocol.

2   Failed to initialize / option error.

3   URL malformed.

6   Could not resolve host.

7   Failed to connect.

8   Weird server reply.

22  HTTP page not retrieved (-f with a >= 400 status).

23  Write error.

28  Operation timed out (includes -y/-Y low-speed abort).

47  Too many redirects.

63  Maximum file size exceeded.

EXAMPLES
Fetch a page:

    rsurl https://example.com/

POST JSON and print the status and timing:

    rsurl --json '{"a":1}' -w '%{http_code} %{time_total}\n' https://api.example.com/

Download through a SOCKS5 proxy, resumable name, deleting partials on failure:

    rsurl -x socks5h://127.0.0.1:1080 --remove-on-error -O https://example.com/file.bin

SEE ALSO
curl(1). Run rsurl --help for the complete, build-specific option list.