Skip to main content

​
Quickstart Guide

This guide will walk you through downloading your first file with Surge in under 5 minutes.

​
Your First Download

1

Launch the TUI

Simply run surge to enter the interactive Terminal User Interface:
surge
You’ll see the Surge dashboard with a beautiful interface showing your download queue, progress, and speed graphs.
Surge automatically starts an HTTP API server on port 1700 (or the next available port) for browser extension integration and remote control.
2

Add a Download

There are several ways to add downloads:Method 1: Start with URLs (Recommended)Queue downloads directly when launching:
surge https://example.com/file1.zip https://example.com/file2.zip
Method 2: Use a Batch FileCreate a text file with URLs (one per line):
# urls.txt
https://example.com/file1.zip
https://example.com/file2.zip
https://example.com/file3.zip
Then run:
surge --batch urls.txt
Method 3: Combine Both
surge https://example.com/file.zip --batch urls.txt
Surge will automatically start downloading files in parallel based on your configured MaxConcurrentDownloads setting.
3

Specify Output Directory

Control where files are downloaded:
surge https://example.com/file.zip --output ~/Downloads
Or set a default download directory in your settings file at ~/.config/surge/settings.json:
{
  "default_download_dir": "/home/user/Downloads"
}
4

Monitor Progress

The TUI shows real-time information:
  • Download progress with percentage and speed
  • Active workers downloading chunks in parallel
  • Speed graphs showing bandwidth utilization
  • Queue status for pending downloads
Navigate using keyboard shortcuts:
  • ↑/↓ - Navigate downloads
  • p - Pause/Resume selected download
  • d - Delete download
  • q - Quit
5

Wait for Completion

Surge will download your file using multiple parallel connections. When complete, you’ll see a success message.Want to exit automatically when done?
surge https://example.com/file.zip --exit-when-done

​
Advanced Usage

​
Download with Multiple Mirrors

Speed up downloads by using multiple mirrors simultaneously: 
surge "https://mirror1.com/file.zip,https://mirror2.com/file.zip,https://mirror3.com/file.zip"
Surge distributes workers across all available mirrors and automatically handles failover if a mirror becomes unavailable.

​
Server Mode (Headless)

Run Surge in the background without the TUI—great for servers or Raspberry Pi:
1

Start the Server

surge server
Or start with a download:
surge server https://example.com/file.zip
2

Get Your API Token

In another terminal:
surge token
Save this token—you’ll need it for CLI commands and API requests.
3

Add Downloads via CLI

Add downloads to the running server:
surge add https://example.com/file.zip
4

Check Status

List all downloads:
surge ls
The server binds to 0.0.0.0 by default, making it accessible via localhost and your local network IP.

​
Remote TUI

Connect to a running Surge daemon from another terminal or machine: 
# Connect to local server (auto-detected)
surge connect
By default, surge connect uses http:// for loopback and private IP targets, and https:// for public/hostname targets.

​
Resume Interrupted Downloads

Surge automatically saves download state. If interrupted: 
# Surge auto-resumes paused downloads on startup by default
surge

# Disable auto-resume
surge --no-resume

​
Browser Extension Integration

Intercept browser downloads and send them straight to Surge:
1

Ensure Surge is Running

Start Surge in TUI or server mode:
surge
2

Install the Extension

Chrome/Edge/Brave:
  1. Clone the Surge repository
  2. Navigate to chrome://extensions
  3. Enable “Developer mode”
  4. Click “Load unpacked”
  5. Select the extension-chrome folder
Firefox:
  • Stable: Get the Add-on
  • Development: Load manifest.json from extension-firefox folder via about:debugging
3

Start Downloading

Click any download link in your browser—Surge will automatically intercept it and handle the download!
The extension communicates with Surge on port 1700 by default.

​
Common Operations

​
Global Flags

These flags work with all commands: 
# Connect to a specific server
surge --host 192.168.1.10:1700 --token <token> ls

# Enable verbose logging
surge --verbose

# Specify output directory
surge --output ~/Downloads https://example.com/file.zip

​
CLI Commands Quick Reference

surge

​
Next Steps

CLI Reference

Explore all available commands, flags, and options.

Settings Guide

Configure Surge to match your preferences.

API Reference

Integrate Surge with your automation workflows.

Optimizations

Learn how Surge achieves blazing fast speeds.
Surge runs a single background “engine.” If you try to start Surge while it’s already running, you’ll get an error. Use surge add <url> to add downloads to the active instance instead.