Metadata-Version: 2.4
Name: clash-tui
Version: 0.1.1
Summary: A pragmatic terminal UI for Clash external controller
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests<3,>=2.32
Requires-Dist: urwid<3,>=2.6

# 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

```bash
pip install .
```

For local development:

```bash
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:

```json
{
  "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:

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

List profiles:

```bash
clash-tui sub list
```

Switch to a saved profile:

```bash
clash-tui sub use office
```

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

```bash
clash-tui sub update
clash-tui sub update office
```

Delete one profile:

```bash
clash-tui sub delete office
```

Show the current subscription state:

```bash
clash-tui sub show
```

## TUI

Default command:

```bash
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:

```bash
eval "$(clash-tui env on)"
```

Disable it:

```bash
eval "$(clash-tui env off)"
```

### Child-process only

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

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

Open a subshell with proxy env only for that shell:

```bash
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:

```bash
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:

```bash
clash-tui kernel update
```

Show kernel info:

```bash
clash-tui kernel info
```

## Core Management

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

## Tun Mode

```bash
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
