mihomo-rs

Examples | API Docs

English | 简体中文

Rust SDK and CLI for mihomo: version install/switch, config profiles, service lifecycle, proxy operations, and real-time connection/traffic monitoring.

What It Does

• Manage mihomo versions from GitHub releases (stable, beta, nightly or explicit tag like v1.19.17).
• Manage local config profiles under ~/.config/mihomo-rs (or $MIHOMO_HOME).
• Start/stop/restart mihomo with PID tracking.
• Query/switch proxies and run delay tests.
• Query/filter/close active connections.
• Stream logs, traffic, and connection snapshots via WebSocket APIs.

Install

cargo install mihomo-rs

Homebrew:

brew tap dingdangmaoup/mihomo-rs
brew install mihomo-rs

# Global command
mihomo-rs --help

Or install directly without a separate tap step:

brew install dingdangmaoup/mihomo-rs/mihomo-rs

Upgrade with:

brew update
brew upgrade mihomo-rs

Library usage:

[dependencies]
mihomo-rs = "*"

Quick Start (CLI)

# 1) Install and select a kernel version
mihomo-rs version install stable
mihomo-rs version list
mihomo-rs version use v1.19.17

# 2) Start service (auto-creates default config when missing)
mihomo-rs service start
mihomo-rs service status

# 3) Proxy operations
mihomo-rs proxy groups
mihomo-rs proxy switch GLOBAL "Proxy-A"

# 4) Observability
mihomo-rs service logs --level info
mihomo-rs service traffic
mihomo-rs connection stats

Run mihomo-rs --help for full command list.

Quick Start (SDK)

use mihomo_rs::{Channel, ConfigManager, MihomoClient, ProxyManager, ServiceManager, VersionManager, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let vm = VersionManager::new()?;
    vm.install_channel(Channel::Stable).await?;

    let cm = ConfigManager::new()?;
    cm.ensure_default_config().await?;
    let controller_url = cm.ensure_external_controller().await?;

    let binary = vm.get_binary_path(None).await?;
    let config = cm.get_current_path().await?;
    let sm = ServiceManager::new(binary, config);
    sm.start().await?;

    let client = MihomoClient::new(&controller_url, None)?;
    let pm = ProxyManager::new(client);
    let groups = pm.list_groups().await?;

    println!("groups: {}", groups.len());
    Ok(())
}

Progressive Examples

Examples are organized as an incremental path:

1. 01_bootstrap.rs - isolated home + manager bootstrap
2. 02_config_profiles.rs - save/list/switch config profiles
3. 03_version_inventory.rs - local version inventory/default lookup
4. 04_service_lifecycle_dry_run.rs - service manager dry-run checks
5. 05_proxy_queries.rs - proxy/group queries (online)
6. 06_connection_queries.rs - connection queries/filters (online)
7. 07_streaming.rs - logs/traffic streaming (online)
8. 08_complete_workflow.rs - full orchestration template

cargo run --example 01_bootstrap

See examples/README.md for details.

CLI Command Map

• Version: version install|update|use|list|list-remote|uninstall
• Config: config list|current|path|set|unset|use|show|delete
• Service: service start|stop|restart|status|logs|traffic|memory
• Proxy: proxy list|groups|switch|test|current
• Connections: connection list [--host ...] [--process ...], connection stats|stream, connection close [--id ...|--all|--host ...|--process ...]
• Doctor: doctor run|fix|list|explain

For proxies, list shows proxy nodes, groups shows selectable groups, and current shows each group's current selection.

Doctor

Use doctor to inspect config, version, service, and controller health in one place.

# Run the default check set
mihomo-rs doctor run

# Inspect only one category or check id
mihomo-rs doctor run --only config
mihomo-rs doctor run --only service.stale_pid

# Machine-readable output
mihomo-rs doctor run --json
mihomo-rs doctor fix --only service.stale_pid --json

# List and explain checks
mihomo-rs doctor list
mihomo-rs doctor explain controller.api_reachable

The current default checks include:

• config parsing and config-directory resolution
• current profile and YAML validity
• default binary availability
• PID consistency and stale pid-file detection
• external-controller resolution
• controller API reachability when the service is running

doctor fix is intentionally conservative and only applies safe fixes:

• create a missing configs directory
• create the missing default/current config file
• repair or add external-controller when it can be derived safely
• remove a stale or malformed mihomo.pid

Exit codes:

• 0: doctor completed without failing checks
• 1: doctor completed and found at least one failing check
• 2: doctor itself failed unexpectedly

Data Directory

By default, data is stored under ~/.config/mihomo-rs/.

~/.config/mihomo-rs/
├── versions/      # Installed kernels
├── configs/       # Profile yaml files
├── config.toml    # Default version/profile
└── mihomo.pid     # PID record

Override with:

export MIHOMO_HOME=/custom/path

To keep only profile files in a cloud-synced folder while leaving binaries and runtime files local, set a dedicated config directory in config.toml:

[paths]
configs_dir = "~/Library/Mobile Documents/com~apple~CloudDocs/mihomo-rs/configs"

You can also override it temporarily with:

export MIHOMO_CONFIGS_DIR=/custom/configs/path

Or write it into config.toml via CLI:

mihomo-rs config set configs-dir "~/Library/Mobile Documents/com~apple~CloudDocs/mihomo-rs/configs"

Development

git clone https://github.com/DINGDANGMAOUP/mihomo-rs.git
cd mihomo-rs
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

Release To Homebrew

Tagged releases update the dedicated Homebrew tap automatically.

• Release archives are published on GitHub Releases.
• The tap repository DINGDANGMAOUP/homebrew-mihomo-rs stores Formula/mihomo-rs.rb.
• Users upgrade with standard Homebrew flow: brew update && brew upgrade mihomo-rs.
• Tap repository: DINGDANGMAOUP/homebrew-mihomo-rs

Security

See SECURITY.md.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.