Skip to the page
Scribble Pad Beta

Write your own right-click tools

A right-click tool is a small script in a folder. Scribble Pad gives it the text you selected, and puts what it prints under your text. Any language your Mac runs works.

How a tool works

  1. Select some text in a sheet (or point at a link) and right-click.
  2. The menu shows Scribble Pad's own items, a line, and then your tools that fit the text.
  3. Choose a tool. Scribble Pad runs the script, and gives it the text on standard input.
  4. What the script prints goes on new lines under your text, with the same indent. One ⌘ Z takes it away.

A tool is not part of the app, so a new tool needs no new version of Scribble Pad. The folder is read again on each right-click, so a new tool shows at once.

Make the folder

Tools live in one folder. Make it once, and open it, in Terminal:

mkdir -p "$HOME/Library/Application Support/Scribble Pad/Add-ons"
open "$HOME/Library/Application Support/Scribble Pad/Add-ons"

Your first tool

Save this text as count-words.sh in that folder:

#!/bin/sh
# name: Count Words
# input: selection
wc -w | tr -d ' '

Then let it run, in Terminal:

chmod +x "$HOME/Library/Application Support/Scribble Pad/Add-ons"/count-words.sh

Select a few lines in a sheet, right-click, and choose Count Words. The number shows under your text.

The lines at the top

The first lines of the script tell Scribble Pad what the tool is. They start with # or //. Only the first 20 lines are read.

LineWhat it does
name:The title in the menu. A file without it is not a tool.
input:selection (the selected text, the default) or link (the link you right-click).
show-when:Optional. A regular expression. The tool shows only when the text matches it.

The rules

  • The text comes in on standard input, as UTF-8.
  • Print nothing, and nothing changes. This suits a tool that opens another app.
  • Exit with a code other than 0, and nothing changes. The status line shows the first line of standard error.
  • After 5 seconds, or 10 MB of output, Scribble Pad stops the script.
  • Output with hidden control characters (other than tab) is refused, so none get into a sheet.
  • Homebrew tools work: /opt/homebrew/bin and /usr/local/bin are on the path.
  • A tool runs with your rights, like any script. Put only your own scripts in the folder.

More examples

Unix time to a date

Shows only when you select a 10-digit number.

#!/bin/sh
# name: Unix Time to Date
# input: selection
# show-when: ^[0-9]{10}$
read -r seconds
date -r "$seconds"

A link without tracking

Right-click a link with a ? or # in it. The clean link goes under the line.

#!/bin/sh
# name: Link Without Tracking
# input: link
# show-when: [?#]
sed 's/[?#].*//'

Open a link in Safari

It prints nothing, so the sheet does not change. Handy when Safari is not your default browser.

#!/bin/sh
# name: Open in Safari
# input: link
read -r link
open -a Safari "$link"

Sort lines, in Python

The same works in any language. This one needs Python 3 on your Mac.

#!/usr/bin/env python3
# name: Sort Lines
# input: selection
import sys
lines = sys.stdin.read().splitlines()
print("\n".join(sorted(lines, key=str.lower)))

A tool does not show?

  • The file must be executable (chmod +x), and it must have a name: line.
  • If it has a show-when: line, the text must match it.
  • The log says why a file was skipped. In Terminal:
/usr/bin/log show --last 10m --predicate 'subsystem == "local.scribblepad"'