Skip to main content
Surge provides a comprehensive command-line interface for managing downloads from the terminal. All commands support both local and remote operation modes.

​
Quick Reference

surge

Launch TUI or queue downloads

add

Add downloads to queue

ls

List all downloads

pause

Pause active downloads

resume

Resume paused downloads

rm

Remove downloads

refresh

Update download URL

server

Manage headless server

connect

Connect to remote server

token

Display API token

​
Global Flags

These flags are available for all commands:
​
--host
string
Server host to connect/control. Can also be set via SURGE_HOST environment variable.Example: 127.0.0.1:1700
​
--token
string
Bearer token for API authentication. Can also be set via SURGE_TOKEN environment variable.
​
--verbose
boolean
default:"false"
Enable verbose logging output.Short form: -v

​
Environment Variables

VariableDescription
SURGE_HOSTDefault server host when --host is not provided
SURGE_TOKENDefault authentication token when --token is not provided

​
Command Categories

​
Core Commands

  • surge - Main command for launching the TUI interface
  • add - Queue new downloads from command line
  • ls - List and inspect downloads

​
Control Commands

  • pause - Pause active or queued downloads
  • resume - Resume paused downloads
  • rm - Remove downloads from queue
  • refresh - Update URL for paused/errored downloads

​
Server Management

  • server - Run Surge in headless mode
  • connect - Connect TUI to remote daemon
  • token - Retrieve API authentication token

​
Usage Patterns

​
Local Mode

Run Surge locally with TUI: 
surge https://example.com/file.zip

​
Headless Mode

Start a background server: 
surge server --port 1700
Then control it via CLI: 
surge add https://example.com/file.zip
surge ls
surge pause <id>

​
Remote Mode

Connect to a remote Surge instance: 
surge connect 192.168.1.100:1700 --token <token>
Or set environment variables: 
export SURGE_HOST=192.168.1.100:1700
export SURGE_TOKEN=your-token-here
surge add https://example.com/file.zip
Most commands automatically detect if a Surge instance is running and connect to it. Use --host to explicitly target a specific server.