XPing

🚀 VLESS connection ping tool using Xray with fragment support

A powerful command-line tool for testing VLESS proxy connections with advanced features like fragment support, real-time ping statistics, and automatic port management.

🎬 Demo Video

https://github.com/user-attachments/assets/6dd3f671-5469-441a-91c0-00b1028e2708

✨ Features

• 🔗 VLESS URL Support: Test connections directly from VLESS URLs
• 📁 Config File Support: Use existing Xray config files
• 🧩 Fragment Mode: Enable fragment for bypassing censorship
• 📊 Real-time Statistics: Live ping results with detailed stats
• 🎯 Smart Port Management: Automatic free port detection to avoid conflicts
• 🌈 Colorful Output: Beautiful colored terminal output
• ⚙️ Environment Variables: Customizable via environment variables
• 🛡️ Config Validation: Built-in Xray config validation

📦 Installation

Prerequisites

• Node.js 16.0.0 or higher
• Xray-core installed and accessible

Install via npm (Global)

npm install -g @nabikaz/xping

Manual Installation

git clone https://github.com/NabiKAZ/xping.git
cd xping
npm install

🚀 Usage

Basic Usage

# Test with VLESS URL
xping "vless://uuid@server:port?security=tls&type=ws&path=/..."

# Test with config file
xping config.json

# Test with fragment mode (VLESS URL only)
xping "vless://..." --fragment

# Test with custom options
xping config.json --count 10 --delay 2000 --timeout 5000

Command Line Options

Usage: xping <input> [options]

Arguments:
  input  VLESS URL or xray config file path to test

Options:
  -f, --fragment  Enable fragment mode (default: false)
  -d, --delay     Delay between pings in milliseconds (default: 1000)
  -t, --timeout   Connection timeout in milliseconds (default: 10000)
  -c, --count     Number of pings to send (default: infinite)
  -h, --help      Show help
  -v, --version   Show version number

Examples

# Basic ping test
xping "vless://[email protected]:443?security=tls&type=ws&path=/path"

# Test with fragment enabled
xping "vless://[email protected]:443?..." --fragment

# Test config file with limited count
xping config.json --count 5

# Test with custom timing
xping config.json --delay 500 --timeout 15000 --count 10

# Continuous testing (Ctrl+C to stop)
xping "vless://..."

🔧 Environment Variables

Configure XPing behavior using environment variables:

| Variable | Description | Default | |----------|-------------|---------| | XPING_XRAY_PATH | Path to xray binary | xray | | XPING_TARGET_URL | Target URL for testing | https://www.google.com/generate_204 | | XPING_FRAGMENT_PACKETS | Fragment packets type | tlshello | | XPING_FRAGMENT_LENGTH | Fragment length range | 5-9 | | XPING_FRAGMENT_INTERVAL | Fragment interval range | 1-2 |

Example with Environment Variables

# Linux/macOS
export XPING_XRAY_PATH="/usr/local/bin/xray"
export XPING_TARGET_URL="https://www.cloudflare.com"
xping config.json

# Windows Command Prompt
set XPING_XRAY_PATH="C:\xray\xray.exe"
set XPING_TARGET_URL="https://www.cloudflare.com"
xping config.json

# Windows PowerShell
$env:XPING_XRAY_PATH="C:\xray\xray.exe"
$env:XPING_TARGET_URL="https://www.cloudflare.com"
xping config.json

🛠️ How It Works

1. Input Detection: Automatically detects whether input is a VLESS URL or config file
2. Config Processing:
   • For VLESS URLs: Generates optimized Xray config
   • For config files: Processes in memory with free port assignment
3. Validation: Validates configuration using xray -test
4. Proxy Setup: Starts Xray with automatic port management
5. Connection Testing: Performs HTTP requests through the proxy
6. Statistics: Provides real-time and summary statistics

💸 Donate

If you find this tool useful and would like to support its development:

• TON Wallet: nabikaz.ton

📄 License

This project is licensed under the GNU GPLv3 - see the LICENSE file for details.

⭐ Star this project if you find it useful!