Fling

Fast, Zero-Configuration Peer-to-Peer File Transfer & Messaging for your Terminal.
AirDrop-like simplicity over local networks, built from scratch on raw UDP with a custom reliable ARQ protocol, automatic LAN peer discovery, and a modern Lazygit-style Terminal UI (TUI).

---

Features

• Zero-Config Discovery: Automatically finds active peers on the LAN via UDP subnet broadcast (stale peers pruned after 10s).
• End-to-End Encryption (E2EE): Automatic zero-config X25519 Elliptic Curve Diffie-Hellman (ECDH) key agreement and AES-256-GCM authenticated encryption across all instant messages and file transfers (zero plaintext on wire).
• Custom Reliable UDP Protocol: Stop-and-Wait ARQ, sequence numbers, packet deduplication, and out-of-order chunk reassembly built directly on raw sockets (no TCP/HTTP).
• Consent-First Handshake: Senders request transfer with file metadata; transfers only begin upon recipient confirmation.
• End-to-End CRC32 Integrity: Packets and fully reassembled files are verified with IEEE CRC32 checksums (zero silent corruption).
• Native File Manager Reveal: Press o to immediately highlight received files in macOS Finder, Windows Explorer, or Linux File Managers.
• Direct Encrypted Instant Messaging: Chat directly with any online peer without initiating file transfers.

---

Installation

[!NOTE] Prerequisite: The Go compiler (Go 1.21+) is required to build and install Fling. Download Go from go.dev/dl or install via your package manager (brew install go on macOS, sudo apt install golang on Debian/Ubuntu).

Option 1: One-Line Installer (macOS & Linux)

curl -fsSL https://raw.githubusercontent.com/SatyamKumarCS/Fling-CLI/main/install.sh | bash

Option 2: Go Install

go install github.com/SatyamKumarCS/Fling-CLI/cmd/fling@latest

Option 3: Build from Source

git clone https://github.com/SatyamKumarCS/Fling-CLI.git
cd Fling-CLI
make install

---

Usage

1. Interactive Dashboard (TUI)

Launch the multi-pane interface:

fling

(Tip: use fling --port 9998 to test multiple nodes on the same computer)

Key	Action	Description
Tab / Shift+Tab	Switch Pane	Cycle focus between Peers, Info, Chat, and Transfers
1–4	Jump to Pane	Directly activate Pane 1, 2, 3, or 4
↑ / ↓ or k / j	Select Peer	Highlight a peer in the Discovered Peers list
F / s	Send File	Open file dialog (press Ctrl+O for Finder picker or drag-and-drop)
Enter / c	Chat	Focus Chat pane to type a live message
o / O	Reveal in Finder	Reveal the received file in Finder / File Explorer
y / n	Accept / Decline	Accept or reject incoming transfer requests
r	Scan	Send immediate UDP presence beacon to refresh discovery
?	Help	Toggle keybindings cheat sheet modal
q	Quit	Exit Fling

---

2. Headless CLI Mode

Use Fling in shell scripts or direct terminal commands:

# Discover active peers on your LAN
fling peers

# Send a file (by index, hostname, or IP)
fling send report.pdf --to 1
fling send archive.tar.gz --to Satyam-MacBook.local
fling send photo.png --to 192.168.1.50:9999

# Send a direct instant message
fling msg "Deployment complete on staging server." --to 1

---

Architecture & Security Specification

• System Architecture (HLD & LLD): For the full High-Level Design, Low-Level Design, and component state machines, see docs/architecture.md.
• Wire Protocol RFC Specification: For the 11-byte binary packet wire format, Stop-and-Wait ARQ state machines, and retransmission timing, see docs/protocol.md.
• Security & Cryptography Policy: For the complete End-to-End Encryption (E2EE), threat model, and vulnerability reporting policy, see SECURITY.md.

---

Verification, Updates & Uninstallation

Verify Installation

# Check installed version
fling version

# Check binary path in $PATH
which fling

# View command guide & flags
fling --help

Updating Fling

# Option 1: Native CLI command
fling update

# Option 2: Via updater script
curl -fsSL https://raw.githubusercontent.com/SatyamKumarCS/Fling-CLI/main/update.sh | bash

# Option 3: Via Makefile
make update

Uninstallation

# Option 1: Native CLI command
fling uninstall

# Option 2: Via Makefile
make uninstall

---

Testing

Run the full automated test suite (including 30% simulated packet loss and race detection):

go test -v -race ./...

---

Contributing

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

---

License

MIT License © 2026 Satyam Kumar