pia-proxy 1.0.0__py3-none-any.whl

cli/__init__.py

@@ -0,0 +1,5 @@
+"""
+PIA SOCKS5 Multi-Worker Proxy Pool - CLI Management Suite
+"""
+
+__version__ = "1.0.0"

cli/api_client.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+
+class APIClientError(Exception):
+    def __init__(self, message: str, status_code: int | None = None, response_body: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class APIClient:
+    def __init__(self, base_url: str, token: str = "", timeout: float = 10.0):
+        self.base_url = base_url.rstrip("/")
+        self.token = token.strip()
+        self.timeout = timeout
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        if params:
+            query = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
+            if query:
+                url = f"{url}?{query}"
+
+        headers = {
+            "User-Agent": "pia-proxy-cli/1.0",
+            "Accept": "application/json",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        data_bytes = None
+        if json_data is not None:
+            data_bytes = json.dumps(json_data).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        req = urllib.request.Request(url, data=data_bytes, headers=headers, method=method.upper())
+
+        try:
+            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                if not raw.strip():
+                    return {}
+                return json.loads(raw)
+        except urllib.error.HTTPError as e:
+            raw_err = e.read().decode("utf-8", errors="ignore")
+            try:
+                body = json.loads(raw_err)
+            except Exception:
+                body = raw_err
+            raise APIClientError(
+                message=f"HTTP {e.code}: {e.reason}",
+                status_code=e.code,
+                response_body=body,
+            ) from e
+        except urllib.error.URLError as e:
+            raise APIClientError(message=f"Connection failed: {e.reason}") from e
+        except Exception as e:
+            raise APIClientError(message=f"Request error: {str(e)}") from e
+
+    def is_alive(self) -> bool:
+        try:
+            res = self._request("GET", "/healthz", timeout=3.0)
+            return bool(res.get("ok"))
+        except Exception:
+            return False
+
+    def get_status(self, refresh: bool = False) -> dict[str, Any]:
+        return self._request("GET", "/api/status", params={"refresh": refresh}, timeout=12.0)
+
+    def get_nodes(self, refresh: bool = False) -> list[dict[str, Any]]:
+        res = self._request("GET", "/api/nodes", params={"refresh": refresh}, timeout=10.0)
+        return res.get("nodes", [])
+
+    def get_healthy_nodes(self) -> dict[str, Any]:
+        return self._request("GET", "/api/nodes/healthy", timeout=6.0)
+
+    def get_node(self, node_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/nodes/{node_id}", timeout=6.0)
+
+    def set_mode(self, worker_count: int) -> dict[str, Any]:
+        return self._request("POST", "/api/mode", json_data={"worker_count": worker_count}, timeout=30.0)
+
+    def get_mode(self) -> dict[str, Any]:
+        return self._request("GET", "/api/mode", timeout=5.0)
+
+    def rotate_any(self, country: str | None = None, server: str | None = None, wait_for_ready: bool = False) -> dict[str, Any]:
+        payload: dict[str, Any] = {"wait_for_ready": wait_for_ready}
+        if country:
+            payload["country"] = country
+        if server:
+            payload["server"] = server
+        return self._request("POST", "/api/rotate-any", json_data=payload, timeout=20.0)
+
+    def rotate_node(self, node_id: str, country: str | None = None, server: str | None = None, wait_for_ready: bool = False) -> dict[str, Any]:
+        payload: dict[str, Any] = {"wait_for_ready": wait_for_ready}
+        if country:
+            payload["country"] = country
+        if server:
+            payload["server"] = server
+        return self._request("POST", f"/api/nodes/{node_id}/rotate", json_data=payload, timeout=25.0)
+
+    def recover_all(self, force: bool = False) -> dict[str, Any]:
+        return self._request("POST", "/api/recover", json_data={"force": force}, timeout=15.0)
+
+    def recover_node(self, node_id: str, force: bool = False) -> dict[str, Any]:
+        return self._request("POST", f"/api/nodes/{node_id}/recover", json_data={"force": force}, timeout=15.0)
+
+    def test_proxy(self) -> dict[str, Any]:
+        return self._request("GET", "/api/test-proxy", timeout=15.0)
+
+    def get_countries(self, refresh: bool = False) -> dict[str, Any]:
+        return self._request("GET", "/api/countries", params={"refresh": refresh}, timeout=15.0)
+
+    def get_logs(self, tail: int = 100) -> dict[str, Any]:
+        return self._request("GET", "/api/logs", params={"tail": tail}, timeout=10.0)

cli/commands/__init__.py

@@ -0,0 +1,3 @@
+"""
+CLI Subcommands package
+"""

cli/commands/config.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from cli.config import CLIConfig
+
+
+@click.group("config", help="Manage proxy gateway credentials, environment settings, and ports.")
+def config_group() -> None:
+    pass
+
+
+@config_group.command("show", help="Display all active configuration parameters.")
+@click.pass_obj
+def config_show(obj: dict[str, Any]) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    table = Table(title="[bold cyan]PIA Proxy Configuration Summary[/bold cyan]", expand=True)
+    table.add_column("Parameter", style="bold white", width=24)
+    table.add_column("Value", style="yellow")
+    table.add_column("Location / Source", style="dim")
+
+    table.add_row("Project Root", str(config.project_root), "Detected")
+    table.add_row("Compose Dir", str(config.compose_dir), "Detected")
+    table.add_row(".env File", str(config.env_file), "Detected")
+    table.add_row("Credentials Dir", str(config.credentials_dir), "Detected")
+    table.add_row("SOCKS5 Proxy Port", str(config.proxy_port), ".env (PROXY_PORT)")
+    table.add_row("SOCKS5 Username", config.socks5_user, ".env (SOCKS5_USERNAME)")
+    table.add_row("SOCKS5 Password", "***" + config.socks5_pass[-4:] if len(config.socks5_pass) > 4 else "***", ".env (SOCKS5_PASSWORD)")
+    table.add_row("Backend API Port", str(config.api_port), ".env (API_PORT)")
+    table.add_row("Active Worker Count", str(config.worker_count), ".env (WORKER_COUNT)")
+    table.add_row("Max Worker Count", str(config.max_worker_count), ".env (MAX_WORKER_COUNT)")
+
+    u, p = config.get_pia_account()
+    if u and p:
+        table.add_row("PIA Account", f"{u} / {'*' * len(p)}", "credentials/pia_account_1")
+    else:
+        table.add_row("PIA Account", "[bold red]Not Configured![/bold red]", "credentials/pia_account_1")
+
+    session_file = config.credentials_dir / "pia_session_slot_1.json"
+    table.add_row("PIA Session Cache", "Present" if session_file.exists() else "Missing", "credentials/pia_session_slot_1.json")
+
+    console.print(table)
+
+
+@config_group.command("set-credentials", help="Configure PIA account username and password.")
+@click.option("--username", "-u", prompt=True, help="PIA Username (e.g. p1234567)")
+@click.option("--password", "-p", prompt=True, hide_input=True, confirmation_prompt=True, help="PIA Password")
+@click.pass_obj
+def config_set_credentials(obj: dict[str, Any], username: str, password: str) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    if not username.strip() or not password.strip():
+        console.print("[bold red]Username and password cannot be empty.[/bold red]")
+        raise SystemExit(1)
+
+    config.set_pia_account(username.strip(), password.strip())
+    console.print(f"[bold green]✔ Saved PIA account credentials to {config.credentials_dir / 'pia_account_1'}.[/bold green]")
+
+
+@config_group.command("set-proxy-auth", help="Set username and password required for SOCKS5 proxy clients.")
+@click.option("--username", "-u", prompt=True, help="Proxy username")
+@click.option("--password", "-p", prompt=True, hide_input=True, confirmation_prompt=True, help="Proxy password")
+@click.pass_obj
+def config_set_proxy_auth(obj: dict[str, Any], username: str, password: str) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    config.update_env_value("SOCKS5_USERNAME", username.strip())
+    config.update_env_value("SOCKS5_PASSWORD", password.strip())
+    console.print("[bold green]✔ Updated SOCKS5 credentials in .env.[/bold green]")
+    console.print("[dim]Note: Restart proxy pool with 'pia-proxy restart' to apply new proxy credentials.[/dim]")
+
+
+@config_group.command("set-port", help="Set the external port for SOCKS5 gateway or backend API.")
+@click.option("--proxy-port", type=int, default=None, help="New SOCKS5 gateway port (e.g. 1087, 1080)")
+@click.option("--api-port", type=int, default=None, help="New Backend API port (e.g. 8007)")
+@click.pass_obj
+def config_set_port(obj: dict[str, Any], proxy_port: int | None, api_port: int | None) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    if proxy_port:
+        config.update_env_value("PROXY_PORT", proxy_port)
+        console.print(f"[bold green]✔ Set PROXY_PORT={proxy_port} in .env.[/bold green]")
+    if api_port:
+        config.update_env_value("API_PORT", api_port)
+        console.print(f"[bold green]✔ Set API_PORT={api_port} in .env.[/bold green]")
+
+    console.print("[dim]Note: Restart proxy pool with 'pia-proxy restart' to apply port changes.[/dim]")

cli/commands/doctor.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+from pathlib import Path
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from cli.config import CLIConfig
+
+
+def _is_port_open(port: int, host: str = "127.0.0.1") -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(0.5)
+        return s.connect_ex((host, port)) == 0
+
+
+@click.command("doctor", help="Inspect system readiness, tun device, ports, swap, and Docker requirements.")
+@click.pass_obj
+def doctor_cmd(obj: dict[str, Any]) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    table = Table(title="[bold cyan]System Environment & Health Diagnostics[/bold cyan]", expand=True)
+    table.add_column("Component", style="bold white", width=22)
+    table.add_column("Status", width=16)
+    table.add_column("Details", style="dim")
+
+    # 1. Docker Engine
+    docker_ok = False
+    try:
+        r = subprocess.run(["docker", "info"], capture_output=True, text=True, timeout=3)
+        docker_ok = r.returncode == 0
+    except Exception:
+        pass
+
+    if docker_ok:
+        table.add_row("Docker Engine", Text("✔ OK", style="bold green"), "Daemon is active and reachable")
+    else:
+        table.add_row("Docker Engine", Text("✗ ERROR", style="bold red"), "Docker daemon not running or access denied")
+
+    # 2. Docker Compose
+    compose_ok = False
+    try:
+        r = subprocess.run(["docker", "compose", "version"], capture_output=True, text=True, timeout=3)
+        compose_ok = r.returncode == 0
+        compose_ver = r.stdout.strip()
+    except Exception:
+        compose_ver = "Not installed"
+
+    if compose_ok:
+        table.add_row("Docker Compose", Text("✔ OK", style="bold green"), compose_ver)
+    else:
+        table.add_row("Docker Compose", Text("✗ ERROR", style="bold red"), "docker compose command missing")
+
+    # 3. TUN device
+    tun_path = Path("/dev/net/tun")
+    if tun_path.exists():
+        table.add_row("TUN Device", Text("✔ OK", style="bold green"), "/dev/net/tun is present")
+    else:
+        table.add_row("TUN Device", Text("✗ MISSING", style="bold red"), "Run 'mkdir -p /dev/net && mknod /dev/net/tun c 10 200'")
+
+    # 4. RAM & Swap
+    mem_ok = False
+    mem_info = "Unable to read /proc/meminfo"
+    try:
+        with open("/proc/meminfo") as f:
+            lines = f.readlines()
+            total_ram = 0
+            total_swap = 0
+            for line in lines:
+                if line.startswith("MemTotal:"):
+                    total_ram = int(line.split()[1]) // 1024
+                elif line.startswith("SwapTotal:"):
+                    total_swap = int(line.split()[1]) // 1024
+            mem_info = f"RAM: {total_ram}MB | Swap: {total_swap}MB"
+            mem_ok = total_swap >= 1000 or total_ram >= 3000
+    except Exception:
+        pass
+
+    if mem_ok:
+        table.add_row("Memory & Swap", Text("✔ OK", style="bold green"), mem_info)
+    else:
+        table.add_row("Memory & Swap", Text("⚠ WARN", style="bold yellow"), f"{mem_info} (Recommend adding >= 2GB swap)")
+
+    # 5. PIA Credentials
+    u, p = config.get_pia_account()
+    if u and p:
+        table.add_row("PIA Account", Text("✔ READY", style="bold green"), f"Username: {u}")
+    else:
+        table.add_row("PIA Account", Text("✗ NOT SET", style="bold red"), "Configure with 'pia-proxy config set-credentials'")
+
+    # 6. Gateway Port (1087)
+    gw_in_use = _is_port_open(config.proxy_port)
+    table.add_row(f"Proxy Port ({config.proxy_port})", Text("IN USE" if gw_in_use else "AVAILABLE", style="cyan" if gw_in_use else "green"), "SOCKS5 Proxy Gateway")
+
+    # 7. API Port (8007)
+    api_in_use = _is_port_open(config.api_port)
+    table.add_row(f"API Port ({config.api_port})", Text("IN USE" if api_in_use else "AVAILABLE", style="cyan" if api_in_use else "green"), "FastAPI Backend")
+
+    console.print(table)

cli/commands/export.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import click
+from rich.console import Console
+
+from cli.config import CLIConfig
+
+
+@click.command("export", help="Export proxy connection strings formatted for bots, antidetect browsers, or crawlers.")
+@click.option(
+    "--format",
+    "-f",
+    type=click.Choice(["url", "standard", "curl", "json", "env"]),
+    default="standard",
+    help="Output format (standard = IP:PORT:USER:PASS).",
+    show_default=True,
+)
+@click.option("--host", "-H", default=None, help="Custom server IP or hostname override.")
+@click.pass_obj
+def export_cmd(obj: dict[str, Any], format: str, host: str | None) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    server_ip = host or config.get_public_ip()
+    port = config.proxy_port
+    user = config.socks5_user
+    pwd = config.socks5_pass
+
+    if format == "standard":
+        # IP:PORT:USER:PASS format commonly accepted by antidetect tools
+        click.echo(f"{server_ip}:{port}:{user}:{pwd}")
+    elif format == "url":
+        click.echo(f"socks5h://{user}:{pwd}@{server_ip}:{port}")
+    elif format == "curl":
+        click.echo(f"curl -x socks5h://{user}:{pwd}@{server_ip}:{port} https://api.ipify.org")
+    elif format == "json":
+        data = {
+            "type": "socks5",
+            "host": server_ip,
+            "port": port,
+            "username": user,
+            "password": pwd,
+            "url": f"socks5h://{user}:{pwd}@{server_ip}:{port}",
+            "standard": f"{server_ip}:{port}:{user}:{pwd}",
+        }
+        click.echo(json.dumps(data, indent=2))
+    elif format == "env":
+        click.echo(f'export ALL_PROXY="socks5h://{user}:{pwd}@{server_ip}:{port}"')
+        click.echo(f'export HTTP_PROXY="socks5h://{user}:{pwd}@{server_ip}:{port}"')
+        click.echo(f'export HTTPS_PROXY="socks5h://{user}:{pwd}@{server_ip}:{port}"')

cli/commands/logs.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from cli.docker_ctl import DockerController
+
+
+@click.command("logs", help="Tail or follow real-time logs from proxy containers or workers.")
+@click.option("--service", "-s", default=None, help="Target container or service (e.g. 'gateway', 'backend', 'vpn-worker-1').")
+@click.option("--tail", "-n", default=100, help="Number of historical lines to show.", show_default=True)
+@click.option("--follow", "-f", is_flag=True, help="Follow log output continuously.")
+@click.pass_obj
+def logs_cmd(obj: dict[str, Any], service: str | None, tail: int, follow: bool) -> None:
+    docker_ctl: DockerController = obj["docker_ctl"]
+
+    svc_name = service
+    if svc_name:
+        if svc_name in {"gateway", "proxy-gateway", "haproxy"}:
+            svc_name = "proxy-gateway"
+        elif svc_name in {"api", "backend"}:
+            svc_name = "backend"
+        elif svc_name.isdigit():
+            svc_name = f"vpn-worker-{svc_name}"
+        elif svc_name.startswith("worker"):
+            svc_name = f"vpn-{svc_name}"
+
+    try:
+        for line in docker_ctl.stream_logs(service=svc_name, tail=tail, follow=follow):
+            click.echo(line)
+    except KeyboardInterrupt:
+        pass

cli/commands/proxy.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+from cli.config import CLIConfig
+
+
+@click.command("proxy", help="View or update SOCKS5 proxy port and authentication credentials.")
+@click.argument("port", type=int, required=False, default=None)
+@click.argument("username", required=False, default=None)
+@click.argument("password", required=False, default=None)
+@click.pass_obj
+def proxy_cmd(
+    obj: dict[str, Any],
+    port: int | None,
+    username: str | None,
+    password: str | None,
+) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    # If no arguments provided, view current proxy info
+    if port is None and username is None and password is None:
+        ip = config.get_public_ip()
+        msg = (
+            f"• Cổng SOCKS5 (Port):     [bold cyan]{config.proxy_port}[/bold cyan]\n"
+            f"• Tài khoản đăng nhập:    [bold white]{config.socks5_user}[/bold white]\n"
+            f"• Mật khẩu:               [bold white]{'***' + config.socks5_pass[-4:] if len(config.socks5_pass) > 4 else '***'}[/bold white]\n"
+            f"• URL kết nối nội bộ:     [bold green]socks5h://{config.socks5_user}:{config.socks5_pass}@127.0.0.1:{config.proxy_port}[/bold green]\n"
+            f"• Chuỗi Proxy công khai:  [bold green]{ip}:{config.proxy_port}:{config.socks5_user}:{config.socks5_pass}[/bold green]\n\n"
+            f"[dim]Cú pháp đổi cấu hình: pia-proxy proxy <cổng> [username] [password][/dim]\n"
+            f"[dim]Ví dụ: pia-proxy proxy 1087 myuser mypass[/dim]"
+        )
+        console.print(Panel(msg, title="[bold yellow]Cấu Hình Cổng SOCKS5 Proxy[/bold yellow]", border_style="cyan"))
+        return
+
+    # Update port
+    if port:
+        if port < 1024 or port > 65535:
+            console.print("[bold red]Lỗi: Cổng phải nằm trong khoảng từ 1024 đến 65535.[/bold red]")
+            raise SystemExit(1)
+        config.update_env_value("PROXY_PORT", port)
+
+    # Update username
+    if username:
+        config.update_env_value("SOCKS5_USERNAME", username.strip())
+
+    # Update password
+    if password:
+        config.update_env_value("SOCKS5_PASSWORD", password.strip())
+
+    console.print("[bold green]✔ Đã cập nhật cấu hình SOCKS5 Gateway thành công:[/bold green]")
+    if port:
+        console.print(f"  • Cổng mới: [bold cyan]{port}[/bold cyan]")
+    if username:
+        console.print(f"  • Username mới: [bold cyan]{username}[/bold cyan]")
+    if password:
+        console.print(f"  • Mật khẩu mới: [bold cyan]******[/bold cyan]")
+    console.print("[dim]Chạy 'pia-proxy restart' để áp dụng cấu hình mới vào container.[/dim]")

cli/commands/rotate.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import click
+from rich.console import Console
+
+from cli.api_client import APIClient, APIClientError
+
+
+@click.command("rotate", help="Trigger immediate IP rotation for a worker or across the pool.")
+@click.argument("worker", required=False, default=None)
+@click.option("--all", "rotate_all", is_flag=True, help="Sequentially trigger IP rotation for all active workers.")
+@click.option("--country", "-c", default=None, help="Target country code or region name for new IP.")
+@click.option("--server", "-s", default=None, help="Target specific server hostname.")
+@click.option("--wait", is_flag=True, help="Wait for new IP verification before returning.")
+@click.pass_obj
+def rotate_cmd(
+    obj: dict[str, Any],
+    worker: str | None,
+    rotate_all: bool,
+    country: str | None,
+    server: str | None,
+    wait: bool,
+) -> None:
+    client: APIClient = obj["client"]
+    console = Console()
+
+    if not client.is_alive():
+        console.print("[bold red]Proxy service is offline. Please start it with 'pia-proxy start' first.[/bold red]")
+        raise SystemExit(1)
+
+    if rotate_all:
+        console.print("[bold cyan]Rotating all active workers...[/bold cyan]")
+        try:
+            nodes = client.get_nodes()
+            active_nodes = [n for n in nodes if n.get("active")]
+            for n in active_nodes:
+                wid = n.get("id")
+                try:
+                    res = client.rotate_node(wid, country=country, server=server, wait_for_ready=wait)
+                    console.print(f"  • Worker {wid}: [green]Rotation triggered[/green]")
+                except Exception as e:
+                    console.print(f"  • Worker {wid}: [red]{e}[/red]")
+                time.sleep(0.5)
+            console.print("[bold green]✔ Completed rotation triggers for all active workers.[/bold green]")
+        except Exception as exc:
+            console.print(f"[bold red]Failed to rotate all: {exc}[/bold red]")
+        return
+
+    if worker:
+        wid = f"worker{worker}" if worker.isdigit() else worker
+        wid_clean = wid.replace("vpn-", "").replace("pia-", "")
+        console.print(f"[bold cyan]Rotating worker '{wid_clean}'...[/bold cyan]")
+        try:
+            with console.status(f"[yellow]Rotating {wid_clean}...[/yellow]"):
+                res = client.rotate_node(wid_clean, country=country, server=server, wait_for_ready=wait)
+
+            if res.get("ok"):
+                new_ip = res.get("new_ip") or res.get("current_ip")
+                if new_ip:
+                    console.print(f"[bold green]✔ Worker '{wid_clean}' rotated! New Exit IP: {new_ip}[/bold green]")
+                else:
+                    console.print(f"[bold green]✔ Worker '{wid_clean}' rotation initiated in background.[/bold green]")
+            else:
+                console.print(f"[yellow]Rotation result: {res}[/yellow]")
+        except APIClientError as exc:
+            console.print(f"[bold red]Failed to rotate worker: {exc}[/bold red]")
+            raise SystemExit(1)
+        return
+
+    # Default: rotate any ready worker
+    console.print("[bold cyan]Rotating an active worker behind the gateway...[/bold cyan]")
+    try:
+        with console.status("[yellow]Rotating...[/yellow]"):
+            res = client.rotate_any(country=country, server=server, wait_for_ready=wait)
+
+        if res.get("ok"):
+            node_id = res.get("node_id") or "worker"
+            new_ip = res.get("new_ip") or res.get("current_ip")
+            if new_ip:
+                console.print(f"[bold green]✔ Worker '{node_id}' rotated! New Exit IP: {new_ip}[/bold green]")
+            else:
+                console.print(f"[bold green]✔ Worker '{node_id}' detached and rotating in background.[/bold green]")
+        else:
+            console.print(f"[yellow]Rotation response: {res}[/yellow]")
+    except APIClientError as exc:
+        console.print(f"[bold red]Failed to rotate: {exc}[/bold red]")
+        raise SystemExit(1)

cli/commands/rotate_time.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+from cli.config import CLIConfig
+
+
+@click.command("rotate-time", help="View or set auto-rotation intervals & max uptime (e.g. 'pia-proxy rotate-time 36 69 70').")
+@click.argument("min_sec", type=int, required=False, default=None)
+@click.argument("max_sec", type=int, required=False, default=None)
+@click.argument("max_uptime", type=int, required=False, default=None)
+@click.pass_obj
+def rotate_time_cmd(
+    obj: dict[str, Any],
+    min_sec: int | None,
+    max_sec: int | None,
+    max_uptime: int | None,
+) -> None:
+    config: CLIConfig = obj["config"]
+    console = Console()
+
+    # Read current values from .env
+    cur_min = 36
+    cur_max = 69
+    cur_uptime = 70
+    if config.env_file.exists():
+        for line in config.env_file.read_text(encoding="utf-8", errors="ignore").splitlines():
+            line = line.strip()
+            if line.startswith("AUTO_ROTATE_INTERVAL_MIN_SECONDS="):
+                try: cur_min = int(line.split("=", 1)[1].strip())
+                except: pass
+            elif line.startswith("AUTO_ROTATE_INTERVAL_MAX_SECONDS="):
+                try: cur_max = int(line.split("=", 1)[1].strip())
+                except: pass
+            elif line.startswith("AUTO_ROTATE_MAX_UPTIME_SECONDS="):
+                try: cur_uptime = int(line.split("=", 1)[1].strip())
+                except: pass
+
+    # If no arguments provided, display current settings
+    if min_sec is None:
+        msg = (
+            f"• Thời gian xoay tối thiểu: [bold cyan]{cur_min}s[/bold cyan]\n"
+            f"• Thời gian xoay tối đa:     [bold cyan]{cur_max}s[/bold cyan]\n"
+            f"• Giới hạn cứng Uptime:      [bold yellow]{cur_uptime}s[/bold yellow] (Bất kỳ IP nào quá thời gian này sẽ bị ép xoay ngay)\n\n"
+            f"[dim]Cú pháp cài đặt: pia-proxy rotate-time <min_giây> <max_giây> [max_uptime_giây][/dim]\n"
+            f"[dim]Ví dụ cấu hình chuẩn: pia-proxy rotate-time 36 69 70[/dim]"
+        )
+        console.print(Panel(msg, title="[bold yellow]Cấu Hình Chu Kỳ Xoay IP (Auto-Rotate Rules)[/bold yellow]", border_style="cyan"))
+        return
+
+    # Update values
+    val_min = min_sec
+    val_max = max_sec or (val_min + 30)
+    val_uptime = max_uptime or (val_max + 1)
+
+    if val_min < 5 or val_max <= val_min:
+        console.print("[bold red]Lỗi: Thời gian tối đa phải lớn hơn thời gian tối thiểu (min >= 5s)![/bold red]")
+        raise SystemExit(1)
+
+    config.update_env_value("AUTO_ROTATE_INTERVAL_MIN_SECONDS", val_min)
+    config.update_env_value("AUTO_ROTATE_INTERVAL_MAX_SECONDS", val_max)
+    config.update_env_value("AUTO_ROTATE_MAX_UPTIME_SECONDS", val_uptime)
+
+    console.print("[bold green]✔ Đã cập nhật quy tắc xoay IP thành công:[/bold green]")
+    console.print(f"  • Chu kỳ xoay tự động: [bold cyan]{val_min}s – {val_max}s[/bold cyan]")
+    console.print(f"  • Giới hạn cứng Uptime: [bold yellow]{val_uptime}s[/bold yellow] (Ép xoay)")
+    console.print("[dim]Chạy 'pia-proxy restart' để áp dụng chu kỳ mới cho backend.[/dim]")