📖 Command Reference

Commands that change your current shell (on, off, use, switch, best) must go through the proxy shell function installed by shell integration. Everything else works with the full binary name as well.

Accepted by every subcommand, before or after it.

NO_COLOR (set to any non-empty value) disables coloured output.

# Keep work and personal proxies in separate files
TSPM_CONFIG=~/work-proxies.json proxy best
tspm --config-file ~/work-proxies.json profile list

proxy on                     # Export proxy variables into this shell
proxy off                    # Unset them
tspm env on   # Print the statements without applying them

proxy on is shorthand for evaluating the output of env on. Both set every variable in both letter cases (http_proxy and HTTP_PROXY, and so on) plus GRADLE_OPTS and JAVA_TOOL_OPTIONS, because different tools read different names. off unsets exactly the same set.

Values are POSIX-quoted, so a host containing shell syntax is inert.

proxy status         # Proxy state, IPv4, IPv6, and location
proxy status --json  # The same, machine-readable

The JSON form is stable enough to script against:

proxy status --json | jq -r .ipv4

proxy profile list                 # Every profile, with the active one marked
proxy switch                       # Interactive arrow-key picker
proxy use work                     # Switch by key

proxy profile set work \
  --name "Work SOCKS" \
  --host 127.0.0.1 \
  --port 1080 \
  --protocol socks5                # Create or update, then make it active

proxy profile remove work          # Delete

profile set saves the profile as active but does not touch the variables of the shell you are in. With the proxy on, run proxy use work (or proxy on) afterwards to apply it.

--protocol accepts http, https, socks4, socks4a, socks5, socks5h. Omitted fields keep their current value on an existing profile.

Profiles are validated before being saved: the host must be a plausible hostname or IP, the port must be non-zero, and the protocol must be supported. An unknown profile key exits non-zero, so this works as expected:

proxy use work || proxy best

proxy import ./proxies.json
proxy import https://example.com/subscription.txt

Four input shapes are recognised: a full config.json, a bare map of profile key to profile, an array of profiles, or a newline-separated list of proxy URLs (socks5://host:port, # comments allowed). Invalid entries are reported and skipped; the rest still import.

proxy benchmark            # Latency and availability of every profile
proxy best                 # Benchmark, then switch to the fastest
proxy ping                 # Latency to the endpoints in config.json
proxy ping --timeout 2000  # With a 2 s timeout
proxy speedtest            # Real download throughput

benchmark tests the profiles one after another, probing all ping targets of each profile at once. Unreachable profiles sort last and are shown as a timeout rather than a number.

proxy dash

For Enter to update your shell you need the proxy_dash function from the shell integration; run proxy dash, not the bare binary.

proxy diagnose  # Local socket, session variables, and endpoint reachability
proxy monitor   # Health check; picks the fastest reachable profile on failure

monitor probes health_check_url from config.json through the proxy that is currently in your environment — ALL_PROXY, all_proxy or http_proxy. If the check fails, or none of those is set, it benchmarks the profiles and saves the fastest reachable one as active. It does not change the shell you run it in: apply the new profile there with proxy on, or run proxy on in a new shell.

diagnose lists http_proxy, https_proxy, ALL_PROXY and GRADLE_OPTS from your session. For the complete set that proxy on exports, run env | grep -i proxy.

proxy run curl https://example.com
proxy run -- curl -sS https://example.com
proxy run npm install

Runs a single command with the proxy variables applied, leaving your shell untouched. The child’s exit code is propagated, so proxy run ... && next-step behaves as expected. Flags are passed through; -- is optional but harmless.

proxy git status  # Show the current global git proxy
proxy git on      # Point git at the active profile
proxy git off     # Remove it

proxy export envfile > .env
proxy export docker    # --build-arg flags
proxy export curl      # -x flag

Exits non-zero when no profile is active, so a redirect cannot silently produce an empty file.

proxy config path        # Which config.json is in use
proxy config show        # Print it
proxy settings path
proxy settings show
proxy settings set --config-path ~/proxies.json
proxy lang en            # Persist the interface language

tspm init zsh          # Integration script
tspm completions zsh   # Completions only
proxy prompt                                     # Prompt indicator
proxy debug on                                   # Log the shell hand-off

completions supports zsh, bash, fish and powershell. init already includes completions, so you only need one of the two.

Turn debug on when proxy dash fails to update your shell; it logs the hand-off to ~/.tspm-debug.log.