Skip to main content

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​

CommandWhat it does
tinyshield statusVersion, license, connection mode, network extension, and rule counts
tinyshield mode [allow-all|require-approval|block-all]Show or switch the connection mode
tinyshield pending listApps 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 treeThe main window's list as a tree
tinyshield countriesCountries apps connected to, as on the map
tinyshield recently-blocked [--clear]The latest blocked connections
tinyshield bandwidth [--timeframe day] [--app Safari] / tinyshield liveData 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 --yesDelete 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 --json to any command for machine-readable output.
  • Add --no-launch to fail instead of opening TinyShield.
  • Exit codes:
CodeMeaning
0Success
1The command failed. pending wait also exits 1 when TinyShield isn't in Require Approval mode
3Not found. pending wait also exits 3 when nothing asked before the timeout
4TinyShield PRO is required
69TinyShield 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.