sing-box-cli 0.1.1__tar.gz → 0.1.3__tar.gz

sing_box_cli-0.1.3/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: sing-box-cli
+Version: 0.1.3
+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
+Project-URL: documentation, https://atticuszz.github.io/sing-box-service/
+Project-URL: Changelog, https://github.com/atticuszz/sing-box-service/blob/main/CHANGELOG.md
+Author-email: "A.J.Zeller" <hello@atticux.me>
+Maintainer-email: "A.J.Zeller" <hello@atticux.me>
+License: MIT License
+        
+        Copyright (c) 2024 A.J.Zeller
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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: 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: typer>=0.15.1
+Description-Content-Type: text/markdown
+
+# Sing-Box CLI
+
+🎤 Cross-platform sing-box service manager.
+
+![help](assets/image.png)
+
+## Install
+
+### uv
+
+Windows
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Linux
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### sing-box-cli
+
+Install
+```powershell
+# windows
+uv tool install sing-box-cli
+```
+
+```bash
+# linux
+uv tool install sing-box-cli
+sbc install
+```
+
+On Linux, `sbc install` installs both `sbc` and `sing-box-cli` into
+`/usr/local/bin`, requesting sudo only to write those system launchers. It replaces
+the old manual symlinks and can be run again safely. Use `--bin-dir PATH` to select
+another existing executable directory. Unrelated files are preserved.
+
+The system launchers use Python `-B`, so commands such as `sudo sbc service enable`
+do not create root-owned `__pycache__` files in your uv environment. Run the install
+command as your normal user after installing the tool. Do not run `uv tool install`,
+`uv tool upgrade`, or `uv run` with sudo.
+
+Install with specific sing-box version
+
+```bash
+uv tool install sing-box-cli --with sing-box-bin==x.y.z
+```
+
+Upgrade
+```bash
+uv tool upgrade sing-box-cli
+```
+
+Linux launchers continue to use the same environment after a normal uv upgrade.
+Run `sbc install` again if you move or change the installation environment.
+
+After upgrading on Windows, run the following in an administrator PowerShell:
+
+```powershell
+sbc service enable
+sbc service status
+```
+
+This refreshes the installed service paths and migrates existing NSSM installations
+to the native Go service host, keeping the same `sing-box-service` name and account.
+An existing running service is stopped and restarted when its executable paths change.
+If that update fails, the old service target is restored and the error is reported.
+
+The native host and core are copied into versioned directories under
+`%ProgramFiles%/sing-box-cli/sing-box-service`. The running service does not depend
+on uv's environment, so future uv upgrades do not overwrite its running executables.
+Configuration files stay in their existing location. Windows services run at boot;
+closing the terminal does not stop them. Linux continues to use the existing systemd service.
+
+No Go installation is required when installing a published wheel. Go is needed
+only to build a wheel from source; the required version is in `windows-service/go.mod`.
+Architecture support follows `sing-box-bin`: Windows distributes the amd64 core
+and service helper; Linux distributes amd64 and arm64 cores. No additional CPU
+architectures are introduced by the service helper.
+
+### Logs
+
+The service uses the user's sing-box configuration without changing its log level.
+Set `log.level` to `info` or `warn` in that configuration to reduce generated logs.
+`sbc logs --log-level debug` selects the logs to view; it cannot recover debug entries
+that the core did not generate. For diagnostics, explicitly change the core's log level
+and restart, then restore it when finished.
+
+The native Windows host writes only warnings/errors to the Windows Application event
+log (source `sing-box-service-native`). Core stdout/stderr is kept as a bounded diagnostic
+tail for failures, without an additional debug log file. To persist core logs, use
+sing-box's `log.output` configuration; streaming `sbc logs` continues to use the core API.
+Old versioned executables are retained for rollback. After disabling the service,
+its directory under Program Files may be removed manually; user configuration is separate.
+
+## Run
+
+Windows in Admin powershell
+
+```powershell
+sbc --help
+```
+
+Linux
+
+```bash
+sudo sbc --help
+```
+
+## Serve private GitHub configurations
+
+Set `GH_TOKEN` (or `GITHUB_TOKEN`) with **Contents: read** access to your private
+repository, then run as your normal user:
+
+```bash
+sbc config serve add https://github.com/owner/private-configs --domain sub.example.com
+sbc config serve list
+sbc config serve start
+sbc config serve stop
+```
+
+`list` prints URLs for valid root `.json` configurations. The server reads GitHub
+through its API without cloning; `start` runs in the background at `127.0.0.1:8080`
+by default. Use `--host` and `--port` for another listening address.
+
+Point Traefik at the server using [this example](docs/traefik-config-serve.yml).
+Clients continue to use the existing update command:
+
+```bash
+sbc config update https://sub.example.com/alice.json --restart
+```
+
+See [configuration server details](docs/config-serve.md) for settings, logs and limits.

sing_box_cli-0.1.3/README.md

@@ -0,0 +1,137 @@
+# Sing-Box CLI
+
+🎤 Cross-platform sing-box service manager.
+
+![help](assets/image.png)
+
+## Install
+
+### uv
+
+Windows
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Linux
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### sing-box-cli
+
+Install
+```powershell
+# windows
+uv tool install sing-box-cli
+```
+
+```bash
+# linux
+uv tool install sing-box-cli
+sbc install
+```
+
+On Linux, `sbc install` installs both `sbc` and `sing-box-cli` into
+`/usr/local/bin`, requesting sudo only to write those system launchers. It replaces
+the old manual symlinks and can be run again safely. Use `--bin-dir PATH` to select
+another existing executable directory. Unrelated files are preserved.
+
+The system launchers use Python `-B`, so commands such as `sudo sbc service enable`
+do not create root-owned `__pycache__` files in your uv environment. Run the install
+command as your normal user after installing the tool. Do not run `uv tool install`,
+`uv tool upgrade`, or `uv run` with sudo.
+
+Install with specific sing-box version
+
+```bash
+uv tool install sing-box-cli --with sing-box-bin==x.y.z
+```
+
+Upgrade
+```bash
+uv tool upgrade sing-box-cli
+```
+
+Linux launchers continue to use the same environment after a normal uv upgrade.
+Run `sbc install` again if you move or change the installation environment.
+
+After upgrading on Windows, run the following in an administrator PowerShell:
+
+```powershell
+sbc service enable
+sbc service status
+```
+
+This refreshes the installed service paths and migrates existing NSSM installations
+to the native Go service host, keeping the same `sing-box-service` name and account.
+An existing running service is stopped and restarted when its executable paths change.
+If that update fails, the old service target is restored and the error is reported.
+
+The native host and core are copied into versioned directories under
+`%ProgramFiles%/sing-box-cli/sing-box-service`. The running service does not depend
+on uv's environment, so future uv upgrades do not overwrite its running executables.
+Configuration files stay in their existing location. Windows services run at boot;
+closing the terminal does not stop them. Linux continues to use the existing systemd service.
+
+No Go installation is required when installing a published wheel. Go is needed
+only to build a wheel from source; the required version is in `windows-service/go.mod`.
+Architecture support follows `sing-box-bin`: Windows distributes the amd64 core
+and service helper; Linux distributes amd64 and arm64 cores. No additional CPU
+architectures are introduced by the service helper.
+
+### Logs
+
+The service uses the user's sing-box configuration without changing its log level.
+Set `log.level` to `info` or `warn` in that configuration to reduce generated logs.
+`sbc logs --log-level debug` selects the logs to view; it cannot recover debug entries
+that the core did not generate. For diagnostics, explicitly change the core's log level
+and restart, then restore it when finished.
+
+The native Windows host writes only warnings/errors to the Windows Application event
+log (source `sing-box-service-native`). Core stdout/stderr is kept as a bounded diagnostic
+tail for failures, without an additional debug log file. To persist core logs, use
+sing-box's `log.output` configuration; streaming `sbc logs` continues to use the core API.
+Old versioned executables are retained for rollback. After disabling the service,
+its directory under Program Files may be removed manually; user configuration is separate.
+
+## Run
+
+Windows in Admin powershell
+
+```powershell
+sbc --help
+```
+
+Linux
+
+```bash
+sudo sbc --help
+```
+
+## Serve private GitHub configurations
+
+Set `GH_TOKEN` (or `GITHUB_TOKEN`) with **Contents: read** access to your private
+repository, then run as your normal user:
+
+```bash
+sbc config serve add https://github.com/owner/private-configs --domain sub.example.com
+sbc config serve list
+sbc config serve start
+sbc config serve stop
+```
+
+`list` prints URLs for valid root `.json` configurations. The server reads GitHub
+through its API without cloning; `start` runs in the background at `127.0.0.1:8080`
+by default. Use `--host` and `--port` for another listening address.
+
+Point Traefik at the server using [this example](docs/traefik-config-serve.yml).
+Clients continue to use the existing update command:
+
+```bash
+sbc config update https://sub.example.com/alice.json --restart
+```
+
+See [configuration server details](docs/config-serve.md) for settings, logs and limits.

sing_box_cli-0.1.3/docs/config-serve.md

@@ -0,0 +1,49 @@
+# Configuration server
+
+The server maps one domain to one private GitHub repository. Multiple domains can
+share a server. Set `GH_TOKEN` or `GITHUB_TOKEN` to a fine-grained token with
+**Contents: read** access to all registered repositories.
+
+`config serve add` checks GitHub access and saves the binding; registering the same
+binding again is safe. `config serve list` validates root `.json` files with the
+sing-box core bundled with this package, prints valid URLs, and reports invalid
+configurations on stderr.
+
+## Background process
+
+`config serve start` waits until the socket is listening, then prints the PID,
+address and log path. Closing the terminal leaves the server running. Repeated
+starts use the existing process, and repeated stops are safe. Run `stop` as the
+same user with the same state directory. Restart after changing the GitHub token
+or upgrading the package. Boot-time startup is managed separately by deployment.
+
+Settings, process identity and `serve.log` are stored in the platform's
+`sing-box-cli/serve` application directory (`~/.config/sing-box-cli/serve` on Linux).
+Set `SBC_SERVE_DIR` to use another directory for all commands. Tokens and client
+configuration are not stored there. New registrations take effect while running.
+
+## GitHub reads and validation
+
+Requests read the repository's default branch through the GitHub Contents API.
+No Git installation, clone/pull, background synchronization or persistent config
+cache is needed. File updates and deletions take effect on subsequent requests.
+
+Each response is validated and preserves the original content. Missing files,
+invalid configurations and GitHub errors return HTTP errors. Configurations are
+limited to 5 MiB and must be compatible with the bundled core. Referenced sibling
+files are not downloaded. Existing client `--token` subscriptions and saved
+settings remain supported; server URLs need no client token.
+
+## Traefik
+
+Merge [the example router and service](traefik-config-serve.yml) into the existing
+`http.routers` and `http.services` sections. Traefik must preserve the `Host` header.
+The example uses `websecure` and the host gateway from `digitalocean-public`'s
+`~/devspace/traefik.yml`. Bind to that gateway for this deployment:
+
+```bash
+sbc config serve start --host 172.18.0.1 --port 8080
+```
+
+Replace `sub.example.com` with your domain and configure DNS and the TLS
+certificate through your deployment. `--domain` only registers the binding.

sing_box_cli-0.1.3/docs/traefik-config-serve.yml

@@ -0,0 +1,19 @@
+# Merge these entries into the existing http.routers and http.services sections.
+# Set the domain to match config serve add --domain.
+http:
+  routers:
+    config-serve:
+      rule: "Host(`sub.example.com`)"
+      entryPoints:
+        - websecure
+      service: config-serve
+      tls: {}
+
+  services:
+    config-serve:
+      loadBalancer:
+        passHostHeader: true
+        servers:
+          # Host gateway used by the existing digitalocean-public Traefik config.
+          # Bind sbc config serve start --host 172.18.0.1 --port 8080 on the host.
+          - url: "http://172.18.0.1:8080"

sing_box_cli-0.1.3/hatch_build.py

@@ -0,0 +1,47 @@
+"""Bundle the small Windows SCM helper; the CLI remains Python."""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if self.target_name != "wheel" or version == "editable":
+            return
+        go = shutil.which("go")
+        if go is None:
+            raise RuntimeError(
+                "Building a wheel requires Go (see windows-service/go.mod). Installing a published wheel does not require Go."
+            )
+        root = Path(self.root)
+        output = root / "build" / "windows-service"
+        output.mkdir(parents=True, exist_ok=True)
+        # Match sing-box-bin's single Windows amd64 resource.
+        filename = "sbc-service-windows-amd64.exe"
+        destination = output / filename
+        subprocess.run(
+            [
+                go,
+                "build",
+                "-mod=readonly",
+                "-trimpath",
+                "-ldflags=-s -w",
+                "-o",
+                str(destination),
+                ".",
+            ],
+            cwd=root / "windows-service",
+            env={
+                **os.environ,
+                "GOOS": "windows",
+                "GOARCH": "amd64",
+                "CGO_ENABLED": "0",
+            },
+            check=True,
+        )
+        build_data["force_include"][str(destination)] = f"sing_box_cli/bin/{filename}"

{sing_box_cli-0.1.1 → sing_box_cli-0.1.3}/pyproject.toml

@@ -71,6 +71,12 @@ path = "src/sing_box_cli/__init__.py"
 packages = ["src/sing_box_cli"]
 # FROM: https://hatch.pypa.io/latest/build/
 
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/windows-service", "/docs", "/hatch_build.py", "/pyproject.toml", "/README.md", "/LICENSE"]
+
 ## Test
 [tool.mypy]
 strict              = true
@@ -209,7 +215,7 @@ topo_order = false
 sort_commits = "oldest"
 
 [tool.bumpversion]
-current_version        = "0.1.1"
+current_version        = "0.1.3"
 parse                  = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize              = ["{major}.{minor}.{patch}"]
 search                 = "{current_version}"

{sing_box_cli-0.1.1 → sing_box_cli-0.1.3}/src/sing_box_cli/__init__.py

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

{sing_box_cli-0.1.1 → sing_box_cli-0.1.3}/src/sing_box_cli/api/__init__.py

@@ -1,5 +1,6 @@
 import asyncio
-from typing import Annotated
+from collections.abc import Callable, Coroutine
+from typing import Annotated, Any
 
 import typer
 
@@ -53,16 +54,33 @@ def create_client(
     return SingBoxAPIClient(base_url, token)
 
 
+def _run_tui(
+    ctx: typer.Context,
+    command: Callable[[SingBoxAPIClient], Coroutine[Any, Any, None]],
+    base_url: StrOrNone,
+    token: StrOrNone,
+) -> None:
+    """Run an interactive command and handle user-requested exits consistently."""
+    try:
+        ctx_obj = get_context_obj(ctx)
+        api_client = create_client(ctx_obj.config, base_url, token)
+        asyncio.run(command(api_client))
+    except (KeyboardInterrupt, EOFError):
+        pass
+    print("Exited.")
+
+
 @api.command()
 def stats(
     ctx: typer.Context, base_url: ApiUrlOption = None, token: ApiTokenOption = None
 ) -> None:
     """Show sing-box traffic, memory statistics and connections, requires API token(Optional)"""
-    ctx_obj = get_context_obj(ctx)
-    api_client = create_client(ctx_obj.config, base_url, token)
-    visualizer = ResourceVisualizer()
-    monitor = ResourceMonitor(api_client, visualizer)
-    asyncio.run(monitor.start())
+    _run_tui(
+        ctx,
+        lambda client: ResourceMonitor(client, ResourceVisualizer()).start(),
+        base_url,
+        token,
+    )
 
 
 @api.command()
@@ -70,10 +88,7 @@ def conns(
     ctx: typer.Context, base_url: ApiUrlOption = None, token: ApiTokenOption = None
 ) -> None:
     """Manage sing-box connections, requires API token(Optional)"""
-    ctx_obj = get_context_obj(ctx)
-    api_client = create_client(ctx_obj.config, base_url, token)
-    manager = ConnectionsManager(api_client)
-    asyncio.run(manager.run())
+    _run_tui(ctx, lambda client: ConnectionsManager(client).run(), base_url, token)
 
 
 @api.command()
@@ -81,10 +96,7 @@ def proxy(
     ctx: typer.Context, base_url: ApiUrlOption = None, token: ApiTokenOption = None
 ) -> None:
     """Manage sing-box policy groups, requires API token(Optional)"""
-    ctx_obj = get_context_obj(ctx)
-    api_client = create_client(ctx_obj.config, base_url, token)
-    manager = PolicyGroupManager(api_client)
-    asyncio.run(manager.run())
+    _run_tui(ctx, lambda client: PolicyGroupManager(client).run(), base_url, token)
 
 
 @api.command()
@@ -95,7 +107,5 @@ def logs(
     token: ApiTokenOption = None,
 ) -> None:
     """Show sing-box logs, requires API token(Optional)"""
-    ctx_obj = get_context_obj(ctx)
-    api_client = create_client(ctx_obj.config, base_url, token)
     print("⌛ Showing real-time logs (Press Ctrl+C to exit)")
-    asyncio.run(get_logs(api_client, log_level))
+    _run_tui(ctx, lambda client: get_logs(client, log_level), base_url, token)

{sing_box_cli-0.1.1 → sing_box_cli-0.1.3}/src/sing_box_cli/api/client.py

@@ -5,6 +5,7 @@ Provides an async client for interacting with Sing-Box HTTP API.
 
 import json
 from collections.abc import AsyncGenerator
+from contextlib import aclosing
 from typing import Any, TypeVar
 
 import httpx
@@ -224,8 +225,11 @@ class SingBoxAPIClient:
         Yields:
             TrafficData object containing traffic data (up/down in B/s)
         """
-        async for data in self._make_stream_request("/traffic", TrafficData):
-            yield data
+        async with aclosing(
+            self._make_stream_request("/traffic", TrafficData)
+        ) as stream:
+            async for data in stream:
+                yield data
 
     async def memory_stream(self) -> AsyncGenerator[MemoryData, None]:
         """
@@ -234,8 +238,9 @@ class SingBoxAPIClient:
         Yields:
             MemoryData object containing memory data (inuse/total in bytes)
         """
-        async for data in self._make_stream_request("/memory", MemoryData):
-            yield data
+        async with aclosing(self._make_stream_request("/memory", MemoryData)) as stream:
+            async for data in stream:
+                yield data
 
     async def log_stream(
         self, level: str | None = None
@@ -247,8 +252,11 @@ class SingBoxAPIClient:
             LogEntry object containing log data (type/payload)
         """
         params = {"level": level} if level else None
-        async for data in self._make_stream_request("/logs", LogEntry, params=params):
-            yield data
+        async with aclosing(
+            self._make_stream_request("/logs", LogEntry, params=params)
+        ) as stream:
+            async for data in stream:
+                yield data
 
     async def get_connections(self) -> ConnectionData:
         """