Run terminal commands through a proxy.

Choose a country or city and route a shell session or a single command through a proxy. Your other apps and terminals keep their normal connection. Learn more at shellroute.com.

Need to reproduce country-specific behavior? Run the same command through another country while the rest of your machine keeps its normal connection.

npm install -g shellroute

Or via Homebrew:

brew install shellroute/tap/shellroute

Or via Go:

go install github.com/shellroute/shellroute-cli/cmd/shellroute@latest

Or download binaries from GitHub Releases.

Supports macOS and Linux.

# Log in. A new account is created automatically.
shellroute login

# Shellroute opens after login. Run these inside it:
/connect US
curl https://ipinfo.io/json

shellroute run DE -- curl https://ipinfo.io/json

Read the full quickstart.

For tools configured with an explicit proxy URL:

shellroute proxy --country US

# In another terminal
curl -x http://127.0.0.1:41900 https://ipinfo.io/ip

Already have a proxy, from a provider or your own server? Save it under a name you choose and use that name wherever a country code goes. No Shellroute account is needed and nothing is billed.

your-proxy-name below is a placeholder: the alias you pick when saving the proxy, 3 to 32 characters of lowercase letters, digits, _ or -. Replace USER, PASSWORD, HOST and PORT with what your provider gave you.

# 1. Save it. Schemes: http, https (TLS to the proxy), socks5, socks5h.
shellroute upstream add your-proxy-name http://USER:PASSWORD@HOST:PORT

# 2. Check it: one tunnel, exit IP, observed country, latency.
shellroute upstream test your-proxy-name
#   ✓ via your-proxy-name · exit IP 91.198.0.12 · DE (observed) · 212 ms

# 3. Use it.
shellroute run your-proxy-name -- curl https://ipinfo.io/json   # one command
shellroute                                                       # interactive shell, then: /connect your-proxy-name
shellroute proxy --upstream your-proxy-name                      # persistent local proxy on 127.0.0.1:41900

# Without saving, for example in CI:
shellroute run --proxy socks5://USER:PASSWORD@HOST:PORT -- curl https://ipinfo.io/json
SHELLROUTE_PROXY=http://USER:PASSWORD@HOST:PORT shellroute run -- curl https://ipinfo.io/json

# Manage saved proxies. Passwords are shown as ***.
shellroute upstream list
shellroute upstream remove your-proxy-name

The command only ever sees the local proxy on 127.0.0.1, so your proxy's credentials never reach it, your shell history or your CI logs. Where the proxy exits is observed when the route starts, not declared; a different exit per request is normal on rotating plans. Tested against 3proxy, gost, squid, SSH tunnels and the providers listed in docs/upstream-compatibility.md. Details.

All info commands support --format json.

git clone https://github.com/shellroute/shellroute-cli.git
cd shellroute-cli
./scripts/rebuild-cli.sh
./shellroute --version

Run all checks (lint, tests, audit, cross-compile): ./scripts/run-tests.sh. Requires Go 1.22+.

Your terminal -> shellroute CLI (local proxy) -> shellroute API -> Gateway -> Exit IP -> Internet

Shellroute implements each active route as a local HTTP proxy and provides standard proxy environment variables to the shell or child process. Clients that use those variables send requests through the selected proxy. Each session remains independent, while shellroute manages credentials, rotation, usage, and cleanup.

See what shellroute proxies.

The shellroute CLI is open source and connects to the shellroute service. The service uses prepaid credits. See pricing and the acceptable use policy.

• Config stored in ~/.shellroute/config.toml (mode 600)
• API key generated locally, only the hash is sent to the server
• No analytics or telemetry collected
• Health probe sends a CONNECT to httpbin.org:443 through the proxy to verify upstream connectivity

See CONTRIBUTING.md.

Apache 2.0. See LICENSE.

"shellroute" is a trademark. This license covers the code, not the brand. See NOTICE.