From 5548ec274b0a465afa0ef0f19f6f5a3ecf9496b4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 17 Jun 2026 04:49:51 +0000 Subject: [PATCH 1/2] Initial plan From 40988d2ddd30d343a0b7d8545a49d14deb78ecbf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 17 Jun 2026 04:52:46 +0000 Subject: [PATCH 2/2] Improve --help output, no-argument error message, and README documentation - Rewrite CLI usage text with clear description and structured examples - Improve all option descriptions for clarity and consistency - Show helpful usage examples when no arguments are provided - Rewrite README with professional structure: features list, getting started guide, quick start examples, and options reference - Format tunnel services as a table for better readability - Add License section Closes #58 --- README.md | 145 +++++++++++++++++++++++++++++----------------- bin/index.js | 58 +++++++++++-------- package-lock.json | 4 +- 3 files changed, 127 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index 5f8e9f7..c616fa0 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,121 @@ # sharing -**Share** directories and files from the CLI to iOS and Android devices without the need of an extra client app +Instantly share files, directories, and clipboard content from your terminal to any device with a browser — no apps required. ![Sharing screenshot](/doc/sharing-banner.svg?raw=true "Sharing a directory") -- share directory and file -- share your clipboard -- receive file -- support basic authentication -- support ssl +### Features -## Usage -*sharing works with Node.js v14 or later* -1. Install - - `npm install -g easy-sharing` -2. Share a file or directory - - `sharing /directory-or-file-to-share` -3. Scan the QR-Code with your phone - - both devices must connect to the same Wi-Fi or, if you have a public IP address, use the `--ip` parameter. - - `sharing --ip your-public-ip-address /directory-or-file-to-share` -4. Tada! Just browse the directory and download any file you want +- 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 -*note: macos users should use `easy-sharing` binary instead of `sharing`* +## Getting Started -example: `easy-sharing /file-or-directory` +**Requirements:** Node.js v14 or later + +### Install + +```sh +npm install -g easy-sharing +``` + +> **macOS users:** use the `easy-sharing` command instead of `sharing`. +> Example: `easy-sharing /path/to/file` + +### Quick Start + +```sh +# Share a file or directory +sharing /path/to/file-or-directory + +# Share clipboard content +sharing -c + +# Receive files from another device +sharing /destination/directory --receive +``` + +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: + +```sh +sharing --ip /path/to/file-or-directory +``` + +## Options ``` $ sharing --help -Usage: -• Share file or directory -$ sharing /path/to/file-or-directory +sharing — quickly share files, directories, and clipboard content from your +terminal to any device with a browser. -• Share clipboard -$ sharing -c +Examples: -• Receive file -$ sharing /destination/directory --receive; + Share file or directory + $ sharing /path/to/file-or-directory -• Share file with Basic Authentication -$ sharing /path/to/file-or-directory -U user -P password # also works with ---receive + Share clipboard content + $ sharing -c + + Receive files from another device + $ sharing /destination/directory --receive + + Share with basic authentication + $ sharing /path/to/file-or-directory -U user -P password + + Share over HTTPS + $ sharing /path/to/file-or-directory -S -C cert.pem -K key.pem Options: --version Show version number [boolean] - --debug enable debuging logs - -p, --port Change default port - --ip Your machine public ip address - -c, --clipboard Share Clipboard - -t, --tmpdir Clipboard Temporary files directory - -w, --on-windows-native-terminal Enable QR-Code support for windows native - terminal - -r, --receive Receive files - -q, --receive-port change receive default port - -U, --username set basic authentication username - [default: "user"] - -P, --password set basic authentication password - --tunnel Show guide for exposing your share over the - internet using tunnel services + --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] + -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] + -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] + -C, --cert Path to SSL certificate file [string] + -K, --key Path to SSL private key file [string] + --tunnel Show guide for sharing over the internet via + tunnel services [boolean] --help Show help [boolean] ``` ## Sharing Over the Internet (Tunneling) -If you are on a local network (home Wi-Fi, office, hotel, etc.) and want to share files with someone who is **not** on the same network — for example, sharing photos from your laptop with a friend across the city — you can use a tunnel service to make your share accessible over the internet, without needing a public IP address. +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. -Run `sharing --tunnel` for a quick setup guide, or follow the steps below: +Run `sharing --tunnel` for a quick setup guide, or follow these steps: 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 the tunnel service gives you +3. Share the public URL provided by the tunnel service + +| Service | Command | Documentation | +|---|---|---| +| **ngrok** | `ngrok http 7478` | [Getting started](https://ngrok.com/docs/getting-started/) | +| **localtunnel** | `npx localtunnel --port 7478` | [Docs](https://theboroer.github.io/localtunnel-www/) | +| **cloudflared** | `cloudflared tunnel --url http://localhost:7478` | [Docs](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) | +| **SSH** | `ssh -R 80:localhost:7478 your-server` | — | -- **ngrok**: `ngrok http 7478` — [Getting started](https://ngrok.com/docs/getting-started/) -- **localtunnel**: `npx localtunnel --port 7478` — [Docs](https://theboroer.github.io/localtunnel-www/) -- **cloudflared**: `cloudflared tunnel --url http://localhost:7478` — [Docs](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) -- **ssh**: `ssh -R 80:localhost:7478 your-server` +> Replace `7478` with the port shown when you start sharing. -Replace `7478` with the port shown when you start sharing. +## License -## TODO -- zip the file before transferring it (sharing --zip /path/to/file) -- self-signed certificate creation -- new banner screenshot (also show the --receive functionality) +[MIT](LICENSE) diff --git a/bin/index.js b/bin/index.js index fa609f5..58e5d6f 100755 --- a/bin/index.js +++ b/bin/index.js @@ -14,38 +14,45 @@ const utils = require('./utils'); // Usage const usage = [ '', - 'Usage:', - '• Share file or directory', - '$ sharing /path/to/file-or-directory', + 'sharing — quickly share files, directories, and clipboard content from your', + 'terminal to any device with a browser.', '', - '• Share clipboard', - '$ sharing -c', + 'Examples:', '', - '• Receive file', - '$ sharing /destination/directory --receive;', + ' Share file or directory', + ' $ sharing /path/to/file-or-directory', '', - '• Share file with Basic Authentication', - '$ sharing /path/to/file-or-directory -U user -P password # also works with --receive', + ' Share clipboard content', + ' $ sharing -c', + '', + ' Receive files from another device', + ' $ sharing /destination/directory --receive', + '', + ' Share with basic authentication', + ' $ sharing /path/to/file-or-directory -U user -P password', + '', + ' Share over HTTPS', + ' $ sharing /path/to/file-or-directory -S -C cert.pem -K key.pem', ].join('\n'); // Main (async () => { const options = yargs .usage(usage) - .option('debug', { describe: 'Enable debugging logs', type: 'boolean', default: false }) - .option('p', { alias: 'port', describe: 'Change default port', type: 'number' }) - .option('ip', { describe: 'Your machine public ip address', type: 'string' }) - .option('c', { alias: 'clipboard', describe: 'Share Clipboard', type: 'boolean' }) - .option('t', { alias: 'tmpdir', describe: 'Clipboard temporary files directory', type: 'string' }) - .option('w', { alias: 'on-windows-native-terminal', describe: 'Enable QR-Code support for windows native terminal', type: 'boolean' }) - .option('r', { alias: 'receive', describe: 'Receive files', type: 'boolean' }) - .option('q', { alias: 'receive-port', describe: 'Change receive default port', type: 'number' }) - .option('U', { alias: 'username', describe: 'Set basic authentication username', type: 'string', default: 'user' }) - .option('P', { alias: 'password', describe: 'Set basic authentication password', type: 'string' }) - .option('S', { alias: 'ssl', describe: 'Enable https', type: 'boolean' }) - .option('C', { alias: 'cert', describe: 'Path to ssl cert file', type: 'string' }) - .option('K', { alias: 'key', describe: 'Path to ssl key file', type: 'string' }) - .option('tunnel', { describe: 'Show guide for exposing your share over the internet using tunnel services', type: 'boolean' }) + .option('debug', { describe: 'Enable debug logging', type: 'boolean', default: false }) + .option('p', { alias: 'port', describe: 'Set the server port (default: auto-assigned)', type: 'number' }) + .option('ip', { describe: 'Specify your machine\'s public IP address', type: 'string' }) + .option('c', { alias: 'clipboard', describe: 'Share clipboard content', type: 'boolean' }) + .option('t', { alias: 'tmpdir', describe: 'Set temporary directory for clipboard files', type: 'string' }) + .option('w', { alias: 'on-windows-native-terminal', describe: 'Enable QR code rendering in Windows native terminal', type: 'boolean' }) + .option('r', { alias: 'receive', describe: 'Receive files from another device', type: 'boolean' }) + .option('q', { alias: 'receive-port', describe: 'Set the port for receiving files', type: 'number' }) + .option('U', { alias: 'username', describe: 'Set username for basic authentication', type: 'string', default: 'user' }) + .option('P', { alias: 'password', describe: 'Set password for basic authentication', type: 'string' }) + .option('S', { alias: 'ssl', describe: 'Enable HTTPS', type: 'boolean' }) + .option('C', { alias: 'cert', describe: 'Path to SSL certificate file', type: 'string' }) + .option('K', { alias: 'key', describe: 'Path to SSL private key file', type: 'string' }) + .option('tunnel', { describe: 'Show guide for sharing over the internet via tunnel services', type: 'boolean' }) .help(true) .argv; @@ -156,7 +163,10 @@ const usage = [ } if (!sharePath) { - console.log('Specify directory or file path.'); + console.error('Error: No file or directory specified.\n'); + console.error('Usage: sharing Share a file or directory'); + console.error(' sharing -c Share clipboard content'); + console.error(' sharing --help Show all available options'); process.exit(1); } diff --git a/package-lock.json b/package-lock.json index 06a8d22..f97dd30 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "easy-sharing", - "version": "2.0.0", + "version": "1.3.0", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "easy-sharing", - "version": "2.0.0", + "version": "1.3.0", "license": "MIT", "dependencies": { "clipboardy": "^2.3.0",