karing-rule-cli

简体中文

Manage Karing split-routing rules from a terminal without clicking through the GUI. It updates Karing's visible custom rule, the selected outbound, and the currently running sing-box configuration as one transaction.

Why

Karing's GUI is excellent for everyday use, but adding a custom routing rule takes several screens. This CLI makes the same change reproducible:

karing-rule add "Example direct" \
  --outbound direct \
  --domain-suffix example.com

There is also a built-in preset for NetEase UU Remote:

karing-rule preset uu-remote

Safety

• Never toggles Karing's connection switch.
• Refuses non-local control API endpoints.
• Validates all three JSON documents before changing anything.
• Creates a timestamped local backup before every write.
• Uses atomic file replacement.
• Hot-reloads the sing-box core.
• Restores the previous files if reload fails.
• Does not print, copy, or upload subscriptions, node credentials, or the Karing control secret.

Backups stay inside Karing's configuration directory under karing-rule-cli-backups/.

Install

Python 3.10 or newer is required.

python3 -m pip install karing-rule-cli

For development:

git clone https://github.com/duevan07/karing-rule-cli.git
cd karing-rule-cli
python3 -m pip install -e .

Commands

Check whether the local Karing installation is supported:

karing-rule doctor

List rules and their selected outbound:

karing-rule list

Add or update a direct rule:

karing-rule add "My direct rule" \
  --outbound direct \
  --domain-suffix example.com \
  --process-name ExampleApp

Route through the currently selected node:

karing-rule add "My proxy rule" \
  --outbound current \
  --domain-suffix example.org

Route through a named node:

karing-rule add "My fixed route" \
  --outbound "Japan-1" \
  --domain-suffix example.jp

Remove a rule:

karing-rule remove "My direct rule"

Every command supports --json for agent and automation use. Set KARING_CONFIG_DIR or pass --config-dir when automatic discovery does not cover a platform or packaging format.

Current compatibility

• macOS: tested against Karing's Group Container configuration layout.
• Windows and Linux: discovery paths are included but need community testing.
• Karing must be running for hot reload. --no-reload is available for offline maintenance.

Scope

Version 0.1 manages custom domain suffix, exact domain, IP CIDR, and process name matchers. It supports direct, automatic, current, and exact named outbounds.

Privacy

Bug reports must not attach service_core.json, karing_subscribe.json, or karing_subscribe_use.json; these files may contain private proxy credentials. Use karing-rule --json doctor, which returns only non-secret diagnostics.

License

MIT