go-drop

A fast, minimal command-line file sharing tool written in Go. Serve any file, folder, or text snippet over your local network or expose it to the internet.

This project was mainly a learning experience with Go (and TUI development).

Table of Contents

• Features
• Flags Reference
• Requirements
• Installation
• Directory Tree
• Usage
• Send Mode
• Receive Mode
• Security
• Online Mode
• Known Limitations
• AI Usage
• License

Features

• File Sharing: Serve any file over HTTP/HTTPS directly from your terminal.
• Multi-file & Directory Support: Automatically zip multiple files or entire directories before serving.
• Text Sharing: Share a text snippet as a .txt file without creating one manually.
• Receive Mode: Accept file uploads from other devices through an upload page.
• QR Code: Generates a QR code in the terminal so, for example, phones can scan it.
• HTTPS: Generates a self-signed certificate, with fingerprint shown for verification.
• Online Mode: Exposes your local server to the internet via a localhost.run SSH tunnel.
• Password Protection: Optionally require a password before a file can be downloaded.
• Download Limit: Automatically shut down the server after a set number of downloads.
• Per-IP Restriction: Limit downloads to one per IP address.
• Timeout: Shutdown after a configurable number of seconds.
• Custom Filename: Override the name of the file.
• File Preview: Browser page previews images, text files, and PDFs before download.
• Dark Mode: Web UI respects the system's color scheme preference.
• Live Terminal UI: Real-time transfer status, event log, and progress bar powered by Bubbletea.

Flags Reference

Flag	Default	Description
-port	8080	Port to serve on
-downloads	1	Number of downloads before auto shutdown
-noqr	false	Disable QR code display in terminal
-timeout	0	Seconds before auto-shutdown
-password	``	Require a password to download
-onceip	false	Allow only one download per IP address
-receive	false	Switch to receive mode (accept uploads)
-savedir	.	Directory to save received files into
-https	false	Enable HTTPS with a self-signed certificate
-online	false	Expose via localhost.run tunnel
-name	``	Custom filename shown to the downloader
-text	``	Share a text string as a .txt file
-version	false	Print version

Requirements

• Go: 1.26
• SSH client: Required only for --online mode (tunnel via localhost.run)
• Clipboard tools (Linux): xclip or xsel for automatic clipboard copy

Installation

Download (recommended)

Download the latest binary for your platform from the Releases page.

Linux: extract and install:

tar -xzf go-drop-*.tar.gz
chmod +x go-drop
sudo mv go-drop /usr/local/bin/

Windows: extract the .zip and add the folder to your PATH.

Build from source

git clone https://github.com/artur3333/go-drop.git
cd go-drop
go build -o go-drop .

Or run directly:

go run . [flags] <file>

Directory Tree

go-drop/
├── main.go       # Core logic and entry point
├── tls.go        # Self-signed TLS certificate generation
├── tunnel.go     # localhost.run SSH tunnel
├── ui.go         # Bubbletea terminal UI
├── web.go        # HTML pages served to the browser (download, upload, password)
├── go.mod        # Module definition and dependencies
└── go.sum        # Dependency checksums

Usage

Send Mode

Share a single file:

go-drop photo.jpg

Share multiple files (automatically zipped):

go-drop file1.txt file2.pdf file3.png

Share an entire directory (automatically zipped):

go-drop ./my-project/

Share a text snippet:

go-drop -text "bakaaa"

Set a download limit and password:

go-drop -downloads 3 -password 12345 report.pdf

Use HTTPS with certificate:

go-drop -https document.pdf

Use a custom filename:

go-drop -name "release-v2" ./build/

Expose to the internet via tunnel:

go-drop -online photo.jpg

Set a timeout (auto-quit after 60 seconds in this example):

go-drop -timeout 60 notes.txt

Receive Mode

Accept a file upload into the current directory:

go-drop -receive

Accept uploads into a specific folder:

go-drop -receive -savedir "C:\Users\user\Downloads"

Receive with online access:

go-drop -receive -online

When in receive mode, go-drop spins up an upload page. Any device on the network can navigate to the displayed URL, select a file, and send it. Received files are automatically renamed if a conflict exists.

Security

HTTPS

Running with --https generates a self-signed certificate valid for 24 hours. The SHA-256 fingerprint of the certificate is displayed in the terminal so the receiver can verify their connection manually.

TLS: HTTPS
Certificate: 4A:B2:... (SHA-256 fingerprint)

Note: --https and --online cannot be used together. The localhost.run tunnel already provides HTTPS termination.

Online Mode

go-drop can punch through your local network by tunneling over SSH to localhost.run.

go-drop --online file.zip

Once the tunnel is established, a public https:// URL is printed and copied to your clipboard. A QR code is also generated in the terminal.

Online mode requires an SSH client to be installed and accessible as ssh in your PATH.

Important: localhost.run tunnels can be quite slow depending on your connection and their servers. For large files, local network transfers will always be significantly faster. Online mode is best suited for small files or situations where local sharing isn't an option.

Known Limitations

Terminal resize caused visual bugs.

Resizing the terminal while go-drop is running can cause visual glitches in the Bubble Tea UI, such as overlapping text or misplaced elements.

QR code may not display on small terminals.

If the terminal window is too small, go-drop will hide the QR code to prevent display issues. Resize the terminal or copy the URL from the link section.

AI Usage

This project was built as a personal learning experience with Go, and was developed largely independently. AI was mainly used for:

Bubble Tea (TUI)

• The TUI integration in ui.go was one of the hardest parts of the project. AI was consulted to help understand how Bubble Tea's event/message model works, it took a lot amount of timeee.

localhost.run Tunnel

• AI was consulted when evaluating tunneling options. ngrok was initially considered but turned out to be more complex to integrate (auth flow, setup). AI helped confirm that the localhost.run was simpler and more appropriate for this use case.

Bug Fixing and Debugging

• AI was consulted when facing difficult bugs, particularly in:
  • Event handling in the TUI (e.g. ensuring the UI updates correctly on file transfer progress, handling events)
  • Cache control headers and browser caching issues (e.g. ensuring that files are not cached by the browser to prevent bugs)
  • Other bugs occurring during development, since Go is not a language I'm deeply familiar with.

Documentation

• This README was partially generated by AI and then modified to ensure accuracy.

License

This project is licensed under the MIT License. See the LICENSE file for details.