Back to Blog
Product

Surge CLI Updates

Surge CLI has been expanded with comprehensive management and diagnostics commands across Surge Mac, Surge iOS, and Surge tvOS.

Surge CLI has been significantly expanded into a comprehensive command-line management and diagnostics interface, with the following new commands:

New Commands

  • Added status to display the active profile and its full path, outbound mode, feature states, uptime, and version information.
  • Added version to display Surge, Core, Controller protocol, operating system, and device versions.
  • Added dump summary to provide a passive overview of the current network environment, including interfaces, IP addresses, default router, DNS servers, cellular or Wi-Fi information, and configuration warnings.
  • Added mode to view or switch between Rule, Direct, and Global Proxy modes.
  • Added global-policy to view or change the policy used in Global Proxy mode.
  • Added policy-group to list policy groups, inspect their current selections, manually select a policy, or clear an automatic-group override.
  • Added profile to list, inspect, validate, and switch profiles. Profile listing and validation are available on macOS.
  • Added module to list modules and enable or disable multiple modules in one operation.
  • Added feature to inspect and control MitM, Rewrite, Scripting, HTTP Capture, Packet Capture, and Cellular Mode. On macOS, it also supports System Proxy and Enhanced Mode.
  • Added device to list Gateway Mode devices or inspect an individual device by identifier or MAC address on macOS.
  • Added reconnect-device to reconnect a specified access-point client from the command line on macOS.
  • Added script list to display configured scripts and script run to execute a cron script by name, including disabled scripts, while returning its output or exception.
  • Added log to retrieve up to 10,000 recent log lines from either the persistent log file or the more detailed in-memory log.
  • Added log watch to continuously stream newly generated, unfiltered logs.
  • Added logbook to display recent structured Logbook records.
  • Added script-log to retrieve the log from a specific script execution.
  • Added benchmark encryption to measure the encryption and decryption performance of the device running Surge, with correctness, integrity, and tamper-detection checks.

Diagnostic Improvements

Existing diagnostic commands have also been improved:

  • proxy-runtime-status now provides detailed runtime information for Tailscale and WireGuard, including traffic, recent errors, peer handshakes, DERP connections, Exit Node state, peer paths, and MagicDNS information.
  • Query and diagnostic commands now produce structured, human-readable terminal output by default, while --raw remains available for automation.
  • Commands that change settings now return the resulting state and properly report failures. System Proxy and Enhanced Mode commands wait for the actual state transition to complete.
  • Remote Controller passwords can now be supplied through a secure terminal prompt, SURGE_CLI_PASSWORD, or --password-stdin, avoiding exposure in the process command line.
  • Remote connections now support bracketed IPv6 addresses and include timeouts for stalled connections and finite operations.
  • Interactive mode now supports quoted arguments and backslash escaping.

Availability

The above updates apply to Surge Mac 6.8.0, Surge iOS 5.21.0, and Surge tvOS 5.21.0. Please notice surge-cli can operate remote instances via --remote.

The corresponding updates have also been added to the AI Skills documentation. After the update, AI Agents can automatically gain the new capabilities.