CLI Reference

This page is the canonical reference for the kumo binary. Every command accepts --help for inline reference, and --json to switch from human text to the stable JSON envelope.

The envelope is always:

{ "ok": true,  "data": <payload> }
// or
{ "ok": false, "error": { "code": "...", "message": "...", "details": {} } }

See JSON output for the full contract.

Status

Read the current state.

kumo status --json
kumo st                             # alias

status returns core state, mode, controller endpoint, mixed port, system proxy state, runtime settings, and the last status message.

Lifecycle

Control the Mihomo core process.

kumo start --core /path/to/mihomo   # explicit core
kumo start                          # discover core automatically
kumo stop
kumo restart

When the (planned) Kumo Helper is installed, start, stop, and restart delegate to it; otherwise they fall back to the local-process supervisor inside the app.

Outbound mode

Switch Mihomo's outbound mode without restarting.

kumo mode rule
kumo mode global
kumo mode direct

The mode patches /configs on the running core, closes existing connections, refreshes proxy groups, and persists the new mode.

Proxies

kumo proxies --json                 # every group and its members
kumo proxy --json                   # alias
kumo select "Proxy" "HK-01"         # pick a node inside a `select` group

Automated groups (URLTest, Fallback, LoadBalance) are read-only — the CLI shows the current pick but Mihomo controls it.

Connections

kumo connections --json
kumo connections --close <connection-id>
kumo connections --close-all

Each record carries host, proxy chain, traffic counters, and originating process metadata (when Mihomo can resolve it).

Providers

kumo providers --json

Returns proxy- and rule-provider counts plus per-provider metadata (name, source, last refresh).

Runtime events

kumo runtime-events --json
kumo runtime-events --limit 20

The in-memory ring buffer of Kumo runtime events: core lifecycle, profile switches, system proxy changes.

Doctor

kumo doctor --json

One-shot report combining status, the current profile, and the list of discovered Mihomo cores. Handy when filing a support ticket.

Configuration paths

kumo config             # alias of `kumo config path`
kumo config path        # application support directory
kumo config list        # every CLI-visible path
kumo c list             # short alias

Backup

kumo backup export ~/Documents/kumo-backup
kumo backup import ~/Documents/kumo-backup

A backup captures state.json, the profiles directory, the overrides directory, and Sub-Store data.

Profiles

kumo profile refresh "https://example.com/sub.yaml"

Today the CLI exposes remote-URL refresh. The first refresh imports the profile; subsequent refreshes update the existing entry. The wider profile management surface (importProfile, profileContent, updateProfile, deleteProfile, refresh-by-id, refresh-all-due) is exposed by KumoController for the GUI today and is being added to the CLI alongside rule and provider management.

System proxy

kumo sysproxy on --dry-run --json
kumo sysproxy on --json
kumo sysproxy off --json

--dry-run returns the exact networksetup commands Kumo would run, without executing them or binding the PAC listener.

TUN

kumo tun enable --json
kumo tun disable --json

Without a privileged owner of the utun device, enable returns a clear service-mode error and the stored state rolls back before Mihomo restarts.

Service mode (planned)

kumo service status --json
kumo service install
kumo service uninstall

Install and uninstall use macOS administrator authorization. Until the helper ships, these commands report a not-installed state.

Sub-Store

kumo substore status --json
kumo substore prepare              # copy bundled resources into ~/Library/...
kumo substore start
kumo substore stop
kumo substore restart

See Sub-Store hosting for the backend choices.

Core

kumo core install                  # download a managed core

Agent skills

kumo skills status --json
kumo skills install --agent claude --scope global --dry-run --json
kumo skills install --agent all
kumo skills uninstall --agent cursor --scope project --dry-run --json

--agent accepts cursor, claude, codex, gemini, agents, or all. codex and gemini do not support project scope. --agent all --scope project targets only agents with project-scope support.

Install is non-destructive by default: if the destination directory exists and was not recorded as installed by Kumo, the command fails until --force is passed.

Logs

kumo logs                                # runtime logs (default)
kumo logs runtime --limit 200 --level info --json
kumo logs cli --limit 5 --json
kumo logs path
kumo logs clean --dry-run --json

Completion

kumo completion zsh
kumo completion bash
kumo completion fish

Discovery and help

kumo --help
kumo --long
kumo help status
kumo status --help
kumo --version

Global flags

JSON output

Every command accepts --json and returns the same envelope shape:

{
  "ok": true,
  "data": { /* command-specific payload */ }
}

On failure:

{
  "ok": false,
  "error": {
    "code": "CORE_NOT_RUNNING",
    "message": "Kumo core is not running.",
    "details": {}
  }
}

For automation, branch on error.code rather than on the exit code:

Exit codes are deliberately small:

Anything beyond 1 is reserved.

Logging

kumo writes a per-invocation debug log to ~/Library/Application Support/Kumo/logs/cli/. The terminal output is filtered by --loglevel. See File locations for the layout.