Links

Everything pal can do has a pal:// link and a pal command that say the same thing. A link works from anywhere that opens a URL: a browser (the store's "Open in pal" button), a bookmark, a Shortcuts action, skhd or a Hyprland bind (open pal://toggle, xdg-open pal://toggle), a script, a Stream Deck. The command works from a shell. Both reach the running pal; with none running they start it and apply once the panel has loaded.

open pal://open/emoji/emoji?q=smile        # macOS
xdg-open 'pal://open/emoji/emoji?q=smile'  # Linux
pal open emoji/emoji -q smile              # the same, from a shell
pal link 'pal://open/emoji/emoji?q=smile'  # a link as written
pal link --list                            # every route

Copy deep link (⌘⇧C, in the ⌘K panel under Link) is on every row, inside every palette and view, and on a form: it copies the link for what is under the cursor and the HUD says Copied pal://.... That is the quickest way to get one right.

The grammar

pal://<route>[/<part>...][?key=value&...]. Parts are percent-encoded (%20 or + is a space, %2F a slash inside an id). The first part is one of the routes below; anything else is an extension's name followed by a route that extension declares (pal://timer/start?duration=25m). A repeated key is an array. args (on run) is percent-encoded JSON. A link over 2048 bytes, a route that does not exist, or a missing parameter is one line in the HUD (pal: unknown link, pal: text is required).

The routes

<ext>/<palette> are the extension's and the palette's names from its pal.json, as the palette's Copy deep link writes them (clipboard/history, emoji/emoji), not the one-word id the config file uses. A row's <id> is the extension's own, so a link keeps working across restarts.

pal's own rows (pal://commands/<id>): settings, settings-extensions, settings-features, settings-about, store, install (the install form), reload, refresh (list every palette again), updates (check for updates), install-update (install the release the check found), config-open, config-reveal, tips, docs, bug, diagnostics (copies them), theme (cycles it), history-clear (the search history), quit, restart, version (copies it).

Extension routes

An extension can declare routes of its own; the bundled ones:

A route an extension declares shows on its store page and in Settings > Extensions. pal call timer/start duration=25m name=tea is the command form; pal link --list prints the app's routes.

Examples:

pal call window-management/layout name=left_half   # a skhd bind
open 'pal://snippets/paste?name=sig'                 # a Shortcuts action
open -g 'pal://confetti?text=Deployed'               # at the end of a deploy script (-g: pal stays behind)
pal form quicklinks/quicklinks/create -a create name=GitHub url=https://github.com/search?q={query}
pal copy < notes.txt

What asks first

A web page can emit any of these, so what acts shows a card in the panel before it runs (Enter runs, Escape does not, 30 seconds then no):

• run, form, a bar action and an extension route name what they are about to do ("Run “Safari” from a link?", "“Start a timer” from a link? timer/start duration=25m");
• paste and open?url= ask too: a page must not type into the app in front or launch a file through pal unasked;
• install, update, remove and instance/add, instance/remove always ask: they fetch or delete code, or edit the config file.

What only shows something (open a palette, settings, hud, toast, confetti, copy, a bar popover) never asks.

deeplink_confirm under [general] (Configuration) tunes it: false turns every card off but the store's (a machine that scripts pal by link); a list of extension names, deeplink_confirm = ["timer", "quicklinks"], keeps the cards on except for links into those extensions (their run, form and routes; a name covers every instance of the extension, a key like "gmail@work" one instance). A route the extension declares with confirm: true (system's run) asks whatever the setting says.

The pal commands never ask: typing the command is the consent. So a keybind that runs pal call window-management/layout name=left_half just does it, while a bookmark to the same link asks (unless window-management is on the list).

Errors and exit codes

The outcome of a link is the HUD's: pal: unknown link, pal: no palette x/y, pal: no route x/y, pal: timer/start: duration is required, pal: <what the extension said>. The pal commands print a link they can refuse before sending (the grammar) to stderr and exit 2; a link that is handed over exits 0 at once, and what happened is on screen. pal quit and pal reload with no pal running print not running; every other command starts pal and applies once the panel is up.

Registration

macOS reads the scheme from the app's Info.plist when the .app is first seen in /Applications (or lsregister -f /path/to/pal.app); the deb and AppImage carry MimeType=x-scheme-handler/pal in their desktop entry. On macOS the link is an Apple Event to the app; on Linux it is pal pal://..., which the binary forwards to the running instance like a subcommand. A bare release binary on Linux (no desktop entry) needs one to be a handler: a ~/.local/share/applications/pal.desktop with Exec=/path/to/pal %u and MimeType=x-scheme-handler/pal;, then xdg-mime default pal.desktop x-scheme-handler/pal. A debug build on Linux writes that entry itself at startup; a tauri dev binary on macOS is not a bundle and cannot be a handler (the pal commands still work against it).

macOS activates pal as it hands a link over (a browser's click, open without -g); pal waits for that to settle before showing the panel, so the panel stays up. open -g keeps the app that opened the link in front, which is what a script wants for hud, copy or confetti.

Rendered from docs/links.md in the pal repo, 2026-09-30.