Inspect and manage downloads

surge ls can inspect the local download database when Surge is not running, though a running server is needed for live progress. Commands that change the queue (pause, resume, refresh, limit, and rm) require a running server. Use surge ls first to find a download ID; an unambiguous ID prefix is accepted where an ID is required.

surge ls

List all downloads:

surge ls

Show details for one download:

surge ls ab12

Use JSON when a script needs structured output, or watch the queue in a terminal:

surge ls --json
surge ls --watch

l is an alias for ls.

surge pause

Pause one download:

surge pause ab12

Pause all downloads:

surge pause --all

surge resume

Resume a paused download:

surge resume ab12

Resume every paused download:

surge resume --all

surge refresh

Refresh replaces the source URL of a paused or failed download. This is useful when a signed URL has expired or the original link no longer works.

surge refresh ab12 https://example.com/new-signed-url
surge resume ab12

The download must be paused or in an error state before it can be refreshed.

surge limit

Set a cap for one download:

surge limit ab12 2MB/s

Set a global cap for the active queue:

surge limit --global 10MB/s

Set the default cap for new downloads:

surge limit --default 2MB/s

Use 0 to make an individual download unlimited. Use -1 to make it inherit the default per-download limit.

surge rm

Remove one record from Surge’s queue without deleting the downloaded file:

surge rm ab12

Clean up completed or failed records:

surge rm --clean
surge rm --clean-failed

[!WARNING] surge rm ab12 --purge also deletes the corresponding file or files from disk. kill is an alias for rm; it has the same behavior.

Use these commands remotely

Prefix any command with the target server and token:

surge --host https://192.168.1.10:1700 --token "$SURGE_TOKEN" pause ab12

See remote connections for TLS and token handling.