Surge
Apps & AutomationSurge is an Agent Skill for apps & automation published in the HotKids/Rules repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/HotKids/Rules/blob/HEAD/.claude/skills/surge/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/surge, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Surge CLI Ops
Use this skill to run Surge operations safely and consistently through surge-cli.
Startup
- Resolve executable path in this order:
surge-cliinPATH/Applications/Surge.app/Contents/Applications/surge-cli
- Prefer JSON output with
--rawfor 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
environmentimmediately 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=falseor 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: