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, rule match, rule explain, rule temp
  Profile      profile, module, feature, managed-profile, external-resource
  Network      dns, geoip, http probe, test, diagnostics, flush dns
  Inspection   dump, watch, log, logbook, proxy-runtime-status
  Automation   script, script-log, benchmark
  Gateway      device, vmnet, security ban
  Control      reload, 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.
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. 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.
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.

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+

results matching ""

    No results matching ""