Namespace 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)
Copy

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.

For scripts that write to the pasteboard

If your script temporarily commandeers the pasteboard (e.g. to trigger a paste), add

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

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

For scripts that monitor the pasteboard

If you are building a clipboard history tool with addWatcher, skip or obfuscate entries that

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 …
})
Copy