The panel

The overlay

The panel ⌘⌥C brings up: your whole history, your variables and your actions in one searchable list, and the keys that do something with a row once you have found it.

⌘⌥C brings up the overlay, which shows the clipboard history ordered by most recently copied. Type to fuzzy find it. ⌘1–⌘9, ↩ or a click uses the row, and ⎋ closes the panel.

Closing hands the keyboard back to the app that had it when the overlay came up, so ⎋ leaves the desktop as it was found and typing carries on where it left off. The exceptions are dismissals where focus has already gone somewhere: clicking another window puts it there, and ⌘, puts it in Preferences.

However the overlay is brought up, the search field takes focus, so it can be typed into straight away.

The list

As long as what it is listing, and it scrolls. The whole history with nothing typed; every match once something is. Nine rows fit the panel at a time and the arrows carry on past them, with the highlighted row staying in view.

Nine is how many rows a digit reaches — ⌘1–⌘9 and the family of chords beside them — and not how much there is, so the number beside a row is only drawn for the first nine. Past those the badge is a dot: a row reading 12 would be promising a key that does not exist. Those rows are reached by arrowing to them, or by typing until they are in the nine.

Every row says when it was copied and, where one was recorded, the app it was copied in. The time is worked out when the row is drawn and then left alone — 5m ago, 3h ago, 2d ago, and just now for anything within the minute. It does not tick, and nothing is said in seconds: a row reading 12s ago that then sat there for a minute would be wrong in a way just now never is.

Rows show how many values an entry has held when it has held more than one.

• An image row shows the image itself, small, with the time, what it is and how much disk it takes, and under that the words read out of it run onto one line.
• A file row shows the icon Finder gives the first file, the names — report.pdf, notes.txt and 2 more — and a warning against any that are no longer where they were.
• A variable row is named $name and badged VAR. A list row is named @name, says how many items it holds, and is badged LIST.
• An action row shows its keyword and description. Rest the highlight on one for a second and its help page appears under the list, rendered the same way the Actions pane renders it; the next keystroke takes it away again. This also happens for the filter names offered while a pipeline is being typed, which is where "what does this keyword do" is most often the question.

Searching

Variables and actions are matched as well as the history. The order is variables, then the history, then actions, each group best match first.

A variable leads because you named it: typing part of a name you chose says what you are after more plainly than a word that happens to appear inside something you copied, and there are a handful of variables against a history of hundreds. An action goes last — it is what makes a value rather than one of them.

Neither appears until the query matches it, so an empty bar is the history alone, newest first, exactly as before. Triggers are not listed at all: they fire on a copy and are never run by hand.

The three are ranked against each other as groups rather than scored against each other. A copy that matches the query far better than any variable does is still listed under the variables — how well a query fits one candidate says nothing about whether a name you chose beats a copy you made.

Names and contents are matched differently, because they are different questions.

Names — an action's keyword or description, a variable's name — are matched the way a command palette does: the query's characters appear in order but need not be adjacent, so sfl finds Strip Files List. Each character has to start a word or carry on from the one before it, which is what makes red find url-encode through the r of url and the e and d of encode. A query that appears literally matches wherever it sits, so st still finds abstract, and digits start a word, so b64 finds base64.

Contents — history items, and a variable's value — are matched by term: the query is split on whitespace and each term has to appear literally, in the order typed. So redgifs finds only entries containing that word, and brew fzf finds a command using both. Word starts are too loose here, because an entry a paragraph long contains almost any short query scattered through it.

A variable matches on its name, or failing that on its value — a match on the value alone always ranks below every match on a name. Either way, only the first 4096 characters of an entry are searched.

A secret matches nothing here. A variable named with a leading ! is left out of the search entirely — by value, which is the point of one, and by name as well, so that somebody typing aws is not told by the list that there is an $!aws-key. Typing $! in the search bar is the only way to reach one.

Showing one kind of thing

⌘F asks what to show, and shows only that: a short menu over the list — All, Text, Links, Images, File lists, Variables — answered with a keystroke. The number beside a row, or the arrows and ↩. ⎋ backs out without changing anything, and so does ⌘F again.

Each row says how many rows it would leave, worked out as the menu opens and against whatever is already typed, because none is the answer most worth having before the fact.

A link is listed apart from text. A copy that is one web address and nothing else is a link; a paragraph that mentions one is the paragraph. Nothing appears under both. Actions drop out of a narrowed list whatever it is narrowed to — an action is what makes values rather than one of them. Variables appear under their own choice and nowhere else.

The filter is sticky and shallow: it holds while the overlay is open, across as many searches as you type, and is gone when the overlay closes. A chip beside the search bar says which sort is in force, the field's prompt reads Search links…, and an empty list says No links match "tax" rather than sending you after a better query when what you need is to widen the list. While a command is being typed the chip comes down and the filter does nothing; it is still set, and comes back with the list.

Pins

⌘P pins the highlighted history entry, and unpins one that already is.

The history is a conveyor that runs on time, dropping whatever has outlived its kind's retention. A pin is an entry that has stepped off that belt. It costs one keystroke and asks for nothing else — no name, no dialog, no folder. A pinned entry:

• never expires, whatever its kind is kept for;
• survives Clear History, which is most of what pinning is for, and Clear Older Than as well;
• is not evicted by the image budget, and does not spend it either;
• is still deletable with ⌘⌫, and still forgettable. Both of those are explicit, and explicit wins.

Unpinning puts an entry back on the belt, where its age counts again — so one pinned a month ago, under a retention of a week, goes there and then.

With nothing typed the list is a shelf above a belt: the pins first, oldest pin first, so a new one lands at the end and the ones already there keep the positions your hand has learned. Once something is typed, pins rank like anything else, by what they hold: a pin that floated above better matches would make search worse in exactly the case search exists for.

At most six entries may be pinned. Nine rows can be had by number and pins take the top of them, so six leaves three for recent copies. Pinning a seventh is refused rather than silently unpinning the oldest.

Six is deliberately a shelf rather than a library. Variables are the library: named, unlimited, kept just as firmly, and addressable as $name. If something wants a stable handle, it wants a name — a pin's $n still drifts with every copy, because $n is a position.

Only the history is pinned. A variable is already kept until it is deleted, and an action is not something the history holds at all; both say so rather than doing nothing.

Using a row

⌘1–⌘9 acts on that row, ↩ acts on the highlighted one, and clicking a row does the same thing to it:

• a history entry becomes the clipboard contents and moves to the top of the history;
• an action runs against the current clipboard item, and the result becomes the clipboard contents and the newest entry;
• a variable's value becomes the clipboard contents and the newest entry.

With Automatically paste selection on, the result is also pasted back into the app you were in.

↑/↓ move the highlight, as does ⇧⇥. ⌘, opens Preferences.

A click is a press and a release in the same place: the press picks the row out, so the highlight follows your hand, and the release uses it. A hand that travelled is carrying the row somewhere instead. Under a command being written the rows are names the bar is waiting for, and a click fills one in rather than pasting it — the same thing ⌘1–⌘9 does there.

How it looks

The overlay comes in four themes, chosen in Preferences → Appearance. They cover the overlay, the small HUD that reports what an action did, and the tutorial card; the preferences window itself keeps the standard macOS look.

The themes are listed down the left of that pane, and the one you click is drawn on the right so you can see it before you commit to it. Clicking does not switch to it — Use This Theme does, and a tick in the list shows which one you are actually using.

• Automatic — Paper when your Mac is set to light, Graphite when it is set to dark. This is what you get unless you pick something else, and it means the panel is never the wrong way round for the screen it is on.
• Paper — light and warm, and still see-through. It sets everything a point larger and gives each row a little more room, which is easier to read and fits about four fewer rows at a time.
• Graphite — dark and solid, with a copper highlight. Nothing of your desktop shows through it.
• Classic — the overlay as it looked before themes: the system HUD, in whatever accent colour you have set in System Settings.

Every theme draws the same panel with the same rows and the same keys. What changes is the colour, the highlight on the chosen row and the size of the text. A theme you pick is used the next time the overlay opens.

Making one of your own

The four above cannot be edited. To change one, select it and press + under the list — or Duplicate, on the right: you get a theme of your own, named after the one you copied, that nothing in a future version will overwrite. It appears under Yours, and its settings are on the right, under the preview:

Colours are written as #RRGGBB, so you can paste one in from wherever you decided it, or pick it with the colour well beside the field. The preview above the settings updates as you go.

Use This Theme switches to it. − under the list removes it, and if it was the one in use the overlay goes back to Automatic.

Where the overlay sits

The overlay opens in the middle of the screen your pointer is on.

Hold ⌘ and drag it anywhere. While ⌘ is down the whole panel is the handle, rows included, so you can take hold of it wherever your hand happens to be. Without ⌘ the rows behave as they always have.

Where you let go is where it opens next time, and every time after that. To put it back in the middle, use Centre Again in Preferences → General.

If the display you left it on is gone — a laptop unplugged from its monitor — it opens centred again, and goes back to where you left it when the monitor comes back. A corner that would now hang off an edge is nudged back on screen.

Keeping it up

The overlay closes as soon as anything else takes the keyboard, the way Spotlight does. Keep the overlay up until it is closed, in Preferences → General, turns that off: it stays where it is while you work beside it, and only ⎋, using a row, or a drag that was taken puts it away.

It floats above your other windows without taking focus from them — clicking back into your document goes on typing there, and clicking the overlay again puts the caret back in the search field.

While it stays up, a paste goes into whatever app you were last in, not the one you were in when it opened. That is what keeping it up is for: the panel open beside a document while you take several things out of it, one after another.

Pasting as plain text

⌘⇧V uses the highlighted row as plain text — the text alone, without the bold, the links, the fonts or the background colour it was copied with.

A copy keeps how it looked, so pasting it normally gives the richest version the place you are pasting into can take. That is what you want nearly always, and exactly wrong when you are pasting a paragraph from a web page into a document that is about to keep the web page's fonts.

It is just this once. The row keeps its formatting, so ↩ on it afterwards pastes the rich version again. To narrow a copy for good, use unfmt.

A file list pastes as its paths and a list as its lines, which is what their text already is. An image has no text in it to paste on its own, and says so.

⌘⇧V is the same chord most Mac apps use for "paste and match style". Like every other chord here it can be rebound in Preferences → Shortcuts.

Pasting as plain text is free, and stays free — it is part of the clipboard manager, not the automation a licence buys.

The keys that act on a row

All of them can be rebound in Preferences → Shortcuts; the footer of the overlay names whatever they are bound to now rather than what shipped, and can be hidden with Show shortcut hints in General once you no longer need it. Where a chord does nothing — ⌘⌫ inside a pipeline, say — the key means what it otherwise means there, so a binding never takes a line edit away from the search field.

Shift with a plain digit is deliberately not a shortcut: ⇧4 is how $ is typed, and every shifted digit has to reach the search bar so that pipelines can be written by hand.

Looking at one in full

⌘L shows the highlighted row whole, over the list. The list is rows of one line each, which is what makes it readable at a glance and useless for telling two long copies apart.

• Text — a clipboard item or a variable — is shown in full, monospaced, in something that scrolls and can be selected out of. The arrows, ⇞/⇟, ⌘↑/⌘↓ and space all scroll it, and ⌘C takes a copy of whatever you have dragged over. A file list is its paths, one to a line.
• An image is the picture, as large as the panel will take it and never larger than it was copied.
• An action is its help page, all of it.

The heading says what is being looked at, and under it the facts a page does not show for itself: when it was copied, the app it was copied in, what produced it, how many characters and lines there are, how many values it has held.

Nothing is refused and nothing is changed, which is what makes the page cheap to open. ⎋ goes back to exactly the list that was there, and so does ⌘L again. ↩ uses what you have just read — pastes the item, runs the action — so checking that it is the right one and using it is two keystrokes. The page is a snapshot: something arriving underneath does not rewrite what you are reading, and ↩ uses the row on the page rather than whatever the highlight now stands at.

Past values

⌃↩, or ⌃1–⌃9, opens the past values of that row's entry, newest first, each with when it was set and what set it — the action or trigger that produced it, the app it was copied in, or as entered for one you typed. All of them are listed and the list scrolls.

⌘1–⌘9 or ↩ takes one: it goes on the clipboard, and for a variable it becomes that variable's current value again — which is itself recorded, so a restore can be undone. ⎋ returns to the item list.

Actions have no history of their own, and an entry that has only ever held one value says so rather than opening an empty list.

Storing, gathering and inserting

⇧↩ stores a row in a variable by writing the command that does it into the search bar, waiting on the name: $2 > $ for a clipboard item, $name > $ for a variable, $1 | keyword > $ for an action. Type a name, press ↩, and it is stored. The rows underneath offer the variables that already exist, and ⇥ or ⌘1–⌘9 fills one in — and so does ↩, while the name is still empty: on the $ the redirect just wrote, ↩ takes the highlighted variable and a second ↩ stores the value in it. Once anything has been typed after the $, ↩ runs the command as written instead, because at a destination a name that matches nothing is the ordinary case rather than a half-typed one.

The bar says the same thing a field asking for a name would, in the language the rest of the app is written in: whoever presses ⇧↩ once has been shown how a command redirects, and can go on to type the rest of one around it — $2 | trim > $tidy.

⌘↩ gathers a row into a list, and writes the list itself into the bar:

@<$2, >
      ↑ the caret, inside the brackets, where the next item goes

Press it on another row and that one is written in beside the first — @<$2, $5, > — so a list is built by walking the overlay and pressing one key. While that is in the bar the rows underneath are the clipboard history, since what is being asked for is the next item. ↩ runs it, which puts the list on the clipboard, dealt out an item per paste; typing > @name on the end keeps it instead.

⌥↩, or ⌥1–⌥9, writes a row's shorthand into the search bar — $name for a variable, @name for a list, $n for a clipboard item, and for an action its keyword as the next filter. This is how a pipeline gets built without typing references by hand. Mid-reference it fills in the one being typed rather than starting a new step.

Deleting

⌘⌫ deletes the highlighted row, whole — past values and all, since what something used to hold is no more wanted than what it holds. There is no confirmation and no way back; the HUD names what went.

It deletes values, which is both kinds of them: a history entry, or a variable. Deleting a variable is said louder than deleting an entry — an entry would have fallen off the end of the history sooner or later, and a variable never would.

An action is the one row it will not delete, and says where it is deleted instead: actions are configuration rather than content, and the shipped ones cannot be deleted at all.

The overlay stays up, and the list rebuilds under a highlight that does not move, so ⌘⌫ twice deletes two and the next row slides up under the cursor each time. A pin does not survive it. ⌘⌫ does not act while the bar holds a pipeline: there the caret is in text being written, and ⌘⌫ is the line edit it has always been.

Dragging one out

A row can be picked up and carried into whatever window you let go over. It is the same delivery ↩ makes, by the other hand: pasting puts a copy where the caret is, and dragging puts it where the cursor is — which is how something lands in a place a caret cannot be, like a mail window's attachments or a folder in Finder.

What goes over is exactly what a paste would put on the clipboard. Text goes dressed in the shapes it was copied in, richest first, and a row that is one address and nothing else is offered as an address as well, so dropping a copied link on a browser opens a page. A file list goes as the files, one dragged item each, always as a copy. An image goes as its bytes, with TIFF beside them, and as the file it is kept in for windows that attach things.

A variable is dragged like anything else; a list goes as its text, the items one to a line. An action cannot be dragged — the row simply does not lift, which is the whole message and arrives while your hand is still on it.

A drag that is taken puts the overlay away. One that comes to nothing leaves the panel exactly as it was, so the drop can be tried again without going back for the row.

A press without a drag uses the row, the way ↩ on it would.

The menu bar icon

The icon's menu opens the overlay, pauses or resumes recording, lists the 9 most recent items (⌘1–⌘9), offers every enabled action for manual application in submenus mirroring their folders, clears the history, and opens Preferences, the update check and Quit.

A recent item that is an image carries a thumbnail, and while the newest item is an image the actions submenu says so instead of listing actions that could not run. Where an action carries a shortcut bound everywhere, it is shown as a badge beside it.

Messages

Results, warnings and errors appear in a brief HUD near the bottom of the screen rather than in a dialog, so that triggers never interrupt typing. The three are told apart by colour — plain, orange, red — and a warning is held a little longer, having something to read rather than only to notice.

A message that does not fit on one line wraps onto the next, up to four, and a message that reaches the fourth ends in an ellipsis. How long it stays is worked out from how much there is to read, about four words a second, never shorter than a message used to get and never longer than six seconds.

The daemon's face sits above every message, with the rule or action that fired written underneath it. The HUD is the only place PasteDaemon ever appears unasked — it has no Dock icon and no window of its own — so JSON copied fired over the top of another app would otherwise be a sentence from nowhere. The logo answers which program just rewrote your clipboard before the words are read.