outboundctl blocklist

outboundctl blocklist manages blocklist subscriptions: lists of destinations published online that Outbound downloads and turns into rules. Adding, removing and refreshing are subject to the edit policy.

Listing subscriptions

outboundctl blocklist list

One tab-separated line per subscription: the id, the action (deny or allow), the URL, the name, whether the list is pinned (pinned or unpinned), and when it was last fetched as an ISO-8601 date, or fetched never.

Subscribing

outboundctl blocklist add <https-url> [--pin <sha256>] [--name <name>]

The URL must be https; anything else is refused with exit 65. The command stores the subscription and prints its id; the running background agent checks for due lists every 60 seconds. Nothing is downloaded by the command itself.

–pin: the SHA-256 the downloaded bytes must match, 64 hexadecimal digits. An optional sha256: prefix is dropped, and case and surrounding space are ignored. A list whose bytes do not match its pin is never installed.

–name: a display name. Without it, or with a blank name, the list uses the URL’s host, falling back to the URL text.

Subscribing to the same URL twice fails with already subscribed to … and exit 1, and leaves the first subscription untouched.

Removing

outboundctl blocklist remove <uuid>

Unsubscribes and deletes the rules that came from the list. The subscription is removed first, then its rules, so a refresh already in flight cannot bring them back. An id that is not a subscription exits 1.

Refreshing

outboundctl blocklist update [<id>|--all]
outboundctl update-rule-groups [<id>|--all]

Both spellings do the same thing. With no argument or --all, every subscription is refreshed; with one id, that subscription is. Combining --all with an id is a usage error.

The command does not download anything. It leaves a request for the background agent, which performs the download and installs the new rules, and prints:

Blocklist update requested. Outbound refreshes them in the background.

If the agent is off because someone quit it, a second line says the update waits until it starts, and how to start it: open Outbound and click Start Agent. A request that sits unhandled for an hour is discarded, so run the command again after starting the agent.

Browsing entries

outboundctl blocklists entries <uuid|all> [--filter all|used|enabled|disabled|unapproved]
                                         [--query <text>] [--sort entry|lastUsed|useCount] [--descending] [--offset <cursor>]

Lists the entries of one list, or of every list with all, with how often each one decided a connection and when it last did. --filter shows only entries that have been used, are on, are off, or wait for review. --query searches the entries. Long results come in pages: pass the cursor the command prints to --offset for the next one.

Switching an entry off

outboundctl blocklist entry enable|disable <list-uuid> <entry> [--kind host|domain|address|network]

Turns one entry of a list off for every app, or back on. The entry stays as you set it when the list refreshes. The change goes through the same approval as in the app.

Reviewing new entries

outboundctl blocklists new <uuid|all> [--query <text>] [--offset <cursor>]
outboundctl blocklists approve <uuid> [<entry>] [--kind host|domain|address|network]

When Mark new blocklist entries for review is on in Settings › Advanced, the entries a refresh added wait for review. blocklists new lists them; blocklists approve approves one entry, or every waiting entry of the list when you name none. Approving entries of an allow list asks for your usual approval.

Defaults and exit status

New subscriptions use action deny and a 24-hour refresh interval. For example, outboundctl blocklist add https://example.com/hosts.txt --name "Example list" stores a subscription.

Success exits 0. Invalid URLs or pins exit 65; bad syntax or malformed UUIDs exit 64. Missing subscriptions and file failures exit 1. Edit-policy refusals exit 77. Removing a subscription prints removed <uuid>. If deleting its rules then fails, the subscription is already gone and the command reports the failure.