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

# Check with specific region and timeout
clearproxy check proxies.txt --region us1 --timeout 5000

# Check SOCKS5 proxies
clearproxy check proxies.txt --type socks5

# Output as plain text
clearproxy check proxies.txt --format txt --out working.txt

# Windows: Create custom.json file
# [{"url":"https://discord.com","requiredStatusCodes":[200,301,302]}]

clearproxy check proxies.txt --custom custom.json

# Linux/Mac: Direct JSON string
clearproxy check proxies.txt --custom '[{"url":"https://discord.com","requiredStatusCodes":[200,301,302]}]'

Commands

set-key

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

clearproxy set-key <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

string

Path to proxy file or inline proxies (optional)

string

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

number

default:"4000"

Request timeout per proxy in milliseconds (1000-30000)

string

default:"http"

Proxy type: http, socks4, or socks5

string

default:"result.json"

Output file path

string

default:"json"

Output format: json, txt, or yaml

boolean

default:"false"

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

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:pass@1.1.1.1:8080`
Colon Format	`1.1.1.1:8080:user:pass`

Examples

# Check from file
clearproxy check proxies.txt

# Check with specific region
clearproxy check proxies.txt --region us1

# Check SOCKS5 proxies with custom timeout
clearproxy check proxies.txt --type socks5 --timeout 8000

# Output as plain text
clearproxy check proxies.txt --format txt --out working.txt

# Check inline proxies (no file needed)
clearproxy check 1.1.1.1:8080 8.8.8.8:3128 9.9.9.9:1080

# Simplified output (only ip:port)
clearproxy check proxies.txt --simple --format txt

# 1. Create custom.json file:
# [{"url":"https://discord.com","requiredStatusCodes":[200,301,302]}]

# 2. Run command:
clearproxy check proxies.txt --custom custom.json

# Direct JSON string
clearproxy check proxies.txt \
  --custom '[{"url":"https://discord.com","requiredStatusCodes":[200,301,302]}]'

# Create custom.json:
# [
#   {"url":"https://discord.com","requiredStatusCodes":[200,301,302]},
#   {"url":"https://www.google.com","requiredStatusCodes":[200],"requiredText":"Search"}
# ]

clearproxy check proxies.txt --custom custom.json

# Create ecommerce.json:
# [
#   {"url":"https://shop.com/products","requiredStatusCodes":[200],"requiredText":"Add to Cart"},
#   {"url":"https://shop.com/cart","requiredStatusCodes":[200,302]}
# ]

clearproxy check proxies.txt \
  --region us1 \
  --custom ecommerce.json \
  --out shop-proxies.json

# Create validation.json:
# [{"url":"https://api.example.com","requiredText":"SUCCESS","caseSensitive":true}]

clearproxy check proxies.txt --custom validation.json

# Full example with all options
clearproxy check proxies.txt \
  --region us1 \
  --timeout 5000 \
  --type http \
  --custom custom.json \
  --format json \
  --out validated.json

Output Details

Standard Output
With Custom Url

Console Output (Standard):

──── SUMMARY ────
[+] Working     : 85
[-] Failed      : 15
[*] Total Check : 100
[>] Region Used : us1
[>] Took        : 2.5s

Console Output (UnlimitedPro):

──── SUMMARY ────
[+] Working     : 85
[-] Failed      : 15
[*] Total Check : 100
[>] Plan        : Unlimited Pro
[>] Region Used : us1
[>] Took        : 2.5s

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]

boolean

default:"false"

Show raw JSON response from API

boolean

default:"false"

Display last 10 proxy checks

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
# Output:
# ──── ACCOUNT INFO ────
# [*] User ID       : usr_abc123
# [*] Email         : hello@clearproxy.io
# [+] Subscription  : None
# [+] Checks Left  : 50,000

clearproxy me
# Output:
# ──── ACCOUNT INFO ────
# [*] User ID       : usr_abc123
# [*] Email         : hello@clearproxy.io
# [+] Subscription  : Unlimited Pro
# [*] Plan Expires : Jan 22, 2026, 07:28 PM

clearproxy me --history

clearproxy me --usage

clearproxy me --debug

regions

List all available regions for proxy checking.

clearproxy regions [options]

boolean

default:"false"

Output in JSON format

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

Examples

clearproxy regions

clearproxy regions --json

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.5.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

​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