outboundctl history

Outbound records the connections it decided into a history you can read from the terminal, matching what the app shows in its connection lists. outboundctl history reads it with list, tail and export, and manages it with delete, retention, rotate-key and discard-unreadable.

outboundctl history list --since 1h --app Safari
outboundctl history tail --denied --follow
outboundctl history export --since 2026-10-01T09:00:00Z --format csv

Saved history is encrypted on your Mac, with its keys in the login Keychain, so outboundctl reads it through Outbound’s background agent. If the agent is off, these commands exit 69.

Dates

--since takes an ISO-8601 date, a full timestamp with or without fractional seconds or a bare day such as 2026-10-19, or, for list and tail, a duration back from now such as 10m, 1h or 7d. list and tail default to the last 24 hours; export requires --since. --until is optional and defaults to no end. Both ends of the range are inclusive. A value that does not parse, or a --since after --until, is a data error (exit 65).

history list and history tail

outboundctl history list [--since <date|10m>] [--until <date>] [--limit <n>] [filters]
outboundctl history tail [--since <date|10m>] [filters] [--follow [--heartbeat <seconds>]]

Both print one line per connection, oldest first: time, app, destination, port and protocol, direction, verdict, the deciding rule (or the reason when no rule decided) and the policy revision. An empty range prints No connections in that range. outboundctl log is short for history tail.

--limit caps the rows, from 1 to 10000 (the default). When there are more, outboundctl warns you to narrow the filters or use history export.

Filters match exactly and combine with AND:

Filter	Matches
--app <name>	One app, by name
--domain <host>	One website domain, exactly
--host <host>	One host
--country <code>, --continent <code>	The server’s ISO country code, or af, an, as, eu, na, oc or sa
--direction incoming|outgoing	Connection direction
--allowed, --denied, --verdict allowed|denied|blocked	The decision; denied includes answered alerts, timeouts and overloads
--owner <uid|name|unknown>	The process owner
--rule any|none|unapproved|<uuid>	The deciding rule

The same filters can be written as words, such as app:Example domain:example.com country:DE denied.

history tail --follow keeps reading new connections until the command’s timeout. With --output json it streams NDJSON, one object per connection, and --heartbeat <seconds> adds a heartbeat line at that interval while nothing arrives. Retained history is limited by the app’s recording settings and a 200 MiB disk cap, and a dropped-event marker shows where recording had a gap.

Destinations follow the disclosure policy in every format: website domains rather than full host names, and “address” for IP addresses.

history export

outboundctl history export --since <date> [--until <date>] [--format csv|jsonl]

Writes the range to standard output. The default format is csv; jsonl selects JSON Lines. Anything else for --format is a data error.

The columns, in order:

Column	Contents
time	ISO-8601 with fractional seconds
app	The app’s display name
signing id	The program’s signing identifier, blank when unknown
team	The signing team ID, blank when unknown
path	The app name rather than the full path, blank when unknown
remote	The website domain when known, otherwise “address”
port	The remote port
protocol	tcp, udp, icmp or any (including gap markers)
direction	outgoing, incoming or any (including gap markers)
verdict	allow, deny, ask-allow, ask-deny, timeout-allow, timeout-deny, overload-deny or dropped (a gap marker)
rule id	The deciding rule’s UUID, blank when the mode decided
reason	Why: rule, mode default, learned, strict-denied and similar
bytes in	Blank when unknown
bytes out	Blank when unknown

The CSV is RFC 4180: comma-separated, CRLF line endings, a header row, and fields quoted when they contain a comma, quote or line break. Values that a spreadsheet could run as a formula (starting with =, +, -, @, a tab or a return) are prefixed with an apostrophe unless they parse as numbers, because an app chooses its own name and signing identifier. JSON Lines writes one JSON object per line with the same column names as keys.

If the history files are damaged, the command fails with the reason instead of exporting a partial range that looks complete. bytes in and bytes out stay blank, because the command has no byte totals. In JSON Lines, every value is a string, including ports and byte columns.

Deleting saved history

outboundctl history delete --app <name-or-id> [--host <host>] --yes
outboundctl history delete --host <host> --yes
outboundctl history delete --domain <domain> --yes

Permanently deletes saved connection events for one app, one exact host, that app’s connections to that host, or a domain and its subdomains. Use --domain on its own. Without --yes, nothing is deleted: “Deleting saved history is permanent. Repeat with –yes to confirm. This does not hide traffic or remove rules.” The app’s lists update to match.

Deleting is separate from hiding. Hiding affects what you see, removing a monitor row clears its current counters, and deleting history removes saved events. None of them changes live traffic or rules.

Retention and keys

Command	What it does
history retention off|1|7|30	Sets how many days of history the signed-in user keeps. Turning recording off or shortening retention asks for administrator authorization before anything is deleted. If you cancel, the history and its setting are kept
history rotate-key	Rotates the history encryption key. Earlier keys stay in the login Keychain for recovery
history discard-unreadable --yes	Permanently discards history files that can no longer be read, and pending erase requests. Readable history is kept

Fixtures

The OUTBOUND_HISTORY_PATH environment variable points outboundctl at a history directory of its own, for tests and fixtures, instead of asking the agent.

Success exits 0. Unreadable history exits 1, and a refusal exits 77.