---
title: "CLI reference | Kilobat Docs"
url: "https://kilobat.app/docs/cli"
description: "Every kilobat command, JSON output and scripting."
---

# CLI reference

Every kilobat command, JSON output and scripting.

## Commands

### Monitor

|  |  |
|---|---|
| `kilobat status [--watch] [--json]` | Live per-app traffic and session budget; a JSON snapshot, or a JSON-lines stream with --watch |
| `kilobat report [--csv\|--json] [--summary] [--days 1…365]` | Locally recorded usage history, or daily totals and top apps; CSV has one row per app |
| `kilobat report compare --total 40GB [--unit GB\|GiB] [--direction both\|download\|upload] (--from DATE --to DATE \| --period last-month) [--network NAME] [--json\|--csv]` | A router's or provider's figure beside what Kilobat recorded on this Mac for the same period, in the same unit, with the hours recorded, every gap and likely reasons for a difference |
| `kilobat health-history [--hours 1…720] [--json]` | Router, internet, jitter and DNS checks the app recorded over time |
| `kilobat proxy [routes [--app name] \| test] [--json]` | Proxy apps, the system proxy and their problems; which rule and node each app took; how fast each node answers |
| `kilobat vpn [--json]` | The VPN, whether DNS or IPv6 skip it, and the VPN kill switch's state |
| `kilobat vpn leaks [--json]` | Leak test: whether DNS, IPv6 or UDP (what WebRTC uses) goes around the VPN, each with the setting that fixes it; asks bash.ws, Cloudflare and a STUN server |
| `kilobat calls [--limit 1…200] [--json]` | After each call: how many times it froze and what caused it, from the reports the app writes |
| `kilobat remote [--limit 1…200] [--kind ssh\|mosh\|desktop] [--json]` | After each SSH, Mosh or remote desktop session: why typing lagged or the screen froze, and when Mosh would help |
| `kilobat stream [status\|check\|reports] [--json]` | OBS over its local WebSocket: whether it is live and dropping frames, a go-live check of your upload against its bitrate plus 30% (check [--bitrate <kbps>] [--measure\|--no-measure]), and the reports after each stream (reports [--limit 1…200]) |
| `kilobat cloud-gaming [status\|reports] [--limit 1…200] [--json]` | GeForce NOW, Xbox Cloud Gaming, Boosteroid, Amazon Luna and Shadow: the session now (ping, jitter, loss, bitrate, data, what is in the way) and the report after each, with when it stuttered and why |
| `kilobat overlay [--port 7171] [--target internet\|router\|cs2:fra\|host]` | A live ping overlay for OBS and other streaming apps, served on localhost until Ctrl-C; a game region such as cs2:fra pings that data center |
| `kilobat support-report [--hours 1…168] [--host h] [--include-sites] [--markdown\|--html] [--output f]` | A report for your provider or IT desk: findings, latency, outages and speed tests, without your network’s name or local addresses |
| `kilobat plan [--days 7…90] [--json]` | Speed tests against the plan you pay for on each network: the median, evenings beside the rest of the day, and how often a test got under half |
| `kilobat credit [--provider id] [--price n] [--month this\|last\|YYYY-MM] [--draft] [--json]` | The month’s outages beyond your router against your provider’s published credit rule, what they may qualify for, and a drafted claim; <code>credit providers</code> lists the rules |
| `kilobat week [--weeks-ago 0…12] [--json]` | The weekly digest: last week’s most notable outages, frozen calls, router, blocks and metered data, compared with the week before |
| `kilobat router [--all] [--json]` | Router check-up: its usual replies, loss and drops against the last three days, restarts and whether they helped, from the checks the app keeps |
| `kilobat router connect [fritzbox\|unifi\|mikrotik\|openwrt] [--json]` | Setup steps for the app’s Pro router connection; never takes credentials on the command line |
| `kilobat router devices [--json]` | The connected router’s clients, measured rates and today’s totals through the app; FRITZ!Box and other whole-home counters never imply a single device’s share; client counters may include LAN traffic |
| `kilobat router disconnect [--json]` | Forget the router for this network; the app removes its Keychain credential, or does so on its next start |
| `kilobat service-speed [--all] [--test <service>] [--list] [--json]` | Your own downloads from GitHub, iCloud, Steam, npm and more against the line, and when your provider’s route to one is slow; <code>--test</code> downloads up to 25 MB from one now |
| `kilobat hotspot [--all] [--carrier <id>] [--detect] [--json]` | On a phone hotspot: whether every download stops at a carrier’s hotspot cap, the measurements behind it and the carrier’s published rules; <code>hotspot carriers</code> lists them |
| `kilobat networks [forget <name>]` | Networks seen, with the profile, budget and data cost remembered for each |
| `kilobat networks cost <metered\|unmetered\|automatic> [name]` | Treat this network, or a named one, as metered or unmetered, or follow macOS again |
| `kilobat bandwidth [app] [hour\|day\|week\|month] [--back N] [--json]` | One app's sent and received bytes over an hour, day, week or month, with the peak; --back steps to earlier periods |
| `kilobat access-policy <bundle-id> [--json]` | The connections an app's developer declares in its Internet Access Policy, and why |

### Diagnose

|  |  |
|---|---|
| `kilobat diagnose [--json]` | Wi-Fi, router, internet, DNS and captive-portal checks with advice |
| `kilobat radar [--watch] [--json]` | Signal score and best-spot finder |
| `kilobat scan [--json]` | Nearby networks, channels, widths and security |
| `kilobat channels [--json]` | Congestion per channel and the least crowded one |
| `kilobat speedtest [--json] [--budget-mb 1…80] [--parallel]` | Cloudflare speed, loaded latency and call and streaming verdicts, 80 MB at most. One connection by default; --parallel opens four, as most speed-test sites do |
| `kilobat speed-compare [<test> <test>] [--json]` | What differed between two saved speed tests: network, time, server, connections, Wi-Fi band and signal, VPN, other traffic |
| `kilobat ip [--public] [--json]` | Where traffic leaves: the interface and any VPN, read on this Mac; --public also asks Cloudflare for your public IP and its registry country |
| `kilobat portal [open] [--json]` | Wi-Fi sign-in pages: a check now (open, sign-in page or offline, with the page’s address, query values redacted), whether this network wants a sign-in, logged you out or how long is left, and each network’s usual sign-in length; open opens the page in your browser |
| `kilobat stutter [--seconds 10…60] [--target router\|internet\|<host>] [--json]` | Ping every 50 ms to find the short latency spikes speed tests miss, when they happen and whether they repeat |
| `kilobat starlink [--hours 1…720] [--json]` | A Starlink dish on this network, read from it locally: state, ground-station ping, alerts, the sky map and which way it’s blocked, and outages split into your setup, Starlink’s network and dish restarts |
| `kilobat games [--game <game> \| --all \| --match] [--json]` | List the games Kilobat pings and the ones it can't, with why; with --game, ping each of that game's data centers (Valve relays, Epic ping servers, or the AWS and Azure regions it hosts in) five times and name the one closest to you; with --match, find and ping the server of the match you're playing, for any game, ready for the streaming overlay |
| `kilobat airdrop [status\|everyone\|contacts\|off] [--json]` | AirDrop visibility, the AirDrop link (AWDL) and what uses it; changing visibility opens System Settings |
| `kilobat bluetooth [--json]` | Bluetooth devices and whether they share 2.4 GHz with your Wi-Fi |
| `kilobat bluetooth audio [--json]` | While AirPods or other Bluetooth headphones play: what can make them crackle (2.4 GHz, AirDrop, a big download, a weak signal) and what to change, in order |
| `kilobat local [check] [--quick] [--json]` | Can I cast or print here? The Chromecasts, AirPlay receivers and printers that answer, whether the network may keep devices apart (never confirmed from discovery alone), a printer's or camera's own Wi-Fi, and what makes a cast stutter |
| `kilobat dns [automatic\|cloudflare\|google\|quad9\|flush]` | Read or set DNS, or flush the cache |
| `kilobat dns fastest [--all] [--json]` | The fastest DNS on this network, from the app’s quiet runs against Cloudflare, Quad9 and Google, with who runs each and where, and its answered lookups over 14 days |
| `kilobat dns auto on\|off [--network <name>]` | Pro: switch to the fastest DNS on joining, everywhere or on one network |
| `kilobat dns exclude\|include <resolver>` | Never time or pick a resolver, or add your own by IP address |
| `kilobat dns fallback <resolver>\|off` | The resolver to move to when the fastest fails, before your network’s own |

### Wi-Fi

|  |  |
|---|---|
| `kilobat wifi [status]` | Current network, signal, channel and width, link rate, Wi-Fi standard, security and transmit power |
| `kilobat wifi on\|off\|restart\|disconnect` | Control Wi-Fi power and the connection |
| `kilobat wifi join <name> [--password-stdin]` | Join a saved network, or a new one |
| `kilobat wifi known` | Saved networks in order of preference |
| `kilobat wifi password\|share <name>` | Show a saved password, or a QR code to scan with a phone |
| `kilobat wifi nodes [name <node> <name>] [--json]` | Mesh nodes or access points of this network, which one the Mac is on, and whether a much closer one is in range; name one, such as Office |
| `kilobat wifi reconnect [--json]` | Move to the closer node, then say where the Mac ended up |
| `kilobat low-latency on [--for 15m\|1h\|2h] [--until-quit <app>]` | Pause AirDrop and AWDL during calls and games: 15 minutes by default, up to 4 hours, or until an app quits |
| `kilobat low-latency off` | Restore AirDrop and AWDL, also for a pause started in the app |

### Awake & agents

|  |  |
|---|---|
| `kilobat awake [--display]` | Keep the Mac awake until Ctrl-C; closing the lid still sleeps it unless you add --lid-closed |
| `kilobat awake --lid-closed [--for 2h\|--until-quiet\|-- <command>]` | Keep running with the lid closed too, 8 hours at most, through the app’s power helper; needs Allow running with the lid closed in Settings |
| `kilobat awake --for 90m\|2h\|45s` | Stay awake for a while |
| `kilobat awake --until-quiet [--app <id>] [--quiet 1…60]` | Stay awake until downloads or one app go quiet, below 16 KB/s for 3 minutes by default |
| `kilobat awake -- <command> [args]` | Stay awake while a command runs, then report the data its processes moved and exit with its status |
| `kilobat awake --while-frontmost <app> [--display] [--for 2h]` | Stay awake only while that app is in front, for reading or presenting. Switching away lets the Mac sleep; it ends when the app quits, at 20% battery or after --for. --display keeps the screen on too |
| `kilobat settings awake-on-power on\|off` | The app stays awake whenever the power adapter is in and lets the Mac sleep again when it comes out |
| `kilobat settings keep-screen-on on\|off` | Keep the screen on too for everything the app keeps awake: timers, downloads, agents, the app in front and plugged in |
| `kilobat sessions [--days N] [--json]` | Awake sessions and AI agent runs the app recorded, with data used and network changes |
| `kilobat agent-log [--all] [--since 2h\|3d\|date] [--agent claude] [--flagged] [--json]` | Every host an AI agent and the commands it started contacted, with bytes and flags: the latest session, or the agent's own when run from it. Recorded by the app with Pro |
| `kilobat history forget <host> [--subdomains] [--json]` | Remove a host from blocked attempts, the agent network log, agent-run destinations and Protection notification memory |
| `kilobat history clear --hour\|--today\|--all [--json]` | Clear those host histories for the last hour, since midnight or entirely; future activity can be recorded again |
| `kilobat agent-log --watch [--agent claude] [--flagged] [--json]` | Records the same live in this terminal, without the app; nothing is saved |
| `kilobat protect [status\|on\|off\|update] [--threats\|--trackers\|--agents] [--json]` | Protection: block known malware, phishing and scam hosts (Pro), trackers in apps (free, off by default) and the agent guard (Pro); update downloads the lists now |
| `kilobat protect check <host> [--json]` | Whether a host is on a threat or tracker list, which one, and whether Kilobat blocks it; exits 1 if it does |
| `kilobat protect allow\|unallow <host>` | Let a site and its subdomains past every Protection list, or undo it |
| `kilobat agent-event <start\|working\|waiting\|done\|failed> [--agent name] [--stdin-json\|--json-arg]` | For an agent's hooks: tells the app a run started, waits for you or is done. Silent, always exits 0 |
| `kilobat why <url\|host> [--app <id>] [--proxy <url>] [--context container\|vm\|remote\|provider] [--failed-at <time>] [--error <text>] [--json]` | Find the layer that stops a connection: network and interface, proxy and the app's own proxy, DNS, Kilobat rules, IPv4 and IPv6, TLS, the server and each redirect, and whether this network blocks it or the service refuses your region. Requests the exact URL; output hides query values. Also kilobat doctor <url\|host> |
| `kilobat down [service\|host…] [--all] [--list] [--json]` | Is it them or me? What the public status pages of Slack, Zoom, GitHub, Claude, OpenAI and about seventy other services report now, and whether each connects from here: blocked on this network, or not available in your region; with no service, those of the apps running on this Mac |
| `kilobat explain <process\|host…> [--process name --host name] [--json]` | What a macOS process or host is, how much traffic is normal, whether blocking it is safe and what breaks, from Kilobat's own database on this Mac. The facts Kilobat has for anything it doesn't know |
| `kilobat conditions [--json]` | Metered, Low Data Mode, VPN, latency, battery and heat, whether the lid may close, with advice for long runs |

### Control

|  |  |
|---|---|
| `kilobat profile [travel\|work\|unrestricted]` | List or select a profile |
| `kilobat allow\|block <bundle-id> [--minutes 1…1440] [--profile name]` | Save an app rule, optionally temporary or for another profile |
| `kilobat reset <bundle-id> [--profile name]` | Remove an app's rule so it follows the default |
| `kilobat rules [--profile name] [--json]` | A profile’s rules |
| `kilobat limit [GB] [--cycle session\|daily\|weekly\|monthly] [--reset-day N] [--alert 50,80,100]` | Read or set this network’s data budget, when it starts over and when it notifies |
| `kilobat quota <bundle-id> <GB> [--upload] [--all-networks]` | Limit one app’s data per budget cycle; quota <bundle-id> --remove takes it off |
| `kilobat quota --list [--json]` | App quotas with what each used this cycle |
| `kilobat pack [status] [--json]` | Data packs such as a travel eSIM, with what is left and the day each runs out at the last three days’ pace |
| `kilobat pack add <GB> <days\|YYYY-MM-DD> [--network <name>] [--name <label>] [--start YYYY-MM-DD]` | Add a data pack on this network, on networks Kilobat has seen, or on any network whose name contains some text |
| `kilobat pack correct <GB-left> [--pack <name>]` | Set what the carrier’s app says is left, since Kilobat counts this Mac only |
| `kilobat pack end [--pack <name>]` | End a data pack now; it stays in the history |
| `kilobat updaters [--json]` | Updaters paused on metered networks, the update bytes that still got through on this network, and the apps that update from inside themselves |
| `kilobat updaters on\|off` | Pause updater helpers such as Google Updater and macOS Software Update while the network is metered (on by default); the apps keep working |
| `kilobat settings kill-switch on\|off` | Pro: block new connections whenever the VPN is down; kill-switch-lan on\|off keeps the local network reachable meanwhile |
| `kilobat uploads [--json]` | Apps uploading a lot right now, with the rate, what they sent so far and the time left when the total is known, and the uploads held for later |
| `kilobat uploads hold <app> [--until unmetered\|fast\|fast:<Mbps>\|2h\|manual]` | Hold an app’s upload until an unmetered or faster network, for a while, or until you resume it (Pro); uploads resume <app> lets it go |
| `kilobat settings [name [value] ]` | Read or change settings such as new-apps (allow, ask or block), apple-software, auto-travel, pause-updaters, kill-switch, awake-on-power, public-ip (off by default), speed-streams, alerts and menu-bar |
| `kilobat verdict <host> [--app <id>] [--port N] [--incoming] [--json]` | Why Kilobat allows or blocks a connection: every rule that matches, in the order the filter checks them, the one that decides and the command that changes each; verdict --app <id> for an app's own rules |
| `kilobat verdict --blocked [1…50] [--json]` | The rules behind the latest blocked attempts, as the filter recorded them when it blocked |
| `kilobat approvals [--json]` | Apps waiting for approval while new apps are asked about, with signer and destinations |
| `kilobat approve\|deny <app-id> [--minutes 1…1440]` | Block a waiting app at once, or ask the person to confirm allowing it in Kilobat |
| `kilobat block-host\|unblock-host <domain\|IP\|CIDR> [--app <id>]` | Block a domain (subdomains included, *.example.com accepted), an IP or a range for every app, or for one app |
| `kilobat quit <PID> [--force]` | Quit a process |

### Setup

|  |  |
|---|---|
| `kilobat open` | Open the Mac app |
| `kilobat doctor` | Check the app, network filter and monitoring |
| `kilobat completion [zsh\|bash\|fish]` | Print a shell completion script |
| `kilobat mcp` | Run the MCP server for AI agents over stdio |
| `kilobat update` | Update a Homebrew install |

### Expert

|  |  |
|---|---|
| `kilobat destinations [--pid PID] [--json]` | Observed process sockets |
| `kilobat devices [--all] [--bonjour] [--json]` | Devices on your network, each new, known, unknown or ignored, with its type and how sure Kilobat is; --all adds ones that aren’t here now |
| `kilobat devices name <MAC> <name>` | Name a device |
| `kilobat devices mark <MAC> mine\|unknown\|ignored` | Answer for a new device, as the app’s alert does |
| `kilobat devices type <MAC> <type>\|auto` | Set a device’s type (camera, doorbell, tv, speaker, printer, plug, hub, console, phone, computer, drone, router, nas…); auto goes back to Kilobat’s reading |
| `kilobat household [--json]` | Macs paired in the app and what each moves now; pairing stays in the app |
| `kilobat smarthome [--json]` | Thread networks and border routers, Matter and HomeKit devices, and whether the network is ready for Matter; read-only |
| `kilobat trace <host> [--rounds 2…10] [--json]` | Bounded 12-hop route probe; --rounds traces several times and shows each hop’s loss and delay |
| `kilobat route-history --host <host> [--json]` | Every saved trace to a host, hop by hop like mtr: loss, best, average, worst, route changes and where delay starts |
| `kilobat http-check <URL> [--json]` | DNS, connect, TLS and first-byte timing |
| `kilobat dns-benchmark` | Resolver timings |
| `kilobat lan-test <server> [--reverse] [--json]` | Five-second iperf3 test to a device running iperf3 -s; needs iperf3, which Kilobat never installs |
| `kilobat interfaces [--json]` | Physical and VPN counters, separately |
| `kilobat capture <interface> <file.pcap>` | Bounded packet capture |
| `kilobat connection-rule allow\|block <app> <host> [port]` | Save a destination rule |
| `kilobat blocklist status\|import <path>\|clear` | Manage a domain blocklist |
| `kilobat wake <MAC-address>` | Send a Wake-on-LAN packet |
| `kilobat spots [save <name>\|remove <id>]` | Saved Wi-Fi spots |
| `kilobat outages / speed-history [--days N]` | Recorded outages and speed tests as JSON |

## Scripting and JSON

Output switches to JSON automatically when piped, so scripts never parse the human layout. Pass `--json` to be explicit.

```
kilobat diagnose | jq .health            # "good", "degraded", "poor" or "unknown"
kilobat status --watch --json             # one JSON object per line, every second
kilobat report --summary --days 7 --json  # daily totals and top apps
kilobat report compare --total 40GB --period last-month --csv  # beside your provider's figure
```

Set `NO_COLOR` to turn off colors. Changes to DNS require administrator approval.