> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearproxy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ClearProxy CLI

## Installation

<Steps>
  <Step title="Install via npm">
    ```bash theme={null}
    npm i clearproxy -g
    ```
  </Step>

  <Step title="Set API Key">
    ```bash theme={null}
    clearproxy set-key <your_api_key>
    ```
  </Step>

  <Step title="Verify Installation">
    ```bash theme={null}
    clearproxy me
    ```
  </Step>
</Steps>

## Quick Start

<CodeGroup>
  ```bash Basic Usage theme={null}
  # Set API key
  clearproxy set-key clearpx_blablabla6767

  # Check account info
  clearproxy me

  # Check proxies from file
  clearproxy check proxies.txt
  ```

  ```bash Advanced Usage theme={null}
  # 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
  ```

  ```bash Custom URL Validation theme={null}
  # 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]}]'
  ```
</CodeGroup>

***

## Commands

### set-key

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

```bash theme={null}
clearproxy set-key <apiKey>
```

<ParamField path="apiKey" type="string" required>
  Your ClearProxy.io API key from the dashboard
</ParamField>

***

### check

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

```bash theme={null}
clearproxy check [input] [options]
```

#### Parameters

<ParamField path="input" type="string">
  Path to proxy file or inline proxies (optional)
</ParamField>

<ParamField path="--region" type="string">
  Region to use for checking (us1, us2, sg1, jp1, etc.)
</ParamField>

<ParamField path="--timeout" type="number" default="4000">
  Request timeout per proxy in milliseconds (1000-30000)
</ParamField>

<ParamField path="--type" type="string" default="http">
  Proxy type: `http`, `socks4`, or `socks5`
</ParamField>

<ParamField path="--out" type="string" default="result.json">
  Output file path
</ParamField>

<ParamField path="--format" type="string" default="json">
  Output format: `json`, `txt`, or `yaml`
</ParamField>

<ParamField path="--simple" type="boolean" default="false">
  Simplified output (only ip:port or user:pass\@ip:port)
</ParamField>

<ParamField path="--custom" type="string|file">
  Custom URL validation as JSON array or file path (.json)
</ParamField>

#### Custom URL Validation

Test working proxies against specific URLs with custom validation rules.

**JSON Format:**

```json theme={null}
[
  {
    "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)

<Note>
  **Platform-Specific Usage:**

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

#### 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

<CodeGroup>
  ```bash Basic Check theme={null}
  # Check from file
  clearproxy check proxies.txt
  ```

  ```bash With Region theme={null}
  # Check with specific region
  clearproxy check proxies.txt --region us1
  ```

  ```bash SOCKS5 with Timeout theme={null}
  # Check SOCKS5 proxies with custom timeout
  clearproxy check proxies.txt --type socks5 --timeout 8000
  ```

  ```bash Plain Text Output theme={null}
  # Output as plain text
  clearproxy check proxies.txt --format txt --out working.txt
  ```

  ```bash Inline Proxies theme={null}
  # Check inline proxies (no file needed)
  clearproxy check 1.1.1.1:8080 8.8.8.8:3128 9.9.9.9:1080
  ```

  ```bash Simple Output theme={null}
  # Simplified output (only ip:port)
  clearproxy check proxies.txt --simple --format txt
  ```

  ```bash Custom URL - Windows theme={null}
  # 1. Create custom.json file:
  # [{"url":"https://discord.com","requiredStatusCodes":[200,301,302]}]

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

  ```bash Custom URL - Linux/Mac theme={null}
  # Direct JSON string
  clearproxy check proxies.txt \
    --custom '[{"url":"https://discord.com","requiredStatusCodes":[200,301,302]}]'
  ```

  ```bash Multiple Custom URLs theme={null}
  # 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
  ```

  ```bash E-commerce Validation theme={null}
  # 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
  ```

  ```bash Case-Sensitive Text Match theme={null}
  # Create validation.json:
  # [{"url":"https://api.example.com","requiredText":"SUCCESS","caseSensitive":true}]

  clearproxy check proxies.txt --custom validation.json
  ```

  ```bash Full Example theme={null}
  # Full example with all options
  clearproxy check proxies.txt \
    --region us1 \
    --timeout 5000 \
    --type http \
    --custom custom.json \
    --format json \
    --out validated.json
  ```
</CodeGroup>

#### Output Details

<Tabs>
  <Tab title="Standard Output">
    **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
    ```
  </Tab>

  <Tab title="With Custom Url">
    **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):**

    ```json theme={null}
    {
      "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": [...]
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

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

\--

### me

Display account information and remaining quota.

```bash theme={null}
clearproxy me [options]
```

<ParamField path="--debug" type="boolean" default="false">
  Show raw JSON response from API
</ParamField>

<ParamField path="--history" type="boolean" default="false">
  Display last 10 proxy checks
</ParamField>

<ParamField path="--usage" type="boolean" default="false">
  Show usage chart for last 30 days
</ParamField>

**Output includes:**

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

#### Examples

<CodeGroup>
  ```bash Basic Info theme={null}
  clearproxy me
  # Output:
  # ──── ACCOUNT INFO ────
  # [*] User ID       : usr_abc123
  # [*] Email         : hello@clearproxy.io
  # [+] Subscription  : None
  # [+] Checks Left  : 50,000
  ```

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

  ```bash With History theme={null}
  clearproxy me --history
  ```

  ```bash With Usage Chart theme={null}
  clearproxy me --usage
  ```

  ```bash Raw Response theme={null}
  clearproxy me --debug
  ```
</CodeGroup>

***

### regions

List all available regions for proxy checking.

```bash theme={null}
clearproxy regions [options]
```

<ParamField path="--json" type="boolean" default="false">
  Output in JSON format
</ParamField>

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

#### Examples

<CodeGroup>
  ```bash List Regions theme={null}
  clearproxy regions
  ```

  ```bash JSON Output theme={null}
  clearproxy regions --json
  ```
</CodeGroup>

***

### health

Check the health and availability of ClearProxy API.

```bash theme={null}
clearproxy health
```

Returns status, version, uptime and active regions information.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid --custom JSON Error (Windows)">
    **Problem**: Windows CMD/PowerShell cannot parse JSON strings correctly

    **Solution**: Use file method instead

    ```bash theme={null}
    # Create custom.json file with your validation rules
    clearproxy check proxies.txt --custom custom.json
    ```
  </Accordion>

  <Accordion title="API Key Not Found">
    **Problem**: CLI cannot find saved API key

    **Solution**: Set your API key again

    ```bash theme={null}
    clearproxy set-key your_api_key_here
    ```
  </Accordion>

  <Accordion title="No Proxies Found">
    **Problem**: CLI cannot parse proxy file

    **Solution**: Ensure your proxy file uses supported formats:

    * `ip:port`
    * `user:pass@ip:port`
    * `ip:port:user:pass`
  </Accordion>

  <Accordion title="Custom URL Validation Not Showing">
    **Problem**: Custom validation results not in output

    **Solution**:

    * Verify JSON format is correct
    * Check API response includes `custom_url_validation` field
    * Ensure you're using the latest CLI version
  </Accordion>
</AccordionGroup>

***

## Version

Current version: **1.5.0**

Use `clearproxy --version` or `clearproxy -v` to check your installed version.