Skip to content

USAGE.md

Latest commit

 

History

History
64 lines (47 loc) · 6.14 KB

USAGE.md

File metadata and controls

64 lines (47 loc) · 6.14 KB

CLI Usage

Surge provides a robust Command Line Interface for automation and scripting. For configuration options, see SETTINGS.md.

Command Table

Command What it does Key flags Notes
surge [url]... Launches local TUI. Queues optional URLs. --batch, -b
--port, -p
--output, -o
--no-resume
--exit-when-done		 -o defaults to CWD. If --host is set, this becomes remote TUI mode.
surge server [url]... Launches headless server. Queues optional URLs. --batch, -b
--port, -p
--output, -o
--exit-when-done
--no-resume
--token		 -o defaults to CWD. Primary headless mode command.
surge connect [host:port] Launches TUI connected to a server. Auto-detects local server when no target is given. --insecure-http Convenience alias for remote TUI usage.
surge add <url>... Queues downloads via CLI/API. --batch, -b
--output, -o		 -o defaults to CWD. Alias: get.
surge ls [id] Lists downloads, or shows one download detail. --json
--watch		 Alias: l.
surge pause <id> Pauses a download by ID/prefix. --all
surge resume <id> Resumes a paused download by ID/prefix. --all
surge refresh <id> <url> Updates the source URL of a paused or errored download. None Reconnects using the new link.
surge rm <id> Removes a download by ID/prefix. --clean Alias: kill.
surge token Prints current API auth token. (Also visible in TUI > Settings > Extension) None Useful for remote clients.
surge service <cmd> Manages Surge as a system service (daemon). install, uninstall, start, stop, status Cross-platform (Linux/Windows/macOS). See Service Management.
surge bug-report Opens a pre-filled GitHub bug report. Prompts for target (Core/Extension) and optional system/log details. None Prints a manual URL fallback if browser open fails.

Service Management

The service command allows you to manage Surge as a background daemon that starts automatically on boot.

  • surge service install: Registers Surge as a system service.
  • surge service uninstall: Removes the system service.
  • surge service start: Starts the background service.
  • surge service stop: Stops the background service.
  • surge service status: Checks if the service is installed and running.

Note: On most systems, these commands require administrative privileges (e.g., sudo surge service install).

Server Subcommands (Compatibility)

Command What it does
surge server start [url]... Legacy equivalent of surge server [url]....
surge server stop Stops a running server process by PID file.
surge server status Prints running/not-running status from PID/port state.

Global Flags

These are persistent flags and can be used with all commands.

Flag Description
--host <host:port> Target server for TUI and CLI actions.
--token <token> Bearer token used for API requests.

Environment Variables

Variable Description
SURGE_HOST Default host when --host is not provided.
SURGE_TOKEN Default token when --token is not provided.

Fonts

Surge bundles a Nerd Font, but terminal fonts are controlled by your terminal emulator. Install the bundled font and set your terminal to JetBrainsMono Nerd Font Mono.

See FONTS.md for install steps and licensing details.