Skip to main content
Surge is designed to integrate seamlessly into automated workflows, supporting batch processing, exit-on-completion, and machine-readable JSON output.

​
Exit When Done

The --exit-when-done flag makes Surge automatically exit when all downloads complete, perfect for scripts and automation. 
# Download a file and exit when complete
surge server https://example.com/file.zip --exit-when-done
The --exit-when-done flag works with both surge (TUI mode) and surge server (headless mode).

​
Batch File Processing

Surge can process multiple URLs from a file using the --batch (or -b) flag.

​
Batch File Format

Create a text file with one URL per line:
urls.txt
https://example.com/file1.zip
https://example.com/file2.tar.gz
https://example.com/archive.iso

# Comments are supported
https://example.com/document.pdf

# Inline comments work too
https://example.com/video.mp4  # Downloaded last
Batch files support:
  • One URL per line
  • Multiple URLs per line (whitespace-separated)
  • Comments using #
  • Blank lines (ignored)
  • Inline comments

​
Using Batch Files

# Start server and process batch file
surge server --batch urls.txt --exit-when-done

​
JSON Output for Parsing

The ls command supports --json flag for machine-readable output, perfect for scripts and automation.

​
List All Downloads

surge ls --json

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "filename": "ubuntu-22.04.iso",
    "status": "downloading",
    "progress": 45.2,
    "total_size": 4294967296,
    "downloaded": 1941160550,
    "speed": 12.5
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "filename": "archive.zip",
    "status": "completed",
    "progress": 100.0,
    "total_size": 1073741824,
    "downloaded": 1073741824,
    "speed": 0
  },
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "filename": "document.pdf",
    "status": "paused",
    "progress": 23.8,
    "total_size": 52428800,
    "downloaded": 12483763,
    "speed": 0
  }
]

​
Get Specific Download Details

# Full ID or prefix (minimum 8 characters)
surge ls a1b2c3d4 --json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://releases.ubuntu.com/22.04/ubuntu-22.04-desktop-amd64.iso",
  "filename": "ubuntu-22.04-desktop-amd64.iso",
  "status": "downloading",
  "progress": 45.2,
  "total_size": 4294967296,
  "downloaded": 1941160550,
  "speed": 12.5
}

​
Scripting Examples

​
Monitor Download Progress

#!/bin/bash
# Monitor download completion

while true; do
  status=$(surge ls --json | jq -r '.[0].status')
  progress=$(surge ls --json | jq -r '.[0].progress')
  
  echo "Status: $status, Progress: $progress%"
  
  if [ "$status" = "completed" ]; then
    echo "Download finished!"
    break
  fi
  
  sleep 5
done

​
Automated Download Workflow

#!/bin/bash
# Complete automated workflow

set -e  # Exit on error

# 1. Start server with batch downloads
echo "Starting Surge server..."
surge server --batch urls.txt --output /downloads --exit-when-done &
SURGE_PID=$!

# 2. Wait for server to start
sleep 2

# 3. Monitor progress
while kill -0 $SURGE_PID 2>/dev/null; do
  downloads=$(surge ls --json)
  active=$(echo "$downloads" | jq '[.[] | select(.status == "downloading")] | length')
  echo "Active downloads: $active"
  sleep 10
done

echo "All downloads completed!"

# 4. Post-process downloaded files
for file in /downloads/*; do
  echo "Processing: $file"
  # Add your post-processing here
done
When using automation, always handle cleanup properly:
  • Use --exit-when-done for automatic termination
  • Trap signals to ensure graceful shutdown
  • Monitor process status before assuming completion

​
Remote Automation

Automate downloads on remote servers using the --host and --token flags.
1

Get the server token

# On the server
surge token
2

Queue downloads remotely

# From your local machine
export SURGE_HOST="192.168.1.10:1700"
export SURGE_TOKEN="your-token-here"

surge add --batch urls.txt
3

Monitor remotely

# Check status with JSON output
surge ls --json

# Watch progress in real-time
surge ls --watch

​
Remote Script Example

#!/bin/bash
# Remote download automation

SERVER="192.168.1.10:1700"
TOKEN="your-token-here"

export SURGE_HOST="$SERVER"
export SURGE_TOKEN="$TOKEN"

# Add downloads
echo "Queueing downloads..."
surge add --batch remote-urls.txt

# Monitor until complete
while true; do
  downloading=$(surge ls --json | jq '[.[] | select(.status == "downloading")] | length')
  
  if [ "$downloading" -eq 0 ]; then
    echo "All downloads complete!"
    break
  fi
  
  echo "Active downloads: $downloading"
  sleep 30
done

​
Environment Variables

Surge supports environment variables for automation:
VariableDescriptionExample
SURGE_HOSTDefault server host192.168.1.10:1700
SURGE_TOKENAPI authentication tokenabc123...
Use environment variables instead of command-line flags for cleaner scripts and better security (tokens won’t appear in process lists).

​
Continuous Integration

Example GitHub Actions workflow:
.github/workflows/download.yml
name: Download Files

on:
  workflow_dispatch:
    inputs:
      urls:
        description: 'URLs to download (comma-separated)'
        required: true

jobs:
  download:
    runs-on: ubuntu-latest
    steps:
      - name: Install Surge
        run: |
          wget https://github.com/surge-downloader/surge/releases/latest/download/surge_linux_amd64
          chmod +x surge_linux_amd64
          sudo mv surge_linux_amd64 /usr/local/bin/surge
      
      - name: Download Files
        run: |
          echo "${{ github.event.inputs.urls }}" | tr ',' '\n' > urls.txt
          surge server --batch urls.txt --exit-when-done
      
      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: downloads
          path: ~/Downloads/
The server mode automatically uses ~/Downloads as the default output directory if not specified.