Get started with Surge
This guide gets a download running, then helps you choose whether the interactive TUI, a headless server, or a system service is the right fit.
Install Surge
Section titled “Install Surge”Use the package manager or release artifact that suits your platform:
| Platform | Command or source |
|---|---|
| Windows | winget install surge-downloader.surge, scoop install surge, or choco install surge |
| macOS / Linux | brew install SurgeDM/tap/surge |
| Arch Linux | yay -S surge |
| Nix / NixOS | nix run github:SurgeDM/Surge |
| Linux / macOS (no package manager) | curl -fsSL https://surgedm.github.io/install | sh |
| Any supported platform | Download a release |
The install script detects your OS and architecture (including Linux ARM64,
e.g. Alpine/postmarketOS), downloads the matching release asset, verifies its
checksum, installs the binary to ~/.local/bin (override with
SURGE_INSTALL_DIR), and sets up shell completion for zsh/bash/fish.
Run the same command again to update an existing installation; it reports the
installed and target versions before replacing the binary.
Run surge --version after installing to confirm that your shell can find the
binary.
Make your first download
Section titled “Make your first download”Pass a URL to surge to open the TUI with that download queued:
surge https://example.com/archive.zipBy default, the file is saved in the directory from which you ran the command.
Use --output to choose a destination:
surge https://example.com/archive.zip --output ~/DownloadsOn Windows, use a PowerShell path such as --output "$HOME\\Downloads".
Choose a mode
Section titled “Choose a mode”Use the TUI when you want to watch and manage downloads in a terminal:
surgeUse the headless server for a machine without an interactive terminal, or when commands and the browser extension should control a single background download manager:
surge serverUse a system service when the server should start with the machine:
surge service installsurge service startSee TUI, server, and remote modes for the differences and Run Surge as a service before installing a service.