https://github.com/surge-downloader/surge
Blazing fast TUI download manager built in Go for power users
https://github.com/surge-downloader/surge
cli download-manager downloader go golang hacktoberfest poweruser terminal tui
Last synced: 2 months ago
JSON representation
Blazing fast TUI download manager built in Go for power users
- Host: GitHub
- URL: https://github.com/surge-downloader/surge
- Owner: surge-downloader
- License: mit
- Created: 2025-10-29T05:00:15.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-03-29T04:40:56.000Z (3 months ago)
- Last Synced: 2026-03-29T07:28:19.073Z (3 months ago)
- Topics: cli, download-manager, downloader, go, golang, hacktoberfest, poweruser, terminal, tui
- Language: Go
- Homepage:
- Size: 28.6 MB
- Stars: 2,617
- Watchers: 12
- Forks: 104
- Open Issues: 31
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-tuis - surge
README
# Surge
**Blazing fast TUI download manager built in Go for power users**
[](https://deepwiki.com/surge-downloader/surge)
[](https://github.com/surge-downloader/surge/releases)
[](go.mod)
[](LICENSE)
[](https://www.buymeacoffee.com/surge.downloader)
[](https://github.com/surge-downloader/surge/stargazers)
[Installation](#installation) • [Usage](#usage) • [Fonts](docs/FONTS.md) • [Benchmarks](#benchmarks) • [Extension](#browser-extension) • [Settings](docs/SETTINGS.md) • [CLI Reference](docs/USAGE.md)
---
## 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:
- **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](docs/OPTIMIZATIONS.md)**.
---
## 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**](https://www.buymeacoffee.com/surge.downloader)
_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](https://github.com/surge-downloader/surge/releases/latest) | 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 install surge-downloader.surge`
or
`scoop install surge` | Recommended for Windows users. |
| **Dockerfile** | [See instructions](#4-server-mode-with-docker-compose) | Run Surge in server mode with Docker Compose |
| **Go Install** | `go install github.com/surge-downloader/surge@latest` | Requires Go 1.25+ |
---
## Usage
Surge has two main modes: **TUI (Interactive)** and **Server (Headless)**.
For a full reference, see the **[Settings & Configuration Guide](docs/SETTINGS.md)** and the **[CLI Usage Guide](docs/USAGE.md)**.
### 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.
```bash
# 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.
```bash
# 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:
```bash
surge token
```
### 3. Remote TUI
Connect to a running Surge daemon (local or remote).
```bash
# 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:
```bash
wget https://raw.githubusercontent.com/surge-downloader/surge/refs/heads/main/docker/compose.yml
docker compose up -d
```
Get the API token:
```bash
docker compose exec surge surge token
```
Save this token - you'll need it to authenticate API requests and connect remotely.
Check downloads/API availability:
```bash
docker compose exec surge surge ls
```
View logs:
```bash
docker compose logs -f surge
```
---
## Fonts
Surge ships a bundled Nerd Font for the TUI, but your terminal controls the
actual font selection. See [docs/FONTS.md](docs/FONTS.md) for install steps and
licensing details.
---
## 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
1. Download `extension-chrome.zip` from the latest GitHub release.
2. Unzip it somewhere on disk.
3. Open your browser and navigate to `chrome://extensions`.
4. Enable **"Developer mode"** in the top right corner.
5. Click **"Load unpacked"**.
6. Select the unzipped `extension-chrome` folder.
### Firefox
1. **Stable:** [Get the Add-on](https://addons.mozilla.org/en-US/firefox/addon/surge/)
2. **Development:**
- Download `extension-firefox.zip` from the latest GitHub release.
- Navigate to `about:debugging#/runtime/this-firefox`.
- Click **"Load Temporary Add-on..."**.
- Select the zip file (or unzip and select `manifest.json`).
---
## Acknowledgements
Huge thanks to the teams and sponsors helping us build and ship Surge:
- [Charm](https://charm.sh/) for the incredible terminal UI ecosystem (Bubble Tea, Lip Gloss, and more).
- [GoReleaser Pro](https://goreleaser.com/pro/) for release automation (provided free for open source).
---
## 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](CONTRIBUTING.md).
You can check out the [Discussions](https://github.com/surge-downloader/surge/discussions) for any questions or ideas, or follow us on [X (Twitter)](https://x.com/SurgeDownloader)!
## License
Distributed under the MIT License. See [LICENSE](https://github.com/surge-downloader/surge/blob/main/LICENSE) for more information.
---
If Surge saved you some time, consider giving it a ⭐ to help others find it!