Surge Download Manager

Blazing fast TUI download manager with multi-connection, queue management, server mode, multiple mirrors, and a beautiful terminal interface.

Security Scan

The skill's behavior matches a download-manager wrapper, but small inconsistencies (metadata vs SKILL.md) and the fact it invokes an external 'surge' binary without an install spec mean you should verify the upstream binary and repository before installing.

Purpose & Capability

The name, description, SKILL.md and scripts/surge.py all describe a wrapper for the 'surge' download manager and the advertised features (TUI, server mode, add/list/pause/resume) align with the code and instructions. However, registry metadata earlier listed no required binaries while SKILL.md metadata explicitly names the 'surge' binary and gives a GitHub homepage — this mismatch is inconsistent and worth verifying.

Instruction Scope

SKILL.md's runtime instructions stay on-task: how to install the surge binary, running server/TUI, adding URLs, and using tokens. The included wrapper script only runs the local 'surge' command, lists status, and starts the server. There are no instructions to read unrelated files, export environment secrets, or call external endpoints beyond the normal download flow.

Install Mechanism

There is no formal install spec in the registry (instruction-only), but SKILL.md recommends installing via brew, go install, or downloading a release from GitHub. That is reasonable, but because the skill will invoke a local 'surge' binary, you should confirm the binary's provenance (the SKILL.md points to a GitHub URL while the top metadata declared no homepage — another minor inconsistency).

Credentials

The skill doesn't request any environment variables, credentials, or config paths. The wrapper script doesn't read env vars or secrets. The only token mentioned is the surge application's API token (returned/managed by the surge binary itself), which is expected for a server-mode download manager.

Persistence & Privilege

The skill does not request 'always: true' or any elevated, persistent platform privileges. It starts subprocesses (surge server) as a normal user operation and does not modify other skills or system-wide agent configuration.

What to consider before installing

This skill appears to be a thin wrapper around a local 'surge' download manager and is generally coherent with that purpose, but there are small metadata inconsistencies (missing required-bins in registry metadata vs SKILL.md) and no install is provided, so the wrapper will call whatever 'surge' binary is on PATH. Before installing or running this skill: (1) Verify the upstream project/release you plan to install (prefer official GitHub releases or your OS package manager), (2) avoid running an untrusted 'surge' binary — inspect or build it from source if possible, (3) be aware the wrapper launches the surge binary with user-provided URLs/args (no extra sanitization), so run it with least privilege and avoid running as root, (4) confirm the SKILL.md homepage and registry info match the repository you download from. If you want higher assurance, request an install spec that pins a vetted package or includes a checksum for the binary.

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

Step	Action	Why
1	INSTALL	Install surge binary (brew/go/binary)
2	START	Launch server mode or TUI
3	ADD	Add URLs to download queue
4	MANAGE	Monitor, pause, resume, or remove downloads
5	RETRIEVE	Get completed files from output directory

---

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

Command	Description
surge server	Start headless daemon
surge add <url>	Add download to queue
surge ls	List downloads
surge pause <id>	Pause download
surge resume <id>	Resume download
surge rm <id>	Remove download
surge token	Get API token

---

Options

Flag	Description	Default
-o, --output PATH	Output directory	./downloads
-b, --batch FILE	Batch file with URLs	-
--exit-when-done	Exit when complete	false
--host HOST	Target server	localhost:9090
--token TOKEN	API token	-

---

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

Task	Command
Start TUI	surge
Start server	surge server
Add download	surge add "URL" -o ./folder
Batch download	surge add -b urls.txt
List downloads	surge ls
Pause/Resume	surge pause <id> / surge resume <id>
Remove	surge rm <id>

---