Surge: a Go TUI download manager with a headless daemon and CLI

What Surge actually solves, and for whom

A browser opens one connection per download. Surge opens several, splits the file into chunks, and pulls them in parallel. The README puts the default ceiling at 16 connections. That is the whole pitch in one sentence, and it is a real difference for large files on a fast link where a single TCP stream cannot fill the pipe.

The second problem is process sprawl. Surge runs one background engine, and the README describes the intent plainly: open ten terminal tabs, queue downloads in each, and they all funnel into the same manager. A lock file dependency (gofrs/flock) in go.mod is consistent with that single-instance design.

The audience is narrow and the README says so: power users who prefer a keyboard-driven workflow. If you want a tray icon and a progress bar in your browser, this is not aimed at you. The project is maintained by two computer science students, according to the README, which is worth knowing before you put it on a production box.

The daemon, the TUI and the HTTP API between them

There are two run modes. `surge` starts the interactive dashboard. `surge server` starts a headless process for servers, Raspberry Pis, or background work. Both bind an HTTP API to 0.0.0.0 by default, so the same instance is reachable on localhost and on your LAN address.

The API is token-protected. `surge token` prints the standard token, and `surge service token` prints the one used when Surge runs as a system service. The TUI also exposes it under Settings > Extension. Remote clients use that token to attach to a running daemon with `surge con`.

The TUI itself is built on Bubble Tea and Lipgloss, with a theme engine and customizable palettes. Two details in the README are more interesting than the theming. Pressing Shift + A, or using the terminal paste shortcut, parses a copied browser cURL command into a new download. Pressing ? opens a bug reporting wizard. The cURL parsing is the pragmatic answer to the missing extension: you copy the request from devtools instead of clicking a button.

The dependency list backs up the architecture claims. Cobra handles the CLI surface, kardianos/service handles daemon installation across platforms, go-toml/v2 handles configuration, and h2non/filetype inspects downloaded content. Nothing here is exotic, which is a point in its favour for anyone auditing the supply chain.

Installing Surge and queuing a first download

The README lists a prebuilt binary, an AppImage, AUR, Homebrew, Nix, winget, scoop, Docker Compose, and `go install`. Homebrew is described as the recommended route for macOS and Linux. On Windows, winget or scoop are recommended.

brew install SurgeDM/tap/surge

That installs the `surge` binary. Running it with no arguments drops you into the dashboard.

surge

You should see the TUI dashboard with the queue, progress and speed graphs. From here you can paste URLs, or press Shift + A to parse a cURL command from your clipboard.

You can also hand it work at launch, either as bare URLs or from a batch file:

surge https://example.com/file1.zip https://example.com/file2.zip
surge https://example.com/file.zip --batch urls.txt

If you want the TUI without the embedded HTTP API, pass `--no-server`. The README is explicit about the consequence: `surge add`, `surge pause` and browser-extension requests will not be able to target that instance. That is a deliberate trade, not a bug, but it will surprise you the first time a CLI command silently has nowhere to go.

For a machine that should keep downloading after you close the terminal, install it as a service:

surge service install
surge service start
surge service status

On Linux these may need `sudo`; on Windows they should run in an elevated terminal. The README does not document rollback beyond `surge service uninstall`.

Where Surge gets in your way

The default bind address is the sharpest edge. `surge` and `surge server` listen on 0.0.0.0, not 127.0.0.1. On a laptop on a coffee shop network, that means the API is reachable by anything on the same network. The token protects it, and the README does not describe a flag for narrowing the bind address. If you want loopback-only, you are relying on a host firewall.

The second limitation is the extension. The README asks for donations partly to pay the Chrome Web Store fee so the extension can be installed officially, with the phrase "no more sideloading" attached. Read that as it is written: the browser extension is not currently a one-click install from the store. If browser integration is your primary reason for choosing a download manager, this is the wrong tool today.

Third, `--no-server` disables the API, which disables CLI control and extension requests for that instance. There is no documented middle ground where the TUI is local but the API is reachable only from the same user account.

Finally, the project is a two-person effort run between classes. The README says so without hedging. That is not a reason to avoid it, but it is a reason to check the release cadence yourself before you depend on it.

How Surge differs from aria2 and wget

aria2 is the obvious comparison. It is a mature, widely packaged download utility with an RPC interface, and it also does segmented downloads and multiple sources. The difference in approach is the interface layer. aria2 gives you a config file and an RPC endpoint; you bring your own frontend, or use one of the many third-party ones. Surge ships the frontend as part of the binary: a Bubble Tea TUI, a theme engine, a settings file in TOML, and a `surge service` subcommand that installs the daemon for you.

That is a real trade. You get a coherent experience out of the box, and you give up the decades of packaging, documentation and third-party tooling around aria2. If you need a download manager that is already in your distribution's main repository and has a decade of Stack Overflow answers behind it, aria2 is the safer pick.

wget and curl are not really competitors here. They are single-stream by default and have no queue, no daemon and no progress dashboard. Surge is a different category of tool: something you leave running.

The mirror failover is where Surge makes a claim worth testing. The README says workers are distributed across all available mirrors and failover is automatic, and points to docs/OPTIMIZATIONS.md for the work-stealing and slow-worker handling. That document is the place to look before you trust the claim, because the README does not quantify it.

Maintenance, upgrades and what the MIT licence means here

The repository is not archived. The last push was on 2026-08-26, which is recent. Releases v0.12.1, v0.12.0 and ext-v2.1.2 all landed within a week of each other in August 2026, so the version numbering is still moving in the 0.x range. Expect breaking changes between minor versions until 1.0, and read the release notes before upgrading a service you depend on.

The AppImage path supports delta updates according to the README, which reduces the download size on each upgrade. Homebrew, winget and scoop users get whatever their package manager does. There is no documented migration step between versions, so the practical upgrade procedure is: stop the service, replace the binary, start the service, and check that your queue survived.

Surge is MIT licensed. That is permissive: you can use it commercially, modify it, and redistribute it, provided you keep the copyright notice and licence text. It comes with no warranty, which matters more than usual for a tool that runs as a background service with a network-facing API. Nothing in the repository suggests any additional restriction, but if you are bundling Surge into a product, read the LICENSE file yourself rather than relying on this summary.

Editorial conclusion

Adopt Surge if you already live in a terminal, want one background engine that several shells can queue work into, and are comfortable running a service that binds its HTTP API to 0.0.0.0 by default. Skip it if you need a browser extension that installs from the Chrome Web Store without sideloading, or if you want a GUI. Before committing, verify three things on your own machine: that `surge service install` works on your init system, that the token from `surge token` is reachable from the clients you plan to use, and that a multi-mirror download actually fails over the way the README describes when one mirror dies.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes