Surge CLI
Surge Mac provides a CLI program for controlling Surge from the command line. You may find it at /Applications/Surge.app/Contents/Applications/surge-cli.
Use --help to get the latest usage information.
Available commands:
reload - Reload the main profile
switch-profile <profile-name> - Switch to another profile
stop - Shutdown Surge
unattended-upgrade - Perform an unattended Surge upgrade if available
dump active - Show all active connections
dump request - Show recent connections
dump rule - Show all effective rules
dump policy - Show all proxies and policy groups
dump dns - Show DNS caches
dump profile [original / effective] - Show the original profile and the effective profile modified by modules
dump event - Show events
watch request - Keep tracing the new requests
environment - Show environment settings
set <key-path> <value> - Modify environment settings
test-network - Test the network delay
test-policy <policy-name> - Test a proxy
test-all-policies - Test all proxies
test-group <group-name> - Immediately retest a policy group
kill <connection-id> - Kill an active connection
flush dns - Flush DNS cache
diagnostics - Run network diagnostics
set-log-level <log-level> - Change log level without writing to the profile
script evaluate <script-js-path> [mock-script-type] [timeout] - Load a script from a file and evaluate
Available parameters:
--raw - Output the result in raw JSON format
--remote/-r - Connect to a remote Surge instance instead of the local. e.g. --remote password@192.168.2.2:6170
-c <profile-path> - Check whether a profile is valid
The --remote parameter requires external-controller-access to be configured on the remote instance; see Surge Dashboard.
Expanded Management and Diagnostics Mac 6.8.0+
Surge CLI includes the following additional command groups. Use surge-cli <command> --help for the complete options supported by a command.
| Command | Purpose |
|---|---|
status |
Show the active profile, outbound mode, feature states, uptime, and version information. |
version |
Show Surge, Core, Controller protocol, operating-system, and device versions. |
dump summary |
Show a passive summary of interfaces, addresses, routers, DNS servers, Wi-Fi or cellular state, and configuration warnings. |
mode |
View or switch the Rule, Direct, and Global Proxy outbound modes. |
global-policy |
View or change the policy used in Global Proxy mode. |
policy-group |
List groups, inspect or change selections, and clear an automatic-group override. |
profile |
Inspect, validate, list, or switch profiles. Listing and validation are available on macOS. |
module |
List modules and enable or disable multiple modules. |
feature |
Inspect or control MitM, Rewrite, Scripting, HTTP Capture, Packet Capture, and Cellular Mode. System Proxy and Enhanced Mode are also available on macOS. |
device |
List or inspect Gateway Mode devices on macOS. |
reconnect-device |
Reconnect an access-point client on macOS. |
script list / script run |
List configured scripts or run a cron script by name. |
log / log watch |
Read recent logs or stream new log entries. |
logbook / script-log |
Read structured Logbook records or the log from a script execution. |
benchmark encryption |
Measure encryption and decryption performance on the Surge device. |
managed-profile update |
Force an update check for the active managed profile, validate the result, replace the profile, and reload it. |
test-policy-bandwidth |
Run a bandwidth test for a policy. |
proxy-runtime-status |
Show protocol-specific runtime details, including Tailscale and WireGuard state. |
These commands can operate compatible Surge iOS 5.21.0 and Surge tvOS 5.21.0 instances through --remote. Query and diagnostic commands use readable formatted output by default; use --raw for automation. Remote Controller passwords can be entered through the secure prompt, SURGE_CLI_PASSWORD, or --password-stdin instead of placing the password in the command line.
See Surge CLI Updates for an overview of the new commands.
Agent Skill Mac 6.5.0+
Surge includes an agent skill that exposes surge-cli capabilities to AI agents that support skills. The skill can be installed from /Applications/Surge.app/Contents/Resources/Skills/. Use a symbolic link when installing it so the skill can be updated together with the application bundle.
The bundled skill in Surge Mac 6.8.0 includes instructions for the expanded management and diagnostics commands described above. Mac 6.8.0+