xrayvpn 0.4.1__tar.gz

xrayvpn-0.4.1/.gitignore

@@ -0,0 +1,41 @@
+# Python environments
+.venv/
+venv/
+__pycache__/
+
+# Ansible
+.ansible/
+*.retry
+downloaded-configs/
+downloaded-clients/
+inventory.yml
+.xrayvpn-inventory.yml
+.xrayvpn-fetch-playbook.yml
+
+# VS Code
+.vscode/
+
+# OS cruft
+.DS_Store
+Thumbs.db
+
+.llm_context/
+
+.kilo/
+
+# --- Python extras ---
+.ruff_cache/
+.pytest_cache/
+
+# --- Binary builds ---
+python-client/build/
+python-client/dist/
+python-client/dist-binary/
+
+# --- Env files (any project) ---
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+*.env

xrayvpn-0.4.1/BUILD.en.md

@@ -0,0 +1,67 @@
+# Building standalone xrayvpn binaries
+
+Summary: `xrayvpn` is packaged by Nuitka (`--mode=onefile`) into a single
+executable `xrayvpn-<os>-<arch>[.exe]` carrying the bundled payload (`roles/`,
+`config/`, `deploy.yml`, `inventory.yml.example` → `xrayvpn/payload/…`; the same
+allowlist used for server uploads). The PyInstaller spec `xrayvpn.spec` is a
+fallback with the identical payload contract (shared staging in `build_support.py`).
+
+## Requirements
+
+- `uv` (same pin as CI) — the wrapper syncs the `build` dependency group itself.
+- C compiler: Windows — Visual Studio 2022 (or Nuitka auto-downloads MinGW),
+  Linux — gcc, macOS — clang (Xcode CLT).
+- Python 3.12+ (`requires-python` in `pyproject.toml`).
+
+## Commands
+
+```
+# Windows
+.\build-binary.ps1                       # onefile, canonical
+.\build-binary.ps1 -Mode standalone      # debug mode (onedir folder)
+.\build-binary.ps1 -Engine pyinstaller   # fallback spec
+.\build-binary.ps1 -Version 0.4.1        # release version fed to metadata/--version (default: __version__)
+
+# Linux/macOS
+./build-binary.sh
+./build-binary.sh --mode standalone
+./build-binary.sh --engine pyinstaller --version 0.4.1
+```
+
+Artifacts land in `dist-binary/`. Contract: identical payload paths for both
+engines, `--version` = the version passed, file name = `xrayvpn-<os>-<arch>[.exe]`.
+
+## Debug loop
+
+1. `--mode standalone` → inspect `dist-binary/xrayvpn-*.dist/` by hand.
+2. No complaints → `--mode onefile` (default) → smoke below.
+3. Nuitka surprises (bcrypt/cffi/plugin deps) — fix with flags/`--include-package`,
+   not client code; as a last resort use the PyInstaller spec (payload contract unchanged).
+
+## Onefile cache
+
+Extraction goes to `{CACHE_DIR}/xrayvpn/{VERSION}` (a stable path so Windows
+Firewall does not treat every run as a new program; repeat launches skip
+re-extraction). A version change creates a fresh cache directory.
+
+## Smoke set (MUST run from a NEUTRAL cwd)
+
+Outside the repo checkout — `--dry-run` would otherwise find the bundle via the
+composite clone marker `roles/xray_vpn` inside the repo and the check would not count:
+
+```
+cd $TMPDIR/some-empty-dir
+XRAYVPN_UPDATE_CHECK=0 ./xrayvpn-… --version          # first line: xrayvpn <version>
+XRAYVPN_UPDATE_CHECK=0 ./xrayvpn-… deploy --dry-run --no-interactive --host 127.0.0.1
+XRAYVPN_LANG=ru XRAYVPN_UPDATE_CHECK=0 ./xrayvpn-… --ru --help   # RU output (l10n-patch sentinel in freeze)
+XRAYVPN_REPL_SELFTEST=1 ./xrayvpn-… repl               # stdin feeding: help\nexit\n → rc 0
+# Windows: double-click on the .exe = same entry with a console (--windows-console-mode=force);
+# on a fatal error the window stays open with the message until you press Enter.
+```
+
+## Known environment notes
+
+- Unsigned Windows exe → SmartScreen “More info”; macOS → `chmod +x`,
+  Gatekeeper → right-click Open / `xattr -d com.apple.quarantine`.
+- Reset the onefile cache: delete `{CACHE_DIR}/xrayvpn/<version>`.
+- On low-memory hosts add `--low-memory` / `--jobs=1` inside `build_binary.py`.

xrayvpn-0.4.1/BUILD.md

@@ -0,0 +1,67 @@
+# Сборка standalone-приложения xrayvpn
+
+Суть: `xrayvpn` упаковывается Nuitka (`--mode=onefile`) в один исполняемый
+файл `xrayvpn-<os>-<arch>[.exe]` с bundled payload (`roles/`, `config/`, `deploy.yml`,
+`inventory.yml.example` → `xrayvpn/payload/…`; тот же allowlist, что у загрузки на сервер).
+PyInstaller-спека `xrayvpn.spec` — фолбэк с тем же контрактом payload
+(общий staging из `build_support.py`).
+
+## Требования
+
+- `uv` (тот же пин, что в CI) — окружение и группу `build` ставит сам через wrapper.
+- C-компилятор: Windows — Visual Studio 2022 (или авто-догруз MinGW Nuitka),
+  Linux — gcc, macOS — clang (Xcode CLT).
+- Python 3.12+ (_requires-python_ из `pyproject.toml`).
+
+## Команды
+
+```
+# Windows
+.\build-binary.ps1                       # onefile, канон
+.\build-binary.ps1 -Mode standalone      # отладочный режим (папка onedir)
+.\build-binary.ps1 -Engine pyinstaller   # фолбэк-спека
+.\build-binary.ps1 -Version 0.4.1        # версия в метаданные/--version (дефолт: __version__)
+
+# Linux/macOS
+./build-binary.sh
+./build-binary.sh --mode standalone
+./build-binary.sh --engine pyinstaller --version 0.4.1
+```
+
+Артефакты — `dist-binary/`. Контракт: одинаковые payload-пути у обоих движков,
+`--version` = переданная версия, имя файла = `xrayvpn-<os>-<arch>[.exe]`.
+
+## Цикл отладки
+
+1. `--mode standalone` → проверить `dist-binary/xrayvpn-*.dist/` вручную.
+2. Претензий нет → `--mode onefile` (дефолт) → смоук ниже.
+3. Nuitka-сюрпризы (bcrypt/cffi/плагин-зависимости) — чинить флагами/`--include-package`,
+   не кодом клиента; в крайнем случае — PyInstaller-спека (контракт payload не меняется).
+
+## Onefile-кэш
+
+Распаковка идёт в `{CACHE_DIR}/xrayvpn/{VERSION}` (стабильный путь — Windows Firewall
+не считает каждый запуск новой программой; повторные запуски без переупаковки).
+Смена версии = новая папка кэша.
+
+## Smoke-набор (ОБЯЗАТЕЛЬНО из НЕЙТРАЛЬНОГО cwd)
+
+Каталог вне checkout репо (`--dry-run` сам нашёл бы бандл по композит-маркеру
+`roles/xray_vpn`, если запускать внутри репо — проверка бандла не считается):
+
+```
+cd $TMPDIR/some-empty-dir
+XRAYVPN_UPDATE_CHECK=0 ./xrayvpn-… --version          # первая строка: xrayvpn <версия>
+XRAYVPN_UPDATE_CHECK=0 ./xrayvpn-… deploy --dry-run --no-interactive --host 127.0.0.1
+XRAYVPN_LANG=ru XRAYVPN_UPDATE_CHECK=0 ./xrayvpn-… --ru --help   # RU-вывод (страж l10n-патчей в freeze)
+XRAYVPN_REPL_SELFTEST=1 ./xrayvpn-… repl               # feeding stdin: help\nexit\n → rc 0
+# Windows: двойной клик по .exe = тот же entry с консолью (--windows-console-mode=force);
+# при фатальной ошибке окно остаётся с текстом до нажатия Enter.
+```
+
+## Known environment notes
+
+- Не-подписанный Windows-exe → SmartScreen «показать подробности», macOS → `chmod +x`,
+  Gatekeeper → ПКМ→Открыть/`xattr -d com.apple.quarantine`.
+- Сброс кэша onefile: удалить папку `{CACHE_DIR}/xrayvpn/<версия>`.
+- `--low-memory` / `--jobs=1` добавить в `build_binary.py` на малоразмерных хостах.

xrayvpn-0.4.1/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: xrayvpn
+Version: 0.4.1
+Summary: Python client for provisioning Xray VLESS + REALITY VPN servers (local and remote execution)
+License-Expression: AGPL-3.0-or-later
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Requires-Dist: fabric>=3.2.3
+Requires-Dist: inquirerpy>=0.3.4
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer<0.28,>=0.27.2
+Description-Content-Type: text/markdown
+
+# `python-client/`
+
+> English version: [README.en.md](README.en.md).
+
+Основной клиент `xrayvpn` (Python) — развертывание, обновление и ротация Xray-сервера.
+Одинаково на Windows, Linux и macOS; удалённый и локальный режимы в одном CLI.
+
+## Установка и запуск
+
+Самый простой вариант — готовая standalone-сборка без Python: скачайте файл своей платформы
+из [Releases](https://github.com/lifestreamy/xrayvpn/releases/latest).
+Первый запуск — в [../docs/user/SETUP.md](../docs/user/SETUP.md), раздел «Первый запуск».
+Как собрать самому (Nuitka onefile, режим отладки, smoke) — [BUILD.md](BUILD.md).
+
+Для работы с исходниками в репозитории нужен [uv](https://docs.astral.sh/uv/) (или Python 3.12+):
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
+```
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh                                       # Linux/macOS
+```
+
+Из корня репозитория:
+
+```bash
+uv run --project python-client xrayvpn --help
+```
+
+Внутри `python-client/` (после `uv sync`) работают и `uv run xrayvpn ...`, и `python -m xrayvpn`.
+
+На Windows можно вообще без флагов. Двойной клик по `xrayvpn-deploy.pyw` (английский интерфейс)
+или `xrayvpn-deploy-ru.pyw` (русский) открывает консоль и запускает интерактивный мастер деплоя.
+CLI спросит узел исполнения, хост VPS и SSH-аутентификацию, покажет план и запросит
+подтверждение: без него ничего не выполняется. Окно остаётся открытым — ошибки и код возврата
+видны до нажатия Enter.
+
+Дефис в имени лаунчера обязателен: `xrayvpn.pyw` рядом с пакетом перехватывал бы
+`import xrayvpn` на Windows.
+
+### Команда `xrayvpn` в PATH
+
+Чтобы вводить `xrayvpn` в любом терминале без префикса `uv run`, из корня репозитория:
+
+```bash
+uv tool install --editable python-client
+```
+
+Установка editable — изменения кода в репозитории применяются сразу. Запускать из папки
+репозитория: клиент ищет `deploy.yml` и `config/settings.yml` вверх от текущей директории.
+Удаление — `uv tool uninstall xrayvpn`.
+
+## Интерактивный режим
+
+`xrayvpn` без аргументов (или `xrayvpn repl`) открывает интерактивный режим: команды внутри —
+с тем же синтаксисом, что CLI, без префикса. `deploy` спросит недостающее и покажет план как
+обычно; `help` перечисляет встроенное (`version`, `lang ru|en`, `exit`); `deploy --help` —
+полный список флагов развёртывания. Приветственная плашка перерисовывается при смене языка
+(`lang ru|en` или просто `ru`/`en`) и сразу показывает `service` — аварийные команды по SSH.
+Под ссылками — строка «прервалось — повтори деплой» со ссылкой на docs; во время прогона видно
+прогресс этапов `[1/7]…[7/7]`, в долгих фазах — счётчик секунд.
+Двойной клик по standalone-приложению и `.pyw`-обёртки —
+это тот же режим. На Windows с Windows Terminal как терминалом по умолчанию двойной клик по `.exe`
+открывает классическое окно conhost с иконкой приложения (перезапуск через `conhost.exe`); остаться
+во вкладке Windows Terminal — флаг `--wt` или `XRAYVPN_IN_WT=1`.
+
+## Куда ставится и где выполняется ansible
+
+Цель деплоя — **всегда удалённый VPS**. `--execution` выбирает лишь узел, где
+выполняется сам ansible:
+
+- **remote** (по умолчанию) — окружение поднимается на VPS по SSH: bootstrap,
+  загрузка репозитория tarball'ом (GitHub серверу не нужен), playbook на сервере,
+  забор готовых клиентских конфигов. На слабом VPS bootstrap и apt могут упираться
+  в память (для этого встроен swap-guard).
+- **local** — ansible-контроллер на вашей машине: на Linux/macOS напрямую
+  (venv/PATH, по умолчанию `~/xray-venv`), на Windows — через WSL. Цель та же —
+  VPS по SSH (creds: флаги `--host/--user/--port/--pkey/--pass` или личный
+  `inventory.yml` через `--use-inventory`), конфиги после прогона подтягиваются тем
+  же ansible-fetch по SSH. Полезно на очень слабых VPS, где Ansible на самом
+  сервере работать не может. Парольная аутентификация требует `sshpass`.
+- Без `--execution` — вопрос в терминале (по умолчанию remote).
+
+Перед любым реальным прогоном клиент показывает **план деплоя** (узел, цель,
+аутентификация — пароль только `******`, изменения, предупреждение при `--rotate`,
+куда лягут конфиги) и спрашивает согласие; `--no-interactive` отключает вопросы
+для скриптов/CI (недостающие обязательные значения тогда — ошибка). `--dry-run`
+план не подтверждает (он ничего не меняет).
+
+## Примеры
+
+```bash
+# VPS по IP: пароль спросит скрыто (или заранее --pkey ~/.ssh/id_ed25519)
+uv run --project python-client xrayvpn deploy --host 1.2.3.4
+
+# параметры подключения из личного inventory.yml
+uv run --project python-client xrayvpn deploy --use-inventory
+
+# ansible с вашей машины против того же VPS, без WARP и без ротации
+uv run --project python-client xrayvpn deploy --execution local --host 1.2.3.4 --no-warp --no-rotate
+
+# план remote-развертывания без какого-либо подключения
+uv run --project python-client xrayvpn deploy --host 1.2.3.4 --dry-run
+```
+
+## Флаги `deploy`
+
+- Узел выполнения: `--execution remote|local` (цель всегда VPS; без флага — вопрос, дефолт remote).
+- Неинтерактивно: `--no-interactive` — без вопросов и подтверждения плана (для CI/скриптов).
+- Язык: `--ru` — полностью русский интерфейс (промпты, сообщения, ошибки, `--help`);
+  работает в любой позиции аргументов, альтернатива — переменная окружения `XRAYVPN_LANG=ru`.
+- Переопределения сервера (иначе берётся из `config/settings.yml`): `--runtime native|docker`,
+  `--xray-port`, `--num-clients`, `--camouflage-domain`, `--warp/--no-warp`,
+  `--rotate/--no-rotate` (перегенерация ключа REALITY и UUID / оставить как есть),
+  `--manage-ufw/--no-ufw`.
+- Инвентарь: `--inventory PATH` — только local, ssh-inventory для прогона (по умолчанию
+  генерируется `.xrayvpn-inventory.yml` с параметрами VPS из флагов/inventory, 0600,
+  после прогона удаляется);
+  `--use-inventory` — читает подключение и переменные из личного `inventory.yml`
+  (перекрывает host/key-флаги с предупреждением).
+- Подключение (цель-VPS, оба узла): `--host`/`-H`, `--user`/`-u` (default `root`), `--port`/`-p` (default 22),
+  `--pkey FILE` (предпочтительно), `--pass TEXT` (пароль в открытом виде, хуже ключа; без него —
+  скрытый запрос). `--user`/`--port` без явного значения не пинуются: для хоста из
+  `~/.ssh/config` работают user/port из конфига, для голого IP — `root:22`.
+- Результат: `--clients-dir PATH` — куда сохранить конфиги клиентов
+  (default `<repo>/downloaded-clients/`, забираются с сервера из `/root/vpn-configs`);
+  `--no-config-download` — вообще не скачивать, оставить их на сервере.
+- Уборка на сервере (remote): по умолчанию staging-каталог удаляется, venv остаётся;
+  `--full-cleanup` — снести и venv, `--no-cleanup` — оставить всё.
+- Windows и `--execution local`: `--wsl-distro` (дистрибутив WSL) и `--wsl-venv` (venv с
+  `ansible-playbook`, по умолчанию `~/xray-venv`).
+- Диагностика: `--dry-run` (узел local: ansible `--check`; узел remote: напечатанный план без подключения),
+  `--debug` / `--verbose` (Ansible -vvv/-vvvv; вместе нельзя, как и `--pkey` с `--pass`).
+
+Полная афиша: `xrayvpn deploy --help`.
+
+## Сервисные действия (`xrayvpn service`)
+
+Когда VPN уже развёрнут и что-то деградировало — точечные действия по SSH теми же флагами
+подключения (`-H/--pkey/--pass/--use-inventory`): `service status` (состояние, журнал, слушатели),
+`service restart` (перезапуск xray — WARP живёт внутри него),
+`service logs [--since 30m] [--lines N] [--out DIR]` (дамп журнала на свою машину: конечный снимок
+окна, по умолчанию 30 минут; Ctrl+C прерывает загрузку и сохраняет частичный файл),
+`service reboot --yes` (крайний случай, только с явным `--yes`).
+Порядок действий при сбое — [`docs/user/RUNBOOK.md`](../docs/user/RUNBOOK.md).
+
+## Где что лежит
+
+- `src/xrayvpn/` — пакет (`cli/`, `core/`, `core/execution/`, `core/transport/`);
+- `tests/` — pytest-набор (в CI нога `python-client` гоняет его и ruff; контракт лаунчеров
+  `.pyw` ↔ CLI проверяется статически и реальным запуском);
+- смежные зоны репо: `shell-clients/` (Bash/PowerShell, поддержка без развития), `scripts/`
+  (инструменты разработки).
+
+Настройка сервера — [../docs/user/SETUP.md](../docs/user/SETUP.md), ротация ключей —
+[../docs/user/ROTATION.md](../docs/user/ROTATION.md).

xrayvpn-0.4.1/README.en.md

@@ -0,0 +1,153 @@
+# `python-client/`
+
+> This is the English copy of [README.md](README.md); the Russian file is the base.
+
+The primary `xrayvpn` client (Python) — deploy, update and rotate an Xray server.
+Works the same on Windows, Linux and macOS; remote and local modes in one CLI.
+
+## Install and run
+
+The simplest option is the standalone binary with no Python: download the build for your
+platform from [Releases](https://github.com/lifestreamy/xrayvpn/releases/latest). First run —
+[../docs/user/SETUP.en.md](../docs/user/SETUP.en.md), "First run" section. To build the binary
+yourself (Nuitka onefile, debug mode, smoke) — [BUILD.en.md](BUILD.en.md).
+
+Working with the sources in the repository requires [uv](https://docs.astral.sh/uv/) (or Python 3.12+):
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
+```
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh                                       # Linux/macOS
+```
+
+From the repository root:
+
+```bash
+uv run --project python-client xrayvpn --help
+```
+
+Inside `python-client/` (after `uv sync`) both `uv run xrayvpn ...` and `python -m xrayvpn` work.
+
+On Windows you can skip flags entirely. Double-click `xrayvpn-deploy.pyw` (English UI) or
+`xrayvpn-deploy-ru.pyw` (Russian UI): a console opens and the interactive deploy wizard starts.
+The CLI asks for the execution node, the VPS host and SSH auth, prints a deploy plan and asks
+for confirmation: nothing runs without it. The window stays open — failures and the exit code
+are visible until you press Enter.
+
+The hyphen in the launcher name is mandatory: `xrayvpn-deploy.pyw` cannot shadow
+`import xrayvpn`, while a plain `xrayvpn.pyw` next to the package would.
+
+### The `xrayvpn` command on PATH
+
+To type `xrayvpn` in any terminal without the `uv run` prefix, from the repository root:
+
+```bash
+uv tool install --editable python-client
+```
+
+The install is editable — repository code changes apply immediately. Run it from the repository
+folder: the client locates `deploy.yml` and `config/settings.yml` by walking up from the current
+directory. Remove with `uv tool uninstall xrayvpn`.
+
+## Interactive mode
+
+`xrayvpn` with no arguments (or `xrayvpn repl`) opens the interactive mode: commands use the exact
+CLI syntax without the prefix. `deploy` still asks for the missing pieces and confirms the plan;
+`help` lists the built-ins (`version`, `lang ru|en`, `exit`); `deploy --help` shows every flag of
+the deploy command. The welcome banner is reprinted whenever the language switches
+(`lang ru|en` or just `ru`/`en`) and already shows `service` — the SSH recovery commands. The banner carries a "interrupted — rerun deploy" line with a docs link; a run shows stage progress `[1/7]…[7/7]`, counting seconds on the long stages.
+Double-clicking the binary and the `.pyw` launchers are this very mode. On Windows with
+Windows Terminal as the default terminal, double-clicking the `.exe` opens a classic conhost window
+with the app icon (a `conhost.exe` relaunch); to stay in a Windows Terminal tab, use the `--wt`
+flag or `XRAYVPN_IN_WT=1`.
+
+## Where the deploy goes and where ansible runs
+
+The target is **always a remote VPS**. `--execution` only picks the node where
+ansible itself runs:
+
+- **remote** (default) — the client bootstraps the VPS over SSH itself: environment
+  setup, repo uploaded as a tarball (the server never needs GitHub), the playbook on the
+  server, then it fetches the generated client configs. On a very small VPS the bootstrap
+  and apt may hit the RAM limit (a built-in swap-guard covers this).
+- **local** — the ansible control node is your own machine: directly on Linux/macOS
+  (venv/PATH, default `~/xray-venv`), through WSL on Windows. The target stays the same
+  VPS over SSH (creds: `--host/--user/--port/--pkey/--pass` flags or the personal
+  `inventory.yml` via `--use-inventory`); generated configs are pulled back with the same
+  ansible-fetch over SSH. Useful on weak VPSes where Ansible cannot run on the server
+  itself. Password auth additionally requires `sshpass`.
+- Without `--execution` the CLI asks in the terminal (default: remote).
+
+Before any real run the client prints a **deploy plan** (node, target, auth — a password
+is shown only as `******`, overrides, a warning when `--rotate` is set, where the configs
+land) and asks for consent; `--no-interactive` skips all prompts for scripts/CI (missing
+required values then fail). `--dry-run` needs no confirmation (it changes nothing).
+
+## Examples
+
+```bash
+# VPS by IP: the password is prompted with hidden input (or pass --pkey ~/.ssh/id_ed25519)
+uv run --project python-client xrayvpn deploy --host 1.2.3.4
+
+# connection parameters from the personal inventory.yml
+uv run --project python-client xrayvpn deploy --use-inventory
+
+# ansible on your own machine against the same VPS, no WARP, no forced rotation
+uv run --project python-client xrayvpn deploy --execution local --host 1.2.3.4 --no-warp --no-rotate
+
+# the remote deploy plan without connecting anywhere
+uv run --project python-client xrayvpn deploy --host 1.2.3.4 --dry-run
+```
+
+## `deploy` flags
+
+- Execution node: `--execution remote|local` (the target is always the VPS; no flag asks, default remote).
+- Non-interactive: `--no-interactive` — no prompts and no plan confirmation (for CI/scripts).
+- Language: `--ru` — fully Russian interface (prompts, messages, errors, `--help`);
+  works in any argument position, alternative — the `XRAYVPN_LANG=ru` environment variable.
+- Server overrides (otherwise taken from `config/settings.yml`): `--runtime native|docker`,
+  `--xray-port`, `--num-clients`, `--camouflage-domain`, `--warp/--no-warp`,
+  `--rotate/--no-rotate` (regenerate the REALITY key and UUIDs / keep them),
+  `--manage-ufw/--no-ufw`.
+- Inventory: `--inventory PATH` — `--execution local` only: the ssh-inventory to run with
+  (by default `.xrayvpn-inventory.yml` is generated from flags/inventory.yml, 0600, removed after the run);
+  `--use-inventory` — reads connection vars from the personal `inventory.yml` in both nodes
+  (overrides the host/key flags with a warning).
+- Connection (the VPS target, both nodes): `--host`/`-H`, `--user`/`-u`, `--port`/`-p`,
+  `--pkey FILE` (preferred), `--pass TEXT` (plain password, worse than a key; omit both and
+  it prompts, hidden). Left alone, `--user`/`--port` are not pinned: a `~/.ssh/config` host
+  keeps its user and port, a bare IP falls back to `root:22`.
+- Output: `--clients-dir PATH` — where client configs are saved
+  (default `<repo>/downloaded-clients/`, fetched from the server's `/root/vpn-configs`);
+  `--no-config-download` skips fetching and leaves them on the server.
+- Server-side cleanup (remote): by default the staging dir is removed, the venv stays;
+  `--full-cleanup` removes the venv too, `--no-cleanup` leaves everything.
+- Windows and `--execution local`: `--wsl-distro` (the WSL distro) and `--wsl-venv` (a venv holding
+  `ansible-playbook`, default `~/xray-venv`).
+- Diagnostics: `--dry-run` (local node: ansible `--check`; remote node: printed plan without connecting),
+  `--debug` / `--verbose` (Ansible -vvv/-vvvv; mutually exclusive, as are `--pkey` with `--pass`).
+
+Full list: `xrayvpn deploy --help`.
+
+## Service actions (`xrayvpn service`)
+
+Once the VPN is deployed and something degrades — point actions over SSH with the same
+connection flags (`-H/--pkey/--pass/--use-inventory`): `service status` (state, journal,
+listeners), `service restart` (restarts xray — WARP lives inside it), `service logs
+[--since 30m] [--lines N] [--out DIR]` (dumps the journal to your machine: a finite snapshot
+of the window, 30 minutes by default; Ctrl+C aborts the download and keeps the partial file),
+`service reboot --yes` (last resort, requires the explicit `--yes`). The recovery sequence —
+[`docs/user/RUNBOOK.en.md`](../docs/user/RUNBOOK.en.md).
+
+## Layout
+
+- `src/xrayvpn/` — the package (`cli/`, `core/`, `core/execution/`, `core/transport/`);
+- `tests/` — pytest suite (the `python-client` CI leg runs it plus ruff; the `.pyw` launcher ↔ CLI
+  contract is checked statically and by a real end-to-end launch);
+- sibling repo zones: `shell-clients/` (Bash/PowerShell, maintained, not developed) and
+  `scripts/` (contributor tooling).
+
+Server configuration — [../docs/user/SETUP.en.md](../docs/user/SETUP.en.md), key rotation —
+[../docs/user/ROTATION.en.md](../docs/user/ROTATION.en.md).