Raycast Extension

pinakea can be used with a Raycast extension that lets you search, open items, and clip URLs directly from Raycast.

The Raycast extension is available on Free, Pro Monthly, and Pro Lifetime. Raycast can expose pinakea search results, summaries, and item content to launcher workflows, automation, and AI tools, so it still uses a marked local API path and narrow route matrix. pinakea must also be signed in and this Mac must be active on the account.

It supports two connection modes:

Local Mode (same Mac): talks to pinakea over a loopback-only connection (no Web Server needed)
Remote Mode (different Mac): talks to pinakea via Web Server

This can make it faster to:

Search your items from the Raycast launcher
Open recent items quickly
Clip a URL into pinakea

Note

Raycast extensions are separate from the pinakea app. The current source ZIP is linked from the download page.

red_distortion_4

Set scope

The Raycast extension operates on pinakea’s currently selected Set. It can’t switch Sets remotely — switch Sets in pinakea first. See Sets (Libraries).

Prerequisites

Raycast installed
pinakea installed

For Local Mode:

pinakea must be running on the same Mac

For Remote Mode:

Web Server enabled in pinakea (Settings → Web Server)
A Web Server password set (used by the extension)

If pinakea runs on a different Mac, you also need network access to that Mac:

Same local network (Wi‑Fi), or
Remote access via Tailscale

Setup (typical)

Download the Raycast source ZIP from the download page, install it in Raycast’s developer extension workflow, then choose the connection mode below.

Local Mode (same Mac)

Make sure pinakea is running.
In Raycast → Extension Settings, set Connection Mode to Local Mode.
Use the Raycast commands (Search, Recent Items, Clip URL, …).

Info

In Local Mode, app-target actions are labeled Open in pinakea App (and Open Search in pinakea App). If pinakea is not running, the launch action is Open pinakea App. No-view commands such as Chat with Library do not silently launch pinakea. If pinakea is not running, Raycast shows a message; use the explicit Open pinakea App action when you want to start it.

Note

In Local Mode, Open Original for local files opens the item in pinakea instead of opening a raw local loopback URL in the browser. This keeps local file access behind the marked Raycast API path.

Remote Mode (different Mac)

Enable Web Server in pinakea (see Web Server).
Set a Web Server password in pinakea (Settings → Web Server).
In Raycast → Extension Settings:
- Set Connection Mode to Remote Mode
- Set the Web Server URL (one of):
  - Local network: http://192.168.x.x:8080
  - Remote (Tailscale): http://100.x.x.x:8080 (you can use Copy Tailscale URL in pinakea Settings)
- Enter the Web Server password

In Remote Mode, Chat with Library opens the Web Server chat page in the browser. It does not launch a local copy of pinakea on the Raycast Mac.

Troubleshooting

Local Mode says offline: make sure pinakea is running on the same Mac.
Local Mode says a route is denied: make sure pinakea is running and the extension is using Local Mode.
Local Mode says Sign in, Refresh Status, or Activate this Mac: open pinakea on this Mac and follow that action. Choose Activate this Mac only when this Mac is inactive; if the account already has five active Macs, deactivate one first.
Remote Mode says offline: verify Enable Web Server is on in pinakea and that the Web Server status section shows URLs.
Remote Mode says Sign in, Refresh Status, or Activate this Mac: open pinakea on the Mac running Web Server and follow that action. Raycast checks the public health route and then a protected library route so account-device locks appear before a command returns empty results.
Auth fails (Remote Mode): confirm the password in Settings → Web Server and update it in Raycast.
Tailscale URL doesn’t work: ensure Enable Remote Access (Tailscale) is enabled in pinakea and both devices are connected in Tailscale.