Skip to content

CLI Reference

qrtransfer is the single entry point. Its first argument selects a mode:

  • qrtransfer ... — the send mode (default).
  • qrtransfer receive ... — the receive mode.

Table of Contents

Send mode

qrtransfer [OPTIONS] [PATHS...]
Argument / Option Description
PATHS One or more files or directories to serve. A directory, or more than one path, is zipped automatically.
-z, --zip Force zipping even for a single file.
--text TEXT Share a text snippet as a temporary .txt file instead of PATHS.
--once Stop after the first successful download. This is the default behaviour; the flag exists for explicitness.
-k, --keep-alive Keep serving after transfers complete.
--max-downloads N Stop after N successful downloads (at least 1).

You must provide at least one PATHS entry or --text, otherwise the command prints a usage error and exits with code 2.

Auto-zipping

  • A single directory → <dirname>.zip.
  • Multiple files → files.zip.
  • A single file with -z → <stem>.zip.

Zip archives are created in a temporary directory and removed when the session ends.

Receive mode

qrtransfer receive [DEST] [OPTIONS]
Argument / Option Description
DEST Directory to save uploads (default: ~/Downloads, else the current directory). Created if missing.
-k, --keep-alive Keep serving after uploads complete.
--max-downloads N Stop after N successful uploads (each POST counts as one).
--max-upload-size MB Reject uploads larger than MB megabytes (default: 1024).

The receive page (/) supports file picking and drag-and-drop, and posts multipart/form-data to the token URL. Every upload must include a Content-Length header; requests above the size limit get 413.

Common options

Both modes accept these:

Option Description
-i, --interface IFACE Network interface to use, e.g. wlan0. Remembered for the next run.
--port PORT Port to bind. Remembered for the next run; auto-selected when free otherwise.
--force Ignore saved interface/port configuration.
-e, --expire SECONDS Link expires after SECONDS (0 = never). Implies keep-alive.
-p, --password SECRET Require a password via URL param ?passed=SECRET or header X-Password.
--tls Serve over HTTPS with a self-signed certificate.
--cert FILE TLS certificate (used with --tls).
--key FILE TLS private key (used with --tls).
--ipv6 Prefer IPv6 addresses.
--clipboard Copy the URL to the clipboard (needs the clipboard extra).
--max-clients N Maximum concurrent connections (0 = unlimited); excess connections are closed.
--history Show the last 200 transfers and exit.
-v, --verbose Log every HTTP request.
-q, --quiet Suppress non-essential output. Mutually exclusive with -v.
--version Print the version and exit.
-h, --help Show help and exit.

Notes on behaviour

  • Default lifecycle — without --keep-alive, --expire, or --max-downloads, a session stops after one successful transfer.
  • Password discovery — the token is checked before the password, so a wrong token always returns 404 and never reveals whether a password exists.
  • Config memory — a chosen interface or --port is saved to config.json (see configuration) and reused, unless --force is given.
  • Receive counter — one upload batch (one POST) increments the counter once, no matter how many files it contains.

Exit codes

Code Meaning
0 Clean exit: help/version, --history, or a session ended normally.
2 Usage error: unknown flag, missing PATHS/--text, path not found, mutually exclusive flags.
1 Runtime error: unable to determine the network IP, or TLS setup failed.

Examples

qrtransfer report.pdf
qrtransfer -z report.pdf
qrtransfer -p secret --expire 300 report.pdf
qrtransfer --keep-alive --max-downloads 10 assets/
qrtransfer --text "hello world"
qrtransfer --interface wlan0 --port 8080 photo.jpg
qrtransfer --tls report.pdf
qrtransfer receive
qrtransfer receive ~/incoming --max-upload-size 200
qrtransfer --history

More examples with platform-specific notes: usage.

Back to README