Start Here Quickstart Agents & Automation Use Cases Interactive Mode Direct Mode Proxy Mode Support

Direct Mode

Run a single command through the proxy without opening an interactive shell. Shellroute connects, routes your command's HTTP traffic through the exit IP, and disconnects. For scripts, CI, agents, and one-off commands.

Authentication

Direct mode works with --api-key flag, SHELLROUTE_API_KEY env var, or a stored key from shellroute login. Get your key with shellroute reveal-key from any logged-in machine.

auth options
# Env var (set once, all commands use it)
export SHELLROUTE_API_KEY=pk_29f6a...

# Inline flag (per-invocation, nothing stored)
shellroute --api-key pk_29f6a... run US -- curl https://httpbin.org/ip

# Or use a stored key from shellroute login
shellroute run US -- curl https://httpbin.org/ip
Auth priority: --api-key flag > SHELLROUTE_API_KEY env var > stored key from login

Direct login

Log in without interactive prompts. The same email + code flow, but with flags instead of a terminal prompt.

non-interactive login
# 1. Agent requests a code
shellroute login --email [email protected] --request-code

# 2. Human checks email, gives code to the agent

# 3. Agent verifies and stores the key
shellroute login --email [email protected] --verify-code 847291

# 4. Done — agent can now use shellroute
shellroute run US -- curl https://httpbin.org/ip

After verification, the key is stored locally. The agent only needs to log in once — subsequent commands use the stored key automatically.

shellroute run

Run a single command through the proxy. The country can be a positional arg or --country flag.

Flag Description Default
<country> 2-letter country code (positional or --country US) required
--city <name> Target a specific city. Fails if not found. any
--iptype <type> residential ($3/GB), datacenter ($1/GB), or mix residential
--sticky Attempts to keep the same IP on reconnect. off
--no-stat Suppress session summary. Clean output for piping. off
-- <command> Everything after -- runs through the proxy required
examples
shellroute run US -- curl https://httpbin.org/ip
shellroute run --country DE --city Berlin -- python3 check.py
shellroute run --iptype datacenter US -- npm run test:geo
shellroute run --sticky US -- python3 monitor.py
shellroute run --no-stat GB -- curl -s https://ipinfo.io/ip
shellroute --api-key pk_... run US -- curl https://httpbin.org/ip

shellroute proxy

Start a persistent proxy in the background. Prints connection info and blocks until Ctrl+C. Use this when you need a proxy in one terminal while working in another.

Flag Description Default
--country <code> 2-letter country code required
--city, --iptype, --sticky Same as shellroute run
--format <fmt> json or env (prints export commands for another terminal) json
examples
# Terminal 1 — start proxy (blocks until Ctrl+C)
shellroute proxy --country US

# Terminal 2 — use the proxy
export HTTP_PROXY=http://127.0.0.1:41900
curl https://httpbin.org/ip

# Or get env vars to paste
shellroute proxy --country DE --format env

Other commands

These work from any terminal — no active session required.

Command Description
shellroute login Log in with email OTP. Creates account if new. Also supports --email + --request-code / --verify-code for non-interactive login.
shellroute logout Remove stored credentials from this machine
shellroute reveal-key Print your API key (requires prior login)
shellroute status Show all active sessions with live data and cost. Supports --format json.
shellroute balance Show credit balance and per-GB rates. Supports --format json.
shellroute countries List available countries with IP counts. Supports --format json.
shellroute cities <country> List cities in a country with IP counts. Supports --format json.
shellroute proxy stop Stop running proxy sessions. Does not affect interactive or run sessions.
examples
shellroute status
shellroute balance --format json
shellroute countries
shellroute cities US
shellroute cities DE --format json

Global flags

Flag Description
--api-key <key> Authenticate for this invocation. Not stored on disk.
--skip-version-check Skip version check on startup (useful in CI)
--version Print version and exit
Interactive Mode Agents & Automation