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) or installed (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 list shows 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-memory for the recent requests kept while HTTP Capture is off, on-disk for 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.

results matching ""

    No results matching ""