mihomo-cli 0.1.0__tar.gz

mihomo_cli-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

mihomo_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 - 2026-10-21
+
+- First release: Linux (Ubuntu 20.04 / 22.04 / 24.04) command-line client built on the mihomo core.
+- Interactive menu and direct commands; proxy services (subscription / local file / manual nodes),
+  node switching, latency test and `node auto`, global / rule / direct modes, CN-sites switch.
+- systemd service installed with a single sudo; TUN mode with systemd-resolved DNS takeover.
+- Automatic backup before every change with rollback on failure; `backup restore`.
+- `doctor` with 15 checks and `--fix`; `--json` output; English / Chinese help; shell completion.

mihomo_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jakoes-wu
+
+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.

mihomo_cli-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: mihomo-cli
+Version: 0.1.0
+Summary: A command-line Clash-style client for Linux servers, powered by the mihomo kernel
+Project-URL: Homepage, https://github.com/jakoes-wu/mihomo-cli
+Project-URL: Issues, https://github.com/jakoes-wu/mihomo-cli/issues
+Author: jakoes-wu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: clash,cli,mihomo,proxy,tun
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Proxy Servers
+Requires-Python: >=3.8
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.24
+Requires-Dist: pyyaml>=5.4
+Requires-Dist: questionary>=1.10
+Requires-Dist: rich>=12.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mihomo-cli
+
+English | [简体中文](README.zh-CN.md)
+
+A command-line, Clash-style proxy client for Linux machines without a desktop, powered by the
+[mihomo](https://github.com/MetaCubeX/mihomo) core. Use it through an interactive menu or plain commands.
+
+- Proxy services: an airport subscription, a local Clash/mihomo file, or hand-added node links (e.g. your own VPS)
+- Switch nodes without restarting; latency test and automatic fastest-node pick
+- Global / rule / direct modes, plus a switch for whether domestic (CN) sites go direct
+- Background systemd service, installed with a single `sudo`; no root needed day to day
+- Optional TUN mode for the whole machine, including programs that ignore proxy settings
+- Every change is validated, backed up, and rolled back automatically if it fails
+- `doctor` self-check with fixes, `--json` output, English / Chinese interface, shell completion
+
+Supported: Linux (tested on Ubuntu 20.04 / 22.04 / 24.04), Python 3.8+. macOS and Windows are not supported yet.
+
+## Install
+
+```bash
+pipx install mihomo-cli
+mihomo-cli install            # downloads the mihomo core and geo data, installs the service (asks for sudo once)
+```
+
+If GitHub is slow to reach, pass a mirror that proxies `https://github.com`:
+
+```bash
+mihomo-cli install --mirror https://your-mirror.example/https://github.com
+```
+
+## Quick start
+
+```bash
+mihomo-cli profile add airport --url 'https://example.com/sub?token=...'
+# or a single self-hosted node
+mihomo-cli profile add vps --node 'vless://...#my-vps'
+
+mihomo-cli node auto          # pick the fastest node
+mihomo-cli status             # one-screen overview including exit IP
+eval "$(mihomo-cli proxy-env on)"   # proxy the current shell (127.0.0.1:7897)
+```
+
+Run `mihomo-cli` with no arguments to open the menu. `mihomo-cli help <command>` shows help and examples.
+
+## Commands
+
+| Command | What it does |
+| ---- | ---- |
+| `status` | Service, core, proxy service, node, mode, CN switch, TUN, port, exit IP |
+| `install` / `uninstall` | Install or remove the core and the systemd service |
+| `core upgrade` | Replace the core; the old one is kept if verification fails |
+| `service start/stop/restart/status/logs` | Control the background service |
+| `profile list/show/add/rm/use/update/rename` | Manage proxy services |
+| `node list/use/add/rm/restore/test/auto` | Manage nodes of the active proxy service |
+| `mode [global/rule/direct]` | Show or set the mode |
+| `cn [direct/proxy]` | Domestic sites direct or via proxy (rule mode) |
+| `tun on/off/status` | Whole-machine TUN mode (on/off need sudo) |
+| `proxy-env [on/off]` | Print shell statements for proxy variables |
+| `conns` / `logs` | Active connections and core logs |
+| `backup list/restore` | Automatic backups (latest 10) |
+| `doctor [--fix]` | 15 checks with fix hints |
+| `completion bash/zsh [--install]` | Shell completion and the `mproxy on/off` helper |
+
+Global options: `--json`, `--lang zh|en`, `--home DIR` (or `MIHOMO_CLI_HOME`), `--version`.
+
+Exit codes: 0 ok, 1 error, 2 usage, 3 core unreachable, 4 invalid config or rolled back, 5 needs sudo
+or run as root, 6 unsupported platform, 7 rollback incomplete (manual action needed).
+
+## Files
+
+Everything lives in `~/.local/share/mihomo-cli` (mode 0700): `state.yaml` (what you asked for — the
+source of truth), the generated `config.yaml`, the core in `bin/`, `backups/`, and `mihomo-cli.log`.
+The service unit is `/etc/systemd/system/mihomo-cli.service`.
+
+## Notes
+
+- The mihomo core (GPL-3.0) is not bundled; it is downloaded from the official releases and checked
+  against the published SHA-256 digest when available.
+- mihomo-cli runs as its own instance and does not touch other mihomo / Clash services. Only one TUN can
+  be active on a machine; `tun on` refuses if another one is running.
+- Do not run mihomo-cli with `sudo`; it calls sudo itself for the few steps that need it.
+
+## License
+
+MIT

mihomo_cli-0.1.0/README.md

@@ -0,0 +1,85 @@
+# mihomo-cli
+
+English | [简体中文](README.zh-CN.md)
+
+A command-line, Clash-style proxy client for Linux machines without a desktop, powered by the
+[mihomo](https://github.com/MetaCubeX/mihomo) core. Use it through an interactive menu or plain commands.
+
+- Proxy services: an airport subscription, a local Clash/mihomo file, or hand-added node links (e.g. your own VPS)
+- Switch nodes without restarting; latency test and automatic fastest-node pick
+- Global / rule / direct modes, plus a switch for whether domestic (CN) sites go direct
+- Background systemd service, installed with a single `sudo`; no root needed day to day
+- Optional TUN mode for the whole machine, including programs that ignore proxy settings
+- Every change is validated, backed up, and rolled back automatically if it fails
+- `doctor` self-check with fixes, `--json` output, English / Chinese interface, shell completion
+
+Supported: Linux (tested on Ubuntu 20.04 / 22.04 / 24.04), Python 3.8+. macOS and Windows are not supported yet.
+
+## Install
+
+```bash
+pipx install mihomo-cli
+mihomo-cli install            # downloads the mihomo core and geo data, installs the service (asks for sudo once)
+```
+
+If GitHub is slow to reach, pass a mirror that proxies `https://github.com`:
+
+```bash
+mihomo-cli install --mirror https://your-mirror.example/https://github.com
+```
+
+## Quick start
+
+```bash
+mihomo-cli profile add airport --url 'https://example.com/sub?token=...'
+# or a single self-hosted node
+mihomo-cli profile add vps --node 'vless://...#my-vps'
+
+mihomo-cli node auto          # pick the fastest node
+mihomo-cli status             # one-screen overview including exit IP
+eval "$(mihomo-cli proxy-env on)"   # proxy the current shell (127.0.0.1:7897)
+```
+
+Run `mihomo-cli` with no arguments to open the menu. `mihomo-cli help <command>` shows help and examples.
+
+## Commands
+
+| Command | What it does |
+| ---- | ---- |
+| `status` | Service, core, proxy service, node, mode, CN switch, TUN, port, exit IP |
+| `install` / `uninstall` | Install or remove the core and the systemd service |
+| `core upgrade` | Replace the core; the old one is kept if verification fails |
+| `service start/stop/restart/status/logs` | Control the background service |
+| `profile list/show/add/rm/use/update/rename` | Manage proxy services |
+| `node list/use/add/rm/restore/test/auto` | Manage nodes of the active proxy service |
+| `mode [global/rule/direct]` | Show or set the mode |
+| `cn [direct/proxy]` | Domestic sites direct or via proxy (rule mode) |
+| `tun on/off/status` | Whole-machine TUN mode (on/off need sudo) |
+| `proxy-env [on/off]` | Print shell statements for proxy variables |
+| `conns` / `logs` | Active connections and core logs |
+| `backup list/restore` | Automatic backups (latest 10) |
+| `doctor [--fix]` | 15 checks with fix hints |
+| `completion bash/zsh [--install]` | Shell completion and the `mproxy on/off` helper |
+
+Global options: `--json`, `--lang zh|en`, `--home DIR` (or `MIHOMO_CLI_HOME`), `--version`.
+
+Exit codes: 0 ok, 1 error, 2 usage, 3 core unreachable, 4 invalid config or rolled back, 5 needs sudo
+or run as root, 6 unsupported platform, 7 rollback incomplete (manual action needed).
+
+## Files
+
+Everything lives in `~/.local/share/mihomo-cli` (mode 0700): `state.yaml` (what you asked for — the
+source of truth), the generated `config.yaml`, the core in `bin/`, `backups/`, and `mihomo-cli.log`.
+The service unit is `/etc/systemd/system/mihomo-cli.service`.
+
+## Notes
+
+- The mihomo core (GPL-3.0) is not bundled; it is downloaded from the official releases and checked
+  against the published SHA-256 digest when available.
+- mihomo-cli runs as its own instance and does not touch other mihomo / Clash services. Only one TUN can
+  be active on a machine; `tun on` refuses if another one is running.
+- Do not run mihomo-cli with `sudo`; it calls sudo itself for the few steps that need it.
+
+## License
+
+MIT

mihomo_cli-0.1.0/README.zh-CN.md

@@ -0,0 +1,84 @@
+# mihomo-cli
+
+[English](README.md) | 简体中文
+
+给没有桌面环境的 Linux 机器用的命令行版简易 Clash，以 [mihomo](https://github.com/MetaCubeX/mihomo) 为内核。
+既可以用交互菜单，也可以直接敲命令。
+
+- 代理服务：机场订阅、本地 Clash / mihomo 配置文件，或手工添加的节点链接（比如自建 VPS）
+- 切换节点不重启、不断网；测延迟，一键选最快节点
+- 全局 / 规则 / 直连三种模式，另有“国内网站走不走代理”开关
+- 后台 systemd 服务，安装时输一次 sudo 密码，日常不需要 root
+- 可选 TUN 模式：整台机器（包括不认代理设置的程序）都走代理
+- 每次改配置都先校验、先备份，失败自动恢复原状
+- `doctor` 自检并可自动修复，`--json` 输出，中英文界面，shell 补全
+
+支持：Linux（在 Ubuntu 20.04 / 22.04 / 24.04 上测试），Python 3.8 及以上。暂不支持 macOS 和 Windows。
+
+## 安装
+
+```bash
+pipx install mihomo-cli
+mihomo-cli install            # 下载 mihomo 内核与地区数据库，安装后台服务（输一次 sudo 密码）
+```
+
+访问 GitHub 慢时，可以指定一个代理 `https://github.com` 的镜像：
+
+```bash
+mihomo-cli install --mirror https://your-mirror.example/https://github.com
+```
+
+## 快速上手
+
+```bash
+mihomo-cli profile add airport --url 'https://example.com/sub?token=...'
+# 或者只加一台自建节点
+mihomo-cli profile add vps --node 'vless://...#my-vps'
+
+mihomo-cli node auto          # 选最快的节点
+mihomo-cli status             # 一屏概览，含出口 IP
+eval "$(mihomo-cli proxy-env on)"   # 当前终端走代理（127.0.0.1:7897）
+```
+
+不带参数运行 `mihomo-cli` 进入菜单。`mihomo-cli help <命令>` 查看说明和示例。
+
+## 命令一览
+
+| 命令 | 作用 |
+| ---- | ---- |
+| `status` | 后台服务、内核、代理服务、节点、模式、国内开关、TUN、端口、出口 IP |
+| `install` / `uninstall` | 安装或删除内核与后台服务 |
+| `core upgrade` | 更换内核；校验不通过时原内核不变 |
+| `service start/stop/restart/status/logs` | 控制后台服务 |
+| `profile list/show/add/rm/use/update/rename` | 管理代理服务 |
+| `node list/use/add/rm/restore/test/auto` | 管理当前代理服务的节点 |
+| `mode [global/rule/direct]` | 查看或切换模式 |
+| `cn [direct/proxy]` | 规则模式下国内网站直连或走代理 |
+| `tun on/off/status` | 整机 TUN 模式（开 / 关需要 sudo） |
+| `proxy-env [on/off]` | 输出终端代理环境变量语句 |
+| `conns` / `logs` | 当前连接与内核日志 |
+| `backup list/restore` | 自动备份（保留最近 10 份） |
+| `doctor [--fix]` | 15 项自检与修复建议 |
+| `completion bash/zsh [--install]` | shell 补全与 `mproxy on/off` 函数 |
+
+全局选项：`--json`、`--lang zh|en`、`--home 目录`（或环境变量 `MIHOMO_CLI_HOME`）、`--version`。
+
+退出码：0 成功，1 一般错误，2 用法错误，3 内核不可达，4 配置校验失败或已回滚，5 需要 sudo 或被以 root 运行，
+6 平台不支持，7 回滚未完成、需要手动处理。
+
+## 文件位置
+
+全部放在 `~/.local/share/mihomo-cli`（权限 0700）：`state.yaml`（记录你想要的状态，是权威来源）、
+生成的 `config.yaml`、`bin/` 里的内核、`backups/` 和 `mihomo-cli.log`。服务单元是
+`/etc/systemd/system/mihomo-cli.service`。
+
+## 说明
+
+- mihomo 内核（GPL-3.0）不随包分发，从官方发布页下载，能拿到官方 SHA-256 时会核对。
+- mihomo-cli 是独立实例，不改动机器上其它 mihomo / Clash 服务。同一台机器只能开一个 TUN，
+  已有其它 TUN 时 `tun on` 会拒绝。
+- 不要用 `sudo` 运行 mihomo-cli；需要权限的几步它会自己调用 sudo。
+
+## 许可证
+
+MIT

mihomo_cli-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mihomo-cli"
+dynamic = ["version"]
+description = "A command-line Clash-style client for Linux servers, powered by the mihomo kernel"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.8"
+authors = [{ name = "jakoes-wu" }]
+keywords = ["mihomo", "clash", "proxy", "cli", "tun"]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: Proxy Servers",
+]
+# 只写下限：pip 按各版本的 requires_python 自动挑出 Python 3.8 还能装的最后版本（方案 §3）。
+dependencies = [
+    "click>=8.0",
+    "rich>=12.0",
+    "questionary>=1.10",
+    "httpx>=0.24",
+    "PyYAML>=5.4",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+mihomo-cli = "mihomo_cli.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jakoes-wu/mihomo-cli"
+Issues = "https://github.com/jakoes-wu/mihomo-cli/issues"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+# 仓库还没有任何标签时（本地开发 / 首次构建）给一个可识别的占位版本。
+fallback_version = "0.0.0"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mihomo_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "README.zh-CN.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B", "UP"]
+ignore = ["UP006", "UP007", "UP035", "UP031", "UP037", "UP045", "E501"]

mihomo_cli-0.1.0/src/mihomo_cli/__init__.py

@@ -0,0 +1,13 @@
+"""mihomo-cli：以 mihomo 为内核的命令行代理客户端。"""
+
+try:
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+except ImportError:  # pragma: no cover - Python 3.8 起标准库自带 importlib.metadata
+    _pkg_version = None
+    PackageNotFoundError = Exception
+
+try:
+    # 版本号由 hatch-vcs 从 git 标签写进包元数据，代码里不写死（方案 5.1.11）。
+    __version__ = _pkg_version("mihomo-cli") if _pkg_version else "0.0.0"
+except PackageNotFoundError:
+    __version__ = "0.0.0"

mihomo_cli-0.1.0/src/mihomo_cli/__main__.py

@@ -0,0 +1,6 @@
+# 供 `<python> -m mihomo_cli` 使用：sudo 自调用与 systemd 单元都走这条路径，
+# 不依赖 ~/.local/bin 是否在 sudo 的 secure_path 里（方案 5.1.7「sudo 的使用方式」）。
+from mihomo_cli.cli import main
+
+if __name__ == "__main__":
+    main()