top of page
Search

On-Call Runbooks in Raycast: Keeping Them Current and Two Keystrokes Away

Writer: MacSmithAI
MacSmithAI
Oct 16
7 min read

At 2 a.m. what decides how an incident goes is not the quality of your runbook. It is whether the person on call can reach it in under ten seconds, and whether they believe what it says when they get there. Most Mac admin teams have the first part solved on paper — a wiki, a repo full of markdown — and the second part not solved at all, because nobody keeps a document current when updating it means a browser, a login and a click on Edit.


Runbook rot has two independent causes. Retrieval latency: if the right page costs more than a few seconds to reach, the responder works from memory, the document stops being load-bearing, and nobody notices it has gone wrong. Authoring friction: runbooks decay through small corrections nobody makes — a changed MDM payload name, a step that now needs a reboot, a path that moved in the last OS release — each costing thirty seconds of typing and five minutes of ceremony. Most tooling fixes one of the two.


Raycast is worth a look here, and not for the reason people usually reach for it: the capture surface, the retrieval surface and the AI that rewrites your prose all sit behind one hotkey.


What Raycast Notes actually is

Raycast Notes is a lightweight note surface that opens in a floating window above whatever else is on screen, with Markdown applied as you type — # for a heading, * for a bullet.


Raycast's manual ships no default hotkey for it; it suggests you assign one and names ⌥ N as a common choice — worth knowing before you promise a shortcut that does not exist by default. Once the window is open: ⌘ N for a new note, ⌘ P to browse, ⌘ [ and ⌘ ] to move through recently opened notes, ⇧ ⌘ P to pin. Pinned notes sort to the top of Search Notes and Browse Notes, and — the part that makes this viable at 2 a.m. — while the Notes window is open, ⌘ 0 through ⌘ 9 open pinned notes directly. Search Notes searches every note by title and content, so a half-remembered error string finds the right page.


That is genuinely two keystrokes to a specific runbook: your assigned hotkey, then the pin slot.


One constraint to design around: notes sync through Cloud Sync, which requires an active Pro subscription, and the Raycast Notes category has to be on under Settings → Cloud Sync → Synced Content. The manual warns that v1 and iOS devices use legacy Cloud Sync, so syncing between v1 and v2 devices can lag — test that before anyone relies on reading a runbook from a phone.


The authoring half: one AI Command per editing job

AI Commands do the actual work here. Raycast describes them as a way to "turn your favorite prompts into one press commands," and they run against text selected in any app. You create one by searching Create AI Command in Root Search; the only required field is Prompt, with Name & Icon, Organization, Model, Creativity and a handful of others optional.


The placeholder syntax is what turns a prompt into a tool. {selection} drops in the highlighted text. {argument name="Language"} prompts you for a value before the command runs. Typing @ inserts an AI Extension, and typing { inserts a Dynamic Placeholder. So a runbook-tightening command looks like this:


You are editing an on-call runbook for a macOS fleet managed with Intune.

Rewrite the steps below so that each one is a single imperative
sentence, preserves every command, file path and key name exactly
as written, and ends with the observable result the responder
should see.

Do not invent a step. If a step is ambiguous, leave it unchanged
and append "[VERIFY]" on its own line beneath it.

Target OS version: {argument name="macOS version"}

{selection}

Select the stale section in your note, run the command, and you get back something consistently shaped. The [VERIFY] instruction matters more than the rewriting: it makes the model a flagger rather than an author, which is the only way I would let one near a document somebody follows under pressure. Same split as reviewing shell scripts with AI before they hit 10,000 Macs — generate the mechanical part, keep the judgement.


Two team-shaped details. The Organization field decides whether a command is personal or shared with your Raycast team, a Share AI Command action produces a one-click install link, and Import AI Commands pulls a set in from a JSON file — that last one is how a consistent editing toolkit lands on eight admins' Macs. And note that Quick Fix, whose default trigger is a double press of the right Shift key, always uses Raycast AI and spends AI credits even if your AI Commands point at your own provider.


Where Notes is the wrong place for a runbook

Raycast's own Notes documentation describes no team or collaboration features. You can export a note as plain text, Markdown or HTML, or send it to Apple Notes, and that is the extent of it — no organization-managed Notes store appears on the Teams or Enterprise pages either.


So Notes is not your system of record. The authoritative runbook still belongs where your team reviews changes, with history and approvals. Notes is good at being the on-call working copy: pinned, instantly reachable, AI-editable, carried by one engineer through a shift, corrections flowing upstream afterwards. If you want the model reading the system of record itself, that is closer to building an MCP server over your software repo than to a notes app.


Raycast gives you five places to put on-call material, and they are not interchangeable:


Where it lives

What the keyboard gets you

What an admin can control

Raycast Note (personal)

Your assigned hotkey, then a pinned slot from Command-0 to Command-9; Search Notes matches title and content

Cloud Sync on or off per content category - no organization-level Notes controls documented

Shared Quicklink

An alias or hotkey opens the real document, with up to three arguments

Created once, then available to every member of the organization

Shared Snippet

Expands boilerplate inline wherever you are typing

Shared organization-wide with Raycast for Teams

Shared AI Command

One run over selected text; the @ key pulls in an AI Extension

Organization field, share link and JSON import; AI provider allow-list on Enterprise

Organization-managed MCP server

AI chat reaches your real systems over stdio or HTTP

Enterprise only - a manager configures each server and toggles it on or off


Shared Quicklinks are the underrated one. A Quicklink points at a web URL, a file, a folder or a deeplink, takes up to three arguments in the {argument name="query"} form, and the manual says plainly that you can "Assign an alias or hotkey to any Quicklink for faster access." One shared Quicklink aliased rb, opening your real runbook index with a search argument, reaches every member of the organization — the cheapest available fix for retrieval latency, and it moves your documentation nowhere.


What changes when you manage this for a fleet

Most of the controls a Mac admin would ask for sit on Raycast's Enterprise tier, not Pro. The Enterprise page lists SSO via SAML, SCIM provisioning, MDM sign-in enforcement, organization-wide AI availability, an AI providers allow-list, your own AI gateway, organization-managed MCP servers, an extensions allow-list with automated vulnerability scanning, enforced two-factor authentication and an IP allow-list, plus a SOC 2 Type II report, annual penetration testing, GDPR alignment and CCPA readiness. It does not mention audit logs or data residency, and names no price — "Enterprise customers receive dedicated, tailored terms and conditions."


MDM sign-in enforcement is the one to deploy first. It requires Raycast users on managed Macs to sign in with an approved work email: the client is blocked until they do, another domain errors out, and logging out is disabled so nobody switches accounts around it. The configuration is a profile for bundle identifier com.raycast.macos carrying a RequiredSignInDomain key set to your email domain, with PayloadIdentifier com.raycast.mdm.requiredsignin and a UUID you generate per profile. Raycast publishes a .mobileconfig template — deploy that rather than hand-writing the XML.


Then the question your security team will ask. Raycast's AI privacy page states that "We do not log or retain any user prompts," that it stores only "some basic metadata, such as the number of completion tokens, for operational purposes only," and that "Your data is not used to train AI models." Read the named exceptions: Mistral AI retains data for a rolling 30-day abuse-monitoring window, xAI for 30 days before automatic deletion, and for Claude Fable 5.1 "Anthropic doesn't offer Zero Data Retention for this model" while "Other Anthropic models remain Zero Data Retention." Local models are the clean case — "Your prompts and responses aren't sent to Raycast or to any third party."


The sharper issue for a runbook is not prompts but Cloud Sync, the thing that makes pinned notes follow an engineer between Macs. Raycast says synced content is stored "encrypted in our databases" — a reasonable posture, and still a copy of your operational documentation in a vendor's database. If your runbooks carry recovery procedures, break-glass account names or internal hostnames, that belongs in the same bucket as what a Mac fleet can enforce when staff paste into ChatGPT.


On pricing: Raycast restructured its AI plans on 10 September 2026 — Pro at $10 a month with 500 AI credits, Pro+ at $20 with 3,000, Max at $50 with 7,500; an existing Claude or ChatGPT account connects on any paid plan. Team and Enterprise terms are negotiated, so budget from a conversation.


The practical takeaway

Do not move your runbooks into Raycast Notes. Do put the on-call working copy there.


Concretely: one shared Quicklink with an alias that opens your real runbook index with a search argument — that alone kills most of the retrieval problem and costs nothing. Then one Raycast Note per recurring incident class, pinned into slots ⌘ 1 through ⌘ 5, plus one shared AI Command that tightens steps and flags whatever it cannot verify. Corrections go upstream to the repo at the end of the shift, not during the incident.


If you are standing this up across a managed fleet rather than for yourself, Enterprise is the only version of this story with real controls in it — MDM sign-in enforcement and the extensions allow-list in particular — and the absence of documented audit logs is the gap to raise in that negotiation rather than discover afterwards.



Comments

bottom of page