Skip to main content
The add command queues one or more downloads to a running Surge instance. It requires an active Surge server or TUI to be running.

​
Usage

surge add [url]...

​
Aliases

  • get
surge get https://example.com/file.zip

​
Description

Adds new downloads to the queue of a running Surge instance. The command:
  • Connects to the local or remote Surge server via HTTP API
  • Sends download requests with optional output directory
  • Supports batch file input for multiple URLs
  • Auto-detects the running server port from the runtime directory
  • Returns success count for queued downloads
This command requires a running Surge instance. Start one with surge or surge server first.

​
Arguments

​
url
string
One or more URLs to download. Can include mirror URLs separated by commas.Examples:
surge add https://example.com/file.zip
surge add https://example.com/file1.zip https://example.com/file2.tar.gz

​
Flags

​
--batch
string
default:""
Path to a file containing URLs to download (one per line).Short form: -bExample:
surge add --batch downloads.txt
​
--output
string
default:""
Output directory for the downloads. If not specified, uses the server’s configured default download directory.Short form: -oExample:
surge add --output ~/Downloads https://example.com/file.zip

​
Examples

​
Add Single Download

surge add https://releases.ubuntu.com/22.04/ubuntu-22.04-desktop-amd64.iso
Output: 
Successfully added 1 downloads.

​
Add Multiple Downloads

surge add https://example.com/file1.zip https://example.com/file2.tar.gz
Output: 
Successfully added 2 downloads.

​
Add from Batch File

Create a file urls.txt: 
https://example.com/file1.zip
https://example.com/file2.tar.gz
https://example.com/file3.iso
Then run: 
surge add --batch urls.txt
Output: 
Successfully added 3 downloads.

​
Specify Output Directory

surge add --output /data/downloads https://example.com/file.zip

​
Add with Mirrors

Provide mirror URLs separated by commas: 
surge add "https://mirror1.com/file.zip,https://mirror2.com/file.zip,https://mirror3.com/file.zip"
Surge will automatically try mirrors if the primary URL fails.

​
Using Alias

surge get https://example.com/file.zip

​
Batch File Format

Batch files should contain one URL per line: 
https://example.com/file1.zip
https://example.com/file2.tar.gz

# Comments and empty lines are ignored
https://example.com/file3.iso
Mirrors can be specified in batch files: 
https://mirror1.com/file.zip,https://mirror2.com/file.zip
https://example.com/file2.tar.gz

​
Connection Behavior

​
Auto-Detection

The command automatically detects a running local Surge instance by reading the port from the runtime directory (~/.surge/port or ~/.local/state/surge/port).

​
Remote Servers

To add downloads to a remote server, use the --host flag: 
surge add --host 192.168.1.100:1700 https://example.com/file.zip
Or set the SURGE_HOST environment variable: 
export SURGE_HOST=192.168.1.100:1700
surge add https://example.com/file.zip

​
Authentication

For remote servers, you may need to provide a token: 
surge add --host 192.168.1.100:1700 --token <token> https://example.com/file.zip
Or use the SURGE_TOKEN environment variable: 
export SURGE_TOKEN=your-token-here
surge add --host 192.168.1.100:1700 https://example.com/file.zip
Use surge token to retrieve the authentication token from a running instance.

​
Error Handling

If no Surge instance is running: 
Error: No running Surge server found.
If a URL fails to queue: 
Error adding https://example.com/file.zip: connection refused
Successfully added 2 downloads.
The command reports individual failures but continues processing remaining URLs.