proxy-manager

proxy-manager

Manage Webshare proxies with the webshare CLI: list active proxies, dump the proxy list to a file, refresh rotating pools, read and update proxy config, manage IP allowlists, build proxy URLs, inspect subscription plans and usage, and kick off an express-checkout flow to buy more proxies. Use when the user wants to work with webshare.io proxies — not scraping, just provisioning and ops.

6stars
0forks
Updated 10/2/2026
SKILL.md
read-only
name
proxy-manager
description

Manage Webshare proxies with the webshare CLI: list active proxies, dump the proxy list to a file, refresh rotating pools, read and update proxy config, manage IP allowlists, build proxy URLs, inspect subscription plans and usage, and kick off an express-checkout flow to buy more proxies. Use when the user wants to work with webshare.io proxies — not scraping, just provisioning and ops.

version
2.0

Webshare Proxy Manager

You help the user manage their Webshare proxy account through the webshare
CLI: list proxies, refresh the pool, configure auth, build proxy URLs, watch
usage, and purchase more capacity via the express-checkout flow.

What this skill does / needs / will not do

Does: everything in the workflow below, through webshare CLI commands.

Needs:

  1. The webshare CLI — install with brew install webshare-proxy/tap/webshare,
    or download a binary from
    https://github.com/webshare-proxy/webshare-cli/releases.
  2. A Webshare account — sign up at https://www.webshare.io/ (10 free
    proxies, no card required).
  3. An API key from https://dashboard.webshare.io/userapi/keys, exported as
    WEBSHARE_API_KEY. Verify with webshare whoami.

Will not do:

  • Targeted replacement of individual proxies — the CLI has no
    per-proxy replacement command. webshare proxies refresh replaces the
    entire list; for replacing specific blocked IPs point the user at the
    sibling proxy-optimizer skill or the dashboard.
  • Headless purchases — checkout always finishes in the browser; the
    express-checkout script only pre-fills the page.
  • Scraping. That's the scraper skill.

Workflow

Step 1: Identify the target plan

Webshare accounts can own multiple plans simultaneously. Before any action
that touches proxies, config, or IP allowlists, run:

webshare plans list

If there is more than one active plan, show the list (id, type, proxy count,
status) and ask which plan to operate on (use AskUserQuestion), then pass
--plan <id> on every subsequent command. If there is exactly one plan you
can skip asking — but still pass --plan explicitly so the intent is obvious
in the command history. webshare plans show <plan-id> gives full detail.

Step 2: Run the action

Ask which action the user wants (use AskUserQuestion if unclear):

  • plans — webshare plans list / webshare plans show <plan-id>
  • list — webshare proxies list --plan <id> (filters: --country us,fr,
    --limit N, --mode direct|backbone; formats: --format txt|csv|json)
  • download — webshare proxies list --plan <id> > proxies.txt writes the
    standard address:port:username:password lines most tools accept.
    webshare proxies download fetches the server-rendered list instead
    (--auth sourceip for IP-auth setups).
  • proxy-url — webshare proxy-url builds ready-to-use connection URLs:
    --country us --rotate for per-request rotation, --sessions 5 for a
    sticky-session worker pool, --session <id> to pin one.
  • config — webshare config show / webshare config set (--username,
    --password, --request-timeout, --idle-timeout)
  • ipauth — webshare ipauth list / webshare ipauth add --current (or an
    explicit IP) / webshare ipauth remove <id-or-ip>
  • stats — webshare stats --since 24h (or --hourly);
    webshare activity list --error '*' shows recent failed requests
  • refresh — webshare proxies refresh replaces the whole list;
    webshare proxies replaced shows past replacements and successors
  • buy — open an express-checkout URL in the browser (see below)

Read references/CLI.md for the full flag reference and JSON output notes.

Buying proxies (express-checkout)

Use scripts/express_checkout.py. It builds a dashboard URL with the right
query string and opens it in the default browser. Six presets are supported:

  • datacenter-shared / datacenter-semidedicated / datacenter-dedicated
  • isp-shared / isp-semidedicated / isp-dedicated (static residential)
  • residential (rotating residential, shared only)

Ask the user for preset, proxy count, bandwidth (GB, datacenter/ISP only), and
countries (dict of ISO codes → count, or ZZ for any). Example:

python scripts/express_checkout.py datacenter-dedicated \
  --count 75 --bandwidth 5000 --countries ZZ=75

The script prints the URL and opens the browser. The user completes checkout
manually in the dashboard — there is no headless purchase path.

Key principles

  • Never print the API key. The CLI reads WEBSHARE_API_KEY from the
    environment; never echo it or paste it into commands.
  • Confirm before mutations. webshare proxies refresh consumes an
    on-demand refresh and replaces every proxy — always confirm with the user
    first and let the CLI's own confirmation prompt stand (never pass --yes
    unless the user explicitly asked). Same care for config set,
    ipauth remove and subusers delete.
  • Prefer --json when you need to parse. Every command supports it, and
    piped output is machine-readable automatically.
  • Country codes are ISO 3166-1 alpha-2. ZZ means "any country".
  • Residential plans are backbone-only. If proxies list returns nothing,
    try --mode backbone or webshare proxy-url.