Skip to content

Usage Guide

This guide covers qrtransfer in depth, with examples for Linux/macOS shells, Windows cmd, and Windows PowerShell.

Table of Contents

Installing

pip install qrtransfer-lite
Shell Activate a venv Notes
bash / zsh source .venv/bin/activate
fish source .venv/bin/activate.fish
cmd .venv\Scripts\activate.bat
PowerShell .venv\Scripts\Activate.ps1 May require Set-ExecutionPolicy RemoteSigned first.

After install, qrtransfer is on your PATH. If you did not create a venv, install with pip install --user qrtransfer-lite.

Sending files

qrtransfer photo.jpg                 # single file
qrtransfer docs/*.pdf                # multiple files → zipped automatically
qrtransfer -z single.pdf             # force-zip a single file
qrtransfer project/                  # whole directory → zipped

On Windows cmd, globs are expanded by the shell just like POSIX; in PowerShell the * must be quoted to let the tool receive the pattern, or just list the files:

qrtransfer (Get-ChildItem docs -Filter *.pdf).FullName
qrtransfer docs\a.pdf docs\b.pdf

Sharing text

qrtransfer --text "Meeting at 3pm in room 4"

The snippet is saved to a temporary .txt file and shared like any other file.

Choosing the network interface

qrtransfer auto-detects your IP by probing the default route. When that is ambiguous it lists the up interfaces and asks you to pick one:

Choose the network interface to use (type the number):
[0] wlan0 (192.168.1.5)
[1] eth0 (10.0.1.2)

Your choice is remembered in the config file and reused next time. Force a choice on a single run:

qrtransfer -i wlan0 holiday.jpg

Skip the prompt and ignore saved settings:

qrtransfer --force holiday.jpg

The config file location follows platformdirs conventions:

OS Location
Linux ~/.config/qrtransfer/config.json
macOS ~/Library/Application Support/qrtransfer/config.json
Windows %APPDATA%\qrtransfer\config.json

Password protection

qrtransfer -p hunter2 builds/

Scanning the QR code works because the password is embedded as ?passed=hunter2. To avoid putting the secret in the URL (e.g. when sharing the link manually), require the header instead and hand the secret out of band:

curl -H "X-Password: hunter2" -O http://192.168.1.5:44321/f9aX23_qY8M

Expiration

qrtransfer --expire 300 builds/      # link dies after 5 minutes (HTTP 410)

Combined with --password this means even a screenshot of the QR code stops working after the window closes. Note that --expire also keeps the server alive until expiry (it implies keep-alive).

Download limits

The default is exit-after-first-download:

qrtransfer -i wlan0 holiday.jpg      # stops after one download

Stay up indefinitely, or cap the count:

qrtransfer --keep-alive builds/
qrtransfer --max-downloads 10 builds/

--max-downloads stops the session once the counter reaches N; a concurrent request beyond the cap gets HTTP 403.

Receive mode

Send files from your phone to your computer:

qrtransfer receive
qrtransfer receive ~/incoming        # custom destination
qrtransfer receive --max-upload-size 200

Then scan the printed QR code, use the file picker or drag-and-drop on the receive page. Multiple files upload in parallel and land in the destination directory with sanitized filenames (path traversal is blocked). Uploads require Content-Length and are rejected with 413 above --max-upload-size.

TLS (HTTPS)

qrtransfer --tls secret.pdf

A self-signed certificate is generated and cached under the platform cache dir (platformdirs user_cache_dir). Browsers will warn about the certificate — accept it to proceed. For a custom certificate:

qrtransfer --tls --cert server.crt --key server.key secret.pdf

The tls extra is required for automatic certificate generation:

pip install "qrtransfer-lite[tls]"

IPv6

qrtransfer --ipv6 file

The URL is printed with bracketed IPv6, e.g. http://[2001:db8::1]:44321/token.

Clipboard

qrtransfer --clipboard file

Copies the URL to the clipboard. Needs the optional pyperclip dependency:

pip install "qrtransfer-lite[clipboard]"

Without it the tool prints a notice and continues.

History

qrtransfer --history

Lists the last 200 transfers (date, mode, size, download count, filename or destination). History is stored in a small JSON file under platformdirs user_data_dir.

Stopping a session

Press Enter or Ctrl+C in the terminal that runs qrtransfer. Temporary zip archives are removed and the session summary is printed:

Transfer session ended.
Total downloads: 3

Exit codes

Code Meaning
0 Clean exit (help/version, or session ended normally).
2 Usage error (unknown flag, missing paths, bad interface choice, ...).
1 Runtime error (e.g. unable to determine the network IP).

Back to README