Skip to main content
The resume command resumes one or more paused downloads by ID.

​
Usage

surge resume <ID>

​
Description

Resumes a paused download from where it left off. The command:
  • Restores download state from .surge file
  • Continues from the last downloaded byte
  • Supports partial ID matching for convenience
  • Can resume all paused downloads with --all flag
  • Validates file integrity before resuming
Surge uses HTTP range requests to resume downloads efficiently without re-downloading completed chunks.

​
Arguments

​
ID
string
required
Download ID (full or partial) to resume. You can use just the first few characters.Example:
surge resume abc12345

​
Flags

​
--all
boolean
default:"false"
Resume all paused downloads.Example:
surge resume --all
The --all flag is currently not fully implemented for remote servers.

​
Examples

​
Resume Single Download

Using full ID: 
surge resume abc12345-6789-1234-5678-90abcdef1234
Using partial ID: 
surge resume abc12345
Output: 
Resumed download abc12345

​
Resume All Downloads

surge resume --all
The --all flag currently shows “not yet implemented” when targeting a running server. Use the TUI to resume all downloads.

​
Behavior

​
Resume Process

When a download is resumed:
  1. State file (.surge) is validated
  2. Server is queried for file size and range support
  3. Download continues from last byte position
  4. If server doesn’t support ranges, download restarts
  5. Status updates to “active” or “queued”

​
Partial ID Resolution

Surge automatically resolves partial IDs: 
# These are equivalent if abc12345 is unique:
surge resume abc
surge resume abc123
surge resume abc12345
If multiple downloads match: 
Error: multiple downloads match ID "abc"

​
Auto-Resume on Startup

By default, Surge automatically resumes paused downloads when started: 
surge  # Auto-resumes paused downloads
Disable with: 
surge --no-resume

​
Use Cases

​
Resume After Pause

# Pause for bandwidth
surge pause abc12345

# Resume later
surge resume abc12345

​
Resume Failed Downloads

Resume downloads that errored due to network issues: 
surge ls --json | jq -r '.[] | select(.status == "error") | .id' | while read id; do
  surge resume "$id"
done

​
Resume All After Restart

If you started with --no-resume, manually resume: 
surge resume --all

​
Selective Resume

Resume only large files: 
surge ls --json | jq -r '.[] | select(.status == "paused" and .total_size > 1000000000) | .id' | while read id; do
  surge resume "$id"
done

​
Remote Servers

Resume downloads on a remote server: 
surge resume --host 192.168.1.100:1700 abc12345
Or with environment variable: 
export SURGE_HOST=192.168.1.100:1700
surge resume abc12345

​
Error Handling

​
Download Not Found

Error: download not found: xyz
List downloads to find the correct ID: 
surge ls

​
Missing State File

If the .surge file is missing: 
Error: cannot resume - state file missing
The download cannot be resumed and must be removed and re-added.

​
No Server Running

Error: No running Surge server found.
Start Surge first: 
surge

​
Already Active

Resuming an active download has no effect: 
surge resume abc12345
# Resumed download abc12345

surge resume abc12345
# Resumed download abc12345 (already active)

​
Server Doesn’t Support Resume

Some servers don’t support HTTP range requests. Surge will:
  1. Attempt to resume with Range header
  2. If server returns 200 (instead of 206), restart from beginning
  3. Remove incomplete file and start fresh

​
Integrity Validation

Before resuming, Surge validates:
  • State file exists and is readable
  • Downloaded file exists at expected path
  • File size matches expected progress
  • Chunk boundaries are valid
If validation fails, the download is marked as corrupted and must be restarted.

​
State File Location

Resume state is stored in: 
~/.local/state/surge/downloads/<filename>.surge
Keep .surge files until downloads complete. They enable resume functionality.