TinyShield Command Line Tool (tinyshield-cli)
tinyshield-cli controls TinyShield from Terminal and your own scripts. It
offers the same tools as the MCP server. For example, a build
script can approve the tools it runs, and a cron job can export your rules.
The command line is a TinyShield PRO feature. Turn it on with the MCP server in TinyShield › Settings › MCP.
1. Set it up
The tool is inside the app:
"/Applications/Tiny Shield.app/Contents/MacOS/tinyshield-cli" --help
Add an alias to your shell profile (~/.zshrc), as shown in Settings › MCP:
alias tinyshield='"/Applications/Tiny Shield.app/Contents/MacOS/tinyshield-cli"'
For the Setapp edition, use /Applications/Setapp/Tiny Shield.app instead.
If TinyShield isn't running, a command opens it in the background first.
2. Commands
| Command | What it does |
|---|---|
tinyshield status | Version, license, connection mode, network extension, and rule counts |
tinyshield mode [allow-all|require-approval|block-all] | Show or switch the connection mode |
tinyshield pending list | Apps waiting for approval, and where they tried to connect |
tinyshield pending allow <app>… / block <app>… | Allow or block waiting apps by name, bundle ID, path, pid, or ID (--all for every one) |
tinyshield pending wait [--timeout 60] | Wait until an app needs approval |
tinyshield decisions [list|allow|block|remove] | The App Connection Decisions of Require Approval mode |
tinyshield block-list [list|add|remove|enable|disable] | The Block List |
tinyshield allow-list [list|add|remove] | The Allow List |
tinyshield apps [--range 1h] [--status blocked] | Apps that used the network |
tinyshield app <app> or --pid <pid> | One app: signature, rules, activity, and bandwidth |
tinyshield connections <app> or --pid <pid> | The domains and IP addresses an app connected to |
tinyshield domain <domain> / tinyshield ip <ip> | Who connected to a domain or IP, and the rules that match it |
tinyshield tree | The main window's list as a tree |
tinyshield countries | Countries apps connected to, as on the map |
tinyshield recently-blocked [--clear] | The latest blocked connections |
tinyshield bandwidth [--timeframe day] [--app Safari] / tinyshield live | Data usage, and the current speed |
tinyshield settings [get|set <setting> on|off] | Settings such as block-list, dns, apple-programs, launch-at-login |
tinyshield export <file> / tinyshield import <file> [--replace] | Save or load your configuration |
tinyshield open <window> [--search text] | Show a TinyShield window, for example main, block_list or mcp_settings |
tinyshield clear-activity --yes | Delete the recorded network activity (rules are kept) |
tinyshield tools / tinyshield call <tool> '<json>' | List every tool, or call one with JSON arguments |
Run tinyshield <command> --help for every option.
In block-list add and allow-list add, a value that starts with /, ~
or ./ is an app or executable. Anything else is a domain, wildcard
(*.example.com), or IP address.
3. Examples
Approve the package manager a build uses, then run the build:
tinyshield pending allow ~/.local/bin/uv
uv pip install -r requirements.txt
Pre-approve tools before a long unattended job:
tinyshield allow-list add /opt/homebrew/bin/node ~/.local/bin/uv
Alert someone when an app needs approval:
if tinyshield pending wait --timeout 600 --only-new; then
osascript -e 'display notification "An app is waiting for approval" with title "TinyShield"'
fi
Block a tracker everywhere and check what it reached:
tinyshield block-list add '*.doubleclick.net'
tinyshield domain doubleclick.net --subdomains --range 7d
4. Scripting
- Add
--jsonto any command for machine-readable output. - Add
--no-launchto fail instead of opening TinyShield. - Exit codes:
| Code | Meaning |
|---|---|
0 | Success |
1 | The command failed. pending wait also exits 1 when TinyShield isn't in Require Approval mode |
3 | Not found. pending wait also exits 3 when nothing asked before the timeout |
4 | TinyShield PRO is required |
69 | TinyShield can't be reached: the server is off, or TinyShield isn't installed or running (with --no-launch) |
Decisions made from the command line show Command Line in TinyShield's Decisions list.