Surge Downloader Junaid Islam

cli download-manager downloader go golang terminal tui

Use this command to install Surge Downloader:

winget install --id=surge-downloader.surge -e

Surge is a blazing fast, open-source terminal (TUI) download manager built in Go.

Surge

Blazing fast TUI download manager built in Go for power users

Installation • Usage • Benchmarks • Extension • Settings • CLI Reference

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.

Surge Demo

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:

Blazing Fast: Designed to maximize your bandwidth utilization and download files as quickly as possible.
Multiple Mirrors: Download from multiple sources simultaneously. Surge distributes workers across all available mirrors and automatically handles failover.
Sequential Download: Option to download files in strict order (Streaming Mode). Ideal for media files that you want to preview while downloading.
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.

For a deep dive into how we make downloads faster (like work stealing and slow worker handling), check out our Optimization Guide.

Support the Project

We are just two CS students building Surge in between classes and exams. We love working on this, but maintaining a project of this scale takes time and resources. That's where you come in!

If Surge saves you time, consider supporting the development! Donations go directly toward:

Publishing the Extension: Paying the Chrome Web Store fee so you can finally install the extension officially (no more sideloading!).
Dev Tools: Licenses for tools like GoReleaser Pro to help us automate our builds.
Debrid Integration: Covering subscription costs so we can test and build native Debrid support.

☕ Buy us a coffee

Totally optional—your stars, issues, and contributions already mean the world to us! :)

Installation

Surge is available on multiple platforms. Choose the method that works best for you.

Platform / Method	Command / Instructions	Notes
Prebuilt Binary	Download from Releases	Easiest method. Just download and run.
Arch Linux (AUR)	`yay -S surge`	Managed via AUR.
macOS / Linux (Homebrew)	`brew install surge-downloader/tap/surge`	Recommended for Mac/Linux users.
Windows (Winget)	`winget install surge-downloader.surge`	Recommended for Windows users.
Dockerfile	See instructions	Run Surge in server mode with Docker Compose
Go Install	`go install github.com/surge-downloader/surge@latest`	Requires Go 1.21+.

Usage

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

For a full reference, see the Settings & Configuration Guide and the CLI Usage Guide.

1. Interactive TUI Mode

Just run surge to enter the dashboard. This is where you can visualize progress, manage the queue, and see 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

2. Server Mode (Headless)

Great for servers, Raspberry Pis, or background processes.

# Start the server
surge server

# Start the server with a download
surge server https://url.com/file.zip

# Start with explicit API token
surge server --token

surge and surge server bind the HTTP API to 0.0.0.0 (all interfaces) by default. This means the server is accessible via localhost (127.0.0.1) as well as your local network IP.

The API is token-protected. Generate/read your token by running:

surge token

3. Remote TUI

Connect to a running Surge daemon (local or remote).

# Connect to local server (auto-detected)
surge connect

# Connect to a remote daemon
surge connect 192.168.1.10:1700 --token 

# Equivalent global-flag form
surge --host 192.168.1.10:1700 --token

By default, surge connect uses:

http:// for loopback and private IP targets
https:// for public/hostname targets

4. Global Connection Flags (CLI + TUI)

These global flags are available on all commands:

--host : target server for TUI and CLI operations.
--token : bearer token for authentication.

Environment variable fallbacks:

SURGE_HOST
SURGE_TOKEN

5. Server Mode with Docker Compose

Download the compose file and start the container:

wget https://raw.githubusercontent.com/surge-downloader/surge/refs/heads/main/docker/compose.yml
docker compose up -d

Get the API token:

docker compose exec surge surge token

Save this token - you'll need it to authenticate API requests and connect remotely.

Check downloads/API availability:

docker compose exec surge surge ls

View logs:

docker compose logs -f surge

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. It communicates with the Surge client on port 1700 by default.

Chrome / Edge / Brave

Clone or download this repository.
Open your browser and navigate to chrome://extensions.
Enable "Developer mode" in the top right corner.
Click "Load unpacked".
Select the extension-chrome folder from the surge directory.

Firefox

Stable: Get the Add-on
Development:
- Navigate to about:debugging#/runtime/this-firefox.
- Click "Load Temporary Add-on...".
- Select the manifest.json file inside the extension-firefox folder.

Community & Contributing

We love community contributions! Whether it's a bug fix, a new feature, or just cleaning up typos. PRs are always welcome. For a quick guide, see CONTRIBUTING.md.

You can check out the Discussions for any questions or ideas, or follow us on X (Twitter)!

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!