Library
Menu

btrzp:// URL Scheme

BetterZip registers the btrzp:// URL scheme so other apps can hand it work without launching it from Finder. Open a URL of the form btrzp://command/argument?files and BetterZip carries out the matching action. The Finder extension uses this internally for its right-click commands – the same URLs work from Terminal, AppleScript, web pages, automation tools, and browser bookmarklets.

URL anatomy

  • Host – the command: open, extract, compress, …
  • Path – the command’s primary argument: the file to open, the preset name, the destination folder, or the registration code.
  • Query – a list of file paths separated by semicolons (;). Each path must be percent-encoded; ; stays unescaped as a separator.

From a shell, open hands the URL to LaunchServices:

open "btrzp://default-extract?/Users/robert/Downloads/photos.zip"

Opening archives

open

Opens a single archive in BetterZip’s main window. The full file path goes in the URL path.

btrzp://open/Users/robert/Downloads/photos.zip

open-archives

Opens one or more archives. Paths are percent-encoded and joined by ; in the query.

btrzp://open-archives?/Users/robert/a.zip;/Users/robert/b.7z

view

Opens a single file from inside an archive. The archive path goes in the URL path, the in-archive path follows after a ;. The action it triggers (preview, open in external app, view in BetterZip) follows the Quick Look click action set in Settings.

btrzp://view/Users/robert/photos.zip;DCIM/IMG_0001.jpg

Extracting

default-extract

Extract the listed archives using the default extract preset.

open "btrzp://default-extract?/Users/robert/Downloads/photos.zip"

extract

Extract using a named extract preset. The preset name goes in the URL path (percent-encoded if it contains spaces or other special characters).

open "btrzp://extract/Photos%20to%20Desktop?/Users/robert/photos.zip"

extract-to

Extract to a specific folder. The destination folder goes in the URL path; the special value 1 means “next to the original archive.”

open "btrzp://extract-to/Users/robert/Desktop?/Users/robert/photos.zip"
open "btrzp://extract-to/1?/Users/robert/photos.zip"

test

Test the integrity of the listed archives without extracting them.

open "btrzp://test?/Users/robert/photos.zip;/Users/robert/backup.7z"

Compressing

default-compress

Compress the listed files with the default save preset.

open "btrzp://default-compress?/Users/robert/Documents/Project"

compress

Compress using a named save preset.

open "btrzp://compress/Encrypted%20ZIP?/Users/robert/Documents/Project"

add

Open the targeted archive and force-add the listed items to it. Useful for dragging files into an existing archive from automations.

open "btrzp://add?/Users/robert/photos.zip;/Users/robert/IMG_0002.jpg"

collect

Open BetterZip in Collect Mode, ready to receive items from anywhere on the system. Takes no arguments.

open "btrzp://collect"

Registration

register

Used to automatically import a license code into the app, e.g., from the registration email. The code goes in the URL path. Not available in the Setapp build.

btrzp://register/XXXX

Encoding rules

  • File paths in the query are percent-encoded and joined by ;. Slashes inside paths stay as /; spaces become %20.
  • Preset names and destination folders in the URL path are also percent-encoded.
  • The query separator is ;, not &, so file paths can contain ampersands without conflict.

Security & the local-origin token

Because any app – or a web page through the browser – can open a btrzp:// URL, the actions that write to disk or run tools on the named files are protected. These guarded commands are extract, default-extract, extract-to, compress, default-compress, add, test, and view. (open, open-archives, collect, and register are not guarded.)

When a guarded command arrives, BetterZip shows a confirmation dialog naming the files and destination, unless the URL carries a valid local-origin token. The token proves the request came from code running locally as you – something a remote web page cannot do, because it has no access to your local files.

BetterZip generates a random token on first launch and writes it to:

~/Library/Application Support/com.macitbetter.betterzip/url-token

Automation that runs locally (a shell script, a LaunchBar or Alfred action, a Dropzone action, a Service) can read that file and append the token as the URL fragment – after a #, following the query – to skip the confirmation:

token=$(cat "$HOME/Library/Application Support/com.macitbetter.betterzip/url-token")
open "btrzp://default-extract?/Users/robert/Downloads/photos.zip#$token"

The token is optional: a URL without it (or with a wrong one) still works – BetterZip just asks you to confirm first. The bundled LaunchBar and Dropzone templates already read and append it automatically. The Finder extension uses the same token via the shared app group.