Skip to content
Get packs

Guide · Open source

How to use clashctl: install, turn on the proxy and switch nodes

Updated · written with AI from the project's own documentation and checked against our catalogue data

clashctl is a set of shell scripts for Linux that installs the mihomo (Clash) proxy core and a web dashboard, then lets you turn the proxy on or off for your current terminal with short commands. This guide covers installing it, adding a subscription, switching the proxy on and off, and the main commands you will use day to day. It is written for readers comfortable with a terminal who want a command-driven Clash setup.

clashctlnelvko/clashctl · ★ 15.1k · MIT

Quick start

  1. 1Check prerequisites. Confirm you are on Linux with Bash, Zsh, or Fish, and that curl is installed.
  2. 2Run the install one-liner. Paste the README install command into your terminal. It downloads install.sh through the GH_PROXY accelerator and runs it.
  3. 3Add a subscription. Run clashctl sub add --use with your own subscription link, replacing the placeholder.
  4. 4Turn the proxy on. Run clashctl on to start the core and enable the proxy in the current terminal.
  5. 5Test the connection. Run curl -I against a test URL to confirm traffic goes through the proxy.
  6. 6Check status and switch nodes. Use clashctl status to see the state, and clashctl node to switch nodes.
  7. 7Update or uninstall when needed. Use clashctl update and clashctl upgrade to update, or run clashctl off before the uninstall script.

What clashctl does and who it is for

clashctl is described in its README as a tool for installing and managing mihomo / Clash on Linux. Its features include one-step deployment of the mihomo core, a web dashboard, and runtime dependencies. It also covers proxy on/off, core start and stop, status and log viewing, subscription management, node switching, TUN mode, core upgrades, and Mixin configuration.

  • Linux users comfortable with the terminal who want a command-driven Clash setup
  • People managing several subscription links and switching nodes from the shell
  • Server or container users who need a proxy for command-line tools

What you need before installing

The README lists two prerequisites: Linux with a shell (Bash, Zsh, or Fish), and curl. The project lists Linux as its platform, so Windows and macOS are not covered. The README says clashctl supports both root and regular users, and it mentions systemd and OpenRC service methods.

  • A Linux system with Bash, Zsh, or Fish
  • curl installed

Install clashctl

The README install command is a single one-liner. It downloads install.sh through a GitHub download accelerator proxy, set in the GH_PROXY variable, and then runs it with bash. The README says to use this for a first install or an upgrade from an older version. If the proxy stops working, the README suggests choosing another address from the proxy list it links to.

  • GH_PROXY is the download accelerator. Replace it if it fails.
GH_PROXY=https://gh-proxy.org/ curl -fsSL "${GH_PROXY}https://raw.githubusercontent.com/nelvko/clashctl/HEAD/install.sh" | \ bash -s -- --gh-proxy "$GH_PROXY"

Add a subscription and turn the proxy on

The README's quick start first adds and enables a subscription. This step is optional. Replace the placeholder with your own subscription link. Then run clashctl on, which starts the core if needed and enables the proxy in the current terminal. To check the connection, the README uses curl against a test URL.

  • clashctl on starts the core automatically and enables the proxy for the current terminal
  • clashctl off disables the terminal proxy and keeps the core running by default
  • clashctl status shows core and terminal proxy state along with the proxy addresses
clashctl sub add --use "<订阅链接>" clashctl on curl -I https://www.google.com

Manage nodes, the dashboard and other commands

The command list in the README covers the main areas. sub manages subscriptions, node switches nodes, tun controls TUN mode, mixin manages Mixin configuration, and ui shows the dashboard address. secret handles the web secret, and log shows logs. The README points to its Wiki for usage examples and advanced setup. Run clashctl --help to see the full list on your installed version.

  • sub: subscription management
  • node: node switching
  • tun: TUN mode
  • mixin: Mixin configuration
  • ui: dashboard address
  • secret: web secret
  • log: view logs
  • upgrade: upgrade the core
  • update: update clashctl itself
  • version: script and core versions
clashctl --help

Update or uninstall clashctl

To update, the README uses clashctl update for the clashctl upstream version and clashctl upgrade for the proxy core. To uninstall, first run clashctl off to clear proxy variables in the current shell, because the uninstall script cannot do this. Then run the uninstall script from the install directory. The README warns that uninstalling deletes the install directory and its data, so back up anything you want to keep. Recovery files in .clashctl-backups/ are kept, and you can delete them yourself once you no longer need them.

  • Back up anything you need before uninstalling
  • Recovery files in .clashctl-backups/ remain after uninstall
clashctl off bash "$CLASHCTL_HOME/uninstall.sh"

What people use it for

  • Setting up a Clash proxy on a headless Linux server for command-line tools
  • Managing several subscription links and switching nodes from the terminal
  • Turning the proxy on and off for a single shell session
  • Running a web dashboard without configuring the mihomo core by hand

Frequently asked questions

Is clashctl free?

The README lists the project under the MIT licence, and the source does not mention any fees. The README also names third-party providers for subscriptions, and it does not offer a proxy service of its own.

What operating systems does clashctl support?

The README lists Linux as the platform. Its install instructions and features are all written for Linux, so Windows and macOS are not supported.

What do I need to install clashctl?

You need Linux with a shell (Bash, Zsh, or Fish) and curl. The README install command also downloads a script from GitHub, through a download accelerator proxy by default.

Does clashctl work with Zsh or Fish?

Yes. The README says it provides command integration for Bash, Zsh, and Fish.

How is clashctl different from Clash for Linux or v2rayA?

The source only lists clashctl, clash-verge-rev, mihomo, Clash for Linux (clash-for-linux), and v2rayA as comparable projects. It does not compare them in detail, so check each project's own documentation to decide.

How do I fix the install if the download fails?

The README says the GH_PROXY address may stop working. In that case, choose another proxy address from the list it links to and run the install command again with that value.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

clashctl suits Linux users and server admins who are comfortable in a terminal and want Clash managed by simple commands, with subscriptions, node switching and a dashboard included. It is not a good fit for Windows or macOS users, people who prefer a graphical client, or beginners with no shell experience.

Install options & downloads