ProxyCTL

ProxyCTL is a cross-platform command line proxy manager for subscription-based proxy profiles. It can install and run either sing-box or mihomo, import remote profiles, list servers from those profiles, and choose the server you want to use before starting the core.

Features

• Install and update external proxy cores.
• Supports sing-box and mihomo.
• Import remote subscription profiles.
• List profiles and switch between them.
• List servers with their host or IP address.
• Choose a server by name or by list index.
• Start, stop, restart, and inspect the proxy runtime.
• Stores state under the user config directory instead of the project folder.

Install

From npm:

npm install -g proxyctl

From source:

npm install
npm run build
npm link

Quick Start

proxyctl core install mihomo
proxyctl core use mihomo
proxyctl import https://example.com/subscription.yaml
proxyctl profiles
proxyctl use <profile-id>
proxyctl list servers
proxyctl use server 1
proxyctl start
proxyctl status

Use proxyctl stop when you want to stop the current core process.

Commands

Runtime

proxyctl start
proxyctl stop
proxyctl restart
proxyctl status

start launches the configured core in the background. When a server is selected from a Mihomo or Clash profile, ProxyCTL writes a runtime profile that prioritizes the selected server before starting the core.

Profiles

proxyctl import <url>
proxyctl profiles
proxyctl use <profile-id>
proxyctl delete <profile-id>

Imported JSON profiles are treated as sing-box style profiles. YAML profiles are treated as Clash/Mihomo style profiles.

Server Picker

proxyctl list servers
proxyctl list servers --all
proxyctl use server <name-or-index>
proxyctl choose <name-or-index>

proxyctl list servers reads the active profile and prints each server with:

• list index
• server name
• host or IP address
• port
• type
• profile id
• selected marker

Example:

proxyctl list servers
proxyctl use server 3
proxyctl start

If no active profile is selected, run proxyctl list servers --all to inspect every imported profile.

Core Management

proxyctl core install
proxyctl core install sing-box
proxyctl core install mihomo
proxyctl core update mihomo
proxyctl core list
proxyctl core use sing-box
proxyctl core use mihomo

The default core is sing-box. Mihomo can be installed and selected with:

proxyctl core install mihomo
proxyctl core use mihomo

ProxyCTL downloads the latest release for the current platform and CPU architecture from the upstream GitHub release page.

Configuration

ProxyCTL stores its files under the OS config directory:

• Linux: ~/.config/proxyctl
• macOS: ~/Library/Application Support/proxyctl
• Windows: %APPDATA%\proxyctl

Important folders:

• config.json: active profile, selected core, and selected server
• profiles/: imported profile metadata
• subscriptions/: raw imported subscription files
• runtime/: generated runtime profiles
• cores/: installed proxy core binaries
• logs/: core stdout and stderr logs
• state/: runtime status

Example config:

{
  "dataDir": "/home/user/.config/proxyctl",
  "currentProfileId": "e3b0c442",
  "coreVersion": "mihomo",
  "selectedServerName": "Tokyo-01"
}

Development

npm install
npm run build
npm test

Useful source paths:

• src/cli/index.ts: command definitions
• src/services/core: core download and install logic
• src/services/profiles: profile import and server discovery
• src/services/process: runtime process management
• src/services/config: persisted config schema

Release 1.1

Version 1.1.0 adds the server picker and Mihomo-focused workflow.

Before publishing:

npm test
npm run build
npm pack --dry-run
npm publish --access public

Publishing requires an npm account with permission to publish the proxyctl package.