Clash-Verge-CLI

A comfortable Clash Verge For AI Agents

cvctl is a small companion CLI for a running Clash Verge Rev / Mihomo instance. The demo uses Mihomo's stable HTTP External Controller API; it does not depend on Clash Verge's private IPC protocol.

cvctl doctor
cvctl status

cvctl mode
cvctl mode rule
cvctl mode global
cvctl mode direct

cvctl proxy groups
cvctl proxy current "节点选择"
cvctl proxy select "节点选择" "香港 01"
cvctl proxy delay "香港 01"

cvctl connection list
cvctl connection show "connection-id"
cvctl connection close "connection-id"
cvctl connection close --all --yes

cvctl provider list
cvctl provider show "provider-name"
cvctl provider update "provider-name"
cvctl provider healthcheck "provider-name"

cvctl rule list
cvctl rule list --type DOMAIN --proxy "Proxy" --enabled --limit 20
cvctl rule show 0

cvctl dns query example.com
cvctl dns query example.com --type AAAA

cvctl traffic
cvctl traffic --watch
cvctl memory
cvctl memory --watch

Every read command supports --json for scripts:

cvctl status --json
cvctl proxy groups --json
cvctl connection list --json
cvctl provider list --json
cvctl rule list --json
cvctl dns query example.com --json

traffic and memory return one meaningful sample by default. Add --watch to continue until Ctrl+C. With --json, watch mode emits one compact JSON object per line (NDJSON), so consumers can process samples without buffering an unbounded array. --idle-timeout defaults to five seconds.

Closing one connection validates that its full ID is active before sending the request. Closing every connection is intentionally guarded and requires both --all and --yes.

The default endpoint is http://127.0.0.1:9090. Override it with a flag:

cvctl status --endpoint http://127.0.0.1:9097

Configure the secret with an environment variable, a bounded file, or stdin:

$env:CVCTL_ENDPOINT = "http://127.0.0.1:9097"
$env:CVCTL_SECRET = "your-secret"
cvctl doctor

cvctl doctor --secret-file .\mihomo-secret.txt
Get-Content .\mihomo-secret.txt -Raw | cvctl doctor --secret-stdin

--secret remains available for compatibility, but it prints a deprecation warning because command-line arguments can be exposed in shell history and process listings. --secret, --secret-file, and --secret-stdin are mutually exclusive. File and stdin secrets are limited to 64 KiB and must not be empty.

Keep the External Controller on loopback whenever possible and configure a secret. The client does not follow HTTP redirects. It refuses to send a secret to a non-loopback plain HTTP endpoint; use HTTPS. The explicit --allow-insecure-remote override exists for controlled legacy environments and should be treated as a high-risk exception.

Example Mihomo configuration:

external-controller: 127.0.0.1:9090
secret: change-me

Go 1.23 or newer is required.

go test ./...
go vet ./...
go build -o cvctl.exe .

Tests use local httptest servers and never change a real controller.

This demo intentionally supports only the stable HTTP(S) controller:

• GET /version
• GET and PATCH /configs
• GET /proxies
• GET and PUT /proxies/:name
• GET /proxies/:name/delay
• GET and DELETE /connections
• DELETE /connections/:id
• GET /providers/proxies
• GET and PUT /providers/proxies/:name
• GET /providers/proxies/:name/healthcheck
• GET /rules
• GET /dns/query
• streaming GET /traffic
• streaming GET /memory

Unix sockets and Windows named pipes can be added behind a transport abstraction later, but they are not part of this stable demo.