---
title: "CLI 参考 | Kilobat 文档"
url: "https://kilobat.app/zh-hans/docs/cli"
description: "所有 kilobat 命令、JSON 输出与脚本。"
---

# CLI 参考

所有 kilobat 命令、JSON 输出与脚本。

## 命令

### 监控

|  |  |
|---|---|
| `kilobat status [--watch] [--json]` | 每个应用的实时流量和本次会话预算；输出一次 JSON 快照，加 --watch 则输出 JSON Lines 流 |
| `kilobat report [--csv\|--json] [--summary] [--days 1…365]` | 本地记录的用量历史，或每日总量和用量最多的应用；CSV 每个应用一行 |
| `kilobat report compare --total 40GB [--unit GB\|GiB] [--direction both\|download\|upload] (--from DATE --to DATE \| --period last-month) [--network NAME] [--json\|--csv]` | 把路由器或运营商的数字与 Kilobat 在这台 Mac 上同期记录的数据并排显示，使用相同单位，并列出已记录的时长、每一段空缺以及差异的可能原因 |
| `kilobat health-history [--hours 1…720] [--json]` | 应用随时间记录的路由器、互联网、抖动和 DNS 检查 |
| `kilobat proxy [routes [--app name] \| test] [--json]` | 代理应用、系统代理及其问题；每个应用走了哪条规则和哪个节点；每个节点的响应速度 |
| `kilobat vpn [--json]` | VPN、DNS 或 IPv6 是否绕过了它，以及 VPN 断网保护的状态 |
| `kilobat vpn leaks [--json]` | 泄漏测试：DNS、IPv6 或 UDP（WebRTC 使用的协议）是否绕过 VPN，并分别给出修复设置；会询问 bash.ws、Cloudflare 和一个 STUN 服务器 |
| `kilobat calls [--limit 1…200] [--json]` | 每次通话后：卡顿了几次以及原因，来自 App 生成的报告 |
| `kilobat remote [--limit 1…200] [--kind ssh\|mosh\|desktop] [--json]` | 每次 SSH、Mosh 或远程桌面会话后：输入延迟或画面卡顿的原因，以及 Mosh 何时有帮助 |
| `kilobat stream [status\|check\|reports] [--json]` | 通过 OBS 的本地 WebSocket 查看是否正在直播和丢帧；直播前将上传速度与码率加 30% 比较（check [--bitrate <kbps>] [--measure\|--no-measure]）；以及每次直播后的报告（reports [--limit 1…200]） |
| `kilobat cloud-gaming [status\|reports] [--limit 1…200] [--json]` | GeForce NOW、Xbox Cloud Gaming、Boosteroid、Amazon Luna 和 Shadow：当前会话（ping、抖动、丢包、码率、流量及干扰因素）和每次会话后的报告，包括卡顿时间和原因 |
| `kilobat overlay [--port 7171] [--target internet\|router\|cs2:fra\|host]` | 适用于 OBS 等直播应用的实时 ping 叠加层，在 localhost 上提供，直到按下 Ctrl-C；cs2:fra 这样的游戏区域会 ping 该数据中心 |
| `kilobat support-report [--hours 1…168] [--host h] [--include-sites] [--markdown\|--html] [--output f]` | 给运营商或 IT 支持部门的报告：发现的问题、延迟、断网和速度测试，不含你的网络名称和本地地址 |
| `kilobat plan [--days 7…90] [--json]` | 每个网络上与付费套餐对比的速度测试：中位数、晚间与其他时段的对比，以及测试结果不到一半的频率 |
| `kilobat credit [--provider id] [--price n] [--month this\|last\|YYYY-MM] [--draft] [--json]` | 本月路由器之外的断网与运营商公布的补偿规定的对比、可能符合的补偿，以及申请草稿；<code>credit providers</code> 列出所有规定 |
| `kilobat week [--weeks-ago 0…12] [--json]` | 每周摘要：上周最值得注意的断网、卡顿通话、路由器、阻止记录和按流量计费网络上的流量，并与前一周对比 |
| `kilobat router [--all] [--json]` | 路由器体检：路由器平时的响应、丢包和断开情况与最近三天的对比，以及重启记录和是否有帮助，数据来自 App 保留的检查 |
| `kilobat router connect [fritzbox\|unifi\|mikrotik\|openwrt] [--json]` | 应用的 Pro 路由器连接设置步骤；绝不会通过命令行获取凭据 |
| `kilobat router devices [--json]` | 通过应用查看已连接路由器的客户端、测得的速度和今日总量；FRITZ!Box 等全家庭计数器不能说明单个设备的占比；客户端计数器可能包含 LAN 流量 |
| `kilobat router disconnect [--json]` | 忘记此网络的路由器；应用会移除其钥匙串凭据，或在下次启动时移除 |
| `kilobat service-speed [--all] [--test <service>] [--list] [--json]` | 将来自 GitHub、iCloud、Steam、npm 等服务的下载与线路速度比较，并显示运营商到某服务的路径何时缓慢；<code>--test</code> 立即从一个服务下载最多 25 MB |
| `kilobat hotspot [--all] [--carrier <id>] [--detect] [--json]` | 在手机热点上：每次下载是否都止于运营商的热点限速、相关测量和运营商公布的规则；<code>hotspot carriers</code> 列出运营商 |
| `kilobat networks [forget <name>]` | 见过的网络，以及为每个网络记住的配置、预算和流量计费方式 |
| `kilobat networks cost <metered\|unmetered\|automatic> [name]` | 把当前网络或指定网络视为按流量计费或不限流量，或重新跟随 macOS |
| `kilobat bandwidth [app] [hour\|day\|week\|month] [--back N] [--json]` | 某个应用在一小时、一天、一周或一个月内发送和接收的字节数及峰值；--back 回溯到更早的时段 |
| `kilobat access-policy <bundle-id> [--json]` | 应用开发者在其互联网访问策略中声明的连接及原因 |

### 诊断

|  |  |
|---|---|
| `kilobat diagnose [--json]` | Wi-Fi、路由器、互联网、DNS 和强制门户检查，并给出建议 |
| `kilobat radar [--watch] [--json]` | 信号评分和最佳位置查找 |
| `kilobat scan [--json]` | 附近的网络、信道、宽度和安全性 |
| `kilobat channels [--json]` | 每个信道的拥挤程度，以及最不拥挤的信道 |
| `kilobat speedtest [--json] [--budget-mb 1…80] [--parallel]` | Cloudflare 测速、负载下延迟，以及通话和流媒体判断，最多 80 MB。默认使用 1 个连接；--parallel 会打开 4 个，和大多数测速网站一样 |
| `kilobat speed-compare [<test> <test>] [--json]` | 两次已存速度测试之间有何不同：网络、时间、服务器、连接数、Wi-Fi 频段和信号、VPN、其他流量 |
| `kilobat ip [--public] [--json]` | 流量出口：在这台 Mac 上读取的网络接口和 VPN；--public 还会向 Cloudflare 查询你的公网 IP 及其注册国家或地区 |
| `kilobat portal [open] [--json]` | Wi-Fi 登录页面：立即检查（畅通、登录页面或离线，附带页面地址，查询参数值已隐去）、这个网络是否需要登录、是否已让你退出登录或还剩多久，以及每个网络通常的登录时长；open 会在浏览器中打开该页面 |
| `kilobat stutter [--seconds 10…60] [--target router\|internet\|<host>] [--json]` | 每 50 ms ping 一次，找出速度测试漏掉的短暂延迟尖峰、发生时间以及是否重复出现 |
| `kilobat starlink [--hours 1…720] [--json]` | 这个网络上的 Starlink 天线，从本地读取：状态、地面站 ping、警报、天空地图及遮挡方向，以及按你的设备、Starlink 的网络和天线重启分类的断网 |
| `kilobat games [--game <game> \| --all \| --match] [--json]` | 列出 Kilobat 能 ping 的游戏和不能 ping 的游戏，并说明原因；使用 --game 时，向该游戏的每个数据中心（Valve 中继、Epic ping 服务器，或它所在的 AWS 和 Azure 区域）各 ping 五次，找出离你最近的那个；使用 --match 时，找到你正在玩的对局的服务器并 ping 它，适用于任何游戏，可直接用于直播叠加层 |
| `kilobat airdrop [status\|everyone\|contacts\|off] [--json]` | 隔空投送可见性、隔空投送链路（AWDL）及其使用者；更改可见性会打开系统设置 |
| `kilobat bluetooth [--json]` | 蓝牙设备，以及它们是否与 Wi-Fi 共用 2.4 GHz |
| `kilobat bluetooth audio [--json]` | AirPods 或其他蓝牙耳机播放时：可能导致杂音的因素（2.4 GHz、隔空投送、大型下载、信号弱）以及按顺序该改什么 |
| `kilobat local [check] [--quick] [--json]` | 这里可以投屏或打印吗？显示响应的 Chromecast、隔空播放接收器和打印机，网络是否可能隔离设备（仅凭发现结果绝不确认）、打印机或相机自身的 Wi-Fi，以及投屏卡顿的原因 |
| `kilobat dns [automatic\|cloudflare\|google\|quad9\|flush]` | 读取或设置 DNS，或清除缓存 |
| `kilobat dns fastest [--all] [--json]` | 根据应用的后台静默测试，显示此网络上 Cloudflare、Quad9 和 Google 中最快的 DNS、各自的运营方和所在地，以及过去 14 天的查询响应情况 |
| `kilobat dns 自动 on\|off [--network <name>]` | Pro：加入网络时切换到最快的 DNS，适用于所有网络或单个网络 |
| `kilobat dns exclude\|include <resolver>` | 永不测量或选择某个解析器，或按 IP 地址添加自己的解析器 |
| `kilobat dns fallback <resolver>\|off` | 最快解析器失败时，在切回网络自身解析器之前使用的备用解析器 |

### Wi-Fi

|  |  |
|---|---|
| `kilobat wifi [status]` | 当前网络、信号、信道和宽度、链路速率、Wi-Fi 标准、安全性和发射功率 |
| `kilobat wifi on\|off\|restart\|disconnect` | 控制 Wi-Fi 电源和连接 |
| `kilobat wifi join <name> [--password-stdin]` | 加入已存网络或新网络 |
| `kilobat wifi known` | 按优先顺序列出已存网络 |
| `kilobat wifi password\|share <name>` | 显示已存密码，或生成可用手机扫描的二维码 |
| `kilobat wifi nodes [name <node> <name>] [--json]` | 此网络的 Mesh 节点或接入点、Mac 当前连接的节点，以及范围内是否有近得多的节点；可为节点命名，例如“办公室” |
| `kilobat wifi reconnect [--json]` | 切换到较近的节点，然后显示 Mac 最终连接的位置 |
| `kilobat low-latency on [--for 15m\|1h\|2h] [--until-quit <app>]` | 在通话和游戏时暂停隔空投送和 AWDL：默认 15 分钟，最长 4 小时，或直到某个应用退出 |
| `kilobat low-latency off` | 恢复隔空投送和 AWDL，在应用中开始的暂停也适用 |

### 唤醒与智能体

|  |  |
|---|---|
| `kilobat awake [--display]` | 保持 Mac 唤醒，直到按下 Ctrl-C；合上盖子仍会睡眠，除非加上 --lid-closed |
| `kilobat awake --lid-closed [--for 2h\|--until-quiet\|-- <command>]` | 合盖时也继续运行，最长 8 小时，通过应用的电源辅助程序实现；需要在设置中开启“允许合盖运行” |
| `kilobat awake --for 90m\|2h\|45s` | 保持唤醒一段时间 |
| `kilobat awake --until-quiet [--app <id>] [--quiet 1…60]` | 保持唤醒，直到下载或某个应用安静下来：默认为连续 3 分钟低于 16 KB/s |
| `kilobat awake -- <command> [args]` | 在命令运行期间保持唤醒，然后报告其进程传输的数据量，并以该命令的状态退出 |
| `kilobat awake --while-frontmost <app> [--display] [--for 2h]` | 仅在该应用位于前台时保持唤醒，适合阅读或演示。切换到其他应用后 Mac 可以睡眠；应用退出、电量降到 20% 或到达 --for 时长后结束。--display 还会让屏幕保持常亮 |
| `kilobat settings awake-on-power on\|off` | 接通电源适配器时应用始终保持唤醒，拔掉后让 Mac 恢复睡眠 |
| `kilobat settings keep-screen-on on\|off` | 应用保持唤醒的所有情况下都让屏幕常亮：定时、下载、智能体、前台应用和接通电源 |
| `kilobat sessions [--days N] [--json]` | 应用记录的唤醒会话和 AI 智能体运行，包括使用的流量和网络变化 |
| `kilobat agent-log [--all] [--since 2h\|3d\|date] [--agent claude] [--flagged] [--json]` | AI 智能体及其启动的命令连接过的每个主机，附字节数和标记：显示最近一次会话；由智能体运行时，显示它自己的会话。由 App 在 Pro 下记录 |
| `kilobat history forget <host> [--subdomains] [--json]` | 从被阻止的尝试、智能体网络日志、智能体运行的目标地址和防护通知记录中移除主机 |
| `kilobat history clear --hour\|--today\|--all [--json]` | 清除过去一小时、午夜以来或全部主机历史记录；之后的活动仍可被记录 |
| `kilobat agent-log --watch [--agent claude] [--flagged] [--json]` | 无需 App，在此终端中实时记录相同内容；不保存任何东西 |
| `kilobat protect [status\|on\|off\|update] [--threats\|--trackers\|--agents] [--json]` | 防护：阻止已知的恶意软件、网络钓鱼和诈骗主机（Pro）、App 中的跟踪器（免费，默认关闭），以及智能体守卫（Pro）；update 会立即下载列表 |
| `kilobat protect check <host> [--json]` | 主机是否在威胁或跟踪器列表中、在哪个列表中，以及 Kilobat 是否阻止它；如果阻止，则以 1 退出 |
| `kilobat protect allow\|unallow <host>` | 让某个网站及其子域名不受任何防护列表限制，或撤销这项设置 |
| `kilobat agent-event <start\|working\|waiting\|done\|failed> [--agent name] [--stdin-json\|--json-arg]` | 供智能体的钩子使用：告诉应用某次运行已开始、正在等待你或已完成。无输出，始终以 0 退出 |
| `kilobat why <url\|host> [--app <id>] [--proxy <url>] [--context container\|vm\|remote\|provider] [--failed-at <time>] [--error <text>] [--json]` | 找出阻止连接的环节：网络和接口、代理及应用自身的代理、DNS、Kilobat 规则、IPv4 和 IPv6、TLS、服务器及每次重定向，以及是此网络封锁还是服务拒绝你所在地区。请求准确的 URL；输出隐藏查询值。也可使用 kilobat doctor <url\|host> |
| `kilobat down [service\|host…] [--all] [--list] [--json]` | 是服务的问题还是我的问题？查看 Slack、Zoom、GitHub、Claude、OpenAI 及约 70 项其他服务的公开状态页面当前报告，以及各服务能否从此处连接：被此网络封锁，还是在你所在地区不可用；不指定服务时检查此 Mac 正在运行的应用 |
| `kilobat explain <process\|host…> [--process name --host name] [--json]` | 根据此 Mac 上 Kilobat 自身的数据库，说明 macOS 进程或主机是什么、正常流量是多少、阻止是否安全以及哪些功能会失效。对于未知对象，显示 Kilobat 掌握的事实 |
| `kilobat conditions [--json]` | 按流量计费、低数据模式、VPN、延迟、电池和发热、能否合盖，并为长时间运行给出建议 |

### 控制

|  |  |
|---|---|
| `kilobat profile [travel\|work\|unrestricted]` | 列出或选择配置 |
| `kilobat allow\|block <bundle-id> [--minutes 1…1440] [--profile name]` | 保存应用规则，可设为临时规则或用于其他配置 |
| `kilobat reset <bundle-id> [--profile name]` | 移除应用的规则，让它遵循默认设置 |
| `kilobat rules [--profile name] [--json]` | 某个配置的规则 |
| `kilobat limit [GB] [--cycle session\|daily\|weekly\|monthly] [--reset-day N] [--alert 50,80,100]` | 读取或设置当前网络的流量预算、重置时间和提醒时机 |
| `kilobat quota <bundle-id> <GB> [--upload] [--all-networks]` | 限制单个应用在每个预算周期内的流量；quota <bundle-id> --remove 可取消限制 |
| `kilobat quota --list [--json]` | 各应用的配额及本周期已用量 |
| `kilobat pack [status] [--json]` | 旅行 eSIM 等流量包的剩余量，以及按过去三天的速度预计各自用尽的日期 |
| `kilobat pack add <GB> <days\|YYYY-MM-DD> [--network <name>] [--name <label>] [--start YYYY-MM-DD]` | 在此网络、Kilobat 曾见过的网络或名称包含特定文字的任何网络上添加流量包 |
| `kilobat pack correct <GB-left> [--pack <name>]` | 设置运营商应用显示的剩余量，因为 Kilobat 只统计此 Mac |
| `kilobat pack end [--pack <name>]` | 立即结束流量包；它会保留在历史记录中 |
| `kilobat updaters [--json]` | 在按流量计费的网络上暂停的更新程序、在此网络上仍然漏过的更新流量，以及在自身进程内更新的应用 |
| `kilobat updaters on\|off` | 当网络按流量计费时，暂停 Google Updater 和 macOS 软件更新等更新辅助程序（默认开启）；应用本身照常工作 |
| `kilobat settings kill-switch on\|off` | Pro：VPN 断开时阻止新连接；kill-switch-lan on\|off 让本地网络在此期间仍可访问 |
| `kilobat uploads [--json]` | 当前正在大量上传的 App，包括速率、目前已发送的量以及已知总量时的剩余时间，还有暂缓到稍后发送的上传 |
| `kilobat uploads hold <app> [--until unmetered\|fast\|fast:<Mbps>\|2h\|manual]` | 暂缓某个 App 的上传，直到不限流量或更快的网络、一段时间后，或直到你恢复它（Pro）；uploads resume <app> 会放行 |
| `kilobat settings [name [value] ]` | 读取或更改设置，例如 new-apps（allow、ask 或 block）、apple-software、auto-travel、pause-updaters、kill-switch、awake-on-power、public-ip（默认关闭）、speed-streams、alerts 和 menu-bar |
| `kilobat verdict <host> [--app <id>] [--port N] [--incoming] [--json]` | Kilobat 允许或阻止连接的原因：所有匹配规则按过滤器的检查顺序排列，显示决定结果的规则和更改各规则的命令；verdict --app <id> 查看应用自身的规则 |
| `kilobat verdict --blocked [1…50] [--json]` | 最近被阻止的尝试背后的规则，按过滤器阻止时的记录显示 |
| `kilobat approvals [--json]` | 在询问新应用模式下等待批准的应用，附签名者和目标地址 |
| `kilobat approve\|deny <app-id> [--minutes 1…1440]` | 立即阻止等待中的应用，或请用户在 Kilobat 中确认允许 |
| `kilobat block-host\|unblock-host <domain\|IP\|CIDR> [--app <id>]` | 为所有应用或单个应用阻止一个域名（含子域名，也接受 *.example.com）、IP 或地址段 |
| `kilobat quit <PID> [--force]` | 退出进程 |

### 初始设置

|  |  |
|---|---|
| `kilobat open` | 打开 Mac 应用 |
| `kilobat doctor` | 检查应用、网络过滤器和监控 |
| `kilobat completion [zsh\|bash\|fish]` | 输出 shell 补全脚本 |
| `kilobat mcp` | 通过 stdio 为 AI 智能体运行 MCP 服务器 |
| `kilobat update` | 更新通过 Homebrew 安装的版本 |

### 进阶

|  |  |
|---|---|
| `kilobat destinations [--pid PID] [--json]` | 观察到的进程套接字 |
| `kilobat devices [--all] [--bonjour] [--json]` | 网络中的设备，标明新增、已知、未知或已忽略，以及类型和 Kilobat 的判断把握；--all 加入目前不在的设备 |
| `kilobat devices name <MAC> <name>` | 为设备命名 |
| `kilobat devices mark <MAC> mine\|unknown\|ignored` | 为新设备作答，和 App 通知里一样 |
| `kilobat devices type <MAC> <type>\|auto` | 设置设备类型（camera、doorbell、tv、speaker、printer、plug、hub、console、phone、computer、drone、router、nas…）；auto 恢复 Kilobat 的判断 |
| `kilobat household [--json]` | 在 App 中配对的 Mac 以及每台当前的流量；配对只能在 App 中进行 |
| `kilobat smarthome [--json]` | Thread 网络和边界路由器、Matter 和 HomeKit 设备，以及网络是否为 Matter 准备就绪；只读 |
| `kilobat trace <host> [--rounds 2…10] [--json]` | 最多 12 跳的路由探测；--rounds 会多次追踪，并显示每一跳的丢包和延迟 |
| `kilobat route-history --host <host> [--json]` | 到某个主机的所有已存追踪，像 mtr 一样逐跳汇总：丢包、最佳、平均、最差、路由变化以及延迟从哪里开始 |
| `kilobat http-check <URL> [--json]` | DNS、连接、TLS 和首字节耗时 |
| `kilobat dns-benchmark` | 解析器耗时 |
| `kilobat lan-test <server> [--reverse] [--json]` | 对运行 iperf3 -s 的设备进行 5 秒 iperf3 测试；需要 iperf3，Kilobat 不会替你安装 |
| `kilobat interfaces [--json]` | 物理接口和 VPN 计数器，分开显示 |
| `kilobat capture <interface> <file.pcap>` | 有限时长的数据包捕获 |
| `kilobat connection-rule allow\|block <app> <host> [port]` | 保存目标规则 |
| `kilobat blocklist status\|import <path>\|clear` | 管理域名阻止列表 |
| `kilobat wake <MAC-address>` | 发送网络唤醒（Wake-on-LAN）数据包 |
| `kilobat spots [save <name>\|remove <id>]` | 已存的 Wi-Fi 位置 |
| `kilobat outages / speed-history [--days N]` | 以 JSON 格式输出记录的断网事件和速度测试 |

## 脚本与 JSON

通过管道输出时会自动切换为 JSON，脚本永远不用解析给人看的排版。也可以传入 `--json` 明确指定。

```
kilobat diagnose | jq .health            # "good"、"degraded"、"poor" 或 "unknown"
kilobat status --watch --json             # 每秒输出一行，每行一个 JSON 对象
kilobat report --summary --days 7 --json  # 每日总量和用量最高的应用
kilobat report compare --total 40GB --period last-month --csv  # 与运营商的数值并列显示
```

设置 `NO_COLOR` 可关闭颜色。更改 DNS 需要管理员批准。