### Install Surge via Package Managers

Source: https://github.com/surgedm/surge/blob/main/README.md

Commands for installing Surge on various operating systems using common package managers.

```bash
yay -S surge
```

```bash
brew install SurgeDM/tap/surge
```

```bash
winget install surge-downloader.surge
```

```bash
scoop install surge
```

```bash
go install github.com/SurgeDM/Surge@latest
```

--------------------------------

### Start Interactive TUI

Source: https://context7.com/surgedm/surge/llms.txt

Launch the main Surge interface to manage downloads visually and monitor progress.

```bash
# Start the TUI dashboard
surge

# Start TUI and queue downloads
surge https://example.com/file1.zip https://example.com/file2.zip

# Queue downloads from a batch file
surge --batch urls.txt

# Combine URLs and batch file with custom output directory
surge https://example.com/file.zip --batch urls.txt --output /downloads

# Exit automatically when all downloads complete
surge https://example.com/file.zip --exit-when-done
```

--------------------------------

### Start TUI with downloads

Source: https://github.com/surgedm/surge/blob/main/README.md

Initiate the Surge TUI with specific URLs or a batch file containing multiple download links.

```bash
surge https://example.com/file1.zip https://example.com/file2.zip
```

```bash
surge https://example.com/file.zip --batch urls.txt
```

--------------------------------

### GET /list

Source: https://context7.com/surgedm/surge/llms.txt

Lists all currently active download tasks.

```APIDOC
## GET /list

### Description
Get status of all active downloads.

### Method
GET

### Endpoint
/list

### Response
#### Success Response (200)
- **Array** (object) - List of active download objects.

#### Response Example
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "downloading"
  }
]
```

--------------------------------

### Start Server Mode

Source: https://context7.com/surgedm/surge/llms.txt

Run Surge as a background daemon for headless systems or remote management.

```bash
# Start headless server
surge server

# Start server with initial downloads
surge server https://example.com/file1.zip https://example.com/file2.zip

# Start server on specific port with custom token
surge server --port 1700 --token my-secret-token

# Start server with batch file and auto-exit
surge server --batch urls.txt --exit-when-done

# Server subcommands for process management
surge server start https://example.com/file.zip  # Legacy start command
surge server stop                                 # Stop running server via SIGTERM
surge server status                               # Check if server is running
```

--------------------------------

### Surge settings.json Configuration Example

Source: https://github.com/surgedm/surge/blob/main/docs/SETTINGS.md

This JSON structure represents the settings.json file for Surge. You can customize general, network, performance, and categories settings. Missing keys will use default values.

```json
{
  "general": {
    "default_download_dir": "/path/to/downloads",
    "theme": 2
  },
  "network": {
    "max_connections_per_host": 16
  },
  "performance": {
    "max_task_retries": 5
  },
  "categories": {
    "category_enabled": true
  }
}
```

--------------------------------

### Get Download History

Source: https://context7.com/surgedm/surge/llms.txt

Retrieve a list of completed download tasks.

```bash
# Get download history
curl http://localhost:1700/history \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
[
  {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/completed.zip",
    "filename": "completed.zip",
    "dest_path": "/downloads/completed.zip",
    "total_size": 104857600,
    "completed_at": "2024-01-15T10:30:00Z",
    "status": "completed"
  }
]
```

--------------------------------

### Get Authentication Token

Source: https://context7.com/surgedm/surge/llms.txt

Retrieve the API authentication token for external configuration.

```bash
# Print current auth token
surge token
```

--------------------------------

### Start Surge TUI

Source: https://github.com/surgedm/surge/blob/main/README.md

Command to launch the interactive Terminal User Interface.

```bash
surge
```

--------------------------------

### GET /health

Source: https://context7.com/surgedm/surge/llms.txt

Checks the availability and status of the Surge server instance.

```APIDOC
## GET /health

### Description
Check server availability without authentication.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The current status of the server (e.g., "ok").
- **port** (integer) - The port the server is listening on.

#### Response Example
{
  "status": "ok",
  "port": 1700
}
```

--------------------------------

### GET /download

Source: https://context7.com/surgedm/surge/llms.txt

Retrieves the current status and progress of a specific download by its ID.

```APIDOC
## GET /download

### Description
Retrieve status of a specific download by ID.

### Method
GET

### Endpoint
/download

### Parameters
#### Query Parameters
- **id** (string) - Required - The unique ID of the download.

### Response
#### Success Response (200)
- **id** (string) - Download ID.
- **status** (string) - Current status.
- **progress** (number) - Percentage complete.
- **speed** (number) - Current download speed.

#### Response Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "downloading",
  "progress": 45.5,
  "speed": 35.4
}
```

--------------------------------

### Get Download Status

Source: https://context7.com/surgedm/surge/llms.txt

Retrieve the current status and progress of a specific download by its ID.

```bash
# Get download status
curl http://localhost:1700/download?id=550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/file.zip",
  "filename": "file.zip",
  "status": "downloading",
  "progress": 45.5,
  "total_size": 1073741824,
  "downloaded": 488636416,
  "speed": 35.4
}
```

--------------------------------

### Add Downloads

Source: https://context7.com/surgedm/surge/llms.txt

Queue new downloads to a running Surge instance.

```bash
# Add a single download
surge add https://example.com/file.zip

# Add multiple downloads
surge add https://example.com/file1.zip https://example.com/file2.zip

# Add downloads with mirrors (comma-separated)
surge add "https://mirror1.com/file.zip,https://mirror2.com/file.zip"

# Add with custom output directory
surge add https://example.com/file.zip --output /downloads

# Add from batch file
surge add --batch urls.txt --output /downloads
```

--------------------------------

### Add Download via API

Source: https://context7.com/surgedm/surge/llms.txt

Queue a new download task. Requires an authorization token and a valid URL.

```bash
# Basic download request
curl -X POST http://localhost:1700/download \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/file.zip"
  }'

# Download with filename and output path
curl -X POST http://localhost:1700/download \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/file.zip",
    "filename": "custom-name.zip",
    "path": "/downloads"
  }'

# Download with mirrors for parallel fetching
curl -X POST http://localhost:1700/download \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mirror1.com/file.zip",
    "mirrors": [
      "https://mirror1.com/file.zip",
      "https://mirror2.com/file.zip",
      "https://mirror3.com/file.zip"
    ],
    "path": "/downloads"
  }'

# Download with custom headers (from browser extension)
curl -X POST http://localhost:1700/download \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/protected-file.zip",
    "headers": {
      "Cookie": "session=abc123",
      "Referer": "https://example.com"
    },
    "skip_approval": true
  }'

# Response
{
  "status": "queued",
  "message": "Download queued successfully",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### POST /download

Source: https://context7.com/surgedm/surge/llms.txt

Queues a new download task with optional configuration for filename, path, mirrors, and custom headers.

```APIDOC
## POST /download

### Description
Queue a new download via the HTTP API.

### Method
POST

### Endpoint
/download

### Request Body
- **url** (string) - Required - The source URL of the file.
- **filename** (string) - Optional - Custom name for the file.
- **path** (string) - Optional - Destination directory.
- **mirrors** (array) - Optional - List of mirror URLs for parallel fetching.
- **headers** (object) - Optional - Custom HTTP headers.
- **skip_approval** (boolean) - Optional - Skip manual approval if required.

### Request Example
{
  "url": "https://example.com/file.zip",
  "filename": "custom-name.zip",
  "path": "/downloads"
}

### Response
#### Success Response (200)
- **status** (string) - The status of the request.
- **message** (string) - Confirmation message.
- **id** (string) - Unique identifier for the download.

#### Response Example
{
  "status": "queued",
  "message": "Download queued successfully",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### Run All Tests

Source: https://github.com/surgedm/surge/blob/main/CONTRIBUTING.md

Execute all tests in the codebase from the repository root. Ensure all tests pass before submitting a PR.

```bash
go test ./...
```

--------------------------------

### Configure Surge Settings

Source: https://context7.com/surgedm/surge/llms.txt

Define application behavior, network limits, and performance thresholds using a JSON configuration file.

```json
{
  "general": {
    "default_download_dir": "/home/user/Downloads",
    "theme": 2,
    "auto_resume": true,
    "clipboard_monitor": true,
    "warn_on_duplicate": true,
    "log_retention_count": 5
  },
  "network": {
    "max_connections_per_host": 32,
    "max_concurrent_downloads": 3,
    "max_concurrent_probes": 3,
    "sequential_download": false,
    "min_chunk_size": 2097152,
    "worker_buffer_size": 524288,
    "proxy_url": "",
    "user_agent": ""
  },
  "performance": {
    "max_task_retries": 3,
    "slow_worker_threshold": 0.3,
    "slow_worker_grace_period": "5s",
    "stall_timeout": "3s",
    "speed_ema_alpha": 0.3
  },
  "categories": {
    "category_enabled": false
  }
}
```

--------------------------------

### Deploy Surge with Docker Compose

Source: https://github.com/surgedm/surge/blob/main/README.md

Commands for managing a containerized Surge instance, including deployment, authentication, and monitoring.

```bash
wget https://raw.githubusercontent.com/SurgeDM/Surge/refs/heads/main/docker/compose.yml
docker compose up -d
```

```bash
docker compose exec surge surge token
```

```bash
docker compose exec surge surge ls
```

```bash
docker compose logs -f surge
```

--------------------------------

### Send Download Request to Surge Daemon

Source: https://context7.com/surgedm/surge/llms.txt

Use this POST request to initiate a download through Surge. Include URL, filename, path, and optional headers. Set 'skip_approval' to true to bypass manual confirmation for trusted requests.

```typescript
// Extension sends download request to Surge
const response = await fetch('http://localhost:1700/download', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN'
  },
  body: JSON.stringify({
    url: 'https://example.com/file.zip',
    filename: 'file.zip',
    path: '/downloads',
    headers: {
      'Cookie': 'session=abc123',
      'Referer': 'https://example.com'
    },
    skip_approval: true  // Skip TUI confirmation for extension-vetted requests
  })
});

```

--------------------------------

### Configure Environment Variables

Source: https://context7.com/surgedm/surge/llms.txt

Set host and authentication credentials via environment variables for CLI operations.

```bash
# Set default server host for CLI commands
export SURGE_HOST="192.168.1.10:1700"

# Set authentication token
export SURGE_TOKEN="your-auth-token"

# Example: Add download to remote server using environment variables
SURGE_HOST="192.168.1.10:1700" SURGE_TOKEN="token123" surge add https://example.com/file.zip
```

--------------------------------

### List Downloads

Source: https://context7.com/surgedm/surge/llms.txt

Display active downloads and their status with optional JSON or watch modes.

```bash
# List all downloads in table format
surge ls

# Show download details by ID (partial ID matching supported)
surge ls abc123

# Output in JSON format
surge ls --json

# Watch mode: auto-refresh every second
surge ls --watch

# Combine JSON and watch mode
surge ls --json --watch
```

--------------------------------

### Manage Server Mode

Source: https://github.com/surgedm/surge/blob/main/README.md

Run Surge in headless mode for background processes. Requires an API token for secure access.

```bash
# Start the server
surge server

# Start the server with a download
surge server https://url.com/file.zip

# Start with explicit API token
surge server --token <token>
```

--------------------------------

### Open File or Folder

Source: https://context7.com/surgedm/surge/llms.txt

Open a completed file or its containing folder using the default system application.

```bash
# Open downloaded file with default application
curl -X POST "http://localhost:1700/open-file?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Open containing folder in file manager
curl -X POST "http://localhost:1700/open-folder?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "status": "ok",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### POST /resume

Source: https://context7.com/surgedm/surge/llms.txt

Resumes a previously paused download task.

```APIDOC
## POST /resume

### Description
Resume a paused download.

### Method
POST

### Endpoint
/resume

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the download to resume.
```

--------------------------------

### List All Downloads

Source: https://context7.com/surgedm/surge/llms.txt

Retrieve the status of all active download tasks.

```bash
# List all downloads
curl http://localhost:1700/list \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "file1.zip",
    "status": "downloading",
    "progress": 45.5,
    "total_size": 1073741824,
    "downloaded": 488636416,
    "speed": 35.4
  },
  {
    "id": "660f9511-f30c-52e5-b827-557766551111",
    "filename": "file2.zip",
    "status": "paused",
    "progress": 20.0,
    "total_size": 524288000,
    "downloaded": 104857600,
    "speed": 0
  }
]
```

--------------------------------

### Connect to Remote Daemon

Source: https://github.com/surgedm/surge/blob/main/README.md

Establish a connection to a local or remote Surge instance using host and token parameters.

```bash
# Connect to local server (auto-detected)
surge connect

# Connect to a remote daemon
surge connect 192.168.1.10:1700 --token <token>

# Equivalent global-flag form
surge --host 192.168.1.10:1700 --token <token>
```

--------------------------------

### Subscribe to Server-Sent Events

Source: https://context7.com/surgedm/surge/llms.txt

Use curl to connect to the events stream for real-time download progress updates.

```bash
# Subscribe to events stream
curl -N http://localhost:1700/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: text/event-stream"

# Example events received:
# event: progress
# data: {"id":"550e8400...","downloaded":104857600,"speed":35.4}

# event: completed
# data: {"id":"550e8400...","filename":"file.zip","dest_path":"/downloads/file.zip"}

# event: error
# data: {"id":"550e8400...","error":"connection timeout"}
```

--------------------------------

### Deploy Surge with Docker Compose

Source: https://context7.com/surgedm/surge/llms.txt

Run Surge in a containerized environment using Docker Compose.

```yaml
# docker/compose.yml
services:
  surge:
    image: ghcr.io/SurgeDM/Surge
    container_name: surge
    ports:
      - "1700:1700"
    volumes:
      - ./downloads:/downloads
      - ./surge-config:/root/.local/state/surge
    restart: unless-stopped
    environment:
      - TZ=UTC
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 256M
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
```

```bash
# Download compose file and start container
wget https://raw.githubusercontent.com/SurgeDM/Surge/refs/heads/main/docker/compose.yml
docker compose up -d

# Get the API authentication token
docker compose exec surge surge token

# List downloads
docker compose exec surge surge ls

# Add a download
docker compose exec surge surge add https://example.com/file.zip

# View logs
docker compose logs -f surge
```

--------------------------------

### Resume Download

Source: https://context7.com/surgedm/surge/llms.txt

Resume a previously paused download task.

```bash
# Resume download by ID
curl -X POST "http://localhost:1700/resume?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "status": "resumed",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### Pause and Resume Downloads

Source: https://context7.com/surgedm/surge/llms.txt

Control the execution state of specific downloads or the entire queue.

```bash
# Pause a download by ID (partial ID supported)
surge pause abc123

# Resume a paused download
surge resume abc123

# Pause all downloads (planned feature)
surge pause --all

# Resume all paused downloads (planned feature)
surge resume --all
```

--------------------------------

### Subscribe to SSE Events for Download Progress

Source: https://context7.com/surgedm/surge/llms.txt

Connect to the SSE endpoint to receive real-time updates on download progress and completion. Parse the JSON data from 'progress' and 'completed' events.

```typescript
// Subscribe to SSE events for real-time updates
const eventSource = new EventSource('http://localhost:1700/events', {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});

eventSource.addEventListener('progress', (event) => {
  const data = JSON.parse(event.data);
  console.log(`Download ${data.id}: ${data.progress}% at ${data.speed} MB/s`);
});

eventSource.addEventListener('completed', (event) => {
  const data = JSON.parse(event.data);
  console.log(`Download completed: ${data.filename}`);
});

```

--------------------------------

### POST /pause

Source: https://context7.com/surgedm/surge/llms.txt

Pauses an active download task.

```APIDOC
## POST /pause

### Description
Pause an active download.

### Method
POST

### Endpoint
/pause

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the download to pause.

### Response
#### Success Response (200)
- **status** (string) - The new status.
- **id** (string) - The download ID.
```

--------------------------------

### Connect to Remote Daemon

Source: https://context7.com/surgedm/surge/llms.txt

Establish a connection between the TUI and a local or remote Surge daemon.

```bash
# Auto-detect and connect to local server
surge connect

# Connect to remote server
surge connect 192.168.1.10:1700 --token my-secret-token

# Alternative using global flags
surge --host 192.168.1.10:1700 --token my-secret-token

# Allow plain HTTP for non-loopback targets
surge connect 192.168.1.10:1700 --insecure-http
```

--------------------------------

### Retrieve API Token

Source: https://github.com/surgedm/surge/blob/main/README.md

Display the current authentication token required for remote connections and extension integration.

```bash
surge token
```

--------------------------------

### Refresh Download URL

Source: https://context7.com/surgedm/surge/llms.txt

Update the source URL for a paused or errored download without losing progress.

```bash
# Update URL for a download (useful when original link expires)
surge refresh abc123 https://newmirror.com/file.zip
```

--------------------------------

### Run Focused Tests

Source: https://github.com/surgedm/surge/blob/main/CONTRIBUTING.md

Run specific tests within a package to isolate issues or verify changes. The -count=1 flag ensures tests are run only once.

```bash
go test ./internal/engine/concurrent -run TestConcurrentDownloader_SwitchOn429 -count=1
```

```bash
go test ./internal/download -run TestIntegration_PauseResume -count=1
```

```bash
go test ./internal/tui -count=1
```

--------------------------------

### Health Check API

Source: https://context7.com/surgedm/surge/llms.txt

Verify server availability via the HTTP API.

```bash
# Health check endpoint (no auth required)
curl http://localhost:1700/health

# Response
{
  "status": "ok",
  "port": 1700
}
```

--------------------------------

### Update Download URL

Source: https://context7.com/surgedm/surge/llms.txt

Update the source URL for a paused or errored download task.

```bash
# Update download URL
curl -X PUT "http://localhost:1700/update-url?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://newmirror.com/file.zip"}'

# Response
{
  "status": "updated",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://newmirror.com/file.zip"
}
```

--------------------------------

### Pause Download

Source: https://context7.com/surgedm/surge/llms.txt

Pause an active download task using its ID.

```bash
# Pause download by ID
curl -X POST "http://localhost:1700/pause?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "status": "paused",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

--------------------------------

### Remove Downloads

Source: https://context7.com/surgedm/surge/llms.txt

Delete downloads from the queue or clean up completed entries.

```bash
# Remove a download by ID
surge rm abc123

# Alternative command
surge kill abc123

# Clean up all completed downloads from database
surge rm --clean
```

--------------------------------

### DELETE /delete

Source: https://context7.com/surgedm/surge/llms.txt

Removes a download task from the queue.

```APIDOC
## DELETE /delete

### Description
Remove a download from the queue.

### Method
DELETE

### Endpoint
/delete

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the download to remove.
```

--------------------------------

### PUT /update-url

Source: https://context7.com/surgedm/surge/llms.txt

Updates the source URL for a download that is paused or has encountered an error.

```APIDOC
## PUT /update-url

### Description
Update the source URL for a paused or errored download.

### Method
PUT

### Endpoint
/update-url

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the download.

### Request Body
- **url** (string) - Required - The new source URL.
```

--------------------------------

### Delete Download

Source: https://context7.com/surgedm/surge/llms.txt

Remove a download task from the queue.

```bash
# Delete download (POST or DELETE method supported)
curl -X DELETE "http://localhost:1700/delete?id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
{
  "status": "deleted",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.