Skip to main content

How can I use the Webshare CLI?

Learn how to install the Webshare CLI, sign in, and manage your account, proxies, usage, and IP authorizations from the terminal.

Webshare CLI lets you manage your Webshare account and proxies from the terminal. You can export your proxy list, check usage, manage IP authorizations, and more, without opening the dashboard.

Before you start: you'll need a Webshare account. Most Webshare Skills also use the CLI, so installing it is the first step for those too. See What are Webshare Skills? for details.

Install the Webshare CLI

Follow the steps for your operating system.

For macOS

  1. Install Homebrew if you don't have it.

  2. Run this command in your terminal:

    brew install webshare-proxy/tap/webshare

For Linux

  1. Check your processor type:

    uname -m

    If it shows x86_64, use the amd64 file. If it shows aarch64 or arm64, use the arm64 file.

  2. Download the archive for your processor.
    ​For amd64:

    curl -LO https://github.com/webshare-proxy/webshare-cli/releases/download/v0.3.0/webshare_0.3.0_linux_amd64.tar.gz

    For arm64:

    curl -LO https://github.com/webshare-proxy/webshare-cli/releases/download/v0.3.0/webshare_0.3.0_linux_arm64.tar.gz

  3. Unpack it (use the file name you downloaded):

    tar -xzf webshare_*_linux_*.tar.gz

  4. Move the program into your PATH:

    sudo mv webshare /usr/local/bin/

For Windows

  1. Download webshare_windows_amd64.zip from the latest release. On an ARM device, download webshare_windows_arm64.zip instead.

  2. Right-click the file and choose Extract All. Put the extracted folder somewhere permanent, such as C:\Tools\webshare.

  3. Add that folder to your PATH:

    1. Press the Windows key, search for Edit the system environment variables, and open it.

    2. Click Environment Variables.

    3. Under User variables, select Path and click Edit.

    4. Click New, paste the folder path (for example C:\Tools\webshare), then click OK on each window.

  4. Close and reopen PowerShell so the change takes effect.

Check that it is installed

Run:

webshare --version

You should see a version number. If you get "command not found" or "not recognized," see Troubleshooting Common Issues.

Sign in to the Webshare CLI

You can sign in with your browser or with an API key. Use the browser method on your own computer. Use an API key on servers, CI, SSH sessions, and containers, where a browser isn't available.

Method 1: Sign in with your browser

  1. Run webshare login.

  2. Your browser opens. Log in to Webshare if asked, then allow access.

  3. Run webshare whoami to confirm. It should show your account details.

To sign out, run webshare logout. While you're signed in, the CLI appears under Integrations → Connected Apps in your dashboard.

Method 2: Sign in with an API key

  1. In the Webshare dashboard, go to Integrations → API Keys, and create a key.

  2. Set the key in your terminal:

    • macOS and Linux: export WEBSHARE_API_KEY=your-key

    • Windows PowerShell: $env:WEBSHARE_API_KEY="your-key"

  3. Run webshare whoami to confirm.

Good to know

  • If both a stored login and an API key are present, the API key is used.

  • To keep the key across sessions on macOS or Linux, add the export line to your shell profile (for example ~/.bashrc or ~/.zshrc). On Windows, run setx WEBSHARE_API_KEY "your-key" and open a new PowerShell window.

  • Treat your API key like a password: it gives full access to your Webshare account. Don't share it or commit it to a code repository. If it's exposed, delete it under API Keys and create a new one.

Run your first command

Try one of these:

  • webshare whoami shows which account you're signed in to.

  • webshare proxies list --format csv > proxies.csv exports your proxy list as a CSV file.

  • webshare stats shows your bandwidth and request stats.

Common commands

  • Proxies: webshare proxies list (add --country or --limit; output as a table, txt, csv, or json), webshare proxies download, webshare proxies replaced, webshare proxy-url, webshare proxies refresh (replaces your whole proxy list, uses one of your on-demand refreshes, and asks you to confirm first)

  • Usage: webshare stats (add --hourly or --since), webshare activity list (add --error), webshare activity export

  • Account: webshare plans list, webshare config show, webshare transactions list, webshare invoices download, webshare notifications

  • IP authorization: webshare ipauth list, webshare ipauth add, webshare ipauth remove, and webshare ip to see your current public IP

If your account has more than one plan, add --plan to commands that work on a single plan. Add --json for machine-readable output. Run webshare --help to see everything.
​
Most commands only read your account. A few change it, such as webshare proxies refresh, webshare ipauth add and webshare ipauth remove.

The full command reference is in the Webshare CLI README. The Webshare API is documented at apidocs.webshare.io.

Troubleshooting Common Issues

  • "command not found" or "not recognized" after installing
    The CLI isn't in your PATH.

    • macOS: check that the Homebrew install finished without errors, then open a new terminal.

    • Linux: check that webshare is in /usr/local/bin/ (run ls /usr/local/bin/webshare).

    • Windows: confirm the folder you extracted is in your PATH, then close and reopen PowerShell.

  • "Exec format error" on Linux

    You downloaded the wrong version for your processor. Run uname -m and download the matching file (see Linux installation steps).

  • The browser doesn't open during webshare login
    This is expected on servers, CI, SSH sessions, and containers, where no browser is available. Sign in with an API key instead (Method 2).

  • WEBSHARE_API_KEY isn't set
    Create a key under Integrations → API Keys and set it as shown in Method 2. If you set it in an earlier terminal window, new windows won't have it, because the commands only last for the current session (see "Good to know").

  • webshare whoami shows the wrong account, or sign-in fails
    If both a stored login and an API key are present, the API key is used, so an old key in your environment can override your browser login. Remove it, or replace it with a current key:

    • macOS and Linux: unset WEBSHARE_API_KEY

    • Windows PowerShell: Remove-Item Env:WEBSHARE_API_KEY

  • "the account has no active plan; pass --plan explicitly"
    The CLI couldn't find an active plan on your account. Run webshare plans list to see your plans, then add --plan followed by the plan ID to your command.

  • webshare proxies list returns nothing on a Rotating Residential plan

    Add --mode backbone, or use webshare proxy-url.

Need Assistance?

If you have any questions or need further assistance, our Customer Support team is here to help! Feel free to reach out to us at [email protected].

Related Articles
Did this answer your question?