outboundctl prefs

outboundctl prefs reads and writes the same settings the app’s Settings windows own, one key at a time, from scripts or a terminal. Reading does not go through the edit-policy gate; the files must still be readable. prefs set goes through the edit policy, and it refuses a change that would loosen protection, because the command line cannot show you the approval dialog the app would.

outboundctl prefs list
outboundctl prefs get <key>
outboundctl prefs set <key> <value>

Reading settings

prefs list prints one line per key: the key, its current value and its type, tab separated, sorted by key.

alert-detail-level  compact  string
alert-timeout  60  integer
…

prefs get <key> prints just the value. An unknown key is a data error (exit 65) whose message lists every valid key. Boolean values are written true or false in output; when setting them, true, yes, on and 1 all mean true, and false, no, off and 0 mean false, case-insensitively.

The keys

Key	Type	Values	Default	What it is
mode	string	ask, learn, strict; aliases alert, silentAllow, silentDeny	alert if no settings file exists; the app initialises new setups to learn	The firewall mode. Your organisation can force it, in which case it cannot be changed here. Output uses the filter’s names: alert, silentAllow or silentDeny.
timeout-action	string	allow, deny	allow	The default for unanswered alerts; Strict mode still denies. See unanswered connections.
app-absent-action	string	allow, deny, same	same	The default for connections needing a decision while the app is absent. same means the timeout action; a program with neither a signing identity nor an executable path is denied.
alert-timeout	integer	15 to 120 seconds	60	How long a paused TCP connection waits for an answer.
require-approval	bool	true, false	true	Changes that loosen protection need approval with Touch ID or the login password.
verify-hostnames	bool	on, off	on for new installs; off after an upgrade until you turn it on	Allows by host or domain apply only when Outbound’s DNS records confirm the name. Turning it off loosens protection, so it asks for approval.
hide-my-connections	bool	true, false	false	Hide your connections from other users of this Mac. See below.
allow-scripted-alerts	bool	true, false	false	Let connection alerts accept clicks and key presses that other software posts. Off by default; changing it needs administrator authorization. See below.
disable-alerts	bool	true, false	false	Silence alerts (Ask mode then allows by default). Your organisation can force this.
notify-approval	bool	true, false	true	Notifications for decisions waiting for you.
notify-operational	bool	true, false	true	Notifications for operational problems.
notify-security	bool	true, false	true	Notifications for security events.
notify-rules	bool	true, false	true	Notifications for rule activity.
notify-unapplied-answers	bool	true, false	true	A notification when an answer to an alert cannot be applied.
notify-timeouts	bool	true, false	the notify-rules value	A notification when an unanswered alert’s timeout action is saved as a rule.
notify-rule-effects	bool	true, false	true	Notifications from rules you set to notify when they decide a connection. Turning it off silences all of them.
notify-profile	bool	true, false	true	Notifications when a known network switches the profile.
notify-list-success	bool	true, false	false	Notifications when a blocklist refresh installs new contents.
notify-list-failure	bool	true, false	true	Notifications when a blocklist refresh fails.
notify-review	bool	true, false	true	A notice, at most every ten minutes, when connections are waiting in Review.
notify-os-update	bool	true, false	true	A notice when connections were denied while macOS was installing an update.
warn-when-filter-off	bool	true, false	true	The menu bar item warns when the filter is off.
flash-on-block	bool	true, false	false	The menu bar item flashes when a connection is blocked.
count-local-traffic	bool	true, false	false	Count local traffic in the menu bar figures. The choice is remembered, but process-level accounting cannot split local bytes from internet bytes, so it does not change the totals yet.
history-capacity	integer	1,000 to 50,000	5,000	How many distinct connections the Network Monitor’s live list keeps.
auto-update-geo	bool	true, false	true	Update the country database automatically.
alert-detail-level	string	compact, full	compact	How much detail an alert shows at once. See alert details.
return-escape	bool	true, false	true	Answer Allow with Return and Block with Escape.
data-rate-unit	string	bytes, bits	bytes	The unit data rates are shown in.
mark-new-rules	bool	true, false	false	Mark newly added user rules as unapproved.
mark-new-blocklist-entries	bool	true, false	false	Mark new blocklist entries for review.
approve-on-select	bool	true, false	true	Clear a rule’s unapproved mark when you select it in the rules list.
extra-local-ranges	list	IPv4 or IPv6 CIDR networks, comma separated	empty	Extra address ranges counted as local, such as 10.0.0.0/8.
rule-sounds	bool	on, off	on	Sounds when rules decide connections.
rule-sounds-muted-until	date	1h, off	off	1h mutes rule sounds for an hour; off resumes them. Reading it prints the end of the mute as a date, or off.

rule-sounds and rule-sounds-muted-until belong to the signed-in user, so prefs list leaves them out under sudo. They accept --dry-run, which prints the change without making it.

Settings the filter confirms

hide-my-connections and allow-scripted-alerts are enforced by the filter, so outboundctl changes them through Outbound’s background agent, and a change counts only when the filter confirms it (“Confirmed by Outbound.”). Changing allow-scripted-alerts either way needs administrator authorization, as it does in Settings › Security. These two keys do not take --dry-run, --no-wait or --plan. If the agent is off, the command exits 69; if Outbound does not authorize the change, it exits 77.

Changing a setting

After the edit-policy check, prefs set <key> <value> validates the value. A value of the wrong shape is a data error (exit 65) whose message states the accepted forms, for example alert-timeout must be a number of seconds from 15 to 120 or mode must be ask, learn or strict. An invalid extra-local-ranges entry names the range and asks for an IPv4 or IPv6 CIDR.

Three further outcomes:

• A value your organisation forces is refused with exit 65: mode is set by your organization and cannot be changed from outboundctl. The same applies to disable-alerts.
• A change that would loosen protection is refused with exit 77: This change would loosen protection. Approve it in the Outbound app. When your organisation requires administrator approval, the message is Administrator approval required — approve it in the Outbound app; when it does not allow the change at all, Managed by your organization. The app compares the current settings against the proposed ones and asks for its usual approval where the change unblocks something. Before 1.3, this refusal exited 1.
• The edit policy refuses the change with exit 77, as for any modifying command.

Nothing is written when any of these refusals happen; the settings file keeps its previous contents.

Although prefs list labels alert-timeout as integer, setting it accepts fractional seconds in the 15 to 120 range. Reading it prints the truncated whole-second value. Mode names, allow/deny values, alert detail levels and data-rate units are case-insensitive; same must be lowercase.

For example, outboundctl prefs set flash-on-block true enables the flash. Successful set prints nothing and exits 0. Successful reads exit 0; unreadable settings or a store failure exit 1.