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, or help <command> for the detailed usage of one command or command family, for example help rule match or help dump.
Surge CLI
Usage: surge-cli <command> [arguments]
Command groups:
Status status, summary, version
Routing mode, global-policy, policy-group, policy-avoid, rule match, rule explain, rule temp
Profile profile, module, feature, capture-filter, managed-profile, external-resource
Network dns, geoip, http probe, test, diagnostics, flush dns
Inspection dump, watch, log, logbook, proxy-runtime-status, capture-session
Automation script, script-log, benchmark
Gateway device, vmnet, security ban
Control reload, restart-engine, restart-ponte-server, switch-profile, kill, stop, unattended-upgrade
Environment environment, set, set-log-level
Available parameters:
--raw - Output raw JSON instead of the human-readable command format
--remote/-r <host:port> - Connect to a remote Surge instance. IPv6 uses [address]:port
--password-stdin - Read the remote password from the first line of stdin
Remote password fallback: SURGE_CLI_PASSWORD, then a secure terminal prompt
Utilities:
--check/-c <path> - Check whether a profile is valid.
Running surge-cli without a command enters the interactive mode, which supports command auto-completion and history.
The --remote parameter requires external-controller-access to be configured on the remote instance; see Surge Dashboard.
Editor Language Server Mac 6.10.0+
The offline language server requires Surge Mac 6.10.0 or later.
surge-cli lsp
The optional --stdio flag is accepted for clients that append it automatically.
An editor's LSP client starts this process and communicates over standard input and output. It does not require Surge to be running, does not change the active configuration, and cannot be combined with remote Controller options.
For VS Code, install the separately distributed Surge Language Support
extension, then select Surge Configuration, Surge Module, or Surge Rule Set
as the document's language mode. The extension provides syntax highlighting and
starts the CLI automatically. If necessary, set surge.languageServer.path in
User Settings to the absolute path of an LSP-capable CLI. Extension 0.1.7 defaults
to /Applications/Surge.app/Contents/Applications/surge-cli; older Surge builds
without the lsp command must be updated before diagnostics are available.
The VS Code extension (0.1.2+) automatically recognizes .conf files in Surge's
standard iCloud and local Profiles directories. Elsewhere, it recognizes files
whose first 64 KiB contain [Rule] together with [Proxy] or [Proxy Group].
From extension version 0.1.4, .conf, .txt, .module, and extensionless files
with a nonempty #!name= declaration before the first section in that prefix
are recognized as Surge Module, taking priority over profile detection.
Explicit files.associations entries take priority, and manual language changes
are preserved within the current editor session. Disable this behavior with
surge.autoDetect: false. From extension version 0.1.6, rule sets are detected
by content regardless of extension: within the inspected prefix, the first up to
20 nonempty, non-comment lines must match common rule-set syntax, with at least
two matching lines. Pure domain lists, YAML, and rules with a target-policy column
are excluded. Single-line or complex rule sets may require manual language selection.
Diagnostics include unsaved edits. Profiles report the first parsing or
cross-reference error. Unknown keys in [General] produce warnings on the key
name; common, iOS, macOS, and supported legacy keys are accepted without case
sensitivity. Modules and rule sets can report multiple invalid lines.
Open the main profile alongside its included section files to validate those
files in context; their unsaved contents take precedence over disk contents.
Standalone .dconf files are treated as partial profiles: syntax and General key
checks remain enabled, while missing FINAL, policy, and script reference checks
are deferred until their including main profile is open.
Modules are checked independently, without rejecting references supplied by a
main profile. Lines using module arguments without default values are skipped
with an informational diagnostic. Module header #!requirement and #!system
restrictions are ignored during editor validation, allowing modules for other
platforms to be checked. Inline conditions still use the local Mac environment.
Normal module loading continues to enforce the header restrictions.
Rule Set mode is for RULE-SET syntax, not DOMAIN-SET files. Remote includes use existing local caches; the language server does not download resources or apply installed modules. Completion, formatting, and definition navigation are not provided in the initial version.
Other LSP clients can register language IDs surge, surge-module, and
surge-ruleset, using full text synchronization and push diagnostics.
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. |
policy-avoid |
list, add <policy>, remove <policy> or clear the policies that automatic groups avoid while another member is available. See Temporary Avoidance. policy-group list marks the avoided options. iOS 6.0.0+ Mac 6.11.0+ |
profile |
Inspect, validate, list, or switch profiles. Listing and validation are available on macOS. |
module |
List modules and enable or disable multiple modules. module list also shows each module's type, declared version, last modification time, and how many lines each section adds; module show <name> adds every #! header field and the module text. See Module Details. iOS 6.0.0+ Mac 6.11.0+ |
feature |
Inspect or control MitM, Rewrite, Scripting, HTTP Capture, Packet Capture, and Cellular Mode. System Proxy and Enhanced Mode are also available on macOS. |
capture-filter |
Inspect or change the filters that decide which requests are recorded, in memory and during HTTP Capture. See HTTP Capture Automation. iOS 6.0.0+ Mac 6.11.0+ |
capture-session |
List the HTTP Capture sessions saved to disk, read their requests, and fetch captured request and response bodies. See HTTP Capture Automation. iOS 6.0.0+ Mac 6.11.0+ |
dump traffic-stat-breakdown |
Show the traffic of today, this month and last month grouped by one dimension and then another, chosen from host, policy, interface, process and device. For example, dump traffic-stat-breakdown policy host ranks the hosts behind each policy. iOS 6.0.0+ Mac 6.11.0+ |
dump traffic-stat-records <period> |
List the traffic and request count of each host, policy and interface for today, this-month or last-month, as shown in Traffic Statistics on Surge iOS, which also uses it to show the traffic of a remote Surge. iOS 6.0.0+ Mac 6.11.0+ |
dump traffic-stat-hourly |
Show today's traffic per local hour, split into DIRECT and proxied, and each policy's total for today. Use --raw for every policy's hourly figures. iOS 6.0.0+ Mac 6.11.0+ |
dump dns-lookup-times |
List how long each of the last 24 lookups that went to a DNS server took, in milliseconds, with the minimum, median, maximum and average. iOS 6.0.0+ Mac 6.11.0+ |
dump policy-usage |
Show each proxy's recent use score by policy line hash, highest first. The score decays to zero ten minutes after the proxy was last used. iOS 6.0.0+ Mac 6.11.0+ |
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. |
restart-ponte-server |
Restart the device's Ponte server: its channels are set up again, and connections to it from other devices are dropped. Ponte servers run on Surge Mac and Surge tvOS; the command fails when Ponte isn't enabled. iOS 6.0.0+ Mac 6.11.0+ |
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. Pass the policy name, for example surge-cli proxy-runtime-status "My Tailscale". |
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.
Routing and Network Diagnostics Mac 6.9.0+
Surge CLI includes the following commands for diagnosing routing decisions and network state without generating real traffic.
| Command | Purpose |
|---|---|
rule match |
Evaluate the active rule set for a hostname or URL without creating a connection, and show the matched rule and final policy. All matching attributes — process path, User-Agent, source address, client device, protocol, and more — can be supplied as key=value options. |
rule explain |
Show why a request selects a particular policy: the matched rule, each policy-group decision with its reason, the Smart Group selection, and the underlying proxy chain. |
Both rule match and rule explain also report where the matched rule was written — the profile file and line, or the module that added it — and, when it is a RULE-SET or DOMAIN-SET, the entry inside the set that matched, such as DOMAIN-SUFFIX,example.com in https://example.com/China.list. Nested rule sets are listed from the innermost one outward. Rule sets are compiled into indexes when loaded, so the entry is identified by its content rather than a line number. iOS 6.0.0+ Mac 6.11.0+
| rule temp | List, add, remove, modify, or clear temporary rules. Temporary rules take effect immediately, precede all profile rules, and are discarded when Surge stops, making them convenient for debugging sessions. |
| dns lookup / dns trace | Resolve a domain through Surge's DNS pipeline and show the answers, responding server, interface, route, timing, and cache lifetime. dns trace also includes the complete resolver trace log, and the lookup can be forced through a specific network interface. |
| geoip | Look up an IP address in the local GeoIP and ASN databases — the same data GEOIP and IP-ASN rules match against — and show the database dates. |
| http probe | Send an HTTP HEAD request through a specified policy or the active rule system, reporting the status, latency, selected policy, matched rule, and response headers. |
| summary | The passive network summary is now a top-level command; the previous dump summary spelling remains available. |
| profile diff | Compare the original profile with the effective profile after modules have been applied. |
| vmnet | Inspect the virtual network interface used by Gateway Mode on macOS: interface status and addresses, the ARP table, the IPv6 NDP table, and the IPv6 RA takeover state. |
| security ban | Inspect or clear the bans triggered by repeated unauthorized access to the Controller ports. |
| dump performance | Show engine memory usage, uptime, active requests, and the sizes of the DNS cache, virtual IP, and temporary rule tables. |
| dump rule-usage | Show per-rule match counters, helping identify rules that never match. |
| dump virtual-ip | Query the virtual IP database for a specific IP address or domain. |
| benchmark rule-matching | Measure the average matching time of the active rule set. |
| watch speed | Continuously display real-time upload and download speeds. |
These commands can also operate compatible Surge iOS and Surge tvOS instances through --remote.
Module Details iOS 6.0.0+ Mac 6.11.0+
surge-cli module list
surge-cli module show "router.com"
module list shows, for every available module:
- its state and type:
internal(bundled with Surge),local(a file in the profile directory) orinstalled(installed from a URL); - the version, when the module header declares
#!version; - when the module file was last modified;
- how many non-comment lines each section adds, for example
MITM 1, Rule 12, Script 3. The module is loaded with its stored arguments to count them, so a module that fails to load shows the reason instead.
module show <name> shows the same details for one module, every #! header field (including fields Surge does not interpret, such as #!author and #!homepage), the names of the declared arguments, and the module text as written. Argument values are never shown.
Surge does not check whether the remote copy of an installed module has changed; updating modules remains an action in the app.
Editing Profile Sections iOS 6.0.0+ Mac 6.11.0+
A profile can be spread over several files with #!include, so Surge CLI changes it one section at a time rather than as a whole.
surge-cli profile section list
surge-cli profile section get Rule > rule.txt
surge-cli profile section set Rule rule.txt <revision>
profile section listshows every section, the file that holds it, whether it can be edited, and its revision.profile section get <name>prints the content of a section without its header, ready to be edited and passed back.profile section set <name> <file|-> [revision]replaces the entire content of the section with the file's content (-reads from standard input), or creates the section in the main profile when it does not exist yet.
A section is written to the file that actually holds it, and every other section and file is left untouched. The whole profile is validated with the new content before anything is written, then reloaded. When a revision is given, the change is refused if the section was modified after it was read.
Managed and enterprise profiles, sections included from a URL or a managed profile, sections assembled from several files, and sections that mix their own lines with #!include directives are read-only.
Like the other commands, this works with Surge iOS through --remote. Surge iOS uploads a changed file to iCloud Drive right away, and to Dropbox the next time the app is opened. When the Surge folder in iCloud Drive contains more than 200 files and folders, background syncing is unavailable and profiles stored there cannot be modified this way while the app is closed; Surge warns about it when starting.
HTTP Capture iOS 6.0.0+ Mac 6.11.0+
Two commands cover HTTP Capture. Together with feature set capture on|off, they run a capture session and read its results without the app, which also works with Surge iOS through --remote.
capture-filter list | get <in-memory|on-disk> | set <in-memory|on-disk> <option>=<value>...inspects and changes the filters that decide which requests are recorded:in-memoryfor the recent requests kept while HTTP Capture is off,on-diskfor a capture session.capture-session list [include-size] | dump <session> [offset=N] [limit=N] [filter=TEXT] | data <session> <key> <request|response> [offset=N] [length=N]lists the capture sessions saved to disk, reads their requests, and fetches captured request and response bodies.
See HTTP Capture Automation for the complete workflow, from setting the session limits to decoding the bodies, with every option of both 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+
The bundled skill in Surge Mac 6.9.0 additionally covers the routing and network diagnostics commands, including rule match/rule explain, temporary rule management, DNS and GeoIP lookups, and the vmnet gateway diagnostics. Mac 6.9.0+
Shortcuts iOS 6.0.0+
Surge iOS provides a Run Surge CLI Command action in the Shortcuts app. It runs one command on the running Surge engine, such as dump policy or policy-group list, and returns the output as text. Enable Raw JSON Output to get each controller response as a line of JSON instead, like --raw.
Commands that keep streaming output until stopped, such as watch, log watch and diagnostics, are not supported. help lists the available commands and works even when the engine is not running; other commands fail if the engine is not running.