thronetools 1.1.0

CLI tool for Throne - xray client

ThroneTools

Cross-platform CLI to install, reinstall, uninstall, and manage configuration for Throne(NekoRay) on Linux, macOS, and Windows.

Requirements

• Python 3.10+
• uv

Features

• Cross-platform — Linux, macOS, and Windows support
• Self-update — Update Throne to the latest release with one command
• Geo data management — Install and verify geoip/geosite databases for sing-box

Quick Start (uv)

# from repo root
uv sync
uv run thronetools --help

Run without subcommands to show the styled help:

uv run thronetools

Commands

thronetools install
thronetools update --app {throne|nekoray}
thronetools backup --app {throne|nekoray} [--output <path-or-dir>]
thronetools restore --app {throne|nekoray} --zip <backup.zip>
thronetools remove --app {throne|nekoray}
thronetools reinstall --app {throne|nekoray} [--backup] [--output <path-or-dir>] [--force]
thronetools version --app {throne|nekoray}
thronetools geo-install --app {throne|nekoray}
thronetools hotspot enable [--iface <iface>] [--ssid <name>] [--password <pass>] [--dry-run]
thronetools hotspot disable [--dry-run]

Common Examples

# Install Throne
uv run thronetools install

# Update Throne to the latest version
uv run thronetools update --app throne

# Install/update geoip and geosite databases
uv run thronetools geo-install --app throne

# Backup Throne config to current directory
uv run thronetools backup --app throne

# Backup NekoRay config to a specific folder
uv run thronetools backup --app nekoray --output ~/Backups

# Restore Throne config
uv run thronetools restore --app throne --zip ~/Backups/throne-backup-2026-02-17.zip

# Reinstall with backup + restore flow
uv run thronetools reinstall --app throne --backup

# Show installed app details
uv run thronetools version --app throne

# Preview hotspot commands without applying changes
uv run thronetools hotspot enable --iface wlp2s0 --dry-run

Notes

• hotspot commands are supported on Linux and macOS. On Windows, hotspot subcommands are not available.
• Some operations require elevated privileges depending on platform/package manager.

Development

# Lint/format (Ruff is configured in pyproject.toml)
uv run ruff check .
uv run ruff format .

# Build package
uv build

Related Projects

Explore other CLI tools by Arian Omrani:

• LinkCovery - Modern bookmark management CLI tool
• PEM - Python Execution Manager - Schedule and execute Python scripts
• OllamaTools - CLI tool for managing Ollama models

Install as a tool (optional)

If you want a globally available command via uv:

uv tool install .
thronetools --help

To update later:

uv tool upgrade thronetools

License

MIT License — see the LICENSE file for details.

Contributing

Contributions are welcome! Feel free to submit a pull request.