cli.md

Command-line reference

This is the stable index for Surge commands. Run surge <command> --help for the exact flags in the installed release.

Command guides

These pages show complete workflows, including prerequisites and recovery steps. They should be your starting point when you know what you want to do.

• surge add and surge get
• surge server
• Inspect and manage downloads: ls, pause, resume, refresh, limit, and rm
• surge connect
• surge service
• surge config
• Tokens, shell completion, and bug reports

Command index

Command	Purpose
surge [url]...	Open the local TUI and optionally queue URLs.
surge server [url]...	Run the headless download server. server start is a compatible explicit form.
surge connect [host:port]	Open the TUI against a running server.
surge add <url>... / surge get	Add URLs to a running server.
surge ls, pause, resume, refresh, limit, and rm	Inspect or manage downloads. rm --purge also deletes files from disk.
surge config [path] [value]	List, read, set, reset, or open settings.
surge token, completion, and bug-report	Print a token, generate shell completion, or open the issue flow.
surge service	Install and manage the current user's service.

See Download and manage files for examples and Run Surge as a service for service commands.

Output contracts

surge ls --output-version 1 selects the opt-in versioned JSON result and exit-code contract. Existing ls --json list/detail shapes remain unchanged. See CLI output contract for fields, failure handling, and schema.

Root command flags

Flag	Meaning
--batch, -b	Read URLs from a file, one per line.
--output, -o	Choose the download directory; defaults to the current directory.
--port, -p	Choose the listening port; the root command defaults to 8080 or the first available port.
--no-resume	Do not resume paused downloads at startup.
--exit-when-done	Exit after all downloads complete.
--no-server	Run the TUI without its HTTP API server.
--reset-settings	Reset settings and keybindings at startup.

Remote connection flags

These persistent flags work with the TUI and control commands.

Flag	Meaning
--host	Target a server; SURGE_HOST provides the same default.
--token	Supply the API bearer token; SURGE_TOKEN provides the same default.
--insecure-http	Allow plain HTTP for a non-private remote target.
--insecure-tls	Skip TLS certificate verification.
--tls-ca-file	Trust certificates signed by the supplied PEM bundle.

The two insecure flags reduce connection security. See Connect to a remote server before using them.

Configuration command

Use the case-sensitive setting path shown by surge config:

surge config Network.Max_Concurrent_Downloads
surge config Network.Max_Concurrent_Downloads 4
surge config Network.Max_Concurrent_Downloads default
surge config open

For setting meanings and configuration-file locations, see the configuration reference.