clash-tui 0.1.1

A pragmatic terminal UI for Clash external controller

clash-tui

clash-tui is a terminal UI and isolated Mihomo manager.

The default design is intentionally conservative:

• it uses its own Mihomo under ~/.clash-tui/
• it uses isolated ports by default
• it does not touch your shell unless you ask for env, exec, or shell
• the default TUI is directly usable, but every modifying action asks for confirmation

Install

pip install .

For local development:

pip install -e .

Directory Layout

First run creates ~/.clash-tui/.

If an older ~/.clash_tui/ exists and ~/.clash-tui/ does not, it is moved once into the new location.

Important files:

• ~/.clash-tui/config.json: app config
• ~/.clash-tui/profiles/index.json: subscription profile index
• ~/.clash-tui/profiles/current.yaml: active subscription source config
• ~/.clash-tui/profiles/*.yaml: saved subscription profiles
• ~/.clash-tui/mihomo/config.yaml: isolated Mihomo config
• ~/.clash-tui/mihomo/geoip.metadb: bundled GeoIP/MMDB database when shipped
• ~/.clash-tui/bin/mihomo: downloaded kernel
• ~/.clash-tui/subconverter/: on-demand local subscription converter
• ~/.clash-tui/run/mihomo.pid: managed process pid
• ~/.clash-tui/logs/mihomo.log: managed process log

Default ports are isolated from the common Clash defaults:

• controller: 127.0.0.1:19090
• proxy: 127.0.0.1:17890

If these ports are already occupied by another process, clash-tui automatically picks free local ports and writes them back to config.json.

Config

config.json starts like this:

{
  "controller": "http://127.0.0.1:19090",
  "secret": "",
  "refresh": 5,
  "timeout": 5.0,
  "http_proxy": "http://127.0.0.1:17890",
  "https_proxy": "http://127.0.0.1:17890",
  "all_proxy": "socks5://127.0.0.1:17890",
  "subscription_url": "",
  "current_profile": "",
  "tun_enabled": false
}

You can edit it directly later.

clash-tui keeps ~/.clash-tui/mihomo/config.yaml in sync for the managed core's controller, secret, mixed port, and Tun settings.

If you import subscriptions, they are stored as named profiles under ~/.clash-tui/profiles/, the active one is mirrored to current.yaml, and the runtime config is generated from it.

Supported subscription formats:

• Clash/Mihomo YAML config URLs
• common base64 node subscriptions; these are converted locally into a simple Mihomo config
• local files, for example file:///home/lenovo/subscription.yaml

Common schemes such as ss, vmess, trojan, vless, hysteria2, and tuic are handled.

If the raw subscription still cannot be used directly, clash-tui can auto-install a local subconverter under ~/.clash-tui/ and retry conversion locally.

Subscription

Import a subscription URL and assign a profile name:

clash-tui sub import "https://example.com/your-subscription" --name office
clash-tui sub import "file:///home/lenovo/subscription.yaml" --name local

List profiles:

clash-tui sub list

Switch to a saved profile:

clash-tui sub use office

Update the current or named subscription again from the saved URL:

clash-tui sub update
clash-tui sub update office

Delete one profile:

clash-tui sub delete office

Show the current subscription state:

clash-tui sub show

TUI

Default command:

clash-tui

This will auto-download Mihomo if needed, auto-start the isolated core if needed, then open the interactive TUI.

Inside the TUI, modifying actions use Enter confirm / Esc cancel dialogs.

• i: import a subscription URL
• s: open the subscription profile manager
• c: edit key config.json fields
• u: update the current subscription
• t: test all nodes in the current selector group in parallel and keep the TUI responsive
• n: toggle Tun mode
• k: install or update Mihomo to the latest release
• Enter: switch the focused proxy after confirmation
• m: switch mode after confirmation

Current-terminal env

Enable proxy env only for the current shell:

eval "$(clash-tui env on)"

Disable it:

eval "$(clash-tui env off)"

Child-process only

Run one command with proxy env only for that child process:

clash-tui exec -- curl https://ip.sb

Open a subshell with proxy env only for that shell:

clash-tui shell

• interactive clash-tui shell prints the current selector route and a latency check for the active node before the prompt appears
• clash-tui exec and clash-tui shell also wrap ssh / scp / sftp and Git-over-SSH so they use the same proxy inside that child environment only

Kernel Management

Download Mihomo automatically:

clash-tui kernel install

• release packages can bundle a matching mihomo asset, and kernel install will use the bundled kernel first when available
• release packages can also bundle geoip.metadb, so first start does not depend on downloading GeoIP/MMDB from GitHub

Update Mihomo:

clash-tui kernel update

Show kernel info:

clash-tui kernel info

Core Management

clash-tui core start
clash-tui core status
clash-tui core restart
clash-tui core stop

Tun Mode

clash-tui tun status
clash-tui tun on
clash-tui tun off

• tun on will restart or start the managed Mihomo core with Tun enabled
• Linux Tun usually needs root or CAP_NET_ADMIN; if the kernel cannot start, clash-tui will keep the previous state and report the log path

Keys

• Tab: switch between groups and proxies
• Enter: apply the focused proxy after confirmation
• m: cycle rule -> global -> direct after confirmation
• i: import a subscription
• s: open subscription profiles
• c: edit key config fields
• t: test the current group in parallel and display latency for each node
• n: toggle Tun mode after confirmation
• u: update the current subscription
• k: install or update Mihomo kernel
• r: refresh now
• q: quit

Notes

• secret is stored as plain text in config.json
• config file permissions are tightened to 600 when possible
• all runtime-managed files stay under ~/.clash-tui
• imported subscriptions and profile index are stored under ~/.clash-tui/profiles/
• port conflicts for the managed controller and proxy ports are resolved automatically with free local ports
• local subconverter files, if needed, also stay under ~/.clash-tui/
• your default desktop Clash or system Mihomo is not touched unless you explicitly point this tool at it