| name | Surge |
| description | Operate and troubleshoot Surge via surge-cli, including command discovery, runtime diagnostics, state inspection (dump/watch/test), and environment mutation with set key-paths. Use when a task asks to control Surge behavior, inspect live status, adjust policy/runtime switches, or automate Surge operations from CLI. |
Surge CLI Ops
Use this skill to run Surge operations safely and consistently through surge-cli.
Startup
- Resolve executable path in this order:
surge-cli in PATH/Applications/Surge.app/Contents/Applications/surge-cli
- Prefer JSON output with
--raw for machine parsing.
- If operating on remote instances, add
--remote password@host:port.
Baseline Context Workflow
Before mutating runtime settings, collect baseline state:
surge-cli --raw environmentsurge-cli --raw dump policysurge-cli --raw dump profile
After changes, re-run the relevant read commands to verify effects.
Mutation Rules
When using set:
- Use minimal key-path deltas only.
- Batch related updates in one command when possible.
- Treat
<nil> and (null) as null assignments.
- Re-check
environment immediately after mutation.
Examples:
surge-cli --raw set ProxyMode=2
surge-cli --raw set ProxyGroupSelection.Proxy=HK
surge-cli --raw set AutoPolicyGroupOverride.Streaming=<nil>
Streaming Command Handling
For streaming commands (for example diagnostics/bandwidth tests):
- Process incremental chunks.
- Respect completion markers (
hasMore=false or command-specific completion payload).
- Do not assume a single response frame.
Platform and Capability Notes
- Some commands are platform-limited (for example certain device-management and profile-edit commands).
- Validate capability and platform before execution in automation workflows.
Reference
Read detailed command semantics, full command list, and environment key definitions from:
