reliability, batch transfer, and privacy

README.md

@@ -1,29 +1,50 @@
 # sharing
 
-Instantly share files, directories, and clipboard content from your terminal to any device with a browser — no apps required.
+**Instantly move files, folders, and clipboard text between your computer and any phone — no app, no account, no cloud. Just run a command and scan the QR code.**
 
 ![Sharing screenshot](/doc/sharing-banner.svg?raw=true "Sharing a directory")
 
-### Features
+```sh
+npx easy-sharing ~/Photos      # share a folder — scan the QR on your phone — done
+```
+
+That's the whole idea. Your phone opens a normal web page over your own Wi-Fi. Nothing to install on the other device, nothing leaves your network.
+
+## Why `sharing`?
+
+If you've ever tried to get a file from your laptop to your phone, you know the options are all a little painful: cloud uploads are slow and nosy, AirDrop is Apple-only, and "real" tools want an app installed on *both* ends. `sharing` takes the simplest path that always works: **a tiny web server and a QR code.** Any phone with a browser can use it.
 
-- Share files and directories over your local network
-- Share clipboard content
-- Receive files from other devices
-- Protect shares with basic authentication
-- HTTPS support via custom SSL certificates
-- Expose shares over the internet with tunnel services
+| | **sharing** | `python -m http.server` | `npx serve` | qrcp | AirDrop / LocalSend |
+|---|:---:|:---:|:---:|:---:|:---:|
+| No app on the phone | ✅ | ✅ | ✅ | ✅ | ❌ (app both ends) |
+| QR code to connect | ✅ | ❌ | ❌ | ✅ | ❌ |
+| **Receive** files from the phone | ✅ | ❌ | ❌ | ✅ | ✅ |
+| Receive **multiple** files / drag-drop | ✅ | ❌ | ❌ | ➖ | ✅ |
+| Download a whole folder as **.zip** | ✅ | ❌ | ❌ | ✅ | ➖ |
+| Share **clipboard** text *and* receive text back | ✅ | ❌ | ❌ | ➖ | ✅ |
+| Built-in auth **and** HTTPS | ✅ | ❌ | ➖ | ➖ | ✅ |
+| One-flag private share (`--secure`) | ✅ | ❌ | ❌ | ❌ | ✅ |
+| Picks the **right** network address automatically | ✅ | ❌ | ➖ | ✅ | ✅ |
+
+`sharing` is the one that does **all** of it from a single command, in a browser, with nothing to install on the device in your hand.
 
 ## Getting Started
 
-**Requirements:** Node.js v14 or later
+**Requirements:** Node.js v14.17 or later.
+
+### Try it without installing
+
+```sh
+npx easy-sharing /path/to/file-or-directory
+```
 
-### Install
+### Install globally
 
 ```sh
 npm install -g easy-sharing
 ```
 
-> **macOS users:** use the `easy-sharing` command instead of `sharing`.
+> **macOS users:** macOS already ships a built-in `/usr/sbin/sharing` command, so use **`easy-sharing`** instead of `sharing`.
 > Example: `easy-sharing /path/to/file`
 
 ### Quick Start
@@ -37,12 +58,67 @@ sharing -c
 
 # Receive files from another device
 sharing /destination/directory --receive
+
+# Share privately — secret link + password + HTTPS, in one flag
+sharing /path/to/file-or-directory --secure
 ```
 
-Scan the QR code displayed in your terminal with your phone to access the shared content. Both devices must be on the same network, or you can use the `--ip` flag to specify a public IP address:
+Scan the QR code shown in your terminal with your phone. Both devices just need to be on the same Wi-Fi.
+
+**QR code won't scan?** (Some Windows terminals and unicode paths can't draw it.) Open the link the terminal prints, or run with `--open` to pop the QR up in a browser window on your computer — then scan that.
+
+## Features
+
+### 📤 Share anything
+
+- **Files and directories** over your local network, with a clean browsable listing.
+- **Download a whole folder as a single `.zip`** — one tap on the phone instead of saving files one by one.
+- **Clipboard text** (`-c`) opens on the phone with a one-tap **Copy** button.
+
+### 📥 Receive just as easily
+
+- Turn your machine into a drop target with `--receive`.
+- **Multiple files at once**, with **drag-and-drop** and a live progress bar.
+- **Send a note or link back** from the phone straight to your terminal (and your clipboard).
+
+### 🔒 Private when you need it
+
+- `--secure` — the easy button: a secret unguessable link **+** an auto-generated password **+** HTTPS, all at once.
+- Or mix and match: `-U`/`-P` for a password, `--token` for a secret link, `-S` for HTTPS.
+- **Auto HTTPS:** `-S` now generates a certificate for you — no more fiddling with OpenSSL. (Bring your own with `-C`/`-K` if you prefer.)
+
+### ⏱️ Ephemeral by choice
+
+- `--once` — stop sharing automatically after the first transfer.
+- `--timeout 10m` — auto-stop after a set time (`30s`, `10m`, `1h`).
+
+### 🎯 It just works
+
+- **Smart network detection:** `sharing` advertises your real Wi-Fi address and skips Docker/VPN/WSL adapters — the #1 reason "the QR scans but the page won't load." Pin one explicitly with `--interface en0` or `--ip`.
+- **QR fallback:** `--open` shows the QR as an image in a browser for terminals that can't render it.
+- **Internet sharing:** `--tunnel` walks you through exposing a share beyond your LAN.
+
+## Usage examples
 
 ```sh
-sharing --ip <your-public-ip> /path/to/file-or-directory
+# Receive a batch of photos from your phone (multi-file + drag & drop)
+sharing ~/Downloads --receive
+
+# Share a folder and let the recipient grab it all as one zip
+sharing ~/project        # the listing shows a "Download as .zip" button
+
+# Copy a snippet to your phone, or send a link from the phone to your terminal
+sharing -c               # then use the Copy button on the page
+sharing ~/x --receive    # the upload page also has a "Send text" box
+
+# A private, self-destructing share
+sharing report.pdf --secure --once
+
+# Pick a specific network interface (multi-homed / VPN machines)
+sharing ~/x --interface en0
+
+# Share over HTTPS with your own certificate
+sharing ~/x -S -C cert.pem -K key.pem
 ```
 
 ## Options
@@ -67,45 +143,62 @@ Examples:
   Share with basic authentication
   $ sharing /path/to/file-or-directory -U user -P password
 
+  Share privately (secret link + password + HTTPS)
+  $ sharing /path/to/file-or-directory --secure
+
   Share over HTTPS
   $ sharing /path/to/file-or-directory -S -C cert.pem -K key.pem
 
 Options:
       --version                     Show version number                [boolean]
-      --debug                       Enable debug logging
-                                                      [boolean] [default: false]
-  -p, --port                        Set the server port (default: auto-assigned)
-                                                                        [number]
-      --ip                          Specify your machine's public IP address
-                                                                        [string]
+      --debug                       Enable debug logging  [boolean] [default: false]
+  -p, --port                        Set the server port (default: auto-assigned) [number]
+      --ip                          Specify your machine's public IP address [string]
+  -i, --interface                   Network interface/adapter name to advertise
+                                    (e.g. en0, eth0)                    [string]
   -c, --clipboard                   Share clipboard content            [boolean]
-  -t, --tmpdir                      Set temporary directory for clipboard files
-                                                                        [string]
-  -w, --on-windows-native-terminal  Enable QR code rendering in Windows native
-                                    terminal                           [boolean]
+  -w, --on-windows-native-terminal  Enable QR code rendering in Windows native terminal [boolean]
+      --open                        Open the QR code in a browser window on this computer [boolean]
   -r, --receive                     Receive files from another device  [boolean]
   -q, --receive-port                Set the port for receiving files    [number]
   -U, --username                    Set username for basic authentication
                                                       [string] [default: "user"]
-  -P, --password                    Set password for basic authentication
-                                                                        [string]
-  -S, --ssl                         Enable HTTPS                       [boolean]
+  -P, --password                    Set password for basic authentication [string]
+  -S, --ssl                         Enable HTTPS (auto self-signed cert when
+                                    -C/-K are not given)               [boolean]
   -C, --cert                        Path to SSL certificate file        [string]
   -K, --key                         Path to SSL private key file        [string]
+      --token                       Add a secret token to the share URL so it is
+                                    unguessable                        [boolean]
+      --secure                      Private share preset: secret link +
+                                    generated password + HTTPS         [boolean]
+      --once                        Stop sharing after the first completed transfer [boolean]
+      --timeout                     Auto-stop the share after a duration (e.g.
+                                    30s, 10m, 1h)                       [string]
       --tunnel                      Show guide for sharing over the internet via
                                     tunnel services                    [boolean]
       --help                        Show help                          [boolean]
 ```
 
+## A note on security
+
+By default a share is open to everyone on your Wi-Fi — perfect for your own devices at home, less so on a café or office network. `sharing` reminds you of this on startup and gives you one-flag protection:
+
+```sh
+sharing ~/private --secure
+```
+
+This generates a **secret link** (so the share isn't browsable by IP alone), a **random password**, and turns on **HTTPS** — printed for you when the server starts.
+
 ## Sharing Over the Internet (Tunneling)
 
-If you want to share files with someone who is **not** on your local network, you can use a tunnel service to make your share accessible over the internet — no public IP address required.
+To share with someone who is **not** on your local network, pair `sharing` with a tunnel service — no public IP required.
 
-Run `sharing --tunnel` for a quick setup guide, or follow these steps:
+Run `sharing --tunnel` for a quick setup guide, or:
 
 1. Start sharing as usual: `sharing /path/to/files`
 2. In a separate terminal, run one of the tunnel commands below
-3. Share the public URL provided by the tunnel service
+3. Share the public URL the tunnel gives you
 
 | Service | Command | Documentation |
 |---|---|---|
@@ -116,6 +209,12 @@ Run `sharing --tunnel` for a quick setup guide, or follow these steps:
 
 > Replace `7478` with the port shown when you start sharing.
 
+## Development
+
+```sh
+npm test    # runs the test suite (no external test framework)
+```
+
 ## License
 
 [MIT](LICENSE)