CLI tool to diagnose HTTP/HTTPS proxy connectivity
npm install proxy-doctorA CLI tool to diagnose HTTP/HTTPS proxy connectivity.
- 🔎 Auto-detect proxy settings from environment variables (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY)
- 🧪 Test connectivity through proxy to target URLs
- 📊 Detailed diagnostics with actionable suggestions for common issues
- 🎨 Beautiful output with colors and spinners
- 📝 JSON output for scripting and CI/CD integration
``bash`
npm install -g proxy-doctor
`bash`Auto-detect proxy from environment variables
proxy-doctor
| Option | Description |
|--------|-------------|
| -p, --proxy | Specify a proxy URL to test (overrides environment variables) |-t, --target
| | Target URL to test connectivity against |--timeout
| | Request timeout in milliseconds (default: 10000) |-v, --verbose
| | Enable verbose output with debug information |-j, --json
| | Output results as JSON |--http
| | Test HTTP proxy only |--https
| | Test HTTPS proxy only |-d, --direct
| | Test direct connection without proxy (for debugging) |-k, --insecure
| | Skip SSL certificate verification (for corporate proxies) |-h, --help
| | Display help |-V, --version
| | Display version |
#### Basic Testing
`bashTest with a specific proxy
proxy-doctor --proxy http://proxy.example.com:8080
#### Direct Connection Testing
bash
Test direct connection (bypass proxy)
proxy-doctor --directCompare direct vs proxy performance
proxy-doctor --verbose # Test with proxy
proxy-doctor --direct --verbose # Test without proxyTest direct connection to specific target
proxy-doctor --direct --target https://api.github.com
`#### Corporate Proxy with SSL Inspection
bash
Skip SSL certificate verification (corporate proxy)
proxy-doctor --insecureVerbose output with SSL bypass
proxy-doctor --proxy http://corporate-proxy:8080 --insecure -vTest HTTPS only with SSL bypass
proxy-doctor --https --insecure
`#### Advanced Usage
bash
Test specific target with custom proxy and SSL bypass
proxy-doctor --proxy http://proxy:8080 --target https://registry.npmjs.com --insecureMultiple protocol override (test both even with custom target)
proxy-doctor --target https://example.com --httpComprehensive test with all options
proxy-doctor --proxy http://proxy:8080 --timeout 15000 --insecure --verbose
`Environment Variables
Proxy Doctor reads the following environment variables:
| Variable | Description |
|----------|-------------|
|
/ http_proxy | Proxy for HTTP requests |
| HTTPS_PROXY / https_proxy | Proxy for HTTPS requests |
| ALL_PROXY / all_proxy | Proxy for all requests (fallback) |
| NO_PROXY / no_proxy | Comma-separated list of hosts to bypass proxy |$3
`bash
Linux/macOS
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.localWindows (Command Prompt)
set HTTP_PROXY=http://proxy.example.com:8080
set HTTPS_PROXY=http://proxy.example.com:8080Windows (PowerShell)
$env:HTTP_PROXY="http://proxy.example.com:8080"
$env:HTTPS_PROXY="http://proxy.example.com:8080"
`Output Examples
$3
🔍 Proxy Doctor - Checking your proxy configuration...📡 Detected Proxy Settings:
HTTP_PROXY: http://proxy.example.com:8080/
HTTPS_PROXY: http://proxy.example.com:8080/
ALL_PROXY: (not set)
NO_PROXY: localhost,127.0.0.1
✅ HTTP Proxy Test
→ Target: http://www.google.com
✓ Success (234ms) [200]
✅ HTTPS Proxy Test
→ Target: https://www.google.com
✓ Success (456ms) [200]
🎉 All proxy connections are working correctly!
$3
🔍 Proxy Doctor - Checking your proxy configuration...📡 Detected Proxy Settings:
HTTP_PROXY: http://127.0.0.1:7890/
HTTPS_PROXY: (not set)
ALL_PROXY: (not set)
NO_PROXY: (not set)
❌ HTTP Proxy Test
→ Target: http://www.google.com
✗ Failed (8ms)
Error: connect ECONNREFUSED 127.0.0.1:7890
💡 Check if the proxy server is running and the port is correct.
⚠️ 1/1 proxy tests failed.
$3
json
{
"config": {
"http": "http://127.0.0.1:7890",
"https": "http://127.0.0.1:7890",
"noProxy": []
},
"results": [
{
"success": true,
"proxyType": "http",
"proxyUrl": "http://127.0.0.1:7890",
"targetUrl": "http://www.google.com",
"responseTime": 234,
"statusCode": 200
}
],
"allPassed": true,
"timestamp": "2026-01-19T05:00:00.000Z"
}
`Diagnostics
Proxy Doctor provides helpful suggestions for common issues:
| Error | Suggestion |
|-------|------------|
|
| Check if the proxy server is running and the port is correct |
| ETIMEDOUT | The proxy server may be unreachable. Check network connectivity |
| ENETUNREACH | Network unreachable. Check firewall settings and routing |
| ENOTFOUND | DNS resolution failed. Check the proxy URL for typos |
| 407 Status | Proxy requires authentication. Add credentials to the URL |
| UNABLE_TO_GET_ISSUER_CERT_LOCALLY | SSL certificate issue. Use --insecure for corporate proxies |
| SELF_SIGNED_CERT_IN_CHAIN | Self-signed certificate detected. Use --insecure if trusted |
| CERT_HAS_EXPIRED | Certificate expired. Contact proxy administrator |
| Request was cancelled | Proxy may not support the request. This is usually harmless |$3
Corporate environments often use proxy servers that perform SSL inspection, which can cause certificate verification errors. If you see errors like:
-
unable to get local issuer certificate
-
- Use the
flag to bypass SSL verification:`bash
proxy-doctor --insecure
`⚠️ Warning: Only use
in trusted environments. It disables all SSL certificate verification.$3
When using
--target, the tool automatically detects which protocol to test:`bash
Only tests HTTPS
proxy-doctor --target https://api.example.comOnly tests HTTP
proxy-doctor --target http://api.example.comOverride: test both protocols
proxy-doctor --target https://api.example.com --http
``MIT