clashrup
Simple CLI to manage your systemd clash.service and config subscriptions on Linux.
- Setup, update, apply overrides, and manage via
systemctl. No more, no less. - Systemd configuration is created with reference from Running Clash as a service.
- No root privilege is required.
clash.serviceis created under user systemd by default. clashrupgot its name from clashup, a friendly Python alternative.
Installation
Using a one-liner installation script
To install clashrup, inside your terminal, run:
curl -fsSL https://raw.githubusercontent.com/spencerwooo/clashrup/main/install.sh | sh -
By default, this installs the executable to ~/.local/bin/clashrup. Add ~/.local/bin to $PATH if needed.
Downloading clashrup manually
Download prebuilt binary for Linux from releases. Move under /usr/local/bin (system-wide), ~/.local/bin (user) or any other directory in your $PATH. Example:
curl -LO https://github.com/spencerwooo/clashrup/releases/download/{VERSION}/clashrup-{TARGET_ARCH}.tar.gz
tar -xvzf clashrup-{TARGET_ARCH}.tar.gz
mv clashrup ~/.local/bin/clashrup
Building from source
Alternatively, clone the repo and install from source:
cargo install --path .
Usage
Note: Run
clashrup --helpto see a list of available commands.
To setup and start clash as a systemd service on a new Linux device, run:
clashrup setup
clashrup will first attempt to read from ~/.config/clashrup.toml for config. If not found, it will generate a default one and abort. You would then need to edit the config file and run clashrup setup again. See Configuration for more details.
With a valid config, rerun clashrup setup to download clash binary and remote config.
Ultimately, clashrup setup will attempt to:
- Download
clashbinary fromremote_clash_binary_urland extract it toclash_binary_path. - Download clash remote config from
remote_config_url, apply overrides, and save it underclash_config_root. - Create a user systemd service file
clash.serviceunderuser_systemd_root. - Enable and start
clash.servicewithsystemctl.
You can then check the status of the newly created clash.service running in the background with:
clashrup status
If something doesn't work as expected, you can check the logs with:
clashrup log
To update clash's config from remote and restart clash.service, run:
clashrup update
If you modified config overrides in ~/.config/clashrup.toml, you can apply them to clash's config (~/.config/clash/config.yaml) and restart clash.service with:
clashrup apply
Finally, to stop clash.service and uninstall clash and config, run:
clashrup uninstall
Additionally, you would often need to set environment variables to proxy your traffic through clash within your current terminal session. clashrup provides a convenient command to generate command for exporting environment variables (http_proxy, https_proxy, and all_proxy) for your current session:
clashrup proxy export
Note: For more proxy export commands, check
clashrup proxy --help.
Configuration
clashrup stores its config at ~/.config/clashrup.toml by default.
Default config is generated upon setup (with command setup) as:
# ~/.config/clashrup.toml
remote_clash_binary_url = ""
remote_config_url = ""
remote_mmdb_url = "https://cdn.jsdelivr.net/gh/Dreamacro/maxmind-geoip@release/Country.mmdb"
clash_binary_path = "~/.local/bin/clash"
clash_config_root = "~/.config/clash"
user_systemd_root = "~/.config/systemd/user"
[clash_config]
port = 7890
socks_port = 7891
allow_lan = false
bind_address = "*"
mode = "rule"
log_level = "info"
ipv6 = false
external_controller = "127.0.0.1:9090"
# external_ui = "folder"
# secret = ""
where,
- Field
remote_clash_binary_urlshould point to a downloadable gzippedclashbinary URL (example). - Field
remote_config_urlshould point to your subscription provider's config URL, which will be downloaded to{clash_config_root}/config.yamlduringsetupandupdate. - Field
clash_configholds a subset of supported config overrides for clash'sconfig.yaml. Inside,port,socks_port,mode, andlog_levelare required. Other fields are optional. For a full list of configurable clashconfig.yamlfields, see clash - Configuration.
If clash binary already exists at clash_binary_path, then remote_clash_binary_url will be ignored and setup will skip downloading and setting up clash binary. (In this case, remote_clash_binary_url can be left empty.)
Other fields should be self-explanatory.
Manage clash's settings
We recommend setting external_controller and secret for clash's RESTful API, which can be used to manage clash via external dashboards like yacd.
If you are using this on a remote Linux server, edit ~/.config/clashrup.toml and set external_controller to :9090:
-external_controller = "127.0.0.1:9090"
+external_controller = ":9090"
to allow external access. Run clashrup apply to apply the changes to clash and restart clash. You can now use http://{YOUR_SERVER_IP}:9090 to access the API and control clash's settings.
Warning: Set
secretif external access is granted to prevent unauthorized access to your clash API.
Shell completions
clashrup has built-in support for generating shell completion information for the CLI. clashrup will output to stdout completions with clashrup completions <shell>. bash, zsh, and fish are currently supported.
bash
mkdir -p ~/.local/share/bash-completion/completions
clashrup completions bash > ~/.local/share/bash-completion/completions/clashrup
zsh
mkdir -p ~/.local/share/zsh/site-functions
clashrup completions zsh > ~/.local/share/zsh/site-functions/_clashrup
Additionally, add directory ~/.local/share/zsh/site-functions to your fpath where completions are loaded from. Ideally, above where compinit is called in your ~/.zshrc:
+fpath=(~/.local/share/zsh/site-functions $fpath)
autoload -Uz compinit
compinit -u
fish
clashrup completions fish > ~/.config/fish/completions/clashrup.fish
9 Feb 1, 2023
5 Oct 31, 2022
6 Nov 3, 2022
327 Dec 20, 2022
125 Dec 23, 2022
42 Nov 10, 2022
2 Jul 3, 2022
401 Dec 28, 2022
11 Dec 26, 2022
40 Oct 21, 2021
8 Dec 30, 2022
2 Aug 17, 2022
215 Dec 3, 2021
2 May 2, 2022
4 Nov 8, 2022
4 Dec 15, 2022
24 Dec 1, 2022
4 Aug 29, 2023