|
1 | 1 | # Settings & Configuration |
2 | 2 |
|
3 | | -This document provides a detailed overview of all configuration options and CLI commands available in Surge. |
| 3 | +This document covers all configuration options available in Surge. For CLI commands and flags, see [USAGE.md](USAGE.md). |
4 | 4 |
|
5 | 5 | ## Configuration File |
6 | 6 |
|
7 | 7 | You can **access the settings in TUI** or if you prefer |
8 | 8 | from the `settings.json` file located in the application data directory: |
| 9 | + |
9 | 10 | - **Windows:** `%APPDATA%\surge\settings.json` |
10 | 11 | - **macOS:** `~/Library/Application Support/surge/settings.json` |
11 | 12 | - **Linux:** `~/.config/surge/settings.json` |
12 | 13 |
|
13 | | -### General Settings |
14 | | -| Key | Type | Description | Default | |
15 | | -| :--- | :--- | :--- | :--- | |
16 | | -| `default_download_dir` | string | Directory where new downloads are saved. If empty, defaults to `~/Downloads` or current directory. | `""` | |
17 | | -| `warn_on_duplicate` | bool | Show a warning when adding a download that already exists in the list. | `true` | |
18 | | -| `extension_prompt` | bool | Prompt for confirmation in the TUI when adding downloads via the browser extension. | `false` | |
19 | | -| `auto_resume` | bool | Automatically resume paused downloads when Surge starts. | `false` | |
20 | | -| `skip_update_check` | bool | Disable automatic check for new versions on startup. | `false` | |
21 | | -| `clipboard_monitor` | bool | Watch the system clipboard for URLs and prompt to download them. | `true` | |
22 | | -| `theme` | int | UI Theme (0=Adaptive, 1=Light, 2=Dark). | `0` | |
23 | | -| `log_retention_count` | int | Number of recent log files to keep. | `5` | |
24 | | - |
25 | | -### Connection Settings |
26 | | -| Key | Type | Description | Default | |
27 | | -| :--- | :--- | :--- | :--- | |
28 | | -| `max_connections_per_host` | int | Maximum concurrent connections allowed to a single host (1-64). | `32` | |
29 | | -| `max_concurrent_downloads` | int | Maximum number of downloads running simultaneously (requires restart). | `3` | |
30 | | -| `user_agent` | string | Custom User-Agent string for HTTP requests. Leave empty for default. | `""` | |
31 | | -| `proxy_url` | string | HTTP/HTTPS proxy URL (e.g., `http://127.0.0.1:8080`). Leave empty to use system settings. | `""` | |
32 | | -| `sequential_download` | bool | Download file pieces in strict order (Streaming Mode). Useful for previewing media but may be slower. | `false` | |
33 | | -| `min_chunk_size` | int64 | Minimum size of a download chunk in bytes (e.g., `2097152` for 2MB). | `2MB` | |
34 | | -| `worker_buffer_size` | int | I/O buffer size per worker in bytes (e.g., `524288` for 512KB). | `512KB` | |
35 | | - |
36 | | -### Performance Settings |
37 | | -| Key | Type | Description | Default | |
38 | | -| :--- | :--- | :--- | :--- | |
39 | | -| `max_task_retries` | int | Number of times to retry a failed chunk before giving up. | `3` | |
40 | | -| `slow_worker_threshold` | float | Restart workers slower than this fraction of the mean speed (0.0-1.0). | `0.3` | |
41 | | -| `slow_worker_grace_period` | duration | Time to wait before checking a worker's speed (e.g., `5s`). | `5s` | |
42 | | -| `stall_timeout` | duration | Restart workers that haven't received data for this duration (e.g., `3s`). | `3s` | |
43 | | -| `speed_ema_alpha` | float | Exponential moving average smoothing factor for speed calculation (0.0-1.0). | `0.3` | |
44 | | - |
45 | | ---- |
| 14 | +## Directory Structure |
46 | 15 |
|
47 | | -## CLI Reference |
| 16 | +Surge follows OS conventions for storing its files. Below is a breakdown of every directory it uses and where to find it on each platform. |
48 | 17 |
|
49 | | -Surge provides a robust Command Line Interface for automation and scripting. |
| 18 | +| Directory | Purpose | Linux | macOS | Windows | |
| 19 | +| :---------- | :-------------------------------- | :--------------------------- | :------------------------------------------ | :---------------------- | |
| 20 | +| **Config** | `settings.json` | `~/.config/surge/` | `~/Library/Application Support/surge/` | `%APPDATA%\surge\` | |
| 21 | +| **State** | Database (`surge.db`), auth token | `~/.local/state/surge/` | `~/Library/Application Support/surge/` | `%APPDATA%\surge\` | |
| 22 | +| **Logs** | Timestamped `.log` files | `~/.local/state/surge/logs/` | `~/Library/Application Support/surge/logs/` | `%APPDATA%\surge\logs\` | |
| 23 | +| **Runtime** | PID file, port file, lock | `$XDG_RUNTIME_DIR/surge/`¹ | `$TMPDIR/surge-runtime/` | `%TEMP%\surge\` | |
50 | 24 |
|
51 | | -### Command Table |
| 25 | +> ¹ Falls back to `~/.local/state/surge/` when `$XDG_RUNTIME_DIR` is not set (e.g. Docker / headless). |
52 | 26 |
|
53 | | -| Command | What it does | Key flags | Notes | |
54 | | -| :--- | :--- | :--- | :--- | |
55 | | -| `surge [url]...` | Launches local TUI. Queues optional URLs. | `--batch, -b`<br>`--port, -p`<br>`--output, -o`<br>`--no-resume`<br>`--exit-when-done` | If `--host` is set, this becomes remote TUI mode. | |
56 | | -| `surge server [url]...` | Launches headless server. Queues optional URLs. | `--batch, -b`<br>`--port, -p`<br>`--output, -o`<br>`--exit-when-done`<br>`--no-resume`<br>`--token` | Primary headless mode command. | |
57 | | -| `surge connect <host:port>` | Launches TUI connected to remote server. | `--insecure-http` | Convenience alias for remote TUI usage. | |
58 | | -| `surge add <url>...` | Queues downloads via CLI/API. | `--batch, -b`<br>`--output, -o` | Alias: `get`. | |
59 | | -| `surge ls [id]` | Lists downloads, or shows one download detail. | `--json`<br>`--watch` | Alias: `l`. | |
60 | | -| `surge pause <id>` | Pauses a download by ID/prefix. | `--all` | | |
61 | | -| `surge resume <id>` | Resumes a paused download by ID/prefix. | `--all` | | |
62 | | -| `surge rm <id>` | Removes a download by ID/prefix. | `--clean` | Alias: `kill`. | |
63 | | -| `surge token` | Prints current API auth token. | None | Useful for remote clients. | |
| 27 | +> **Note:** On Linux, `$XDG_CONFIG_HOME` / `$XDG_STATE_HOME` are respected if set; the paths above show the defaults. |
64 | 28 |
|
65 | | -### Server Subcommands (Compatibility) |
| 29 | +--- |
66 | 30 |
|
67 | | -| Command | What it does | |
68 | | -| :--- | :--- | |
69 | | -| `surge server start [url]...` | Legacy equivalent of `surge server [url]...`. | |
70 | | -| `surge server stop` | Stops a running server process by PID file. | |
71 | | -| `surge server status` | Prints running/not-running status from PID/port state. | |
| 31 | +### General Settings |
72 | 32 |
|
73 | | -### Global Flags |
| 33 | +| Key | Type | Description | Default | |
| 34 | +| :--------------------- | :----- | :------------------------------------------------------------------------------------------------- | :------ | |
| 35 | +| `default_download_dir` | string | Directory where new downloads are saved. If empty, defaults to `~/Downloads` or current directory. | `""` | |
| 36 | +| `warn_on_duplicate` | bool | Show a warning when adding a download that already exists in the list. | `true` | |
| 37 | +| `extension_prompt` | bool | Prompt for confirmation in the TUI when adding downloads via the browser extension. | `false` | |
| 38 | +| `auto_resume` | bool | Automatically resume paused downloads when Surge starts. | `false` | |
| 39 | +| `skip_update_check` | bool | Disable automatic check for new versions on startup. | `false` | |
| 40 | +| `clipboard_monitor` | bool | Watch the system clipboard for URLs and prompt to download them. | `true` | |
| 41 | +| `theme` | int | UI Theme (0=Adaptive, 1=Light, 2=Dark). | `0` | |
| 42 | +| `log_retention_count` | int | Number of recent log files to keep. | `5` | |
74 | 43 |
|
75 | | -These are persistent flags and can be used with all commands. |
| 44 | +### Connection Settings |
76 | 45 |
|
77 | | -| Flag | Description | |
78 | | -| :--- | :--- | |
79 | | -| `--host <host:port>` | Target server for TUI and CLI actions. | |
80 | | -| `--token <token>` | Bearer token used for API requests. | |
81 | | -| `--verbose, -v` | Enable verbose logging. | |
| 46 | +| Key | Type | Description | Default | |
| 47 | +| :------------------------- | :----- | :---------------------------------------------------------------------------------------------------- | :------ | |
| 48 | +| `max_connections_per_host` | int | Maximum concurrent connections allowed to a single host (1-64). | `32` | |
| 49 | +| `max_concurrent_downloads` | int | Maximum number of downloads running simultaneously (requires restart). | `3` | |
| 50 | +| `user_agent` | string | Custom User-Agent string for HTTP requests. Leave empty for default. | `""` | |
| 51 | +| `proxy_url` | string | HTTP/HTTPS proxy URL (e.g., `http://127.0.0.1:8080`). Leave empty to use system settings. | `""` | |
| 52 | +| `sequential_download` | bool | Download file pieces in strict order (Streaming Mode). Useful for previewing media but may be slower. | `false` | |
| 53 | +| `min_chunk_size` | int64 | Minimum size of a download chunk in bytes (e.g., `2097152` for 2MB). | `2MB` | |
| 54 | +| `worker_buffer_size` | int | I/O buffer size per worker in bytes (e.g., `524288` for 512KB). | `512KB` | |
82 | 55 |
|
83 | | -### Environment Variables |
| 56 | +### Performance Settings |
84 | 57 |
|
85 | | -| Variable | Description | |
86 | | -| :--- | :--- | |
87 | | -| `SURGE_HOST` | Default host when `--host` is not provided. | |
88 | | -| `SURGE_TOKEN` | Default token when `--token` is not provided. | |
| 58 | +| Key | Type | Description | Default | |
| 59 | +| :------------------------- | :------- | :--------------------------------------------------------------------------- | :------ | |
| 60 | +| `max_task_retries` | int | Number of times to retry a failed chunk before giving up. | `3` | |
| 61 | +| `slow_worker_threshold` | float | Restart workers slower than this fraction of the mean speed (0.0-1.0). | `0.3` | |
| 62 | +| `slow_worker_grace_period` | duration | Time to wait before checking a worker's speed (e.g., `5s`). | `5s` | |
| 63 | +| `stall_timeout` | duration | Restart workers that haven't received data for this duration (e.g., `3s`). | `3s` | |
| 64 | +| `speed_ema_alpha` | float | Exponential moving average smoothing factor for speed calculation (0.0-1.0). | `0.3` | |
0 commit comments