Skip to content

Improve CLI help, no-argument error, and README documentation #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
parvardegr merged 2 commits into from
Jun 17, 2026
Merged

Improve CLI help, no-argument error, and README documentation #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5548ec2
Initial plan
Copilot Jun 17, 2026
40988d2
Improve --help output, no-argument error message, and README document…
Copilot Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 91 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <your-public-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)
58 changes: 34 additions & 24 deletions bin/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -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 <path> Share a file or directory');
console.error(' sharing -c Share clipboard content');
console.error(' sharing --help Show all available options');
process.exit(1);
}

Expand Down
4 changes: 2 additions & 2 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading