Skip to main content
Surge features a beautiful Terminal User Interface (TUI) built with Bubble Tea and Lipgloss. The TUI provides a keyboard-driven workflow for power users who prefer working in the terminal.

​
Starting the TUI

1

Launch with default settings

Run surge to enter the interactive dashboard:
surge
This launches the TUI where you can visualize progress, manage the queue, and see speed graphs.
2

Queue downloads on startup

Start the TUI with downloads already queued:
surge https://example.com/file1.zip https://example.com/file2.zip
You can combine URLs and batch files:
surge https://example.com/file.zip --batch urls.txt
3

Connect to local server

If you have a Surge server already running, connect to it:
surge connect
This auto-detects the local server and opens the TUI interface.

​
TUI Features

The interactive TUI provides:
  • Real-time Progress Visualization: See download progress with live speed graphs
  • Queue Management: Add, pause, resume, and cancel downloads
  • Speed Graphs: Monitor bandwidth utilization across all downloads
  • Keyboard-Driven Workflow: Navigate and control downloads without touching the mouse
The TUI uses Surge’s daemon architecture. When you launch the TUI, it starts a background engine. You can open multiple terminal tabs and queue downloads - they all funnel into one efficient manager.

​
Common Flags

Enhance your TUI experience with these flags: 
surge --batch urls.txt

​
Keyboard Shortcuts

The TUI is designed for keyboard navigation:
KeyAction
↑ / ↓Navigate download list
EnterView download details
SpacePause/Resume selected download
dDelete/Cancel download
aAdd new download
sOpen settings
qQuit TUI
?Show help
The TUI automatically refreshes download statistics every second, so you always have up-to-date information on your downloads.
The TUI interface is organized into several sections:
  • Download List: Main view showing all active, paused, and queued downloads
  • Speed Graph: Real-time visualization of download speeds
  • Status Bar: Shows server connection status and active downloads count
  • Settings Panel: Access configuration options without leaving the TUI

​
Working with Multiple Downloads

Surge’s daemon architecture means:
Only one Surge engine runs in the background, even if you open multiple TUI windows. This ensures efficient resource management.
If you’re running Surge in server mode on a different port, you’ll need to use the --host flag to connect: surge --host localhost:8080

​
Theme Customization

Surge supports adaptive, light, and dark themes. Access theme settings in the TUI:
  1. Press s to open settings
  2. Navigate to General settings
  3. Change the Theme setting:
    • 0 = Adaptive (follows terminal)
    • 1 = Light mode
    • 2 = Dark mode

​
Clipboard Monitoring

Surge can monitor your system clipboard for URLs:
1

Enable clipboard monitoring

In the TUI, press s for settings, then enable Clipboard Monitor in the General section.
2

Copy a URL

When you copy a URL to your clipboard, Surge will detect it and prompt you to download it.
3

Confirm or dismiss

Accept the prompt to queue the download, or dismiss it to ignore.
The clipboard monitor is enabled by default. You can disable it in settings if you prefer manual control over downloads.