Surge

Blazing fast TUI download manager with multi-connection downloads.

When This Skill Activates

This skill triggers when user wants to download files fast with parallel connections or manage downloads via TUI.

Reasoning Framework

Install

# macOS
brew install surge-downloader/tap/surge

# Go
go install github.com/surge-downloader/surge@latest

# Or download binary from releases

Decision Tree

What are you trying to do?

├── Quick single download
│   └── Use: surge add "URL" -o ./folder
│
├── Multiple files (batch)
│   └── Use: surge add -b urls.txt -o ./folder
│
├── Headless/daemon downloads
│   └── Use: surge server + surge add
│
├── Beautiful TUI interface
│   └── Use: surge (no args, starts TUI)
│
└── Manage running downloads
    └── Use: surge ls/pause/resume/rm

Basic Usage

Start TUI Mode

surge

Start Server Mode (Headless)

# Start server daemon
surge server

# Add download via CLI
surge add "https://example.com/file.zip"

# List downloads
surge ls

Commands

Options

Common Examples

# Download single file
surge add "https://example.com/file.zip" -o ~/Downloads

# Batch download from file
surge add -b urls.txt -o ./downloads

# Start server with output folder
surge server -o /tmp/downloads

# Add to running server
surge add "https://url.com/file.zip"

# Pause/Resume
surge pause 1
surge resume 1

# Remove from queue
surge rm 1

Server Mode

Workflow

# Terminal 1: Start server
surge server

# Terminal 2: Add downloads
surge add "https://file1.zip"
surge add "https://file2.zip" -o /other/folder

# Check status
surge ls

# Server runs in background, downloads continue

API Token

# Get token for remote control
surge token

# Use token to connect
surge add "URL" --token YOUR_TOKEN --host remote:9090

Troubleshooting

Problem: surge: command not found

• Cause: Surge not installed
• Fix: brew install surge-downloader/tap/surge or go install github.com/surge-downloader/surge@latest

Problem: Connection refused

• Cause: Server not running
• Fix: Start server first: surge server

Problem: Permission denied

• Cause: Output folder not writable
• Fix: Check folder permissions or use -o with writable path

Problem: Download failed

• Cause: URL invalid or network issue
• Fix: Verify URL, check network connectivity

Problem: Too many connections

• Cause: Server limit reached
• Fix: Wait for current downloads or pause some

Self-Check

• [ ] Surge installed: surge --version
• [ ] Output directory exists and is writable
• [ ] For server mode: server is running (surge ls to check)
• [ ] For remote: token and host correct

Notes

• Multi-connection downloads up to 32 parallel connections
• TUI mode for interactive downloads
• Server mode for headless/daemon operation
• Batch file support for bulk downloads
• Automatic retry on failure
• Benchmarks: 1.38× faster than aria2, 2× faster than curl/wget

Quick Reference