ClearProxy CLI

Installation

Install via npm

npm i clearproxy -g

Set API Key

clearproxy set-key <your_api_key>

Verify Installation

clearproxy me

Quick Start

# Set API key
clearproxy set-key clearpx_blablabla6767

# Check account info
clearproxy me

# Check proxies from file
clearproxy check proxies.txt

Commands

set-key

Save your ClearProxy.io API key locally for use in all subsequent requests.

clearproxy set-key <apiKey>

apiKey

string

required

Your ClearProxy.io API key from the dashboard

check

Main command for checking proxy lists. Supports input from file, stdin, or inline arguments.

clearproxy check [input] [options]

Parameters

input

string

Path to proxy file or inline proxies (optional)

--region

string

Region to use for checking (us1, us2, sg1, jp1, etc.)

--timeout

number

default:"4000"

Request timeout per proxy in milliseconds (1000-30000)

--type

string

default:"http"

Proxy type: http, socks4, or socks5

--out

string

default:"result.json"

Output file path

--format

string

default:"json"

Output format: json, txt, or yaml

--simple

boolean

default:"false"

Simplified output (only ip:port or user:pass@ip:port)

--custom

string|file

Custom URL validation as JSON array or file path (.json)

Custom URL Validation

Test working proxies against specific URLs with custom validation rules. JSON Format:

[
  {
    "url": "https://example.com",
    "requiredStatusCodes": [200, 301, 302],
    "requiredText": "Welcome",
    "caseSensitive": false
  }
]

Fields:

url (string, required) - Target URL to test
requiredStatusCodes (array, optional) - Valid HTTP status codes (default: [200])
requiredText (string, optional) - Text that must appear in response body
caseSensitive (boolean, optional) - Case-sensitive text matching (default: false)

Platform-Specific Usage:

Windows: Use file method (recommended) - --custom custom.json
Linux/Mac: Can use direct JSON string or file

Supported Proxy Formats

Format	Example
Standard	`1.1.1.1:8080`
With Auth	`user:[email protected]:8080`
Colon Format	`1.1.1.1:8080:user:pass`

Examples

# Check from file
clearproxy check proxies.txt

Output Details

Standard Output
With Custom Url

Includes:

Working/Failed proxy count
Response time & anonymity level
Country & ISP information
Checks used & remaining quota
Processing time

Additional Information:

Overall validation summary
Per-URL success/failure rates
Success percentage for each URL
Total proxies tested per URL
List of successful/failed proxies per URL

Console Output:

──── CUSTOM URL VALIDATION ────

Overall Summary:
[*] URLs Tested   : 2
[*] Proxies Tested: 150
[>] Processing    : 8.45s

Per-URL Results:

[1] https://discord.com
[*] Tested        : 150
[+] Success       : 120 (80.00%)
[-] Failed        : 30 (20.00%)
[>] Status Codes  : 200, 301, 302

[2] https://www.google.com
[*] Tested        : 150
[+] Success       : 90 (60.00%)
[-] Failed        : 60 (40.00%)
[>] Status Codes  : 200
[>] Required Text : Search

File Output (JSON):

{
  "summary": { ... },
  "metadata": { ... },
  "proxies": [ ... ],
  "custom_url_validation": {
    "summary": {
      "total_urls_tested": 2,
      "total_proxies_tested": 150,
      "processing_time": "8.45s"
    },
    "per_url_summary": [
      {
        "url": "https://discord.com",
        "success_count": 120,
        "failed_count": 30,
        "success_rate": "80.00%",
        "successful_proxies": [...],
        "failed_proxies": [...]
      }
    ]
  }
}

When using custom URL validation, the output file will contain the complete response including custom validation results, regardless of --format and --simple flags.

—

me

Display account information and remaining quota.

clearproxy me [options]

--debug

boolean

default:"false"

Show raw JSON response from API

--history

boolean

default:"false"

Display last 10 proxy checks

--usage

boolean

default:"false"

Show usage chart for last 30 days

Output includes:

User ID and email
Remaining checks quota
Recent check history (with —history)
Usage statistics for last 30 days (with —usage)

Examples

clearproxy me

regions

List all available regions for proxy checking.

clearproxy regions [options]

--json

boolean

default:"false"

Output in JSON format

Each region represents a different geographical location where your proxies will be tested from.

Examples

clearproxy regions

health

Check the health and availability of ClearProxy API.

clearproxy health

Returns status, version, uptime and active regions information.

Troubleshooting

Invalid --custom JSON Error (Windows)

Problem: Windows CMD/PowerShell cannot parse JSON strings correctlySolution: Use file method instead

# Create custom.json file with your validation rules
clearproxy check proxies.txt --custom custom.json

API Key Not Found

Problem: CLI cannot find saved API keySolution: Set your API key again

clearproxy set-key your_api_key_here

No Proxies Found

Problem: CLI cannot parse proxy fileSolution: Ensure your proxy file uses supported formats:

ip:port
user:pass@ip:port
ip:port:user:pass

Custom URL Validation Not Showing

Problem: Custom validation results not in outputSolution:

Verify JSON format is correct
Check API response includes custom_url_validation field
Ensure you’re using the latest CLI version

Version

Current version: 1.3.0 Use clearproxy --version or clearproxy -v to check your installed version.

Getting started

Rest API

SDKs

Installation

Quick Start

Commands

set-key

check

Parameters

Custom URL Validation

Supported Proxy Formats

Examples

Output Details

me

Examples

regions

Examples

health

Troubleshooting

Version

Getting started

Rest API

SDKs

​Installation

​Quick Start

​Commands

​set-key

​check

​Parameters

​Custom URL Validation

​Supported Proxy Formats

​Examples

​Output Details

​me

​Examples

​regions

​Examples

​health

​Troubleshooting

​Version

Installation

Quick Start

Commands

set-key

check

Parameters

Custom URL Validation

Supported Proxy Formats

Examples

Output Details

me

Examples

regions

Examples

health

Troubleshooting

Version