# Raycast

Source: https://frameleaf.app/docs/using/raycast/

The Frameleaf extension for Raycast searches the albums you choose and lets you open, copy or download a photo without leaving the keyboard. It works with Raycast on Mac and Windows, and only reads your library.

## Install

The extension ships in the Frameleaf source, in `integrations/raycast`. With Node.js 22.22 or later:

1. In that folder, run `npm ci`.
2. Run `npm run dev`. Raycast loads the extension, and it stays after you stop the command.

## Connect your library

1. Open any Frameleaf command in Raycast.
2. Enter your **Library address**, such as `https://photos.example.com`. A home-network address such as `http://192.168.1.20:2283` also works.
3. Your browser opens Frameleaf. Sign in if asked, choose the albums Raycast may see, or **Read my whole library**, and choose **Allow**.

Raycast asks only to see and search your photos, videos and albums. To download originals too, turn on **Original downloads** (**Ask to download originals**) in the extension's preferences before you connect.

At home, your server's home-network address or your own HTTPS address works without a Frameleaf plan. Connecting through Frameleaf's [remote access](https://frameleaf.app/docs/cloud/remote-access/) needs a plan that includes it.

## Commands

- **Search Photos**: search the albums you allowed, for photos, videos or both.
- **Browse Albums**: open an album and look through it.
- **Disconnect Library**: end Raycast's access and forget the sign-in.

On a photo:

| Action | Mac | Windows |
| --- | --- | --- |
| **Open in Frameleaf** | Return | Enter |
| **Copy image** | ⌘ ⇧ C | Ctrl Shift C |
| **Copy link** | ⌘ ⇧ L | Ctrl Shift L |
| **Download** | ⌘ D | Ctrl D |
| **Download Original** | ⌘ ⇧ D | Ctrl Shift D |
| **Reload** | ⌘ R | Ctrl R |

**Download** saves a large JPEG to your Downloads folder, without location or camera details. **Download Original** saves the original file with its details. Neither overwrites a file that's already there. A video downloads as a still picture.

If you turn on **Original downloads** after connecting, a photo shows **Allow Original Downloads**, which asks you in Frameleaf. Turning the preference off swaps the connection for one that can only see photos, so you sign in again.

Raycast fetches a preview only for the photo you've selected, and deletes previews when the command closes.

## Client ID

The extension normally registers itself. If your administrator has turned that off, they register it once:

1. Open **Settings**, then **Who can sign in**, then **Sign-in methods**. Under **Registered apps**, choose **Set up an app**.
2. Under **Name**, choose **Other** and enter `Raycast`.
3. In **Sends you back to**, enter `https://raycast.com/redirect?packageName=Extension`.
4. Choose **Create** and share the **App ID**. Enter it as **Client ID** in the extension's preferences.

## Fixes

| Raycast says | What to do |
| --- | --- |
| **Library unavailable** | Check the server is on and this computer can reach the address |
| **Not connected** | Choose **Connect Again**. Access was removed or ran out |
| **This address now belongs to a different Library** | The address now points at another server. Disconnect, then connect to it if you meant to |

## Disconnect

Run **Disconnect Library**. Raycast ends its access in Frameleaf and forgets the sign-in. If your server can't be reached, Raycast tries again later; you can also remove Raycast in Frameleaf under **Settings**, then **Your sign-in & privacy**, then **Connected apps**. That's also where you change the albums it may see. Files you downloaded stay on your computer.

The extension's labels are in English. Setup help is in `integrations/raycast/help` in all eleven Frameleaf languages.
