CLI
The commands. blackice help COMMAND, or blackice COMMAND --help, shows a command's options.
| Command | What it does |
|---|---|
blackice start [--config PATH] | Start filtering with ~/.config/blackice/blackice.toml, or PATH, asking a few questions first when there is no file. Run it again after editing the file or upgrading. A mode or answerer switched since the last start stays while the file is unchanged. |
blackice stop | Stop filtering and remove the network extension. Approvals are kept for the time they have left. To take them back, do it while blackice is on: blackice deny for one, blackice deny --all for all of them. |
blackice status | The mode, who answers, what waits, the denials of the last 10 minutes, the rules, the approvals and the timeout. |
blackice mode accept-all | ask | block-all [--agent NAME] | Switch the mode. --agent picks who answers in ask mode: fx, claude-code, codex, opencode or you; its hook must be in blackice.toml. Connections that wait go on if the new mode lets them through, and are dropped otherwise. |
blackice pending | What waits, then the denials of the last 10 minutes, whose connections are dropped without asking, each with the blackice approve line that lets it through (one per app for the denials), then the approvals, with the time each has left. |
blackice approve --app ID [--team TEAM] --host HOST… [--for 1h] [--script PATH | --save] | Let one app reach one or more hosts, and its waiting connections through, with one Touch ID. Repeat --host for up to 16 hosts. --for takes seconds, minutes or hours (30s, 10m, 1h), at most 24 hours; 1 hour by default. For an interpreter, --script approves only the script it runs, as pending shows it; without it, every script. With --save, also add a lasting [[allow]] rule for them to blackice.toml (or --config PATH); it counts from the next blackice start. |
blackice deny --app ID [--team TEAM] --host HOST [--script PATH] | Drop the app's waiting connections to that host and remove its approval. For 10 minutes its new connections there are dropped without asking. For an interpreter, --script denies only that script. |
blackice deny --all | Forget every approval, with one Touch ID. What waits keeps waiting, the denials of the last 10 minutes stay, and connections already let through go on. It works while blackice is on; off, the approvals it saved wait for the next start. |
blackice report [--last 1h] | What the filter dropped, by reason and app, over the last 30m, 2h and so on, up to 168h. In accept-all, what ask mode would have done. It reads macOS's log, which drops lines when the disk is nearly full; when the daemon logged more events than that log has connections asked about, it says the counts are low. No Touch ID. |
blackice agent connect NAME [--model NAME] [--config PATH] | Set fx, claude-code, codex or opencode up to answer in ask mode. See Let an agent answer. |
blackice agent install / uninstall | Start the daemon that runs the hooks, now and at each login, or stop it. agent connect starts it for you. |
blackice menu [--login on | off] | Show blackice in the menu bar until you quit it. --login on also opens it at each login, --login off stops that. |
blackice init [--config PATH] | Ask start's questions and write the file, without starting. It never replaces a file. |
blackice validate PATH | Check a blackice.toml without loading it. |
blackice version | The version and build. |
start, stop, mode, approve and deny ask for Touch ID, or your login password.
--team is the app's Team ID; leave it out for Apple's own code. --cdhash HEX, in place of --app, names code blackice knows only by its cdhash, signed ad hoc or run from a folder macOS protects, by the CDHash that codesign -dvvv prints and pending shows. --host takes a host name, or an IP address for a connection with no name, as pending shows it. Hooks do not use approve and deny: they answer on their last line.
An interpreter's answers are bound to its script. When an agent approves python running /opt/homebrew/bin/aws to sts.amazonaws.com, that covers the AWS CLI only: the same python running another script, or none (python3 -c), is asked about again, and pending lists the approval with the script it covers. pending writes each interpreter's approve line with --script when the script is a full path or -m module, and so do the menu's answers. Your answer without --script covers every script, and takes back the answers for each. npm has no script to show: node writes npm's title over its command line, so pending shows calls itself npm run build, and an answer for it covers node whenever no script can be read, whatever the title. The script name comes from the process's command line, so it only narrows what an answer covers: any program can start python with the AWS CLI's path.
Exit statuses: 0 done, 64 a usage error, 65 an invalid blackice.toml, 66 no file to read, 69 not the signed Blackice.app, or the filter did not answer, 70 a macOS request failed, 73 init found a file already there, 75 run it again (after restarting the Mac, when blackice says so), 77 Touch ID cancelled, 130 a setup stopped by Control-C.