mihoro - The 🦀 Rust™-based Mihomo CLI client on Linux.

• Setup, update, apply overrides, and manage with systemd. No more, no less.
• No root privilege required. Maintains per-user instance.
• First-class support for config subscription.

curl -fsSL https://raw.githubusercontent.com/spencerwooo/mihoro/main/install.sh | sh

Optionally, download over a mirror:

curl -fsSL https://raw.githubusercontent.com/spencerwooo/mihoro/main/install.sh | sh -s -- --mirror https://ghfast.top

mihoro, like mihomo, is a config-based CLI client.

After installing mihoro, initialize its config ~/.config/mihoro.toml first by:

mihoro setup

The default config will be generated:

remote_config_url = ""
mihomo_channel = "stable"
mihomo_binary_path = "~/.local/bin/mihomo"
mihomo_config_root = "~/.config/mihomo"
user_systemd_root = "~/.config/systemd/user"
mihoro_user_agent = "mihoro"
auto_update_interval = 12

[mihomo_config]
port = 7891
socks_port = 7892
mixed_port = 7890
allow_lan = false
bind_address = "*"
mode = "rule"
log_level = "info"
ipv6 = true
external_controller = "0.0.0.0:9090"
external_ui = "ui"
geodata_mode = false
geo_auto_update = true
geo_update_interval = 24

[mihomo_config.geox_url]
geoip = "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geoip.dat"
geosite = "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geosite.dat"
mmdb = "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/country.mmdb"

Before doing anything, fill in remote_config_url, which is your remote mihomo or clash subscription url.

Example:

remote_config_url = "https://tt.vg/freeclash"  # DO NOT USE THIS IF YOU CAN!

Customize other settings as needed, then, run setup once more:

mihoro setup

... to start downloading mihomo binary, your remote config, and geodata.

To configure proxy for the current terminal session:

eval $(mihoro proxy export)

To revert proxy settings:

eval $(mihoro proxy unset)

To check running status of mihomo core:

mihoro status

To update subscribed remote config:

mihoro update
# or explicitly: mihoro update --config

To apply settings changes after modifying mihoro.toml:

mihoro apply

To update mihomo binary (core) and/or geodata:

mihoro update --core     # updates core
mihoro update --geodata  # updates geodata
mihoro update --all      # updates config -> core -> geodata -> restarts mihomo

To enable auto-update via cron job:

mihoro cron enable

To disable auto-update:

mihoro cron disable

To check auto-update status:

mihoro cron status

The auto_update_interval in mihoro.toml controls the update frequency in hours (default: 12, range: 1-24). Set to 0 to disable.

To upgrade mihoro itself to the latest version:

mihoro upgrade

Or check for updates without installing:

mihoro upgrade --check

To manually specify a target architecture (useful when auto-detection fails, e.g., on Ubuntu 20.04):

mihoro upgrade --target x86_64-unknown-linux-musl
mihoro upgrade --target aarch64-unknown-linux-musl

Shell auto-completions are available under mihoro completions for bash, fish, zsh:

# For bash:
mihoro completions bash > $XDG_CONFIG_HOME/bash_completion/mihoro  # or /etc/bash_completion.d/mihoro

# For fish:
mihoro completions fish > $HOME/.config/fish/completions/mihoro.fish

# For zsh:
mihoro completions zsh > $XDG_CONFIG_HOME/zsh/completions/_mihoro  # or to one of your $fpath directories

Full list of commands:

$ mihoro --help
Mihomo CLI client on Linux.

Usage: mihoro [OPTIONS] [COMMAND]

Commands:
  setup        Setup mihoro by downloading mihomo binary and remote config
  update       Update mihomo components (config by default)
  apply        Apply mihomo config overrides and restart mihomo.service
  start        Start mihomo.service with systemctl
  status       Check mihomo.service status with systemctl
  stop         Stop mihomo.service with systemctl
  restart      Restart mihomo.service with systemctl
  log          Check mihomo.service logs with journalctl [aliases: logs]
  proxy        Output proxy export commands
  uninstall    Uninstall and remove mihoro and config
  completions  Generate shell completions for mihoro
  cron         Manage auto-update cron job
  upgrade      Upgrade mihoro to the latest version
  help         Print this message or the help of the given subcommand(s)

Options:
  -m, --mihoro-config <MIHORO_CONFIG>  Path to mihoro config file [default: ~/.config/mihoro.toml]
  -h, --help                           Print help
  -V, --version                        Print version

On controlling mihomo itself, we recommend using a web-based dashboard. Some options include metacubexd, zashboard, or yacd.

Web-based dashboards require enabling external_controller under [mihomo_config]. Applying this config will expose mihomo's control API under this address, which you can then configure your dashboard to use this as its backend.

You can also put the static files of these dashboards under the external_ui directory if defined. In this case, mihomo will serve the dashboard locally under {external_controller}/ui. Please refer to the official documentation of mihomo for more information: docs/external_controller, docs/external_ui.

MIT