Quickstart
This guide walks through the core xrat workflow: import a subscription, test configs, and start a local proxy.
0. Initialize
Run once after installing to create the config directory, default config file, and database:
xrat init
See init for details on what gets created and how to use
a custom path via XRAT_PATH.
1. Import a Subscription
Import from a URL:
xrat import https://example.com/subscription
Import from a local file:
xrat import ./subscription.txt
Import raw subscription text directly:
xrat import "vless://uuid@example.com:443?type=ws&security=tls#MyNode"
xrat automatically detects the input format: subscription URL, local file, raw base64-encoded subscription, plain link list, SIP008 JSON, or Xray JSON.
2. List Imported Configs
xrat list configs
Filter by subscription source:
xrat list configs --subscription f00d
Use enable and disable to control whether a config appears in enabled-only
workflows:
xrat disable a1b2
xrat enable a1b2
3. Test Connectivity
Test a single config by ref:
xrat test a1b2
Bulk-test all enabled configs:
xrat test --enabled-only --concurrency 4
Skip specific stages:
xrat test a1b2 --skip-icmp --skip-download
4. Start a Proxy
Start the daemon first:
xrat daemon start
Connect using a tested config:
xrat connect a1b2
The command sends a daemon IPC request. The daemon starts the Xray (or V2Ray) process with a generated runtime config. By default, it exposes:
- SOCKS5 on
0.0.0.0:18200 - HTTP on
0.0.0.0:18201(if enabled in config.toml)
5. Check Status
xrat status
6. Disconnect
xrat disconnect
Interactive TUI
For an interactive view over configs, sources, tests, runtime status, and diagnostics:
xrat tui
Using the Daemon
For persistent operation with auto-rotation:
xrat daemon start
xrat rotate enable
xrat rotate now
xrat rotate status
xrat daemon stop
xrat connect <id> starts one managed runtime session immediately through the
daemon. xrat rotate enable enables daemon-driven auto-rotation.