surge

README

Surge

Blazing fast, open-source TUI download manager built in Go.

Installation • Usage • Benchmarks • Extension

---

What is Surge?

Surge is designed for power users who prefer a keyboard-driven workflow. It features a beautiful Terminal User Interface (TUI), as well as a background Headless Server and a CLI tool for automation.

Why use Surge?

Most browsers open a single connection for a download. Surge opens multiple (up to 32), splits the file, and downloads chunks in parallel. But we take it a step further:

• Smart "Work Stealing": If a fast worker finishes its chunk, it doesn't sit idle. It "steals" work from slower workers to ensure the download finishes as fast as physics allows.
• Slow Worker Restart: We monitor mean speeds. If a worker is lagging (< 0.3x average), Surge kills it and restarts the connection to find a faster route.
• Daemon Architecture: Surge runs a single background "engine." You can open 10 different terminal tabs and queue downloads; they all funnel into one efficient manager.
• Beautiful TUI: Built with Bubble Tea & Lipgloss, it looks good while it works.

---

Installation

Option 1: Prebuilt Binaries (Easiest)

Download the latest binary for your OS from the Releases Page.

Option 2: Homebrew (macOS/Linux)

brew install surge-downloader/tap/surge

Option 3: Go Install

go install github.com/surge-downloader/surge@latest

Option 4: Build from Source

git clone https://github.com/surge-downloader/surge.git
cd surge
go build -o surge .

---

Usage

Surge has two main modes: TUI (Interactive) and Server (Headless).

1. Interactive TUI Mode

Just run surge to enter the dashboard. This is where you can visualize progress, manage the queue, and see the speed graphs.

# Start the TUI
surge

# Start TUI with downloads queued
surge https://example.com/file1.zip https://example.com/file2.zip

# Combine URLs and batch file
surge https://example.com/file.zip --batch urls.txt

# Start without resuming paused downloads
surge --no-resume

# Auto-exit when all downloads complete
surge https://example.com/file.zip --exit-when-done

2. Server Mode (Headless)

Great for servers, Raspberry Pis, or background processes.

# Start the server
surge server start

# Start on a specific port with options
surge server start --port 8090 --no-resume

# Check server status
surge server status

# Stop the server
surge server stop

3. Command Reference

All other commands can be used to interact with a running Surge instance (TUI or Server).

Command	Alias	Description	Usage Examples
add	get	Add a download to the queue	surge add <url> surge add --batch urls.txt
ls	l	List all downloads	surge ls surge ls --watch surge ls --json
pause	-	Pause a download	surge pause <id> surge pause --all
resume	-	Resume a download	surge resume <id> surge resume --all
rm	kill	Remove/Cancel a download	surge rm <id> surge rm --clean

Note: IDs can be partial (e.g., first 4-8 characters) as long as they are unique.

---

Benchmarks

We tested Surge against standard tools. Because of our connection optimization logic, Surge significantly outperforms single-connection tools.

Tool	Time	Speed	Comparison
Surge	28.93s	35.40 MB/s	—
aria2c	40.04s	25.57 MB/s	1.38× slower
curl	57.57s	17.79 MB/s	1.99× slower
wget	61.81s	16.57 MB/s	2.14× slower

Test details: 1GB file, Windows 11, Ryzen 5 5600X, 360 Mbps Network. Results averaged over 5 runs.

We would love to see you benchmark surge on your system!

---

Browser Extension

The Surge extension intercepts browser downloads and sends them straight to your terminal.

• Chrome / Edge: Enable "Developer Mode" in extensions and load the extension-chrome folder unpacked.
• Firefox: Get the Add-on

---

Community & Contributing

We love community contributions! Whether it's a bug fix, a new feature, or just cleaning up typos.

You can check out the Discussions for any questions or ideas!

License

Distributed under the MIT License. See LICENSE for more information.

---

If Surge saved you some time, consider giving it a ⭐ to help others find it!