CLI Reference

xrat is a command-first CLI tool. All operations are invoked as subcommands.

Global Flags

These flags apply to every command:

Flag	Description
`-v`, `--verbose`	Increase log verbosity. Repeat: `-v`=info, `-vv`=debug, `-vvv`=trace
`-q`, `--quiet`	Suppress output except errors. Ignored if `RUST_LOG` is set
`--database <path>`	SQLite database path override
`--config <path>`	Config file path override
`--xray <path>`	Xray binary path override
`--v2ray <path>`	V2Ray binary path override
`--sing-box <path>`	sing-box binary path override

Command	Description
`setup`	Run post-install setup (init, daemon, completions, desktop)
`import`	Import a subscription URL, file, or raw text into the database
`update`	Refresh stored subscriptions by ref or all at once
`add`	Add a single config URI directly to the database
`stable refs`	Use short stable refs instead of numeric database IDs
`list`	List stored configs or subscriptions
`show`	Show details for a stored config
`enable`	Include a config in normal operations
`disable`	Exclude a config from normal operations
`delete`	Soft-delete or permanently delete a config
`restore`	Restore a soft-deleted config
`parse`	Parse and validate config links without persisting
`test`	Test connectivity and latency for stored configs
`scan`	Scan candidate IPs for TCP reachability
`connect`	Start a managed proxy runtime for a stored config
`disconnect`	Stop the active managed proxy runtime
`status`	Show the managed proxy runtime status
`daemon`	Run or control the daemon supervisor process
`proxy`	Control auto-rotating proxy scheduling via the daemon
`mmdb`	Manage GeoLite2 MMDB assets and inspect GeoIP backend config
`serve`	Start the local HTTP API server
`tui`	Start the interactive terminal UI
`upgrade`	Self-upgrade from the latest release or by building from source
`version`	Print the xrat version

These words appear across the CLI, TUI, API, and database:

Term	Meaning
`enabled`	Included in bulk tests and rotation candidate sets
`disabled`	Stored but normally skipped by filtered workflows
`active`	Config attached to the current managed runtime session
`deleted`	Soft-deleted row hidden from normal lists unless requested

Use connect to make a config active by starting a runtime session.

xrat uses tracing for structured logging. Control verbosity with:

Logs are written to stderr.