hs.pasteboard

Module for interacting with the macOS pasteboard (clipboard)

The macOS pasteboard is "rich" — a single clipboard operation can carry multiple representations of the same content for different applications to consume. For example, text copied from a web browser may carry plain text, HTML, and RTF representations simultaneously.

Basic Usage

// Read and write plain text
const text = hs.pasteboard.readString()
hs.pasteboard.writeString("Hello from Hammerspoon!")

// Check what types are currently on the pasteboard
const available = hs.pasteboard.types()

// Write multiple representations at once
hs.pasteboard.writeObjects({
    "public.utf8-plain-text": "Hello",
    "public.html": "<b>Hello</b>"
})

// Watch for pasteboard changes
const handler = (changeCount) => {
    console.log("Pasteboard changed, count:", changeCount)
    console.log("New text:", hs.pasteboard.readString())
}
hs.pasteboard.addWatcher(handler)
// Later: hs.pasteboard.removeWatcher(handler)

Pasteboard Conventions (nspasteboard.org)

macOS has no built-in notification API for transient or confidential clipboard content, so a community convention has emerged (see nspasteboard.org) around four org.nspasteboard.* UTI marker types. These markers carry no payload — their mere presence on the pasteboard signals intent to other applications.

Standard marker UTIs

Legacy proprietary markers

Several apps defined their own markers before the org.nspasteboard.* standard existed. Clipboard historians should also honour these for compatibility:

For scripts that write to the pasteboard

If your script temporarily commandeers the pasteboard (e.g. to trigger a paste), add org.nspasteboard.TransientType so clipboard historians skip the entry:

hs.pasteboard.writeObjects({
    "public.utf8-plain-text": "temporary value",
    "org.nspasteboard.TransientType": ""
})

For sensitive content such as a generated password, use org.nspasteboard.ConcealedType:

hs.pasteboard.writeObjects({
    "public.utf8-plain-text": "s3cr3t!",
    "org.nspasteboard.ConcealedType": ""
})

For scripts that monitor the pasteboard

If you are building a clipboard history tool with addWatcher, skip or obfuscate entries that carry any of the marker UTIs listed above:

const SKIP_TYPES = [
    "org.nspasteboard.TransientType",
    "org.nspasteboard.AutoGeneratedType",
    "de.petermaurer.TransientPasteboardType",
    "com.typeit4me.clipping",
    "Pasteboard generator type",
]
const CONCEAL_TYPES = [
    "org.nspasteboard.ConcealedType",
    "com.agilebits.onepassword",
]

hs.pasteboard.addWatcher((changeCount) => {
    const types = hs.pasteboard.types()
    if (SKIP_TYPES.some(t => types.includes(t))) return        // ignore transient
    const conceal = CONCEAL_TYPES.some(t => types.includes(t)) // handle sensitively
    // … record or display the pasteboard contents …
})