Skip to content

getting_started_en.md

Latest commit

 

History

History
340 lines (247 loc) · 10.4 KB

getting_started_en.md

File metadata and controls

340 lines (247 loc) · 10.4 KB
Raw

Clashtui User Guide

Clashtui is a terminal tool for managing Mihomo (Clash.Meta) and sing-box proxy cores. In a clean interface, you can switch nodes, update subscriptions, view connection status, and control service start/stop.

Download & Install

Download the appropriate platform binary (e.g. clashtui-linux-amd64) from GitHub Releases, extract it, and place it in your PATH:

chmod +x clashtui
sudo mv clashtui /usr/local/bin/

Starting

clashtui

On first run, it will automatically create the config directory and default files under ~/.config/clashtui.

Specifying a Config Directory

Use the --config-dir argument or CLASHTUI_CONFIG_DIR environment variable to specify a different directory:

clashtui --config-dir /my/config/path

If a data/ subdirectory exists next to the executable, it will be used automatically (portable mode, suitable for USB drives).

TUI Interface

After entering the TUI, a row of tabs appears at the top, with a hint bar at the bottom.

Tabs

Key Tab Description
1 Status View core status: up/down rate, memory, uptime
2 Files Manage subscriptions (Profiles) and templates
3 Proxies Switch proxy nodes, view latency, manage proxy groups
4 Connections View all current connections, close individual or all connections
5 Logs View core logs in real time
6 Settings Modify Clashtui settings
7 CoreSrvCtl Control core services: start, stop, restart, switch between Mihomo / sing-box

Shortcuts

Global (works on all pages):

Shortcut Action
1 ~ 7 Jump to corresponding tab
Tab Next tab
q or Ctrl-c Quit
? Show shortcut help
Ctrl-g then c Open Clashtui config directory in file manager
Ctrl-g then m Open core config directory
Ctrl-g then f Start core service
Ctrl-g then t Close all connections

For page-specific shortcuts, press ? in each tab.

Custom Key Bindings

Create a keymap.yaml file in the config directory to modify key bindings for each page. For example, changing up/down navigation to j k:

proxies:
  j: SelectDown
  k: SelectUp
  enter: ToggleExpand

connections:
  j: SelectDown
  k: SelectUp

settings:
  j: SelectDown
  k: SelectUp
  enter: Edit

file:
  profile:
    j: SelectDown
    k: SelectUp
  template:
    j: SelectDown
    k: SelectUp

You can also use the list format to customize descriptions:

proxies:
  - key: j
    action: SelectDown
    desc: Move down
  - keys: ["g", "g"]
    action: ToggleExpand
    desc: Expand/Collapse

CLI Mode

You can operate without entering the TUI, suitable for scripting or automation.

Managing Subscriptions (Profiles)

# View current profile
clashtui profile select

# List all profiles
clashtui profile list

# Show names only
clashtui profile list --name-only

# Filter by type: file / url / template / singbox
clashtui profile list --type url

# Switch to a specific profile
clashtui profile select --name "my-subscription"

# Update current profile
clashtui profile update --name "my-subscription"

# Update all profiles (including the current one)
clashtui profile update --all

# Update with proxy
clashtui profile update --all --with-proxy

With the above commands, you can use cron to schedule periodic profile updates.

Switching Mode

# View current mode
clashtui mode

# Set to Rule mode
clashtui mode rule

# Set to Global mode
clashtui mode global

# Set to Direct mode
clashtui mode direct

Controlling Services

# Hard restart (via systemd)
clashtui service restart

# Soft restart (via API, without restarting the process)
clashtui service restart --soft

# Stop service
clashtui service stop

Checking for Updates

# Check Clashtui updates
clashtui update clashtui

# Check Mihomo core updates
clashtui update mihomo

Profile (Subscription) Types

Clashtui supports three subscription types:

1. File Profile

Directly select a local YAML (Mihomo) or JSON (sing-box) config file as a profile. The file is not modified; Clashtui only applies overrides on top of it.

2. URL Profile

Enter a proxy subscription link. Clashtui will automatically download and track updates. When updating, proxy-provider resources are also downloaded.

3. Template Profile

The most flexible approach. You write a template file defining the skeleton (DNS, route rules, inbounds, etc.), then manage proxy node groups via template_proxy_providers.yaml.

How Templates Work:

  • Templates are placed in the mihomo/templates/ (or sing-box/templates/) directory
  • Node groups are defined in template_proxy_providers.yaml
  • Templates use variables like ${PPG.group_name} to reference nodes
  • Clashtui automatically expands variables into specific proxies, generating the final config file

A simple example: in the Files tab, create a Template-type Profile, select the corresponding template file and proxy-provider groups, and Clashtui will automatically synthesize a usable final configuration.

Config File Reference

config.yaml

Clashtui's main config, defining core paths and service names:

mihomo:
  core:
    config_dir: /opt/clashtui/mihomo/config     # Core config directory
    bin_path: /opt/clashtui/mihomo/mihomo       # Core binary path
    config_path: /opt/clashtui/mihomo/config/config.yaml  # Final config file path
  core_service:
    service_name: clashtui_mihomo                # systemd service name
    is_user: false                               # Whether it's a user service
singbox:
  core:
    bin_path: /opt/clashtui/sing-box/sing-box
    config_dir: /opt/clashtui/sing-box/config
    config_path: /opt/clashtui/sing-box/config/config.json
  core_service:
    service_name: clashtui_singbox
    is_user: false
timeout: null
extra:
  edit_cmd: kitty -e nvim "%s"      # Command for editing files, %s is replaced by file path
  open_dir_cmd: kitty -e yazi "%s"  # Command for opening directories

core_override_config.yaml

The top-level keys of this file will override the corresponding keys of the subscription config when switching profiles.

mixed-port: 7890
allow-lan: false
mode: Rule
log-level: info

For example, no matter what port your subscription specifies, mixed-port will always be 7890.

This is Mihomo-specific. For sing-box, edit sing-box/core_override_config.json.

core_override_config.json (sing-box)

sing-box uses deep merge. You only need to write the parts you want to override; other fields retain the original subscription values.

{
  "experimental": {
    "clash_api": {
      "external_controller": "127.0.0.1:9090",
      "secret": ""
    }
  },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "127.0.0.1",
      "listen_port": 7890
    }
  ],
  "log": { "level": "info" }
}

Override rules:

  • Objects: recursive merge (your fields override the subscription's; subscription-only fields are kept)
  • Arrays: full replacement (what you write is exactly what you get)
  • Numbers/Strings: direct override

Config Directory Full Structure

~/.config/clashtui/
├── clashtui.db                     # Database: saves profile list, current selection, etc.
├── clashtui.log                    # Log file
├── config.yaml                     # Main config
├── keymap.yaml                     # Custom key bindings (optional)
├── theme.yaml                      # Custom theme (optional)
├── mihomo/
│   ├── core_override_config.yaml   # Override config
│   ├── profiles/                   # Downloaded subscription raw files
│   ├── templates/                  # Template files
│   ├── provider-cache/             # Provider cache
│   └── template_proxy_providers.yaml  # Template proxy node groups
└── sing-box/
    ├── core_override_config.json
    ├── profiles/
    ├── templates/
    ├── proxy-providers/
    └── template_proxy_providers.yaml

Core Management

Switching Cores

In the CoreSrvCtl tab (press 7), you can switch between Mihomo and sing-box cores. After switching, restart Clashtui.

Clashtui automatically detects whether the currently running core type matches the configured one. If there's a mismatch, a popup will warn you and prevent displaying incorrect data.

File Permissions (Linux)

Clashtui uses Linux group file permissions to manage access to core directories. On startup, it automatically checks file permissions under config_dir and will prompt you to confirm if repairs are needed.

Logging

Logs are written to <config_dir>/clashtui.log. To increase log verbosity for troubleshooting:

clashtui -v     # More info
clashtui -vv    # Debug info

FAQ

In non-is-user mode, the core can't download rule files after starting? Non-is_user installations enable TUN by default, which may prevent the core from downloading required startup files (like rule-set, geoip, etc.). A temporary workaround: switch mode to Direct (clashtui mode direct), wait for the core to download the needed files, then switch back to the original mode (clashtui mode rule).

No data displayed after startup? Make sure the Mihomo or sing-box core has been started. Go to the CoreSrvCtl tab (press 7) to start the service.

Seeing "core mismatch" warning? This means the running core doesn't match Clashtui's configured core. Go to the CoreSrvCtl tab to confirm which core you actually want to use, switch to it, then restart Clashtui.

How do I add a subscription? Go to the Files tab (press 2), press ? to see shortcuts. Typically press a to add a new Profile, then enter the subscription URL. Clashtui will automatically download and update.

How do I create a sing-box template subscription?

  1. Place a JSON template file in sing-box/templates/
  2. Define your node groups and URLs in template_proxy_providers.yaml
  3. In the Files tab, create a Template type Profile and select the template you just wrote

What is the profiles directory in the config directory for? It stores the raw content of your subscriptions. These files are not affected by override configs — overrides only take effect when switching subscriptions and writing to the core config directory.