sing-box-cli 0.1.7__tar.gz → 0.1.9__tar.gz

{sing_box_cli-0.1.7 → sing_box_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sing-box-cli
-Version: 0.1.7
+Version: 0.1.9
 Summary: cross-platform sing-box manager.
 Project-URL: Homepage, https://github.com/aittcuszz/sing-box-service
 Project-URL: Issues, https://github.com/atticuszz/sing-box-service/issues
@@ -39,12 +39,14 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: <3.15,>=3.11
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: plotext>=5.3.2
+Requires-Dist: plotext<6,>=5.3.2
 Requires-Dist: prompt-toolkit>=3.0.50
 Requires-Dist: psutil>=6.1.1
 Requires-Dist: pydantic>=2.10.6
-Requires-Dist: sing-box-bin>=1.12.12
+Requires-Dist: sing-box-bin<1.14,>=1.12.12
 Requires-Dist: typer>=0.15.1
+Provides-Extra: desktop
+Requires-Dist: grpcio>=1.60; extra == 'desktop'
 Description-Content-Type: text/markdown
 
 # Sing-Box CLI
@@ -167,6 +169,7 @@ Preview an update before applying it:
 ```bash
 sbc config update https://sub.example.com/alice.json --dry-run
 sbc config update https://sub.example.com/alice.json --restart
+sbc config update --restart   # no URL: the saved subscription
 ```
 
 `--dry-run` downloads and validates the configuration, then shows its diff without
@@ -187,6 +190,64 @@ sbc config get --subscription  # subscription URL
 
 `config show` and `config show-sub` remain available as hidden compatibility aliases.
 
+### Where it is kept
+
+sbc keeps its configuration the way the official sing-box desktop app does, in one
+place, whether the app is installed or not:
+
+```
+<config dir>/settings.db           profiles and the selected one
+<config dir>/profiles/<id>.json    the selected profile's sing-box configuration
+```
+
+The config directory is `~/.config/sing-box` on Linux. The selected profile is the
+configuration and its subscription URL is the subscription. A subscription token is
+stored inside that URL (`?token=...`), as the app stores it. It is still sent as a
+bearer token and never printed.
+
+Without the app, sbc creates this store itself with the app's schema, so the app
+takes it over unchanged if it is installed later. Files of older versions are
+imported the first time sbc runs anything but `config get` or a `--dry-run`, which
+create nothing:
+
+- `config.json` becomes the profile. It stays as a link to the profile, so a
+  service created before keeps running the same file. The previous file is kept as
+  `config.json.migrated`.
+- The URL and token of `app_config.json` become the subscription. The file is kept
+  as `app_config.json.migrated`.
+- A service created before follows the profile: `service restart` and
+  `config update --restart` point it at the profile when it points elsewhere.
+
+A configuration is written exactly as downloaded. The diff, and whether there is a
+change at all, ignore formatting.
+
+## sing-box desktop app (Linux)
+
+When the official sing-box desktop app is installed, sbc drives its daemon instead
+of a systemd service of its own, and the app's `settings.db` is the store. The app
+counts as installed when its `sing-box-daemon.service` exists.
+
+```bash
+uv tool install 'sing-box-cli[desktop]'   # grpcio is only needed for this
+sbc service restart --update              # sudo works too, it acts as the invoking user
+```
+
+| Command | With the desktop app |
+|---|---|
+| `service status/stop/restart/enable` | start, stop and reload the daemon's core. `restart` reloads in place, without a stop in between |
+| `service disable` | stops the core. Autostart stays with the app's `sing-box-daemon.service` |
+| `config update [URL]`, `--update` | refresh the profile selected in the app and record the refresh there. A new URL is saved to that profile once it downloads fine |
+| `--clear-cache`, `config clear_cache` | clear the daemon's working directory, like "clear data" in the app |
+| `stats/conns/proxy/logs` | unchanged, the default API address comes from the profile |
+| `run` | refused, the daemon runs the core |
+
+The core is started with the start options set in the app (OOM killer, memory
+limit, power report). The app's store is never created or repaired from here: if it
+cannot be read, or the daemon is stopped, sbc says so instead of working around it.
+
+- A local profile of the app has no subscription, `config update URL` is refused for it.
+- The app may show an old subscription URL until its profile list is reloaded.
+
 ## Serve private GitHub configurations
 
 Set `GH_TOKEN` (or `GITHUB_TOKEN`) with **Contents: read** access to your private

{sing_box_cli-0.1.7 → sing_box_cli-0.1.9}/README.md

@@ -118,6 +118,7 @@ Preview an update before applying it:
 ```bash
 sbc config update https://sub.example.com/alice.json --dry-run
 sbc config update https://sub.example.com/alice.json --restart
+sbc config update --restart   # no URL: the saved subscription
 ```
 
 `--dry-run` downloads and validates the configuration, then shows its diff without
@@ -138,6 +139,64 @@ sbc config get --subscription  # subscription URL
 
 `config show` and `config show-sub` remain available as hidden compatibility aliases.
 
+### Where it is kept
+
+sbc keeps its configuration the way the official sing-box desktop app does, in one
+place, whether the app is installed or not:
+
+```
+<config dir>/settings.db           profiles and the selected one
+<config dir>/profiles/<id>.json    the selected profile's sing-box configuration
+```
+
+The config directory is `~/.config/sing-box` on Linux. The selected profile is the
+configuration and its subscription URL is the subscription. A subscription token is
+stored inside that URL (`?token=...`), as the app stores it. It is still sent as a
+bearer token and never printed.
+
+Without the app, sbc creates this store itself with the app's schema, so the app
+takes it over unchanged if it is installed later. Files of older versions are
+imported the first time sbc runs anything but `config get` or a `--dry-run`, which
+create nothing:
+
+- `config.json` becomes the profile. It stays as a link to the profile, so a
+  service created before keeps running the same file. The previous file is kept as
+  `config.json.migrated`.
+- The URL and token of `app_config.json` become the subscription. The file is kept
+  as `app_config.json.migrated`.
+- A service created before follows the profile: `service restart` and
+  `config update --restart` point it at the profile when it points elsewhere.
+
+A configuration is written exactly as downloaded. The diff, and whether there is a
+change at all, ignore formatting.
+
+## sing-box desktop app (Linux)
+
+When the official sing-box desktop app is installed, sbc drives its daemon instead
+of a systemd service of its own, and the app's `settings.db` is the store. The app
+counts as installed when its `sing-box-daemon.service` exists.
+
+```bash
+uv tool install 'sing-box-cli[desktop]'   # grpcio is only needed for this
+sbc service restart --update              # sudo works too, it acts as the invoking user
+```
+
+| Command | With the desktop app |
+|---|---|
+| `service status/stop/restart/enable` | start, stop and reload the daemon's core. `restart` reloads in place, without a stop in between |
+| `service disable` | stops the core. Autostart stays with the app's `sing-box-daemon.service` |
+| `config update [URL]`, `--update` | refresh the profile selected in the app and record the refresh there. A new URL is saved to that profile once it downloads fine |
+| `--clear-cache`, `config clear_cache` | clear the daemon's working directory, like "clear data" in the app |
+| `stats/conns/proxy/logs` | unchanged, the default API address comes from the profile |
+| `run` | refused, the daemon runs the core |
+
+The core is started with the start options set in the app (OOM killer, memory
+limit, power report). The app's store is never created or repaired from here: if it
+cannot be read, or the daemon is stopped, sbc says so instead of working around it.
+
+- A local profile of the app has no subscription, `config update URL` is refused for it.
+- The app may show an old subscription URL until its profile list is reloaded.
+
 ## Serve private GitHub configurations
 
 Set `GH_TOKEN` (or `GITHUB_TOKEN`) with **Contents: read** access to your private

{sing_box_cli-0.1.7 → sing_box_cli-0.1.9}/pyproject.toml

@@ -23,11 +23,11 @@ maintainers = [{ name = "A.J.Zeller", email = "hello@atticux.me" }]
 dynamic = ["version"] # https://hatch.pypa.io/latest/config/metadata/#version
 dependencies = [
     "httpx>=0.28.1",
-    "plotext>=5.3.2",
+    "plotext>=5.3.2,<6",
     "prompt-toolkit>=3.0.50",
     "psutil>=6.1.1",
     "pydantic>=2.10.6",
-    "sing-box-bin>=1.12.12",
+    "sing-box-bin>=1.12.12,<1.14",
     "typer>=0.15.1",
 ]
 
@@ -47,6 +47,7 @@ environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
 
 [project.optional-dependencies]
 # optional deps for package installation
+desktop = ["grpcio>=1.60"] # drive the sing-box desktop app's daemon
 
 [dependency-groups]
 dev = [
@@ -61,6 +62,7 @@ dev = [
     "scipy-stubs>=1.15.2.1",
     "coverage>=7.7.1",
     "pytest-sugar>=1.0.0",
+    "grpcio>=1.60", # fake desktop daemon in tests
 ]
 
 [tool.hatch.version]
@@ -121,6 +123,9 @@ ignore = [
 
 isort = { combine-as-imports = true, split-on-trailing-comma = false }
 
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ARG001"] # pytest fixtures are used by being requested
+
 # Avoid trying to fix flake8-bugbear (`B`) violations.
 unfixable = ["B"]
 
@@ -215,7 +220,7 @@ topo_order = false
 sort_commits = "oldest"
 
 [tool.bumpversion]
-current_version        = "0.1.7"
+current_version        = "0.1.9"
 parse                  = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize              = ["{major}.{minor}.{patch}"]
 search                 = "{current_version}"

{sing_box_cli-0.1.7 → sing_box_cli-0.1.9}/src/sing_box_cli/__init__.py

@@ -2,4 +2,4 @@ from .main import main
 
 __all__ = ["main"]
 
-__version__ = "0.1.7"
+__version__ = "0.1.9"

{sing_box_cli-0.1.7 → sing_box_cli-0.1.9}/src/sing_box_cli/api/__init__.py

@@ -2,12 +2,13 @@ import asyncio
 from collections.abc import Callable, Coroutine
 from typing import Annotated, Any
 
+import httpx
 import typer
 
 from ..common import LogLevel, StrOrNone
 from ..config.config import ConfigHandler
 from ..service import get_context_obj
-from .client import SingBoxAPIClient
+from .client import SingBoxAPIClient, SingBoxAPIError
 from .connections import ConnectionsManager
 from .logs import get_logs
 from .monitor import ResourceMonitor, ResourceVisualizer
@@ -67,6 +68,12 @@ def _run_tui(
         asyncio.run(command(api_client))
     except (KeyboardInterrupt, EOFError):
         pass
+    except SingBoxAPIError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    except httpx.HTTPError as e:
+        typer.echo(f"Error: sing-box API request failed: {e}", err=True)
+        raise typer.Exit(1)
     print("Exited.")
 
 

{sing_box_cli-0.1.7 → sing_box_cli-0.1.9}/src/sing_box_cli/api/client.py

@@ -104,6 +104,10 @@ class LogEntry(FrozenBaseModel):
 T = TypeVar("T", bound=FrozenBaseModel)
 
 
+class SingBoxAPIError(Exception):
+    """The sing-box API is unreachable or rejected the client."""
+
+
 class SingBoxAPIClient:
     """Async client for interacting with Sing-Box API.
 
@@ -123,7 +127,10 @@ class SingBoxAPIClient:
         self.headers = {"Authorization": f"Bearer {token}"} if token else {}
         self.timeout = timeout
         if not self._health_check():
-            raise ValueError(f"Invalid to initialize client: {self.base_url}")
+            raise SingBoxAPIError(
+                f"sing-box API is not reachable at {self.base_url}, "
+                "check that sing-box is running and the API URL and token are correct"
+            )
 
     def _health_check(self) -> bool:
         """Check if the API is reachable.
@@ -204,9 +211,11 @@ class SingBoxAPIClient:
         """
         url = f"{self.base_url}{endpoint}"
 
+        # streams may stay idle for long, so only reads are unbounded
+        timeout = httpx.Timeout(self.timeout, read=None)
         async with httpx.AsyncClient() as client:
             async with client.stream(
-                "GET", url, headers=self.headers, params=params, timeout=None
+                "GET", url, headers=self.headers, params=params, timeout=timeout
             ) as response:
                 response.raise_for_status()
                 async for line in response.aiter_lines():

{sing_box_cli-0.1.7 → sing_box_cli-0.1.9}/src/sing_box_cli/api/connections.py

@@ -440,10 +440,18 @@ class ConnectionsManager:
                     pass
 
     async def periodic_refresh(self, interval: float = 0.5) -> None:
-        """Periodically refresh connections."""
+        """Periodically refresh connections, retrying while the API is unreachable."""
+        failed = False
         while self.running:
             try:
                 await asyncio.sleep(interval)
                 await self.refresh_connections()
             except asyncio.CancelledError:
                 break
+            except Exception:
+                # refresh_connections already shows the error in the status bar
+                failed = True
+                continue
+            if failed:
+                failed = False
+                self.status_message = self.get_filter_state()

sing_box_cli-0.1.9/src/sing_box_cli/api/logs.py

@@ -0,0 +1,89 @@
+import re
+from contextlib import aclosing
+from datetime import datetime
+
+from rich import print
+from rich.text import Text
+
+from ..common import LogLevel
+from .client import SingBoxAPIClient
+
+
+async def get_logs(client: SingBoxAPIClient, log_level: LogLevel) -> None:
+    # Define color mapping for log levels with brighter colors
+    # Ref: https://rich.readthedocs.io/en/stable/appendix/colors.html
+    log_level_colors = {
+        "trace": "bright_black",
+        "debug": "grey66",
+        "info": "bright_cyan",
+        "warning": "bright_yellow",
+        "error": "bright_red",
+        "fatal": "bright_magenta",
+        "panic": "bright_magenta",
+    }
+
+    # Bright colors for IDs
+    id_colors = [
+        "bright_red",
+        "bright_green",
+        "bright_yellow",
+        "bright_blue",
+        "bright_magenta",
+        "bright_cyan",
+    ]
+
+    # Dictionary to store ID to color mapping
+    id_color_map = {}
+
+    async with aclosing(client.log_stream(log_level.value.lower())) as stream:
+        async for entry in stream:
+            # Get current timestamp with automatic timezone offset
+            now = datetime.now().astimezone()
+            timestamp = now.strftime("%z %Y-%m-%d %H:%M:%S")
+
+            # Get level color
+            # Start building the output message
+            message = Text()
+            message.append(timestamp, style="bright_black")
+            message.append(" ")
+            message.append(
+                entry.type.upper(),
+                style=log_level_colors.get(entry.type.lower(), "bright_white"),
+            )
+            message.append(" ")
+
+            # Process the payload
+            payload = entry.payload
+
+            # Find all ID patterns in the payload
+            pattern = r"\[(\d+) (\d+ms)\]"
+            last_end = 0
+
+            for match in re.finditer(pattern, payload):
+                # Add text before the match
+                message.append(payload[last_end : match.start()])
+
+                # Extract ID and time part
+                log_id = match.group(1)
+                time_part = match.group(2)
+
+                # Assign a consistent color to this ID
+                if log_id not in id_color_map:
+                    color_index = hash(log_id) % len(id_colors)
+                    id_color_map[log_id] = id_colors[color_index]
+
+                id_color = id_color_map[log_id]
+
+                # Add the ID with coloring
+                message.append("[", style="default")
+                message.append(log_id, style=id_color)
+                message.append(f" {time_part}]", style="default")
+
+                last_end = match.end()
+
+            # Add any remaining text
+            if last_end < len(payload):
+                message.append(payload[last_end:])
+
+            # Print the complete message
+            print(message)

{sing_box_cli-0.1.7 → sing_box_cli-0.1.9}/src/sing_box_cli/api/monitor.py

@@ -2,6 +2,7 @@ import asyncio
 import math
 import statistics
 from collections import deque
+from collections.abc import AsyncGenerator, Callable
 from contextlib import aclosing
 from datetime import datetime
 from enum import Enum
@@ -14,7 +15,13 @@ from rich.panel import Panel
 from rich.table import Table
 from rich.text import Text
 
-from .client import ConnectionInfo, MemoryData, SingBoxAPIClient, TrafficData
+from .client import (
+    ConnectionInfo,
+    FrozenBaseModel,
+    MemoryData,
+    SingBoxAPIClient,
+    TrafficData,
+)
 from .widget import RichPlotMixin, create_header_panel
 
 
@@ -575,7 +582,10 @@ class ResourceVisualizer:
         return table
 
     def create_resources_layout(
-        self, traffic_data: TrafficData, memory_data: MemoryData
+        self,
+        traffic_data: TrafficData,
+        memory_data: MemoryData,
+        api_error: str | None = None,
     ) -> Layout:
         """Create the main layout with all resource components."""
         layout = Layout()
@@ -617,7 +627,17 @@ class ResourceVisualizer:
         )
 
         # Add footer
-        layout["footer"].update(Text("Press Ctrl+C to exit", justify="center"))
+        if api_error:
+            footer = Text(
+                f"{api_error} | Press Ctrl+C to exit",
+                style="bold red",
+                justify="center",
+                no_wrap=True,
+                overflow="ellipsis",
+            )
+        else:
+            footer = Text("Press Ctrl+C to exit", justify="center")
+        layout["footer"].update(footer)
 
         return layout
 
@@ -642,30 +662,44 @@ class ResourceMonitor:
         self.current_memory = MemoryData(inuse=0, total=0)  # in bytes
         # 1.0 fix interval for avoiding repeated data
         self.task_interval = RefreshRate.SLOW.value
+        self.reconnect_interval = RefreshRate.SLOW.value
+        self.api_error: str | None = None
 
     async def monitor_traffic(self) -> None:
         """Monitor traffic stream from the API."""
-        try:
-            async with aclosing(self.api_client.traffic_stream()) as stream:
-                async for traffic_data in stream:
-                    self.current_traffic = traffic_data
-                    if not self.running:
-                        break
-                    await asyncio.sleep(self.task_interval)
-        except Exception as e:
-            self.visualizer.console.print(f"[red]Error monitoring traffic: {str(e)}")
+        await self._follow_stream(
+            self.api_client.traffic_stream, "current_traffic", TrafficData()
+        )
 
     async def monitor_memory(self) -> None:
         """Monitor memory stream from the API."""
-        try:
-            async with aclosing(self.api_client.memory_stream()) as stream:
-                async for memory_data in stream:
-                    self.current_memory = memory_data
-                    if not self.running:
-                        break
-                    await asyncio.sleep(self.task_interval)
-        except Exception as e:
-            self.visualizer.console.print(f"[red]Error monitoring memory: {str(e)}")
+        await self._follow_stream(
+            self.api_client.memory_stream, "current_memory", MemoryData()
+        )
+
+    async def _follow_stream(
+        self,
+        open_stream: Callable[[], AsyncGenerator[FrozenBaseModel, None]],
+        attr: str,
+        empty: FrozenBaseModel,
+    ) -> None:
+        """Keep ``attr`` updated from a stream, reopening it whenever it ends."""
+        while self.running:
+            try:
+                async with aclosing(open_stream()) as stream:
+                    async for data in stream:
+                        setattr(self, attr, data)
+                        self.api_error = None
+                        if not self.running:
+                            return
+                        await asyncio.sleep(self.task_interval)
+                reason = "closed by sing-box"
+            except Exception as e:
+                reason = str(e) or type(e).__name__
+            # don't keep showing stale numbers while sing-box is down
+            setattr(self, attr, empty)
+            self.api_error = f"sing-box API stream lost ({reason}), reconnecting..."
+            await asyncio.sleep(self.reconnect_interval)
 
     async def refresh_display(self) -> None:
         """Main display refresh loop."""
@@ -685,7 +719,7 @@ class ResourceMonitor:
 
                         # Update display
                         layout = self.visualizer.create_resources_layout(
-                            traffic_data, memory_data
+                            traffic_data, memory_data, self.api_error
                         )
                         live.update(layout)
 

{sing_box_cli-0.1.7 → sing_box_cli-0.1.9}/src/sing_box_cli/config/__init__.py

@@ -8,10 +8,13 @@ from ..service import SharedContext, get_context_obj
 from ..service.manager import create_service
 from .config import get_config
 from .serve import serve
+from .utils import redact_url
 
 __all__ = ["config"]
 
-SubUrlArg = Annotated[str, typer.Argument(help="Subscription URL")]
+SubUrlArg = Annotated[
+    StrOrNone, typer.Argument(help="Subscription URL, the saved one if omitted")
+]
 TokenOption = Annotated[
     StrOrNone,
     typer.Option(
@@ -40,7 +43,7 @@ def config_callback(ctx: typer.Context) -> None:
 
 @config.command("update")
 def config_update(
-    url: SubUrlArg,
+    url: SubUrlArg = None,
     token: TokenOption = None,
     restart: RestartServiceOption = False,
     dry_run: DryRunOption = False,
@@ -51,10 +54,13 @@ def config_update(
         print("❌ Failed to update configuration.")
         raise typer.Exit(1)
     if restart and not dry_run:
-        ensure_root()
         service = create_service(cfg)
+        if service.requires_root:
+            ensure_root()
         # init service
-        if not service.check_service():
+        if service.check_service():
+            service.sync_service()
+        else:
             service.create_service()
             print("⌛ Service created successfully.")
         service.restart()
@@ -71,7 +77,7 @@ def config_get(
     cfg = get_context_obj(ctx).config
     if subscription:
         if cfg.sub_url:
-            print(f"🔗 Current subscription URL: {cfg.sub_url}")
+            print(f"🔗 Current subscription URL: {redact_url(cfg.sub_url)}")
         else:
             print("❌ No subscription URL found.")
     else:
@@ -94,4 +100,4 @@ def config_show(ctx: typer.Context) -> None:
 def config_clear_cache(ctx: typer.Context) -> None:
     """Clean cache database"""
     ctx_obj = get_context_obj(ctx)
-    ctx_obj.config.clear_cache()
+    ctx_obj.service.clear_cache()