# Using the shelf (/docs/perch/using) The shelf has no window to open and no icon to click. It appears when you're already dragging something and disappears when you're not, and it can be filling up while you're doing neither. ## Catching a drag [#catching-a-drag] Start dragging anything, then flick up toward the notch. The shelf drops down and catches whatever you let go of over it. You can do that as many times as you like, from as many places as you like (Finder, Safari, Photos, Mail, a Save dialog), and it all piles onto the same shelf. Files, folders, images dragged out of a web page, links and plain text all land the same way. Between drags the shelf doesn't go dark: while it holds something, a small ember glows under the camera housing (under the menu bar on a screen without one), a pip per item and a flare as each new one lands. That's how you know there's a pile without opening it. ## Other ways in [#other-ways-in] A drag is the one you'll use, and none of the others behaves differently: each stages a copy the way a drop does. | | | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Right-click** | **Add to Perch Shelf** sits under **Services** in Finder's context menu, with nothing to enable, and in any other app's Services menu for a selection or a link. perch doesn't have to be running: the Service starts it | | **`perch add`** | From a shell, a Makefile or an agent: `perch add report.pdf`, or `find . -name '*.png' \| perch add -` for a list on stdin. The exit status distinguishes a shelf that never opened from a copy that failed. `perch list` and `perch rm` go the other way; [the terminal half](/docs/perch/install#the-perch-command) has all four verbs | | **Your iPhone** | [**Perch Companion**](https://apps.apple.com/app/id6799443735), free on the App Store, once you've [paired it](/docs/perch/install#the-phone-half). Its Share sheet sends over your network, or peer-to-peer with no network at all, and the phone can pull shelf items back down too | | **Watched folders** | Point Settings ▸ Watched Folders at `~/Downloads` or anywhere else things arrive, and anything **new** there lands on the shelf by itself. perch reads where this Mac saves screenshots and offers that folder at the top of the pane, so the one most people want is one click | ### What a watched folder counts as new [#what-a-watched-folder-counts-as-new] What's already sitting in a folder when you add it stays put; only later arrivals land, including ones that happened while perch wasn't running. A half-written download waits until it's finished and renamed, so nothing reaches the shelf mid-write, and any other file is imported only once its size has stopped changing for a moment. **Replacing a file's contents counts as a new arrival.** Save over one twice and you get two tiles: what is there now is a different file wearing the old name. Renaming doesn't: the tile you already have is that file, whatever it is called now. Dragging an item *out* of the shelf into a watched folder doesn't put it back either; perch recognises what it just wrote. The screenshot folder perch offers at the top of the pane is one click, and the click is still the permission: knowing where a folder is is not being given it, so the panel is what hands it over. What you get is an ordinary watched folder, and **Stop Watching** on its own row is the only way it leaves. It doesn't preview a saved file, it *holds* the capture and writes it out about five seconds later, so a watched folder catches every screenshot five seconds after you took it. System Settings has no switch; the screenshot toolbar's **Options ▸ Show Floating Thumbnail** does, and a haus machine turns it off for you. ## Carrying it out [#carrying-it-out] Drag a tile off the shelf and drop it where it belongs. Grab the **stack** and you take everything at once. Whatever the destination accepts leaves the shelf; a refused drop springs back rather than vanishing. Because perch hands out copies of its own staged copy, dropping the same pile into three places is three drags, not three trips back to where the files came from. Dropping into several places is cheaper still if you **pin**: the pin on a tile's corner, or right-click ▸ **Pin**, keeps it on the shelf after a successful drag, ready for the next destination. A pinned tile survives a relaunch and never expires; unpin it and it's back to one-and-done. When the destination is a folder nothing has open, there's no need to find a window to drag into: right-click a tile and pick **Save to…**. It writes a copy wherever you point the panel, leaves the tile where it was, and only replaces an existing file once the new copy is whole. Nothing on the shelf is ever half-written, which is also why a big folder takes a moment to show up, and why quitting mid-copy doesn't lose it. ## What stays, and for how long [#what-stays-and-for-how-long] Nothing leaves the shelf on its own. **Clear asks first**, and the expiry timer is **off** unless you turn it on in Settings, so a pile you left there yesterday is still a pile today. Your originals are untouched throughout: perch stages a copy inside its own sandbox container (under `~/Library/Containers/com.hausfold.perch/`, one directory per import, so two files of the same name never have to be renamed) and never moves, renames, edits or deletes the thing you dragged in. The manifest records the staged copies and their metadata; **the path you dragged from is never written down**, not to that file and not to a log. Clearing an item deletes its whole import directory outright rather than moving it to the Trash, which is why **Clear asks twice**: the shelf's button arms and wants a second click, and the menu bar's *Clear Shelf…* raises an alert. ## Settings worth knowing [#settings-worth-knowing] | | | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Discard items after** | *Never*, until you say otherwise. Turn it on and the shelf empties itself after a set time; pinned items stay | | **Show a drop target on every display** | On by default: each screen gets its own shelf at the notch. Off keeps it to your main display | | **Launch Perch at login** | perch comes back in the menu bar after a restart: no window, no Dock icon | | **iPhone & iPad** | The phone listener and the **Pair a Device…** button. Off tears the listener down; pairings are remembered for when it comes back | | **Check for new releases** | An hourly look at perch's own release tag, and the only thing it ever sends to the internet. Off means it never checks again | Every one of those switches is a line in a file rather than a hidden `defaults` key, and Settings names the path at the bottom of **General**. Edit the file and perch follows without a relaunch; write only the keys you care about, and a file that isn't valid JSON changes nothing rather than resetting you. `~/.config/perch/config.json` is the other half, and it wins. Name a key there (plus `launchAtLogin`, which lives nowhere else) and that value is the one perch uses: the row goes read-only in Settings with a padlock and a line saying where it came from. That is how a machine you manage, or a haus desktop, pins a setting. Delete the key and the switch is yours again. perch only ever reads that file; the one it writes lives inside its own sandbox container. One key in it has no switch at all: `"fontFamily"` sets the proportional family the shelf, Settings and the pairing window are set in, and left out you get macOS's own. On a haus machine [`haus.fonts.sans.name`](/docs/haus/rooms/appearance#type) writes it for you and moves perch, pounce and trill together; a standalone Mac names it by hand. There is no theme picker in that list, on purpose. The shelf paints from [nebelung](https://github.com/hausfold/nebelung) and follows macOS Light/Dark by itself; on a haus machine it follows your desktop's flavor and accent too. ### Painting it yourself [#painting-it-yourself] A standalone Mac can drop any Catppuccin-shaped palette into the same `~/.config/perch` directory: ```text ~/.config/perch/ config.json { "themeDark": "nebelung", "themeLight": "nebelung-latte", "accent": "mauve" } themes/.json flat "role": "#hex" map: a nebelung *.hex.json verbatim ``` A file in `themes/` **shadows** a built-in of the same name, so a palette bump lands without a new release. perch needs `base`, `crust`, `overlay0`, `text`, `subtext0`, `green` and `red`, plus whichever role `accent` names, and ignores the rest; a missing or malformed file falls back to built-in nebelung rather than failing. `accent` is the one colour the shelf *emphasises* with: the ember's pips under the notch, a pinned tile, the filled button on a notice. It takes a Catppuccin role name (resolved against whichever palette is in force, so the hue follows the flavour and the polarity) or a literal `"#rrggbb"`. Leave it out and the shelf accents with the palette's own `green`, the sage of the app icon under stock nebelung. Changes are picked up the next time the shelf opens, with no relaunch.