meow-cli · git:20261023.0da7dec · 2026-10-23 · sha256 dfe3a313fed10aed
meow-cli git:20261023.0da7decA
Immutable. This exact content never changes and is served at /api/v1/blob/dfe3a313fed10aed.
--- name: meow-cli description: Inspect and control a running meow (meow-rs, the Rust mihomo / Clash Meta kernel) from the shell with meow-cli. Use when the user asks why traffic goes where it goes, which node a proxy group uses, to switch a group's node or the routing mode, to look at or close connections, to test node delays, to query or flush DNS, to update providers or subscriptions, to read the logbook or follow the log, or to reload the config. license: MIT compatibility: Needs the meow-cli binary and a running meow with external-controller set. --- # meow-cli `meow-cli` talks to a running meow over its REST API (the `external-controller`). It never starts or stops meow; every command is one or a few HTTP requests. `meow-cli --help` and `meow-cli <command> --help` list every option. If `meow-cli` is not on PATH, use the one that ships with this skill, two directories above its folder: `<dir>/meow-cli` (`meow-cli.exe` on Windows) beside `<dir>/skills/meow-cli/`. The folder may be a link; go up from its real path (`cd <folder> && pwd -P`), not from the link. ## Connecting meow serves the API only when its config sets `external-controller`. Once the API is up, meow writes its address and secret to a file that only the user meow runs as can read. On that machine, as that user, meow-cli needs no options, whoever started meow: a service, a terminal, or a desktop GUI that passed the secret on meow's command line. meow-cli finds the controller in this order: 1. `--controller host:port` or `MEOW_CONTROLLER` 2. `external-controller` in the config given with `--config FILE` or `MEOW_CONFIG` 3. the meow running as this user, from its file 4. `127.0.0.1:9090` The API secret comes from `--secret-stdin`, else `MEOW_SECRET`, else the file of the meow at that address, else `secret` in the `--config` file. ```bash meow-cli status # the meow running as this user meow-cli --config /etc/meow/config.yaml status meow-cli --controller 192.168.1.1:9090 status # a meow on another host printf '%s\n' "$SECRET_FROM_A_VAULT" | meow-cli --secret-stdin status ``` Rules for the secret: - Never print, echo, log or paste the secret, and never put it on a command line: there is no `--secret` flag on purpose. - Do not open the config file or meow's controller file to show them to the user; they hold the secret, and the config holds node passwords. Let meow-cli read them. - A `401` means the secret is missing or wrong. Ask the user how to supply it. When several meows run as this user, meow-cli lists them and asks for `--controller`; ask the user which one they mean. A meow running as root (a system service, or one started with sudo for TUN) or as another user writes its file for that user only: meow-cli then has to run as that user too, such as `sudo meow-cli status`. Ask before using sudo. If meow-cli cannot connect, meow is not running, or it runs without `external-controller`, or on another address. Say so; do not start meow yourself unless the user asks. ## Reading state These commands change nothing; run them freely. ```bash meow-cli status # version, mode, log level, TUN, ports, traffic totals meow-cli mode # without an argument these three only read meow-cli log-level meow-cli tun meow-cli group list # every group and the member it routes through meow-cli group show "Proxy" # one group's members with their last delay meow-cli proxy list # every proxy, provider members too meow-cli proxy list --filter HK meow-cli proxy show "HK 01" # type, UDP, delay history meow-cli rule list --filter google # rules in match order, with their index meow-cli conn list # open connections: rule, destination, route meow-cli conn list --filter youtube meow-cli conn show 1a2b3c4d # one connection with its notes; an id prefix works meow-cli dns query example.com meow-cli dns query example.com --type AAAA meow-cli dns cache --search example --limit 20 meow-cli provider list # proxy and rule providers, usage and expiry meow-cli subscription list meow-cli logbook # notable engine events, newest first meow-cli logbook --level warning --limit 20 meow-cli logbook --kind config # config.reload, config.change meow-cli stats # bytes each proxy carried since meow started meow-cli listeners meow-cli log --level warning --count 50 # follow the log; --count makes it stop meow-cli traffic --count 5 # one sample per second ``` Add `--json` to any command to get what the API answered, for parsing: ```bash meow-cli --json group show "Proxy" meow-cli conn list --json meow-cli proxy list --json --filter JP ``` Text output puts names last, so names with CJK or emoji do not break the columns. In `conn list` the route reads from the rule's target to the node that dials: `Proxy > Auto > HK 01`. `delay` shows `-` before a first successful test and `down` for a node that failed its last one. ### Answering "why does this go there?" 1. `meow-cli conn list --filter <host>` shows the rule that matched and the route each connection took. 2. `meow-cli conn show <id>` adds the connection's notes when the config sets `connection-notes: true`: DNS answers, the rule decision, each dial hop. 3. `meow-cli rule list --filter <word>` finds the rule; its index is its place in match order. 4. `meow-cli group show <group>` shows which member the group uses now. ### Answering "is something broken?" `meow-cli logbook` lists notable events, newest first: reloads, provider and subscription updates, listener starts, network interface changes and dialer-proxy chain changes, each with how often it repeated. `--level warning` keeps only the failures. The logbook survives restarts, unlike `meow-cli log`. ```bash meow-cli --timeout 5 status # is meow up and answering at all? meow-cli logbook --level warning # what failed, newest first meow-cli logbook --subject airport # one provider, group or listener meow-cli logbook --before 812 # older entries; a full page prints this line ``` ### Checking a dialer-proxy chain `chain-health` dials a proxy through each member of a group, the way `dialer-proxy` chains it, whether or not its config sets one, and tests each member alone too. It records nothing: no delay, no verdict, no switch. Each member gets one verdict: - `reached`: the chain works through it; CHAIN is the chain's delay. - `failed`: the member works alone, and other members carry the proxy, but this one does not: it blocks the proxy's server. Keep it out of the proxy's dialer group. - `inconclusive`: it works alone, but no member carried the proxy: the proxy's own server is the likelier fault. - `down`: it fails alone too, so it says nothing about the chain. - `skipped`: a group, or the proxy itself. ```bash meow-cli chain-health home Auto # can each member of Auto carry home? meow-cli chain-health home "HK 01" # one front proxy meow-cli chain-health home Auto --url https://cp.cloudflare.com --probe-timeout 3000 meow-cli --json chain-health home Auto ``` A proxy that cannot run over another proxy's stream, like hysteria2, is refused (422). The check is TCP only. ## Changing state These change how meow routes or what it keeps. Tell the user what you are about to change and get a yes first, unless they asked for exactly that change. ```bash meow-cli mode global # rule | global | direct meow-cli group select "Proxy" "HK 01" meow-cli group unfix Auto # url-test / fallback back to automatic meow-cli group test Auto # delay-test every member meow-cli group test Auto --url https://cp.cloudflare.com --probe-timeout 3000 meow-cli proxy test "HK 01" meow-cli proxy test "HK 01" --url https://cp.cloudflare.com --probe-timeout 3000 meow-cli conn close 1a2b3c4d meow-cli conn close --all meow-cli dns flush meow-cli dns flush-fakeip meow-cli provider update airport meow-cli provider update reject-list --kind rule meow-cli provider check airport # health-check a provider's nodes meow-cli subscription update airport meow-cli reload # the --config file, else the one meow loaded meow-cli reload /etc/meow/config.yaml meow-cli reload --force # only when the user asks for it, see below meow-cli log-level debug meow-cli tun on meow-cli logbook clear ``` What to know before changing things: - `group select` on a `select` group switches it and meow remembers the pick across restarts. On a `url-test` group it pins that member: the group stops choosing on its own until `group unfix`, and a pinned member that goes down is routed around but stays pinned. On a `fallback` group the pin holds only while the member is up; meow drops it once it sees the member down. - `group test` on a `url-test` or `fallback` group clears its pin first, as mihomo does. To measure without unpinning, test members one by one with `proxy test`. - `select` groups have nothing to unfix; `load-balance` and `relay` groups cannot be selected. - `mode`, `log-level` and `tun` change the running meow, not the config file. meow keeps them in its in-memory copy of the config, though, and whatever saves that copy writes them into the file: a subscription update (by hand or on its timer), or a GUI saving the config. Until then a restart returns to the file's values. `reload` returns `log-level` and `tun` to the file's values, and `mode` only when the file sets `mode:`. - `reload` sends the file's text to meow and closes every open connection, like `conn close --all`. meow refuses a file that does not parse. Otherwise it skips broken proxies, groups and rules with a warning and applies the rest, unless the config sets `strict: true`; check `meow-cli logbook --kind config` afterwards. `--force` also applies a config whose strict checks, TUN, listeners or DNS fail; use it only when the user wants that. - `conn close --all` drops every connection, the user's current calls and downloads included. `dns flush-fakeip` breaks open fake-IP flows. - Provider and subscription updates fetch over the network and can take a minute. `provider check` runs the provider's `health-check:`; a provider without one (or with it disabled) is refused, so test its nodes with `proxy test`. - `logbook clear` deletes the record for good. - Subscription URLs carry access tokens: `subscription list` shows only their host. Never ask for or print the full URL. ## Errors meow-cli exits 0 on success and 1 on any failure, with the reason on stderr: - `cannot reach meow's controller at …`: meow is down, or the address is wrong. - `meow wants the API secret (401)`: see Connecting. - `meow answered 400 …` / `404 …`: meow refused the request; the message says why (unknown group or member, a member that is not in the group, a config that does not parse). - `proxy test` exits 1 when the node fails the test; `group test` lists failed members as `failed` and still exits 0. ## Installing this skill The desktop release archives (Windows, macOS, and Linux glibc and musl on x86_64 and aarch64) carry this skill as `skills/meow-cli/`: copy that folder into the agent's skills directory. `meow-cli skill` prints this file, for a meow-cli installed another way: ```bash mkdir -p ~/.claude/skills/meow-cli meow-cli skill > ~/.claude/skills/meow-cli/SKILL.md ```