OpenParable
Skip to content
← Back to skills

Surge

Apps & Automation

Surge 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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

  1. Resolve executable path in this order:
    • surge-cli in PATH
    • /Applications/Surge.app/Contents/Applications/surge-cli
  2. Prefer JSON output with --raw for machine parsing.
  3. If operating on remote instances, add --remote password@host:port.

Baseline Context Workflow

Before mutating runtime settings, collect baseline state:

  1. surge-cli --raw environment
  2. surge-cli --raw dump policy
  3. surge-cli --raw dump profile

After changes, re-run the relevant read commands to verify effects.

Mutation Rules

When using set:

  1. Use minimal key-path deltas only.
  2. Batch related updates in one command when possible.
  3. Treat <nil> and (null) as null assignments.
  4. 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):

  1. Process incremental chunks.
  2. Respect completion markers (hasMore=false or command-specific completion payload).
  3. Do not assume a single response frame.

Platform and Capability Notes

  1. Some commands are platform-limited (for example certain device-management and profile-edit commands).
  2. Validate capability and platform before execution in automation workflows.

Reference

Read detailed command semantics, full command list, and environment key definitions from: