routing-switch

File Information

Property	Value
Binary Name	routing-switch
Version	9.8.4 (build 320)
Build Date	Not disclosed
Rust Version	1.70.0
File Size	9.6MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	System-wide traffic routing through various proxy protocols
Git Commit	unknown
Metadata Generated	2026-07-11T18:16:16Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

---

Features

#	Feature
1	System-wide traffic routing through proxy protocols
2	Support for OpenVPN, WireGuard, and Dante SOCKS5
3	Support for Tor, Shadowsocks, V2Ray, and Xray protocols
4	Support for Mieru/Mita and Hysteria2 protocols
5	Automatic protocol scoring and selection
6	DNS leak prevention with multiple modes
7	Metric-based and direct routing options
8	External configuration file support
9	IPv4/IPv6 dual-stack support
10	QR code generation for mobile clients
11	VPNGate free VPN integration (100+ public servers, no auth required)
12	Comprehensive logging and monitoring

Global Options

Flag	Description
-h, --help	Print help information
-v, --version	Print version information
-n, --info	Display detailed information
-e, --examples	Show usage examples
--json	Output in JSON format
--json-pretty	Pretty-print JSON output with indentation
--json-human	Enhanced JSON output with improved formatting (like jq)
--verbose	Enable verbose output
-o, --output-format <FORMAT>	Force output format: text (default) or json

Commands

CONNECTION COMMANDS

connect

Connect to a proxy protocol (openvpn, wireguard use native routing; tor uses redsocks; dante, shadowsocks, v2ray, xray-*, mita use tun2socks)

Usage:

disconnect

Disconnect current proxy connection

Usage:

status

Show current connection status

Usage:

INFORMATION COMMANDS

dns-info

Display current DNS server information

Usage:

tor-dns-info

Display Tor DNS and SOCKS endpoint information

Usage:

vps-info

Display VPS server information (hostname, IP, stats)

Usage:

list-protocols

List available protocols with scores

Usage:

TESTING COMMANDS

test-protocol

Test a specific protocol connectivity

Usage:

benchmark

Benchmark all available protocols

Usage:

CONFIGURATION COMMANDS

export-config

Export protocol configurations to files

Usage:

showconfig

Show protocol configuration

Usage:

showconfigurl

Show protocol configuration as URL

Usage:

showconfigqr

Show protocol configuration as QR code

Usage:

validate-qr

Validate QR code configurations against the auth card (file, stdin, or by protocol)

Usage:

MANAGEMENT COMMANDS

auto-select

Auto-select and connect to best protocol

Usage:

reset

Reset all routing to default state

Usage:

cleanup

Clean up orphaned processes and resources

Usage:

recover

Recover from partial failure state

Usage:

check-prerequisites

Check and fix network prerequisites for VPN connections (forwarding, NAT)

Usage:

MICROSOCKS SERVER MANAGEMENT

microsocks-enable

Enable microsocks SOCKS5 server for other devices

Usage:

microsocks-disable

Disable microsocks SOCKS5 server

Usage:

microsocks-status

Show microsocks server status

Usage:

VPNGATE FREE VPN

vpngate-fetch

Fetch VPNGate free public VPN server list

Usage:

vpngate-list

List cached VPNGate servers with filtering and sorting

Usage:

vpngate-connect

Connect to a VPNGate free VPN server by index (no auth required)

Usage:

vpngate-export

Export a VPNGate server's OpenVPN config as .ovpn file

Usage:

vpngate-export-all

Export all cached VPNGate servers as .ovpn files

Usage:

providers

Browse, fetch, and connect through commercial / free third-party VPN providers (VPN Gate, Riseup, NordVPN, IVPN, PIA, Surfshark, AirVPN, Mullvad-WG)

Usage:

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: BASIC CONNECTIONS

Connect to various proxy protocols

Step 1: Connect via OpenVPN

Expected Output: Successfully connected to OpenVPN server

Step 2: Connect via WireGuard

Expected Output: Successfully connected to WireGuard server

Step 3: Connect via Dante SOCKS5 proxy

Expected Output: Successfully connected to Dante server

Step 4: Route traffic through Tor - VPN-only, layered on an active Kodachi tunnel

Expected Output: Layering Tor on the active wireguard tunnel ... Successfully routing traffic through Tor

Step 5: Connect via Shadowsocks

Expected Output: Successfully connected to Shadowsocks server

Step 6: Connect via V2Ray VMess

Expected Output: Successfully connected to V2Ray server

Step 7: Connect via Xray VLESS TLS

Expected Output: Successfully connected to Xray VLESS server

Step 8: Connect via Xray VLESS Reality

Expected Output: Successfully connected to Xray VLESS Reality server

Step 9: Connect via Xray Trojan

Expected Output: Successfully connected to Xray Trojan server

Step 10: Connect via Xray VMess

Expected Output: Successfully connected to Xray VMess server

Step 11: Connect via Mieru/Mita protocol

Expected Output: Successfully connected to Mita server

Step 12: Connect via Hysteria2 protocol

Expected Output: Successfully connected to Hysteria2 server

Scenario 2: EXTERNAL CONFIGURATION FILES

Connect a custom profile with --config instead of the auth card. OpenVPN/WireGuard take standard text bodies; v2ray/xray/shadowsocks/hysteria2/mita take the card-native services.<proto> JSON object (a custom profile is just a card service slice).

Step 1: Connect using external OpenVPN config file

Expected Output: Successfully connected to OpenVPN server

Step 2: Connect using external WireGuard config

Expected Output: Successfully connected to WireGuard server

Step 3: Connect a custom Shadowsocks profile

Expected Output: Successfully connected to Shadowsocks server

Step 4: Connect a custom V2Ray (VMess) profile

Expected Output: Successfully connected to V2Ray server

Step 5: Connect a custom Xray profile (xray-vless / xray-vless-reality / xray-trojan / xray-vmess)

Expected Output: Successfully connected to Xray VLESS Reality server

Step 6: Connect a custom Hysteria2 profile

Expected Output: Successfully connected to Hysteria2 server

Step 7: Connect a custom Mita/Mieru profile

Expected Output: Successfully connected to Mita server

Step 8: Force connection with external config

Expected Output: Disconnecting existing... Connected via external config

Step 9: External config in no-TUN mode

Expected Output: Shadowsocks SOCKS5 proxy ready at localhost:30000

Scenario 3: IPV4/IPV6 SELECTION

Explicitly choose IPv4 or IPv6 connections

Step 1: Force IPv4 connection to Dante

Expected Output: Connected via IPv4

Step 2: Force IPv6 connection to Dante

Expected Output: Connected via IPv6

Step 3: Connect Shadowsocks over IPv4

Expected Output: Shadowsocks connected via IPv4

Step 4: Connect Tor over IPv6

Expected Output: Tor connected via IPv6

Step 5: Use IPv6 for Xray VLESS

Expected Output: Xray VLESS connected via IPv6

Step 6: Connect Hysteria2 over IPv4

Expected Output: Hysteria2 connected via IPv4

Step 7: Connect Hysteria2 over IPv6

Expected Output: Hysteria2 connected via IPv6

Scenario 4: NETWORK PREREQUISITES

Check and manage network prerequisites for VPN connections

Step 1: Check and fix network prerequisites

Expected Output: ✓ IPv4 forwarding: Already enabled (correct) ✗→✓ NAT MASQUERADE: Fixed

Step 2: Check prerequisites for IPv6 connections

Expected Output: ✓ IPv6 forwarding: Enabled

Step 3: Get prerequisites status in JSON format

Expected Output: {"command":"check-prerequisites","data":{"prerequisites":{"checks":[...],"ready":true}},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 4: Connect with automatic prerequisites check

Expected Output: Checking network prerequisites... ✓ All checks passed Connecting to shadowsocks...

Step 5: Connect without prerequisites check

Expected Output: Connecting to shadowsocks...

Step 6: Force reconnection with prerequisites check

Expected Output: Checking network prerequisites... Forcing new connection...

Scenario 5: CONNECTION STATUS

Check and monitor connection status

Step 1: Show current connection status

Expected Output: Protocol: wireguard, Status: Connected

Step 2: Get status in JSON format

Expected Output: {"command":"status","data":{"connected":true,"protocol":"wireguard","connected_since":"...","server":"...","tun_device":"wg0","uptime":"..."},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 3: Pretty-printed JSON status

Expected Output: Formatted JSON with connection details

Step 4: Human-readable JSON status

Expected Output: Enhanced JSON output with descriptions

Scenario 6: DNS MODES AND SECURITY

Control DNS routing for security and compatibility (DEFAULT: auto mode)

Step 1: DEFAULT: Auto mode (no special DNS routing)

Expected Output: DNS handled naturally through tunnel

Step 2: Auto mode: DNS flows naturally through tunnel (explicit)

Expected Output: DNS handled naturally through tunnel

Step 3: Hybrid mode: VPN server DNS bypasses tunnel

Expected Output: Using hybrid DNS mode: VPN server DNS bypasses, others through tunnel

Step 4: Strict mode: ALL DNS through tunnel

Expected Output: Using strict DNS mode: Maximum security

Step 5: System mode: DNS bypasses tunnel

Expected Output: WARNING: System DNS mode - DNS queries will leak!

Step 6: Exclude private networks from VPN

Expected Output: Private networks will bypass VPN tunnel

Step 7: Hybrid DNS with private network exclusion

Expected Output: Using hybrid DNS mode with local network access

Scenario 7: ROUTING MODES - SECURITY vs FAILOVER

Choose between Direct (preferred tunnel route) or Metric (with fallback) routing

Step 1: DEFAULT: Direct routing mode (MOST SECURE)

Expected Output: Using DIRECT routing: TUN route preferred; original route kept as high-metric recovery

Step 2: Metric routing mode (LESS SECURE, has fallback)

Expected Output: Using METRIC routing: Original route kept as backup

Step 3: Direct mode for Shadowsocks (default)

Expected Output: Direct routing: Shadowsocks TUN route is preferred

Step 4: Metric mode for corporate VPN scenarios

Expected Output: Metric routing: Fallback to original connection if VPN drops

Step 5: Metric mode with LAN access preserved

Expected Output: Failover routing with local network bypass

Scenario 8: DISCONNECTION

Disconnect and restore normal routing

Step 1: Disconnect current proxy

Expected Output: Successfully disconnected

Step 2: Force disconnect even if issues

Expected Output: Force disconnected

Step 3: Disconnect and clean all firewall rules

Expected Output: Disconnected and firewall rules cleaned

Step 4: Force disconnect with complete firewall cleanup

Expected Output: Force disconnected, all firewall rules flushed

Step 5: Disconnect with JSON output

Expected Output: {"command":"disconnect","data":{"status":"disconnected","message":"..."},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Scenario 9: FORCE FLAG & PROTOCOL COMPATIBILITY

Understanding --force behavior and which protocols can layer together

Step 1: Creates LAYERED connection: Tor-over-WireGuard ✓ (no --force needed)

Expected Output: → connect tor detects the active WireGuard tunnel and layers on it → WireGuard's wg0 stays up; Tor SOCKS reached at 10.0.0.1:9050 via wg0 → Tor's iptables rules redirect traffic on top

Step 2: Creates LAYERED connection: Tor-over-OpenVPN ✓ (no --force needed)

Expected Output: → connect tor detects the active OpenVPN tunnel and layers on it → Traffic: Your App → Tor (redsocks) → OpenVPN (tun0) → Internet → Tor SOCKS reached at 172.16.0.1:9050 via tun0

Step 3: Creates LAYERED connection: Tor-over-proxy ✓ (works for shadowsocks/v2ray/xray/hysteria2/mita)

Expected Output: → connect tor detects the active proxy tunnel (tun_routing) and layers on it → Traffic: Your App → Tor (redsocks) → Shadowsocks → Internet → Tor SOCKS reached at 172.16.0.1:9050 via tun_routing

Step 4: FAILS: Interface conflict ✗

Expected Output: → ERROR: Both protocols need the same tun_routing interface → Cannot have two tun2socks instances → Must disconnect first

Step 5: May create complex routing (untested)

Expected Output: → Shadowsocks tun_routing remains → Tor adds iptables rules on top → Behavior depends on routing priorities

Step 6: Understanding protocol architectures

Expected Output: → Native VPNs (own interfaces): openvpn (tun0), wireguard (wg0) → Redsocks (iptables NAT): tor → Tun2socks (shared tun_routing): shadowsocks, dante, v2ray, xray-vless, xray-vless-reality, xray-trojan, xray-vmess, mita, hysteria2

Step 7: Best practices for using --force

Expected Output: → ✓ WireGuard/OpenVPN first, then Tor --force for double VPN → ✗ Never layer two tun2socks protocols → Test connectivity after layering

Scenario 10: DNS INFORMATION

Check DNS configuration

Step 1: Show current DNS servers

Expected Output: IPv4: <VPN_IP>:53, IPv6: [<VPN_IPv6>]:53

Step 2: DNS info in JSON format

Expected Output: {"command":"dns-info","data":{"ipv4":{"host":"<VPN_IP>","port":53},"ipv6":{"host":"<VPN_IPv6>","port":53}},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Scenario 11: TOR DNS INFORMATION

Check Tor DNS and SOCKS configuration

Step 1: Show Tor DNS and SOCKS endpoints

Expected Output: DNS: dns://<VPS_IP>:9054#Tor-DNS

Step 2: Tor DNS info in JSON format

Expected Output: {"command":"tor-dns-info","data":{"ipv4":{"dns_url":"dns://...","socks_url":"socks5://..."}},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Scenario 12: VPS SERVER INFORMATION

Display VPS server details and statistics

Step 1: Show basic VPS information

Expected Output: Hostname: <type>-<random>, IPv4: <VPS_IP>

Step 2: Show detailed VPS stats

Expected Output: CPU Load, Memory Usage, Uptime, Network Connections

Step 3: VPS info in JSON format

Expected Output: {"command":"vps-info","data":{"hostname":"...","cpu_load":{...},"memory":{...},"card_type":"...","generation_t":"..."},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Scenario 13: PROTOCOL LISTING

List available protocols with scores

Step 1: List all available protocols

Expected Output: WireGuard (Score: 96.5), OpenVPN (Score: 94.0)...

Step 2: Protocol list in JSON

Expected Output: {"command":"list-protocols","data":{"protocols":[{"name":"wireguard","overall_score":96.5,"available":true,...}],"scoring":{...}},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 3: Show only available protocols

Expected Output: Available: WireGuard, Tor, Shadowsocks

Step 4: Sort by security score

Expected Output: 1. WireGuard (98.0), 2. OpenVPN (95.0)...

Step 5: Sort by speed score

Expected Output: 1. WireGuard (99.0), 2. Shadowsocks (85.0)...

Scenario 14: AUTO-SELECTION

Automatically select best protocol

Step 1: Auto-select best protocol

Expected Output: Selected WireGuard (best overall score)

Step 2: Auto-select with minimum security

Expected Output: Selected OpenVPN (security: 95.0)

Step 3: Prioritize speed in selection

Expected Output: Selected WireGuard (fastest protocol)

Step 4: Auto-select with JSON output

Expected Output: {"command":"auto-select","data":{"selected":"wireguard","reason":"best overall score (95.5)","status":"connected"},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Scenario 15: PORT USAGE INFORMATION

Local SOCKS5 port allocation reference for protocols

Step 1: Each protocol uses specific port ranges

Expected Output: When connecting, protocols allocate ports automatically: Shadowsocks: 30000-30004 V2Ray: 30005-30009 Xray VMess: 30010-30014 Xray VLESS: 30015-30019 VLESS Reality: 30020-30024 Xray Trojan: 30025-30029 Mieru/Mita: 30030-30034 Tor: 30035-30039 Dante: 30040-30044 Hysteria2: 30045-30049

Step 2: How traffic flows through local SOCKS5 proxy

Expected Output: Application → tun_routing interface → tun2socks → localhost:PORT → proxy_client → remote_server

Step 3: Check which local ports are in use

Expected Output: tcp LISTEN 0 128 127.0.0.1:30000 *:* users:(("ss-local",pid=12345,fd=3))

Step 4: Native VPN protocols use different approaches

Expected Output: WireGuard: Uses UDP port specified in config (typically 51820) OpenVPN: Uses TCP/UDP port specified in config (typically 1194)

Scenario 16: JSON OUTPUT FORMATS

Different JSON output options

Step 1: Compact JSON output

Expected Output: {"command":"connect","data":{"status":"connected","protocol":"tor","tun_device":"...","server":"..."},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 2: Pretty-printed JSON

Expected Output: { "command": "status", "data": { "connected": true, "protocol": "tor", ... }, "errors": [], "metadata": {...}, "status": "success", "timestamp": "...", "version": "9.0.1", "warnings": [] }

Step 3: Human-enhanced JSON

Expected Output: JSON with descriptions and metadata

Step 4: Pretty JSON protocol list

Expected Output: Formatted JSON array of protocols

Scenario 17: BENCHMARKING

Test protocol performance

Step 1: Benchmark all protocols (3 iterations default)

Expected Output: WireGuard: 95Mbps, OpenVPN: 75Mbps...

Step 2: Benchmark with custom iteration count

Expected Output: Running 5 iterations... WireGuard: 95Mbps...

Step 3: Benchmark results in JSON

Expected Output: {"command":"benchmark","data":{"results":[{"protocol":"wireguard","avg_download_mbps":95.5,"avg_upload_mbps":90.2,"avg_latency_ms":...}],"iterations":3},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Scenario 18: TESTING PROTOCOLS

Test protocol connectivity without routing

Step 1: Test Tor connectivity

Expected Output: Tor: SOCKS5 proxy responding at 127.0.0.1:9050

Step 2: Extended protocol test

Expected Output: Shadowsocks: Connected, Latency: 45ms, Throughput: OK

Step 3: Test all available protocols

Expected Output: Testing: Tor [OK], Shadowsocks [OK], V2Ray [FAIL]...

Step 4: Test with JSON output

Expected Output: {"command":"test-protocol","data":{"protocol":"wireguard","status":"ok","available":true,"connectivity":true,"latency_ms":12},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Scenario 19: NO-TUN MODE (MANUAL PROXY)

Run proxy without TUN interface for manual configuration

Step 1: Start Shadowsocks SOCKS5 proxy without TUN

Expected Output: Shadowsocks SOCKS5 proxy ready at localhost:30000

Step 2: Connect to Dante SOCKS5 without routing traffic

Expected Output: Dante proxy: host:port, username, password

Step 3: Use Tor SOCKS5 proxy without system routing

Expected Output: Tor SOCKS5 proxy: 127.0.0.1:9050

Step 4: V2Ray proxy in manual mode with JSON output

Expected Output: {"command":"connect","data":{"local_proxy_address":"127.0.0.1","local_proxy_port":30005,"protocol":"v2ray","mode":"no-tun"},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 5: Xray VLESS proxy for manual configuration

Expected Output: Xray SOCKS5 proxy ready at localhost:30015

Step 6: Firefox proxy settings example

Expected Output: Settings → Network → Manual proxy → SOCKS5: localhost, Port: 30000

Step 7: Chrome command line example

Expected Output: chrome --proxy-server="socks5://localhost:30000"

Step 8: Stop the proxy (works for both TUN and no-TUN modes)

Expected Output: Proxy stopped

Scenario 20: CONFIGURATION EXPORT AND DISPLAY

Export and display protocol configurations

Step 1: Export all configurations to default location

Expected Output: Exported 9 configuration(s) to ./results/configs/

Step 2: Export specific protocol configuration

Expected Output: Exported 1 configuration(s) to ./results/configs/ - wireguard: wireguard_20250817_143022.conf

Step 3: Export all configs to custom path

Expected Output: Exported 9 configuration(s) to /tmp/vpn-configs/

Step 4: Export with credentials included

Expected Output: Exported 1 configuration(s) to ./results/configs/

Step 5: Export with JSON output showing results

Expected Output: {"command":"export-config","data":{"exported_count":9,"export_directory":"./results/configs/","files":[...]},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 6: Display WireGuard configuration

Expected Output: {"command":"showconfig","data":{"protocol":"wireguard","config":{"available":true,"config_content":"[Interface]\nPrivateKey = ...","masked":false,"name":"wireguard","status":"available"},"masked":false},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 7: Show all protocol configs in pretty JSON

Expected Output: Formatted JSON with all available protocol configurations

Step 8: Show config with passwords hidden

Expected Output: {"command":"showconfig","data":{"protocol":"dante","config":{"username":"dante_user","password":"***REDACTED***","ipv4_url":"socks5://dante_user:***REDACTED***@...",...},"masked":true},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 9: Get Shadowsocks connection URL

Expected Output: ss://Y2hhY2hhMjAtaWV0Zi1wb2x5MTMwNTp6TDQ4cVYx...@<VPN_IP>:8388#Shadowsocks-IPv4

Step 10: Get SOCKS5 URLs in JSON format

Expected Output: {"ipv4": "socks5://user:pass@<VPN_IP>:1080", "ipv6": "socks5://user:pass@[<VPN_IPv6>]:1080"}

Step 11: Get URLs for all available protocols

Expected Output: Protocol Connection URLs: shadowsocks: ipv4: ss://... dante: ipv4: socks5://...

Step 12: Generate QR code for WireGuard config

Expected Output: [QR Code ASCII Art] URL: wireguard://base64_encoded_config

Step 13: Generate IPv4 QR code for Shadowsocks (default)

Expected Output: [QR Code ASCII Art] URL: ss://...

Step 14: Generate IPv6 QR code for Shadowsocks

Expected Output: [QR Code ASCII Art] URL: ss://...

Step 15: Generate QR without validation (faster)

Expected Output: [QR Code ASCII Art] ⚠ Validation skipped

Step 16: Generate all QR codes with strict validation

Expected Output: ✓ Shadowsocks QR validated ✓ WireGuard QR validated...

Step 17: Get QR data in JSON format

Expected Output: {"command":"showconfigqr","data":{"protocol":"dante","qr":{"content_type":"image/png","format":"ipv4","protocol":"dante","qr_code":"<base64-png>","url":"socks5://...","validated":true}},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 18: Generate QR code and save as PNG file

Expected Output: [QR Code ASCII Art] ✓ IPv4 QR code files saved to ./results/qr-codes/

Step 19: Generate IPv6 QR code and save as PNG file

Expected Output: [QR Code ASCII Art] ✓ IPv6 QR code files saved to ./results/qr-codes/

Step 20: Generate both IPv4 and IPv6 QR codes

Expected Output: [QR Code ASCII Art] ✓ IPv4 and IPv6 QR code files saved to ./results/qr-codes/

Step 21: Generate all QR codes with pretty JSON output

Expected Output: Pretty-formatted JSON with QR data and file paths

Step 22: Save QR file with human-enhanced JSON output

Expected Output: {"command":"showconfigqr","data":{"protocol":"wireguard","qr":{"qr_code":"<base64-png>","saved_file_path":"./results/qr-codes/wireguard.png",...}},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Scenario 21: QR CODE VALIDATION

Validate QR codes against auth card

Step 1: Validate QR code from image file (NEW: direct filename)

Expected Output: ✓ QR valid: Shadowsocks (confidence: 98.5%)

Step 2: Validate QR code from results/qr-codes directory

Expected Output: ✓ QR valid: Dante (confidence: 96.2%)

Step 3: Validate QR code using explicit --file flag (legacy syntax)

Expected Output: ✓ QR valid: Shadowsocks (confidence: 98.5%)

Step 4: Validate QR URL from stdin

Expected Output: ✓ Protocol: shadowsocks ✓ Config matches auth card

Step 5: Validate all generated QR codes

Expected Output: Validating all QR codes... ✓ shadowsocks_ipv4.png: valid ✓ wireguard.png: valid

Step 6: Test QR code readability

Expected Output: Testing QR readability... ✓ QR code is readable

Step 7: JSON validation output

Expected Output: {"command":"validate-qr","data":{"is_valid":true,"protocol":"shadowsocks","confidence_score":0.985,"config_data":{...}},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Scenario 22: ERROR RECOVERY

Recover from connection issues

Step 1: Force disconnect stuck connection

Expected Output: Force killed all processes, routes restored

Step 2: Reset all routing to default

Expected Output: Routing reset to system defaults

Step 3: Clean up orphaned processes

Expected Output: Cleaned up 2 orphaned tun2socks processes

Step 4: Automatically diagnose and fix routing issues, restore network settings

Expected Output: System recovered, ready for new connection

Scenario 23: MICROSOCKS SERVER MODE

Turn Kodachi into a SOCKS5 proxy server for other devices on your network

Step 1: Enable microsocks server with auto port detection

Expected Output: Microsocks server started on port 30050, listening on all interfaces

Step 2: Enable with specific port

Expected Output: Microsocks server started on port 30051

Step 3: Check microsocks server status

Expected Output: Status: Running, Port: 30050, PID: 12345

Step 4: Check status in JSON format

Expected Output: {"command":"microsocks-status","data":{"status":"running","running":true,"port":30050,"pid":12345,"listening_address":"0.0.0.0","username":"...","started_at":"...","uptime_seconds":...},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 5: Stop microsocks server

Expected Output: Microsocks server stopped successfully

Step 6: Full example of using Kodachi as a proxy server

Expected Output: Step 1: sudo routing-switch connect wireguard Step 2: sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds' Step 3: Other PCs connect to socks5://microkodachi-8273:S@Cur9P@s@Wo-Ds@YOUR_IP:30050

Step 7: Microsocks uses dedicated port range

Expected Output: Microsocks: 30050-30054 Other services use different ranges to avoid conflicts

Step 8: How other devices connect

Expected Output: Protocol: SOCKS5 Address: YOUR_KODACHI_IP (e.g., 192.168.1.100) Port: 30050 Username: microkodachi-8273 Password: S@Cur9P@s@Wo-Ds

Scenario 24: VPNGATE FREE VPN

Connect to free VPNGate public servers (no authentication required)

Step 1: Fetch VPNGate server list from public API

Expected Output: Fetched 150 VPNGate servers

Step 2: List all cached VPNGate servers

Expected Output: Index Flag Country IP Speed Ping Score Sessions

Step 3: List top 10 Japanese servers by speed

Expected Output: 10 servers shown, filtered by country: JP

Step 4: List US servers sorted by lowest ping

Expected Output: Servers sorted by ping latency

Step 5: Connect to VPNGate server at index 5

Expected Output: Successfully connected to <server> via openvpn

Step 6: Force connect to server 12 (disconnect existing first)

Expected Output: Force connected to VPNGate server

Step 7: Fetch servers with JSON output

Expected Output: {"command":"vpngate-fetch","data":{"status":"success","server_count":150,"cache_file":"...","fetched_at":"..."},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 8: List servers in pretty JSON format

Expected Output: Pretty-printed JSON array of servers

Step 9: Export top server's OpenVPN config as .ovpn file

Expected Output: Exported: JP Japan (1.2.3.4) -> results/vpngate-configs/1_jp_1-2-3-4.ovpn

Step 10: Export all cached servers as .ovpn files

Expected Output: Exported 99 VPNGate configs to results/vpngate-configs

Step 11: Export server #5 config with JSON output

Expected Output: {"command":"vpngate-export","data":{"action":"vpngate-export","file":"...","server":{"index":5,"country":"...","country_code":"...","flag":"...","ip":"...","speed":"...","ping":...,"score":...}},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Scenario 25: EXTERNAL VPN PROVIDERS

Browse, fetch, and connect through commercial / free third-party VPN providers (VPN Gate, Riseup, NordVPN, IVPN, PIA, Surfshark, AirVPN, Mullvad-WG, …)

Step 1: Show every provider in the catalog with cache freshness

Expected Output: VPN Provider Catalog ... vpngate ... riseup ... nordvpn

Step 2: Same list in machine-readable JSON for the GUI / scripts

Expected Output: {"command":"providers-list","data":{"schema_version":"1.1.0","catalog_path":"...","provider_count":13,"providers":[{"id":"vpngate","tier":"tier_a",...}]},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 3: Fetch the live profile list for a provider into the cache

Expected Output: ✓ Fetched N profiles for 'vpngate' (cached at ...)

Step 4: Bypass the per-provider cache TTL and always re-fetch

Expected Output: Refetches and overwrites the cache

Step 5: Browse cached profiles for a provider (table view)

Expected Output: # Display name | Flag | CC | Remote | Protocol | Port | Load

Step 6: Filter to top 5 Japanese profiles

Expected Output: 5 profiles, all CC=JP

Step 7: JSON form (the GUI's primary surface)

Expected Output: {"command":"providers-list-profiles","data":{"provider_id":"vpngate","profile_count":99,"country_filter":null,"protocol_filter":null,"profiles":[...]},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 8: Dump a single profile's .ovpn content to stdout (or pipe to a file)

Expected Output: (raw .ovpn body)

Step 9: Re-read the catalog JSON after editing it on disk

Expected Output: ✓ Catalog reloaded ...

Step 10: Connect using a profile previously fetched via `providers get-profile`

Expected Output: Successfully connected to OpenVPN server

Step 11: Save NordVPN service credentials (separate from the dashboard login)

Expected Output: ✓ Saved 2 credential field(s) for 'nordvpn'

Step 12: Show which providers have stored credentials (values are never printed)

Expected Output: VPN Provider Credentials ... nordvpn ... yes (username,password)

Step 13: Connect via a provider profile, auto-injecting saved credentials into auth-user-pass

Expected Output: Successfully connected to OpenVPN server

Step 14: Phase 5: import your own .ovpn / .conf / JSON / YAML config as a custom profile

Expected Output: ✓ Imported custom profile ... Protocol: openvpn ... Connect with: routing-switch providers connect custom <id>

Step 15: Save the VPN account username/password for an imported OpenVPN profile (Proton VPN and most commercial providers)

Expected Output: ✓ Saved 2 credential field(s) for custom profile 'my-vpn-20260522'

Step 16: Import inline text with an explicit protocol hint (overrides auto-detect)

Expected Output: ✓ Imported custom profile ... Protocol: wireguard

Step 17: Browse the configs you've imported

Expected Output: Provider: custom ... Profiles: N

Step 18: Remove a previously-imported custom profile

Expected Output: ✓ Deleted custom profile '...'

Step 19: CV-3 dry-run: preview detected protocol + endpoint + warnings without writing to cache

Expected Output: {"command":"providers-validate-config","data":{"detected_protocol":"v2ray","remote_host":"example.com","remote_port":8443,"transport":"tcp","warnings":[],"hint_used":false},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 20: Look up the country for a cached profile via ip-fetch (skips if already tagged)

Expected Output: ✓ Resolved country for riseup/vpn12-nyc_udp_1194: us (United States)

Step 21: DNS-resolve the profile's hostname to an IPv4 and store in remote_ip

Expected Output: ✓ riseup/vpn12-nyc_udp_1194 resolved vpn12-nyc.riseup.net → 198.252.153.x

Step 22: Bulk DNS-resolve every cached profile in a provider that's missing an IP

Expected Output: ✓ N resolved out of M (failed: K)

Step 23: Pick a random profile (optionally filtered by country) and connect

Expected Output: Successfully connected to OpenVPN server

Step 24: Pick the fastest profile and connect (lowest measured latency if you've benchmarked; otherwise highest speed_bps)

Expected Output: Successfully connected to OpenVPN server

Step 25: User-triggered latency probe: pings each cached server (ICMP → TCP-connect fallback) and stores latency_ms. Manual only — same UX as ip-fetch's cache refresh.

Expected Output: {"command":"providers-benchmark","data":{"provider_id":"vpngate","tested":20,"succeeded":18,"failed":2,"elapsed_ms":5200,"timeout_secs":3,"concurrency":8,"fastest":{"profile_id":"1_219-100-37-203","latency_ms":42}},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 26: Drop the on-disk cache for one provider (index + configs/). Credentials are NOT touched.

Expected Output: {"command":"providers-clear-cache","data":{"provider_id":"riseup","removed":true},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Step 27: Bulk wipe: remove every cached provider's index + configs in one shot

Expected Output: {"command":"providers-clear-cache","data":{"scope":"all","providers_cleared":9},"errors":[],"metadata":{...},"status":"success","timestamp":"...","version":"9.0.1","warnings":[]}

Environment Variables

Variable	Description	Default	Values
RUST_LOG	Set logging level (default: info)	info	error, warn, info, debug, trace

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Permission denied

---