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.