Skip to main content
The main surge command launches the Terminal User Interface (TUI) and optionally queues downloads. When a Surge instance is already running, it will show an error and suggest using surge add instead.

​
Usage

surge [url]...

​
Description

Launches Surge in TUI mode with an embedded HTTP server for browser extension integration. The command:
  • Starts the interactive Terminal User Interface
  • Binds an HTTP API server on the specified port (or auto-selects one)
  • Queues any URLs provided as arguments
  • Can resume paused downloads from previous sessions (unless --no-resume is set)
  • Runs startup integrity check to validate database and state files
Only one Surge instance can run at a time. If already running, use surge add to queue additional downloads.

​
Arguments

​
url
string
One or more URLs to download. URLs can include mirrors using comma separation.Multiple URLs can be provided:
surge https://example.com/file1.zip https://example.com/file2.zip

​
Flags

​
--batch
string
default:""
Path to a file containing URLs to download (one per line).Short form: -bExample:
surge --batch urls.txt
​
--port
integer
default:"0"
Port to listen on for HTTP API server. If not specified or set to 0, automatically finds an available port starting from 1700.Short form: -pExample:
surge --port 8080
​
--output
string
default:""
Default output directory for downloads. If not specified, uses the configured default download directory from settings.Short form: -oExample:
surge --output ~/Downloads
​
--no-resume
boolean
default:"false"
Do not automatically resume paused downloads from previous sessions on startup.Example:
surge --no-resume
​
--exit-when-done
boolean
default:"false"
Exit the TUI automatically when all downloads complete. Useful for scripting.Example:
surge --exit-when-done --batch downloads.txt

​
Examples

​
Basic Usage

Launch TUI with a single download: 
surge https://releases.ubuntu.com/22.04/ubuntu-22.04-desktop-amd64.iso

​
Batch Downloads

Queue multiple downloads from a file: 
surge --batch urls.txt --output ~/Downloads
With urls.txt containing: 
https://example.com/file1.zip
https://example.com/file2.tar.gz
https://example.com/file3.iso

​
With Mirrors

Provide mirror URLs (comma-separated): 
surge "https://mirror1.com/file.zip,https://mirror2.com/file.zip"

​
Custom Port

Run on a specific port: 
surge --port 1700

​
Script Integration

Exit automatically when complete: 
surge --batch downloads.txt --exit-when-done --no-resume

​
Startup Behavior

​
Integrity Check

On startup, Surge performs an integrity check that:
  • Validates paused/queued download metadata
  • Removes entries with missing or corrupted .surge state files
  • Cleans orphaned state files without database entries

​
Auto-Resume

By default, Surge automatically resumes:
  • Downloads in “queued” state
  • Downloads in “paused” state (if AutoResume setting is enabled)
Use --no-resume to disable this behavior.

​
Lock File

Surge uses a lock file to prevent multiple instances. The lock is stored in the runtime directory and automatically released on exit.

​
Remote Mode

When --host is specified, surge operates in remote TUI mode: 
surge --host 127.0.0.1:1700
In remote mode, URLs cannot be passed as arguments. Use surge add after connecting.