Raycast

Raycast logo

Overview

Raycast is a macOS "blazingly fast, totally extendable launcher. It lets you complete tasks, calculate, share common links, and much more."

Raycast ...

Raycast extensions can add items to the macOS menu bar. Clicking a menu bar item can reveal a list of items. Clicking a list item can trigger an action such as opening a URL in Safari. Menu bar extensions can specify a refresh interval for automatically updating their contents.

Installing

The steps to install Raycast are:

  1. Browse the Raycast home page.
  2. Click the "Download for Mac" button.
  3. Double-click the downloaded Raycast.dmg file. An installer window will appear.
  4. Drag the Raycast app icon into the Applications folder.
  5. Close the installer window.
  6. In the finder, eject the Raycast "drive" from the left nav.

There is also an option to install it using Homebrew.

Configuring

The steps for first-time configuration of Raycast are:

  1. Open the Finder.

  2. Select "Applications" in the left nav.

  3. Double-click Raycast.app. This will open a Raycast window.

  4. Click the "Begin setup" button.

  5. Scroll down and modify the toggle switches to enable/disable specific built-in extensions. For example, I enabled the "Contacts" extension.

  6. Click the "Continue" button.

  7. Choose the hotkey (keyboard shortcut) that will be used to launch Raycast.

    If you wish to use cmd-space, you will need to change the hotkey for Spotlight. To do this:

    1. Open "System Settings".
    2. Select Keyboard in the left nav.
    3. Click the "Keyboard Shortcuts" button.
    4. Select "Spotlight" in the left nav.
    5. In the row for "Show Spotlight search", double-click "cmd-space".
    6. Type a new hotkey such as cmd-period.
    7. Click the "Done" button.

    Click the hotkey under "Raycast Hotkey". Type a new hotkey such as cmd-space. Click the "Continue" button.

  8. Optionally enter your email address and click the "Subscribe" button to receive periodic information about Raycast.

  9. Click the "Continue" button.

  10. Click the "Launch Raycast" button.

  11. Double-click "Start supercharging your productivity" for a walkthrough of Raycast features.

  12. Double-click each topic to learn more.

Help

See the official Raycast Manual.

There are many YouTube videos about using Raycast.

Raycast Window

The search input at the top of the Raycast window supports fuzzy searches. For example, typing "vc" will match "Visual Studio Code".

Press the up and down arrow keys to highlight an item in the list of suggestions or matches.

Press cmd-k to see a list of actions that can be performed on the highlighted item.

One action that can be performed on a command is "Add to Favorites" which adds it to the list of favorite commands that are always visible on the starting Raycast page. Select a favorite and press cmd-k to get actions for moving it up or down in the list.

Regardless of which Raycast "page" you have navigated to within the window and which item is highlighted, you can press cmd-k to see a popup that lists context-sensitive actions that are available.

For example, on the "Search Files" page when a file is highlighted the available actions include "Open", "Show in Finder", "Quick Look", "Open With...", "Show Info in Finder", "Enclosing Folder", "Toggle Details", "Share...", "Move to...", "Copy to...", "Duplicate", "Copy File", "Copy Name", "Copy Path", and "Move to Trash".

Press esc to go back to the previous page. When on the starting page, pressing esc will close the Raycast window.

Press cmd-esc to go back to the main page.

Press cmd-w on any page to close the Raycast window.

Settings

To open the Raycast settings dialog, open Raycast and press cmd-comma.

Click the "Extensions" tab in the settings dialog to enable and disable extensions.

All your Raycast settings can be exported and imported from the "Advanced" settings tab.

Window State

The Raycast window maintains its state across uses for a configurable amount of time (defaults to 90 seconds). When it is reopened within this amount of time, it will be in on the same page with the same input values as when it was last used.

To return to the root page, press cmd-esc or repeatedly press esc.

To configure the amount of time that Raycast maintains its window state, open the Raycast settings, click the "Advanced" tab, and select a different value in the "Pop to Root Search" dropdown.

Command Aliases and Hotkeys

To assign aliases and hotkeys to commands, open Raycast, open the settings dialog, click the "Extension" tab, select a command, and enter an alias and/or a hotkey for the command.

Contacts

To search contacts, open Raycast, enter "con", select "Contacts", and enter part of a name. The first time you do this you will need to grant permission.

Dictionary

To lookup a word in the dictionary, enter "def" and select the "Define Word" command.

Fun

See the "Confetti" command.

Launching Apps and Settings

To quickly launch an app:

To uninstall the selected app, press cmd-k, scroll to "Uninstall Application...", and select it. This is preferable to deleting the app from the Finder because it will also delete supporting files.

To quickly open the "System Settings" app on a specific panel, enter part of the panel name and press the return key. For example, to open to the "Printers & Scanners" panel, enter "pri" and press return.

Calculator

To perform a calculation, open Raycast, type "calc", select "Calculator History", and enter an expression. The result is automatically copied to the clipboard.

Actually calculator expressions can be entered in the initial search input without first selecting "Calculator History"!

For example, "sin(19)^2 + cos(19)^2" gives 1.

This can also perform unit conversions. For example:

A history of previous calculations is maintained so you can copy their result to the clipboard again. You cannot recall and modify them.

Selecting "Calculator" launches the macOS Calculator app which is probably not what you want.

Calendar

The Calendar extension is enabled by default, but it requires permission. Open the Raycast settings, click the "Extensions" tab, select "Calendar", and click the "Permission Required" button. A dialog will appear. Click the "Grant Access" button. Another dialog will appear. Click the "Allow Full Access" button.

To see your schedule for today, open Raycast, enter "sche", and select "My Schedule".

To show upcoming meetings in the macOS menu bar, open the Raycast settings, select the "My Schedule" command, scroll to the bottom of its settings, and change the value of "Show Events in Menu Bar". It's unclear whether this works with the Bartender utility.

Clipboard History

To view clipboard history, open Raycast, enter "clip", and select "Clipboard History". By default only entries from the last 7 days are saved.

The clipboard history is stored in a local encrypted database for security.

Filter the list by entering search text.

Click an entry to see which application created it, when it was created, and more.

Double-click an entry to copy it to the clipboard AND paste it at the current cursor location.

To disable saving clipboard entries from specific apps (such as 1Password):

To delete entries from the clipboard history, press cmd-k and select "Delete Entry", "Delete Entries..." (last 5, 15, or 30 minutes), or "Delete All Entries".

To search for files, open Raycast, type "sf", select "Search Files", and enter search text. The first time you do this, you will need to enable it by selecting "Authorize to search user folders".

To enable search both file names and contents, open the Raycast settings, click the "Extension" tab, select "Search Files", and change the "Search By" option to "Name and Contents".

Move the cursor to one of the listed files, then press:

So far this doesn't seem to be able to find all files by their name. For example, it cannot file Documents/BeverlyHillbillies.txt.

Quicklinks simplify opening URLs and optionally supplying a query parameter for sites that perform searching. The only quicklinks that are provided are "Search DuckDuckGo" and "Search Google".

To add a predefined quicklink:

To create a basic quicklink:

To create a quicklink for a website that performs a search using a URL query parameter:

To use a quicklink:

To create a quicklink that opens a frequently used local file, use the "Search Files" command to find the file in Raycast, press cmd-k, and select "Create Quicklink". Enter a name for the quicklink, select the application that should open it, and click the "Create Quicklink" button. Now to open the file you can just enter part of the assigned name in the input on the main Raycast page.

I created a quicklink for the website removebg which removes the background from images. I gave it the alias "bg".

I also created a quicklink for ChatGPT.

Mozilla Developer Network (MDN) does not perform searches using a URL query parameters, so you cannot create a quicklink for it. However, there is an extension that can be installed from the "store" that searches MDN called "Search MDN". The command name this adds is "Search Web Docs". It displays documentation in the Raycast window and provides a "Open in Browser" button.

Emojis & Symbols

The "Search Emoji & Symbols" command displays a list of them. To quickly find this command, enter "emo".

Enter a search term to filter the list.

Double-click an emoji or symbol to insert it at the current cursor position.

For example, enter "kiss" to see only the related emojis and symbols.

To enter an emoji in any Raycast input, type a colon. This opens an emoji picker containing recently used emojis. Type part of the name of an emoji to see others.

Floating Notes

The "Floating Notes" built-in feature opens a single window for entering text that always remains on top of other windows.

To toggle the display of this window, open Raycast, enter "fl", and select the "Toggle Floating Notes Window" command. I assigned the hot key hyper-n to this command. (I configured the hyper key using the free app Karabiner-Elements.) The window can also be closed by clicking the "X" in the upper-right corner or by pressing cmd-w when it has focus.

To move focus to this window, click in it. Alternatively, open Raycast, enter "fl", and select the "Toggle Floating Notes Focus" command. If the window is not already open, this will also open it.

The window begins with a height that only accomodates a single line. The height increases automatically as more lines are entered. If the number of lines exceeds its maximum height, a scrollbar is provided.

The window can be repositioned and dragged to any monitor, but it cannot be resized.

To change the background color of the window, click the paint brush icon in the lower-left and select from a predefined set of five colors.

The number of words and characters entered are displayed at the bottom of the window.

Reminders

Install the "Apple Reminders" extension from the store to add the following commands:

Snippets

Raycast snippets are text or emojis identified by keywords. When the keywords are entered in any application, they are replaced by the associated text.

To see the existing snippets:

To define a snippet:

The snippet text can contain placeholders. For details, see Dynamic Placeholders. They can also contain {cursor} to indicate where the cursor should be positioned after the snippet is inserted.

For example, the following snippet adds an HTML anchor tag.

<a href="{argument name="url"}" target="_blank">{argument name="title"}</a>

Argument names must be lowercase. They can be repeated to substitute the same value in multiple occurrences. For example:

console.log('{argument name="expression"} =', {argument name="expression"});

If this is given the keyword "atb" and that keyword is entered in any application, a dialog will appear to prompt for values for "url" and "title". After entering the values, click the "Expand" button or press cmd-return.

To create a snippet for an emoji, use the "Search Emojis" command to find the desired emoji, press cmd-k, select "Save as Snippet", optionally modify the name, and optionally modify the keyword.

Store

The Raycast Store is the place to download more extentions. To open it, open Raycast and enter "store".

It displays three features extensions (updated every 15 days), a list of trending extensions, and an infinite scrolling list of all extensions. Filter the list by entering part of a name.

Popular extensions include:

System Commands

Raycast provides many system commands including:

Window Managment

Raycast provides many commands to change the size and location of windows. The most useful are the following:

I created these keyboard shortcuts:

CommandShortcut
Left Halfcmd-left arrow
Right Halfcmd-right arrow
Bottom Halfcmd-down arrow
Top Halfcmd-up arrow
Center Halfcmd-shift-c
Left Quartercmd-shift-left arrow
Right Quartercmd-shift-right arrow
Maximizecmd-shift-m
Next Displaycmd-shift-n
Previous Displaynone

I didn't assign the shortcut cmd-shift-p to "previous display" because that shortcut is used in VS Code to open the command palette.

For the "Move" commands, you can turn off the "Center Window" option so the window retains its current position in the opposite of the move dimension rather then being centered on the target edge. "Center Window" is a toggle in the settings for each of the four "Move" commands.

Creating Custom Extensions

Raycast extensions are implemented in TypeScript with React (using a custom renderer like React Native), Node, and Markdown. The custom renderer uses Raycast-specific components rather than HTML and CSS. AppleScript is used communication with macOS apps.

An alternative to creating an extension is to write a script command. Script commands are "a simple way to execute a shell script and show some limited output in Raycast". They can be written in any scripting language, so they rely on users having the selecting scripting language installed.

Extensions can be shared with others through the Raycast store, but script commands cannot.

To create a new extension:

  1. Open Raycast

  2. Open the "Create Extension" command.

  3. Select a template.

    The supported template types include:

    • None
    • Detail
    • Form
    • Grid
    • List and Detail
    • Menu Bar Extras
    • Script
    • Static List
    • Typeahead Search

  4. Enter an extension name.

  5. Enter a description.

  6. Select a category.

  7. Select the location where the project will be stored.

  8. Enter a name and description of a command that will be defined.

  9. Optionally describe more commands.

  10. Click the "Create Extension" button.

  11. From a terminal window, cd to the directory of the extension.

  12. Enter npm install and npm run dev.

  13. Open Raycast.

  14. Select your command from the "Development" category and run it.

VS Code

See the VS Code extension "Raycast" by tonka3000. It provides commands for common tasks, debugging, auto-completion, and snippets.

Manifest

The package.json file of an extension serves as its manifest where many aspects of an extension are specified. This includes the extension name, title, description, icon, author, categories, keywords, preferences, license, commands, and more.

For each command, a JSON object specifies its name, title, subtitle, description, icon, mode, interval, keywords, arguments, and preferences. The mode of a command must be set to "view", "no-view", or "menu-bar".

If the extension exports a default function, it will be called automatically. If the function returns a React component, it will rendered as the root component. The default function for commands that do not require a user interface, such as those with mode set to "no-view", can by async.

The supplied package.json file for a new extension will contain the following scripts:

"scripts": {
  "build": "ray build -e dist",
  "dev": "ray develop",
  "fix-lint": "ray lint --fix",
  "lint": "ray lint",
  "publish": "npx @raycast/api@latest publish"
}

The "fix-lint" and "lint" scripts perform some Raycast-specific validations, and also run both ESLint and Prettier.

Arguments

Each extension command can take up to three arguments. The only supported types are "text", "password", and "dropdown". The arguments for a command are described in the JSON description of the command found in the package.json file for the extension. The order in which argument inputs will appear matches their order in the package.json file.

There is no support for validating argument values. For example, it is not possible to require an argument value to be an integer. An extension perform its own validation and display and error message if an argument has an invalid value. For example:

function isInteger(str: string): boolean {
  return Number.isInteger(parseInt(str, 10));
}

...

  const {port} = props.arguments;
  if (!isInteger(port)) {
    showToast({
      style: Toast.Style.Failure,
      title: 'Bad Port',
      message: 'The port must be an integer.'
    });
    return;
  }

Forms

Extensions can display forms that allow users to enter several values. Each field has a label and an input area. Each field can have custom validation logic.

HTTP Requests

Extension commands can fetch data by sending an HTTP request. There are several ways to do this including the useFetch hook from "@raycast/utils" and npm packages like node-fetch and got.

UI Components

Raycast supports a limited set of UI components. This makes it easy for users to use extensions because there is a low learning curve for interaction patterns.

The supported UI components include:

Toast Messages

Toast messages appear at the bottom of the Raycast window. Three styles are supported: Success, Failure, and Animated.

Animated toasts can have their style, title, and message properties modified after they are created.

To display a toast message:

  1. Import these:

    import {showToast, Toast} from '@raycast/api';

  2. Call the showToast function.

    showToast({
      style: Toast.Style.Failure, // or Success or Animated
      title: 'My Title',
      message: 'My message.'
    });

LocalStorage

The LocalStorage object manages data for the current extension. Extensions can only access their own data. The object has the following methods:

Preferences

The Preferences API is used to make an extension configurable. They can be specific to a command defined by the extension or be shared by all commands defined by the extension.

All preferences marked as "required" must be supplied by the user before they can use the commands.

Preferences are defined in the package.json file of an extension. Each command object in the "commands" array can specify a preferences property whose value is an array of objects.

For example:

"preferences": [
  {
    "name": "defaultPort",
    "description": "specifies the default port to use if none is provided",
    "type": "textfield",
    "required": true,
    "placeholder": "Default Port"
  }
]

For more detail, see Preference properties.

Utilities

The following utility functions are provided in "@raycast/api".

The addon package @raycast/utils provides more utility functions and React hooks.

The provided functions include:

The provided React hooks include:

TODO: Are any databases other than SQLite supported?

Publishing an Extension

Here's a checklist of things to do in order to submit an extension for review so it can be published in the store.