Blog
Product Surge Team

Surge CLI Updates #2

Surge CLI gains routing decision diagnostics, DNS and GeoIP lookups, temporary rule management, gateway inspection, and an interactive terminal on iOS.

Following the previous round of Surge CLI updates, this update focuses on a question every Surge user has asked at some point: why did this request go through that policy? Surge CLI can now answer it directly — along with a set of new DNS, network, and gateway diagnostics — all without generating any real traffic.

Rule Matching and Explanation

  • Added rule match to evaluate the active rule set for a hostname or URL without creating a connection, and show the matched rule and final policy. Every matching attribute — process path, User-Agent, source address, client MAC address, device name, protocol, and more — can be supplied as key=value options, so you can reproduce exactly how a specific client would be routed.
  • Added rule explain to answer the deeper why: on top of the match result, it walks the entire policy-group resolution and reports every hop with its decision reason — a manual selection, an automatic test result, an override, or a load-balancing pick — along with the Smart Group selection, the underlying proxy chain, and evaluation notes.
$ surge-cli rule explain https://www.netflix.com
Matched rule: RULE-SET,Streaming,Streaming

Decision path:
  Streaming (select) -> Auto-US  [user selection]
  Auto-US (url-test) -> US-03  [automatic test result]

Final policy: US-03 (snell)
Duration: 3.42 ms
  • Added rule temp to list, add, remove, modify, or clear temporary rules. Temporary rules take effect immediately, precede all profile rules, and are discarded when Surge stops — ideal for testing a hypothesis end to end without touching your profile:
$ surge-cli rule temp add "DOMAIN-SUFFIX,example.com,Proxy"
$ surge-cli rule explain https://example.com
$ surge-cli rule temp flush

DNS and Network Diagnostics

  • Added dns lookup to resolve a domain through Surge’s DNS pipeline, showing the answers, the responding server, interface, route, timing, and cache lifetime.
  • Added dns trace to additionally include the complete resolver trace log. Both commands can force the lookup through a specific network interface.
  • Added geoip to look up an IP address in the local GeoIP and ASN databases — the same data that GEOIP and IP-ASN rules match against — including the database dates. No more cross-checking against third-party websites that may disagree with Surge’s own data.
  • Added http probe to send an HTTP HEAD request through a specified policy or the active rule system, reporting the status code, latency, selected policy, matched rule, and response headers.

Gateway Mode Diagnostics

  • Added vmnet to inspect the virtual network interface that backs Gateway Mode on macOS: vmnet status for the interface configuration and addresses, vmnet arp for the IPv4 neighbor table, vmnet ndp for the IPv6 neighbor table, and vmnet ra for the IPv6 Router Advertisement takeover state, including per-client link-local addresses and known routers.
  • Added security ban to inspect or clear the bans triggered by repeated unauthorized access attempts to the Controller ports.

Engine Inspection

  • Added dump performance to show engine memory usage, uptime, active requests, and the sizes of the DNS cache, virtual IP, and temporary rule tables — particularly useful when investigating memory pressure of the Network Extension on a remote iOS device.
  • Added dump rule-usage to show per-rule match counters, helping identify rules in a large profile that never match.
  • Added dump virtual-ip for targeted virtual IP database queries by IP address or domain, complementing the full dump virtual-ip-db.
  • Added benchmark rule-matching to measure the average matching time of the active rule set, for judging the real cost of very large rule sets.
  • Added watch speed to continuously display real-time upload and download speeds.
  • Added profile diff to compare the original profile with the effective profile after modules have been applied, in unified diff format.
  • The passive network summary is now the top-level summary command; the previous dump summary spelling remains available.

Interactive Mode

The interactive mode has grown into a proper shell: command auto-completion with Tab, command history, quoted arguments, and a reorganized help system — help shows a compact command index by category, and help <command> shows the detailed usage of one command or command family, such as help rule match or help dump.

Terminal on iOS

The same command-line experience is now available directly on iOS: the new Terminal utility provides a full interactive terminal on the device, with the complete command set, auto-completion, history, and Ctrl-C to stop streaming output. It works against the local Surge engine as well as remote devices managed through Remote Access.

Availability

The above updates apply to Surge Mac 6.9.0, Surge iOS 5.22.0, and Surge tvOS 5.22.0. As always, surge-cli can operate remote instances via --remote; the new commands require the remote instance to run a matching version.

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