Skip to main content
Global flags are persistent flags that can be used with any Surge command. These flags control connection settings, authentication, and logging behavior.

​
Available Flags

​
--host
string
Server host to connect/control (e.g., 127.0.0.1:1700)Environment Variable: SURGE_HOSTWhen specified, the CLI will connect to a remote or local Surge server instead of starting a new instance. This is useful for controlling headless servers or remote instances.
surge --host 127.0.0.1:1700 add https://example.com/file.zip
​
--token
string
Bearer token for API authenticationEnvironment Variable: SURGE_TOKENRequired when connecting to a server with authentication enabled. If not provided via flag or environment variable, Surge will attempt to read the token from the local token file.
surge --token abc123 --host 127.0.0.1:1700 ls
Use surge token to print your current authentication token.
​
--verbose
boolean
default:"false"
Enable verbose loggingShort flag: -vWhen enabled, Surge will output detailed debug information to help troubleshoot issues. Logs are written to the logs directory.
surge -v add https://example.com/file.zip

​
Command-Specific Flags

The following flags are available for the root command (surge [url]...) and surge server:
​
--batch
string
File containing URLs to download (one per line)Short flag: -bAccepts a file path containing URLs to download. Each URL should be on its own line. Lines starting with # are treated as comments and ignored.
surge --batch urls.txt
Example batch file:
# Download these files
https://example.com/file1.zip
https://example.com/file2.tar.gz

# Mirror example (comma-separated)
https://mirror1.com/file.iso,https://mirror2.com/file.iso
​
--port
integer
default:"0"
Port to listen on for HTTP APIShort flag: -pSpecifies the port for the HTTP server. If set to 0 (default), Surge will automatically find an available port starting from 1700.
surge --port 8080
The selected port is saved to the runtime directory and used by the browser extension and CLI for autodiscovery.
​
--output
string
Default output directory for downloadsShort flag: -oSpecifies where downloaded files should be saved. If not provided, uses the default_download_dir from settings.json, or the current directory as a fallback.
surge --output ~/Downloads add https://example.com/file.zip
​
--no-resume
boolean
default:"false"
Do not auto-resume paused downloads on startupBy default, Surge respects the auto_resume setting in settings.json. This flag overrides that behavior and prevents automatic resumption of paused downloads.
surge --no-resume
​
--exit-when-done
boolean
default:"false"
Exit when all downloads completeUseful for automation and scripting. Surge will automatically quit when all active downloads finish.
surge --exit-when-done --batch urls.txt
Combine with --batch for unattended batch downloads.

​
Flag Priority

When both a command-line flag and environment variable are set, the command-line flag takes precedence:
  1. Command-line flag (highest priority)
  2. Environment variable
  3. Configuration file
  4. Default value (lowest priority)

​
Examples

​
Connect to Remote Server

surge --host 192.168.1.100:1700 --token mytoken123 ls

​
Batch Download with Custom Output

surge --batch downloads.txt --output /mnt/storage --exit-when-done

​
Verbose Logging for Debugging

surge -v add https://example.com/large-file.iso

​
Start Server on Specific Port

surge server --port 9000