⚡ ycis-file

The elegant, zero-configuration local file transfer utility for terminal power users.

No logins. No cloud servers. No AirDrop walls. Just high-speed, peer-to-peer file sharing directly from your terminal.

⚡ Why does this exist?

Moving files between nearby devices is still surprisingly painful. Cloud drives require you to log in, upload, and download. Messaging apps compress your files and enforce size limits. AirDrop is locked to Apple's ecosystem. LocalSend is great, but lacks a CLI-first workflow. Commands like scp or rsync require SSH keys, open ports, and manual configuration.

ycis-file was built to bridge this gap. It's a CLI tool that automatically discovers other instances on your local network, streams directories and files directly between them, and generates download pages with QR codes for non-CLI devices like phones and tablets.

✨ Features

• 🔍 Zero Configuration (UDP Auto-Discovery): Stop running ifconfig or searching for IP addresses. ycis-file broadcasts its presence on port 41234 so peers find each other instantly.
• 📦 On-the-Fly Directory Streaming: Select an entire folder. It gets tarred, gzipped, and streamed over the network in real-time, extracting on the receiver automatically. Zero disk overhead or pre-compression wait time.
• 🔗 QR Code & Web Sharing: Need to get a file to your phone? Start a link share. The tool spins up a temporary web server and outputs a clean, responsive landing page URL alongside a terminal QR code.
• 🎨 Minimalist Monochrome TUI: Styled with a minimal, high-contrast, premium black-and-white visual aesthetic that fits clean terminal setups.
• 🌐 NAT / AP Isolation Bypass: If your router blocks direct LAN connections (common on public/office Wi-Fi), switch to WebSocket Relay mode to transfer files securely using a lightweight relay.
• 🔒 Private & Safe: Direct LAN transfers happen strictly between your devices. No data touches the cloud.

📊 Comparison at a Glance

| Feature | ycis-file | AirDrop | LocalSend | SCP / SFTP | Magic Wormhole | | :--- | :--- | :--- | :--- | :--- | :--- | | CLI-First | Yes | No | No | Yes | Yes | | Zero Setup | Yes | Yes | Yes | No (requires keys/auth) | Yes | | Cross-Platform| Yes | Apple only | Yes | Yes | Yes | | LAN-Only P2P| Yes | Yes | Yes | Yes | No (relays via WAN) | | Share to Mobile| Yes (QR/Web) | No | No | No | No | | Auto-Discovery| Yes (UDP) | Yes | Yes | No | No |

🚀 Installation

Install globally via npm:

npm install -g ycis-file

[!NOTE] Requires Node.js >= 18.0.0. If you are running Termux on Android, make sure to grant storage permissions with termux-setup-storage.

📖 Interactive Interface

Simply run ycis-file to open the main menu:

ycis-file

On your first run, a setup wizard will help you configure your username and default download folder.

📤 Sending Files & Directories

1. Run ycis-file and choose Send Files.
2. Navigate your folders using the built-in TUI explorer. Press Space to select files/folders and Enter to confirm.
3. Select Discover devices to search the LAN, or enter a target IP manually.
4. Input the 4-digit security PIN displayed on the receiver's screen to authenticate and start the stream.

📥 Receiving Files

1. Run ycis-file and choose Receive Files.
2. Select Local Network (LAN) mode.
3. Share your displayed 4-digit OTP PIN with the sender.
4. Watch the progress bar as files stream directly into your download directory.

🔗 Sharing via Browser Link (for Phones/Tablets)

1. Run ycis-file and choose Create Link.
2. Pick the file or folder you want to share.
3. Scan the terminal-rendered QR code with your phone or tablet's camera, or copy-paste the URL.
4. Download the file instantly through a beautiful, web-browser landing page.

⚙️ Configuration

Settings are saved locally in ~/.ycis-file/config.json:

{
  "username": "developer",
  "downloadDir": "/home/user/Downloads",
  "port": 24816,
  "deviceId": "a1b2c3d4e5"
}

• username: The nickname visible to other peers during discovery.
• downloadDir: The absolute path where incoming transfers are saved.
• port: The starting port for local HTTP receiver servers (Default: 24816).
• deviceId: A randomly generated UUID used to identify your device during UDP discovery.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

If you find this project helpful, please consider giving it a ⭐ to help others discover it!

License: MIT