proxyctl

A tiny shell proxy controller to manage local proxy settings for your shell, package managers, Git, and SSH.

proxyctl currently supports zsh and Oh My Zsh. Bash and Fish support are planned.

Features

• Detect local proxy ports automatically.
• Enable an explicit HTTP, HTTPS, SOCKS4, or SOCKS5 proxy URL.
• Export uppercase and lowercase proxy environment variables.
• Configure npm, pnpm, yarn, and Git proxy settings.
• Manage NO_PROXY / no_proxy entries.
• Generate SSH ProxyCommand rules with HTTP, SOCKS4, and SOCKS5 support.
• Add per-host SSH rules: exclude, chain, wrap, remove, reset.
• Run connectivity checks with proxy test.
• Diagnose configuration issues with proxy doctor.
• Includes zsh completion.

Installation

Oh My Zsh custom plugin

git clone https://github.com/vangie/proxyctl.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/proxyctl

Add proxyctl to your plugin list in ~/.zshrc:

plugins=(... proxyctl)

Reload your shell:

source ~/.zshrc

Antidote

antidote bundle vangie/proxyctl

Zinit

zinit light vangie/proxyctl

Manual source

git clone https://github.com/vangie/proxyctl.git ~/.proxyctl

Add this to ~/.zshrc:

source ~/.proxyctl/proxyctl.plugin.zsh
fpath=(~/.proxyctl/completions ~/.proxyctl $fpath)
autoload -Uz compinit && compinit

Quick start

Detect and enable a local proxy:

proxy enable
proxy status
proxy test

Or enable an explicit proxy URL:

proxy enable http://127.0.0.1:7890
proxy enable socks5://127.0.0.1:1080

Disable proxy settings:

proxy disable

Example output

Proxy  ● enabled

ENV vars
  set       HTTP_PROXY HTTPS_PROXY FTP_PROXY RSYNC_PROXY ALL_PROXY + lower-case
  no_proxy  localhost,127.0.0.1,::1

tools
  npm/pnpm/yarn/git set

SSH rules  (~/.ssh/proxyctl.conf)
  [default]  *  →  nc -X connect -x 127.0.0.1:6152  (all other hosts)

Commands

proxy enable [url]        # Detect and enable proxy, or use explicit URL
proxy disable             # Disable proxy and clear managed tool configs
proxy status              # Show concise proxy state
proxy status --verbose    # Show full proxy details
proxy status --full       # Same as --verbose
proxy env                 # Print export statements
proxy detect              # Scan for a local proxy without enabling it
proxy url                 # Print current proxy URL
proxy test [url|host]     # Test proxy connectivity
proxy doctor              # Run diagnostics

Detection

proxy enable detects a proxy in this order:

1. SHELLPROXY_URL
2. cached URL from ~/.cache/proxyctl-url
3. executable config script at ${SHELLPROXY_CONFIG:-~/.config/proxy}
4. local port scan

Default scanned ports:

8123 6152 41091 7890 1086 1087

Environment variables

When enabled, proxyctl exports:

HTTP_PROXY HTTPS_PROXY FTP_PROXY RSYNC_PROXY ALL_PROXY
http_proxy https_proxy ftp_proxy rsync_proxy all_proxy
NO_PROXY no_proxy

Use this to print export statements:

proxy env

Tools

proxyctl configures supported tools when they are installed:

• npm: proxy, https-proxy
• pnpm: proxy, https-proxy
• yarn: proxy, https-proxy, httpProxy, httpsProxy
• Git: http.proxy, https.proxy

proxy disable clears these managed settings.

NO_PROXY

Default value:

localhost,127.0.0.1,::1

Manage entries:

proxy no-proxy list
proxy no-proxy add github.com
proxy no-proxy add "*.local"
proxy no-proxy remove github.com
proxy no-proxy reset

SSH rules

proxyctl writes SSH proxy rules to:

~/.ssh/proxyctl.conf

It also ensures this include exists in ~/.ssh/config:

Include ~/.ssh/proxyctl.conf

Manage SSH rules:

proxy ssh list
proxy ssh show <host>
proxy ssh exclude <host>
proxy ssh chain <host> <jump-host>
proxy ssh wrap <host> <command>
proxy ssh remove <host>
proxy ssh reset

Examples:

proxy ssh exclude internal.example.com
proxy ssh chain prod.example.com bastion.example.com
proxy ssh wrap legacy.example.com 'ssh-helper --connect'

Diagnostics

Test connectivity:

proxy test
proxy test https://api.github.com
proxy test github.com

Run full diagnostics:

proxy doctor

If you see proxy port is not reachable, make sure your proxy client is running and the configured URL matches the actual listening port.

Uninstall

Disable managed proxy settings first:

proxy disable

Then remove the plugin directory:

rm -rf ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/proxyctl

Optional cleanup:

rm -f ~/.cache/proxyctl-state ~/.cache/proxyctl-url ~/.cache/proxyctl-no-proxy ~/.cache/proxyctl-ssh-rules
rm -f ~/.ssh/proxyctl.conf

Remove this line from ~/.ssh/config if you no longer need it:

Include ~/.ssh/proxyctl.conf

Roadmap

• proxy status --plain
• proxy status --json
• proxy profiles / presets
• Bash support
• Fish support
• Homebrew tap or installer script

License

MIT