Scripts and data files

The zero-code tier. A palette can be a data file (json, jsonl or toml) or a shell script that prints JSON lines, described by a small TOML table. No TypeScript. The scripts extension reads those tables from a pal v1 style config file and turns each into a palette named after its table, with the config id scripts-<name>.

Where the tables live

The extension reads the file named by its config setting, by default ~/.config/pal/config.toml, and takes every [palette.<name>] table in it. That default is pal's own config file, and pal's parser does not know a palette table: it keeps it and reports one "unknown key" warning in the Settings window (the editor's schema flags it too). The palettes still work. To keep the warning away, put the tables in their own file and point the extension at it:

[extensions.scripts]
config = "~/.config/pal/scripts.toml"

Relative paths inside that file (data, base, general.env_file) are resolved against the file's directory. ~ is expanded.

Coming from v1, the first launch does this for you: the v1 config is kept as config.v1.toml next to pal's, and config is set to it (the migration is described in Config).

A data-file palette

[palette.links]
auto_list = true
data = "links.json"       # relative to the config file's directory
icon_utf = "🔗"
actions = [
  { id = "open", title = "Open", action = "open", key = "url", primary = true },
  { id = "copy", title = "Copy link", action = "copy", key = "url", shortcut = "cmd+c" },
]

links.json, a JSON array (or one JSON object per line, or a TOML file whose first top-level array is the rows):

[
  { "name": "Home Assistant", "url": "http://ha.lan", "keywords": ["ha", "home"] },
  { "name": "Grafana", "url": "http://grafana.lan", "subtitle": "dashboards" },
  { "name": "GitHub", "url": "https://github.com", "icon_utf": "🐙" }
]

Every row is an item: name is the title, id defaults to name, subtitle and keywords are what they say. The palette's actions apply to every row: Enter opens url (the primary one goes first), ⌘C copies it, and both show in the action panel.

Without actions, the shorter form is one built-in action for every row:

[palette.links]
auto_list = true
data = "links.json"
auto_pick = true
default_action = "open"   # copy | open | cmd | type
action_key = "url"        # which row field the action takes

A script palette

A directory with a run.sh (or any command) that answers list and pick:

[palette.hosts]
base = "plugins/hosts"    # the directory, relative to the config file
requires = ["awk"]        # gated on the binary being on PATH
ttl = 3600                # reuse a listing for an hour

plugins/hosts/run.sh, listing the hosts in ~/.ssh/config and copying an ssh command line on pick:

#!/usr/bin/env bash
case "$1" in
  list)
    awk '/^Host / && $2 !~ /\*/ {
      printf "{\"id\":\"%s\",\"name\":\"%s\",\"icon_utf\":\"🖥\"}\n", $2, $2
    }' ~/.ssh/config
    ;;
  pick)
    printf '{"clipboard":"ssh %s"}\n' "$PAL_ID"
    ;;
esac

chmod +x it. list prints one JSON object per line; pick gets the picked row as JSON on stdin and every field as an environment variable (PAL_ID, PAL_NAME, ...), and prints a result envelope. Here the envelope copies the text, and the panel hides.

The palette table

Keys of [palette.<name>]. A plugin.toml in the base directory can carry the same keys; the table's values win where set.

The v1 file's [general] env_file = "..." names a .env-style file whose variables every script gets.

The script protocol

command list runs for a listing. For an input palette the query is on stdin and in PAL_QUERY, on every keystroke; otherwise stdin is empty (the null device) and there is no query. The chosen filter is PAL_FILTER. Stdout is JSON lines: one object per row, blank lines skipped, lines that are not a JSON object dropped. Stderr goes to pal's log.

Row fields:

Anything else rides along and comes back to pick as PAL_<KEY>.

command pick runs when a row is picked and the action is a pick one (the default when the row and the palette declare no actions, or an action without action). The row's JSON is on stdin, and every field is in the environment as PAL_<KEY> in upper case: strings as they are, anything else as JSON. PAL_ACTION is the action's id when it has one. Stdout is read for a result envelope: the whole output when it is one JSON object, else the last line. A line that is not JSON is ignored.

Every script also gets _PAL_CONFIG (the config file), _PAL_CONFIG_DIR, _PAL_PALETTE (the table's name) and _PAL_PLUGIN_CONFIG (the merged table as JSON), the variables from env_file, and the arguments of a drill-in (below). PATH is the app's plus ~/.local/bin, ~/.cargo/bin, /opt/homebrew/bin and /usr/local/bin, since the app under launchd has none of them.

A list or pick still running after timeout seconds (default 30) is sent SIGTERM with its whole process group, then SIGKILL two seconds later, and counts as failed.

Actions

An entry of the palette's actions or a row's:

A cmd action is waited on for up to 3 seconds so that a reload sees its work and an envelope it prints counts; a slower one runs on alone.

The result envelope

The JSON object a pick (or a cmd action, or an action plugin) prints. Any of these keys makes it an envelope:

No envelope: the panel hides.

ttl

Two things, one key. In the extension, a listing is cached for ttl seconds per query, filter and drill-in arguments, so a show or a drill-in inside that window does not run the script again. In the core, every listing is written to disk and restored at the next start; with a ttl the palette is listed again only when the restored listing is older than that (in a low-priority pass shortly after startup), without one on every start. A live palette relists on every show; with a ttl only when its last listing is older than that. ⌘R (Refresh) runs the script regardless.

A table without ttl takes the extension's ttl setting (default an hour) when that is above 0; a live table without one is exempt and keeps relisting on every show, since that is what live asks for.

preview: lazy detail

A row of a script palette can carry preview, a shell command. It runs only when the detail pane is open and the cursor has rested on the row; its stdout becomes the pane's markdown, and the row's variables are set as for pick. At most preview_max (default 4) run at once, each with a 10 second limit; the answer is cached per row until the palette lists again. preview_max = 0 turns previews off. Data-file rows never run previews.

Settings

[extensions.scripts]:

config, skip, v1_repo and ttl are read when the extension loads; after changing them, Settings > Restart extension host. timeout and preview_max apply to the next run.

Rendered from docs/scripts.md in the pal repo, 2026-09-16.