---
title: "CLI 參考 | Kilobat 說明文件"
url: "https://kilobat.app/zh-hant/docs/cli"
description: "所有 kilobat 指令、JSON 輸出與指令碼。"
---

# CLI 參考

所有 kilobat 指令、JSON 輸出與指令碼。

## 指令

### 監控

|  |  |
|---|---|
| `kilobat status [--watch] [--json]` | 即時的各 App 流量和工作階段預算；輸出 JSON 快照，或搭配 --watch 輸出 JSON Lines 串流 |
| `kilobat report [--csv\|--json] [--summary] [--days 1…365]` | 本機記錄的用量歷史，或每日總量與用量最多的 App；CSV 每個 App 一列 |
| `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]` | App 隨時間記錄的路由器、網際網路、抖動和 DNS 檢查 |
| `kilobat proxy [routes [--app name] \| test] [--json]` | 代理 App、系統代理伺服器及其問題；每個 App 走了哪條規則和哪個節點；每個節點的回應速度 |
| `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 和其他直播 App 用的即時 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]` | App 的 Pro 路由器連線設定步驟；絕不會透過命令列取得憑證 |
| `kilobat router devices [--json]` | 透過 App 查看已連接路由器的用戶端、測得的速度和今日總量；FRITZ!Box 等全家庭計數器不能說明單一裝置的占比；用戶端計數器可能包含 LAN 流量 |
| `kilobat router disconnect [--json]` | 忘記此網路的路由器；App 會移除其鑰匙圈憑證，或在下次啟動時移除 |
| `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]` | 單一 App 在一小時、一天、一週或一個月內傳送和接收的位元組數，以及尖峰值；--back 可往前回溯期間 |
| `kilobat access-policy <bundle-id> [--json]` | App 開發者在 Internet Access Policy 中宣告的連線，以及原因 |

### 診斷

|  |  |
|---|---|
| `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。預設一條連線；--parallel 會開四條，和大多數測速網站一樣 |
| `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]` | AirDrop 可見度、AirDrop 連結（AWDL）及使用它的項目；更改可見度會打開系統設定 |
| `kilobat bluetooth [--json]` | 藍牙裝置，以及它們是否與你的 Wi-Fi 共用 2.4 GHz |
| `kilobat bluetooth audio [--json]` | AirPods 或其他藍牙耳機播放時：可能造成雜音的因素（2.4 GHz、AirDrop、大型下載、訊號微弱）以及依序該改什麼 |
| `kilobat local [check] [--quick] [--json]` | 這裡可以投放或列印嗎？顯示回應的 Chromecast、AirPlay 接收器和印表機，網路是否可能隔離裝置（僅憑探索結果絕不確認）、印表機或相機本身的 Wi-Fi，以及投放卡頓的原因 |
| `kilobat dns [automatic\|cloudflare\|google\|quad9\|flush]` | 讀取或設定 DNS，或清除快取 |
| `kilobat dns fastest [--all] [--json]` | 根據 App 的背景靜默測試，顯示此網路上 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>` | 顯示已儲存的密碼，或顯示可用手機掃描的 QR Code |
| `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>]` | 在通話和遊戲時暫停 AirDrop 和 AWDL：預設 15 分鐘，最長 4 小時，或直到某個 App 結束 |
| `kilobat low-latency off` | 恢復 AirDrop 和 AWDL，在 App 中開始的暫停也適用 |

### 喚醒與代理程式

|  |  |
|---|---|
| `kilobat awake [--display]` | 讓 Mac 保持喚醒直到按下 Ctrl-C；除非加上 --lid-closed，否則闔上螢幕仍會讓它睡眠 |
| `kilobat awake --lid-closed [--for 2h\|--until-quiet\|-- <command>]` | 闔上螢幕也繼續執行，最長 8 小時，透過 App 的電源輔助程式；需要在「設定」中打開「允許闔上螢幕時執行」 |
| `kilobat awake --for 90m\|2h\|45s` | 保持喚醒一段時間 |
| `kilobat awake --until-quiet [--app <id>] [--quiet 1…60]` | 保持喚醒直到下載或某個 App 安靜下來，預設為低於 16 KB/s 持續 3 分鐘 |
| `kilobat awake -- <command> [args]` | 在指令執行期間保持喚醒，結束後回報其程序傳輸的資料量，並以該指令的狀態碼結束 |
| `kilobat awake --while-frontmost <app> [--display] [--for 2h]` | 只在該 App 位於最前面時保持喚醒，適合閱讀或簡報。切換到別的 App 時 Mac 就能睡眠；App 結束、電量剩 20% 或超過 --for 時結束。--display 會讓螢幕也保持開啟 |
| `kilobat settings awake-on-power on\|off` | 接上電源轉接器時 App 一律保持喚醒，拔掉後讓 Mac 恢復睡眠 |
| `kilobat settings keep-screen-on on\|off` | 凡是 App 保持喚醒的情況，螢幕也一併保持開啟：計時、下載、代理程式、最前面的 App 和插電時 |
| `kilobat sessions [--days N] [--json]` | App 記錄的喚醒工作階段和 AI 代理程式執行，附用量和網路變化 |
| `kilobat agent-log [--all] [--since 2h\|3d\|date] [--agent claude] [--flagged] [--json]` | AI 代理程式及其啟動的指令連過的每台主機，附位元組數和標記：顯示最近一次工作階段；由代理程式執行時，顯示它自己的工作階段。由 App 搭配 Pro 記錄 |
| `kilobat history forget <host> [--subdomains] [--json]` | 從遭阻擋的嘗試、AI 代理程式網路記錄、代理程式執行的目的地和防護通知記錄中移除主機 |
| `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]` | 給代理程式的 hook 使用：告訴 App 某次執行已開始、正在等待你，或已完成。不會輸出任何內容，一律以 0 結束 |
| `kilobat why <url\|host> [--app <id>] [--proxy <url>] [--context container\|vm\|remote\|provider] [--failed-at <time>] [--error <text>] [--json]` | 找出阻止連線的環節：網路和介面、代理伺服器及 App 本身的代理伺服器、DNS、Kilobat 規則、IPv4 和 IPv6、TLS、伺服器及每次重新導向，以及是此網路封鎖還是服務拒絕你所在的地區。要求確切的 URL；輸出隱藏查詢值。也可使用 kilobat doctor <url\|host> |
| `kilobat down [service\|host…] [--all] [--list] [--json]` | 是服務的問題還是我的問題？查看 Slack、Zoom、GitHub、Claude、OpenAI 及約 70 項其他服務的公開狀態頁面目前回報，以及各服務能否從此處連線：遭此網路封鎖，還是在你所在地區無法使用；不指定服務時檢查此 Mac 正在執行的 App |
| `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]` | 儲存 App 規則，可設為暫時規則或用於其他設定檔 |
| `kilobat reset <bundle-id> [--profile name]` | 移除 App 的規則，讓它改用預設處理 |
| `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]` | 限制單一 App 每個預算週期的流量；quota <bundle-id> --remove 可以取消 |
| `kilobat quota --list [--json]` | 各 App 的配額，以及本週期已使用的量 |
| `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>]` | 設定電信業者 App 顯示的剩餘量，因為 Kilobat 只統計此 Mac |
| `kilobat pack end [--pack <name>]` | 立即結束流量包；它會保留在歷史記錄中 |
| `kilobat updaters [--json]` | 在計量網路上暫停的更新程式、在這個網路上仍溜過去的更新位元組數，以及從 App 內部自行更新的 App |
| `kilobat updaters on\|off` | 在網路計量時暫停 Google Updater 和 macOS 軟體更新等更新輔助程式（預設開啟）；App 本身照常運作 |
| `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> 查看 App 本身的規則 |
| `kilobat verdict --blocked [1…50] [--json]` | 最近遭阻擋的嘗試背後的規則，依過濾器阻擋時的記錄顯示 |
| `kilobat approvals [--json]` | 在詢問新 App 模式下等待核准的 App，附簽署者和目的地 |
| `kilobat approve\|deny <app-id> [--minutes 1…1440]` | 立即阻擋等待中的 App，或請使用者在 Kilobat 中確認允許它 |
| `kilobat block-host\|unblock-host <domain\|IP\|CIDR> [--app <id>]` | 對所有 App 或單一 App 阻擋網域（包含子網域，也接受 *.example.com）、IP 或網段 |
| `kilobat quit <PID> [--force]` | 結束程序 |

### 安裝與設定

|  |  |
|---|---|
| `kilobat open` | 打開 Mac App |
| `kilobat doctor` | 檢查 App、網路過濾器和監控 |
| `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 的裝置做五秒的 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  # 每日總量與用量最高的 App
kilobat report compare --total 40GB --period last-month --csv  # 與供應商的數值並列顯示
```

設定 `NO_COLOR` 可以關閉顏色。更改 DNS 需要管理者核准。