# Install (/docs/perch/install) perch is two halves: the shelf on your Mac, and a free companion app that throws things at it from your phone. Do the Mac first: the phone pairs *to* it. You need **macOS 14** or newer on **Apple Silicon**, and **iOS 18** or newer for the phone half. On an Intel Mac the app won't open, and macOS says it's "not supported on this Mac". A notch is nice, not required: the shelf works on any Apple Silicon Mac and any display, and sits at the top middle of the screen where there's no camera housing. Nothing here needs a terminal. ## Turn one macOS setting off [#turn-one-macos-setting-off] Do this before you install anything, or your very first drag will vanish and perch will look broken by the only gesture it has. In **System Settings ▸ Desktop & Dock**, scroll to **Mission Control** and turn *off* **"Drag windows to top of screen to enter Mission Control"**. macOS arms that top-edge trigger for the whole of any drag (files included, despite the setting's name), and it fires over the same band the shelf lives in. Leave it on and the Dock takes your drop into Mission Control before perch ever sees it. It's the only thing perch asks of your Mac, it's reversible in the same place, and a [haus](/docs/haus) machine flips it for you. ## Get perch [#get-perch] The [**latest release**](https://hausfold.co/download/perch) is a signed, notarized download: unzip it and drag `Perch.app` into your **Applications** folder. Gatekeeper clears it, so the first open is macOS's ordinary *"downloaded from the Internet, are you sure?"* and nothing else: no *unidentified developer* block, no right-click-Open, no `xattr`. Or, if you have Homebrew: ```sh brew install --cask hausfold/tap/perch ``` Same build either way. No account, no sign-in, no licence key. Homebrew reads the chip you are *running as*, not the one you have, so a `/usr/local` Homebrew under Rosetta declines perch on an Apple Silicon Mac that would have run it natively. Take the download instead, or install an arm64 Homebrew. **Open it once from your Applications folder.** No window opens and **there is no Dock icon**: that's deliberate. Look for a small tray icon in your menu bar, top right. That's perch, and it's how you reach everything below. ## Turn on Launch at Login [#turn-on-launch-at-login] Menu bar tray icon ▸ **Settings…** ▸ **General** ▸ **Launch Perch at login**. Without it perch is gone after your next restart, which is an odd way to find out you liked it. It comes back in the menu bar only: no window, no Dock icon. ## Try it [#try-it] Grab any file and start dragging it *up toward the notch*. A shelf drops down to catch it. Let go. Pile in as much as you like, from as many places as you like, then drag a tile back out to wherever it's actually going. [Using the shelf](/docs/perch/using) is what to read next. ## The phone half [#the-phone-half] [**Perch Companion**](https://apps.apple.com/app/id6799443735) is free on the App Store, for iPhone and iPad. To pair it, once: 1. On the **Mac**: menu bar tray icon ▸ **Settings…** ▸ **iPhone & iPad** ▸ **Pair a Device…**, which shows a QR code. 2. On the **phone**: open the app (its icon says **Perch**), tap **Pair a Mac**, and point it at the code. 3. Back on the **Mac**: it says your phone wants to pair, and shows six digits. The phone is showing six of its own. Check they match, then click **Approve**. Comparing them is what stops somebody else's phone pairing with your Mac, so if they differ, click **Decline**. It arrives at step 1, and nowhere else: **Pair a Device…** is the moment perch starts announcing itself so a phone can find it. A Mac with nothing paired never advertises, so a fresh install is never asked. Say **Allow** and you never see it again. Say Don't Allow and the shelf keeps working exactly as it does above; only the phone half goes quiet, and nothing sent from a phone will ever arrive. Dismiss it without answering and the next **Pair a Device…** asks again. Nothing here reaches past your own network, and there is no server to reach. After that, share anything from the phone (photos, files, links, text) and it lands on the Mac's shelf. It goes over your own network, or straight phone-to-Mac with no network at all, over the same radio AirDrop uses. Nothing passes through a server; there isn't one, and the link is encrypted end to end. Settings ▸ iPhone & iPad tears the listener down if you'd rather it weren't there. Control Center's Wi-Fi toggle deliberately leaves AWDL (the direct radio link) up, which is why your phone still finds a Mac that looks offline. Airplane Mode, or **System Settings ▸ Wi-Fi ▸ Off**, is what actually ends it; so does Settings ▸ iPhone & iPad in perch. All the link ever needs is the Wi-Fi radio on at both ends: no router, and not the same one. ## Updating [#updating] perch checks its own release tag once an hour. When there's a newer one, the open shelf grows a quiet strip along its bottom edge and the menu bar menu grows a matching row; dismissing a version dismisses that version, and the next release asks again. The button knows how you installed perch. Three of the four routes are owned by something that already updates them, so it hands you the command instead: `brew upgrade --cask perch`, `haus update` or `nix flake update perch`. Swapping the bundle under Homebrew or haus would only be undone by their next run. A copy you dragged in yourself has no such owner, and it gets **Update Now**: one click downloads the release, checks it is a build of ours that Apple notarized, replaces the app and reopens it. Your shelf survives it, because staged items live in perch's own container rather than in the app bundle. If anything fails, perch says so in the strip and the button goes back to opening the release page. Settings ▸ Updates turns the check off altogether. ## The terminal half [#the-terminal-half] Everything above is the whole app. These two are for people who want perch in a script or a flake. ### The `perch` command [#the-perch-command] The command line ships **inside** the app, at `Perch.app/Contents/MacOS/perch-cli`, so it is signed and notarized with it and can never drift from the shelf it talks to. The cask and the Nix flake both put it on your PATH as `perch`, and on a haus machine the Shelf room does. If you installed by dragging the app, link it yourself, once: ```sh ln -s /Applications/Perch.app/Contents/MacOS/perch-cli /usr/local/bin/perch ``` Four verbs, and only the first three touch the shelf: ```sh perch add report.pdf shot.png # put things on it perch list # what's on it, id first perch rm # take one off perch doctor # what this Mac and this copy are ``` `rm` takes ids and never names, because two tiles can share a display name and no removal should have to guess. It takes pinned items too, and, like everything else here, it only ever deletes the copy perch staged. `--json` on `add`, `list`, `rm` or `doctor` gives you the whole answer as one object, which is what makes emptying the shelf but keeping the pins a one-liner: ```sh perch list --json | jq -r '.items[] | select(.pinned | not) | .id' | perch rm - ``` The shelf verbs launch perch and wait if it isn't running; `--no-launch` is how a script says it would rather fail. `doctor` is the one verb that answers with no perch running, and it deliberately never starts one: its first two lines are exactly what the [bug form](https://github.com/hausfold/perch/issues/new/choose) asks you to paste. `perch skill` prints the agent skill and `perch skill install` places it. [Using the shelf](/docs/perch/using) has what a path does once perch has it. ### Nix [#nix] The flake wraps the same notarized build rather than compiling from source: add `github:hausfold/perch` as an input and its `overlays.default` puts `perch` in your pkgs. ## On a haus machine [#on-a-haus-machine] If your Mac runs [haus](/docs/haus), let the Shelf room own perch instead; it installs it, turns the Mission Control setting off for you, and keeps perch current with everything else, surviving a rebuild: ```nix haus.shelf.enable = true; ``` ```sh haus rebuild ``` If you already installed it with Homebrew, letting the room own it is the upgrade. [The Shelf room](/docs/haus/rooms/shelf) has the one option it adds.