Welcome, developers! Our docs cover guides, examples, references, and more to help you build extensions and share them with our community and your team.

The Raycast Platform consists of two parts:

• API: This allows developers to build rich extensions with React, Node.js, and TypeScript. The docs explain how to use the API to build top-notch experiences.

• Store: This lets developers share their extensions with all Raycast users. You'll learn how to .

Key features

Here are a few points that make our ecosystem special:

• Powerful and familiar tooling: Extensions are built with TypeScript, React, and Node. Leverage npm's ecosystem to quickly build what you imagine.

• No-brainer to build UI: You concentrate on the logic, we push the pixels. Use our built-in UI components to be consistent with all our extensions.

• Collaborate with our community: Build your extension, share it with our community, and get inspired by others.

Overview

A quick overview about where to find what in our docs:

• Go over this section to learn how to build extensions in our step-by-step guides.

• Build and share extensions with your teammates to speed up common workflows.

• Kickstart your extension by using an open-source example and learn as you go.

Now, let's build 💪

Create a new extension

Open the Create Extension command, name your extension "Hello World" and select the "Detail" template. Pick a parent folder in the Location field and press ⌘ ↵ to continue.

Working with LLMs can be tricky. Here are some best practices to make the most out of your AI Extension.

1. Use Confirmations to keep the human in the loop. You can use them dynamically based on the user's input. For example, you might ask for confirmation if moving a file would overwrite an existing file but not if it would create a new file.

2. Write Evals for common use-cases to test your AI Extension and provide users with suggested prompts.

3. Include information in your tool's input on how to format parameters like IDs or dates. For example, you might mention that a date should be provided in ISO 8601 format.

4. Include information in your tool's input on how to get the required parameters. For example, you want to teach AI how to get a team ID that is required to create a new issue.

System Requirements

Before you can create your first extension, make sure you have the following prerequisites.

• You have Raycast 1.26.0 or higher installed.

• You have 22.14 or higher installed. We recommend to install Node.

• You have 7 or higher

• You are familiar with and . Don't worry, you don't need to be an expert. If you need some help with the basics, check out TypeScript's and React's guide.

Sign In

You need to be signed in to use the following extension development commands.

• Store: Search and install all published extensions

• Create Extension: Create new extensions from templates

• Import Extension: Import extensions from source code

There are two ways to leverage the power of AI inside your extensions.

AI APIs

Use our to generate content such as summaries, translations, and more. For example, the uses AI.ask(...) as part of it's Quick Capture command to generate a summary of a website.

AI Extensions

Create an to enable natural language interactions in Quick AI, AI Chat, and AI Commands. For example, the allows you to manage your team's issues or check your personal priorities by simply chatting to it.

To turn your regular extension into an AI-powered one, you need to add a set of tools that allow Raycast AI to interact with your extension.

Add AI Tools

The simplest way to add a tool to your extensions is to open the Manage Extensions command, search for your extension and perform the Add New Tool action via the Action Panel (or press ⌥ ⌘ T).

This example shows how to build commands that don't show a UI in Raycast. This type of command is useful for interactions with other apps such as skipping songs in Spotify or just simply running some scripts that don't need visual confirmation.

Action

Actions are accessible via the in a . They are little functionality to control something; for example, to add a label to the selected GitHub issue, copy the link to a Linear issue, or anything else. Actions can have assigned keyboard shortcuts.

To publish an extension, run npm run publish in the extension directory. The command verifies, builds and publishes the extension to the owner's store. The extension is only available to members of this organization. A link to your extension is copied to your clipboard to share it with your teammates. Happy publishing 🥳

To mark an extension as private, you need to set the owner field in your package.json to your organization handle. If you don't know your handle, open the Manage Organization command, select your organization in the dropdown on the top right and perform the Copy Organization Handle action (⌘ ⇧ .).

Raycast has several ways to provide feedback to the user:

• - when an asynchronous operation is happening or when an error is thrown

• - to confirm an action worked after closing Raycast

Isn't it more fun to work with your colleagues together on your extension? For this, we recommend to share all your extensions in a single repository, similar to how we organize the . If you follow the , we will set up a local repository for you that is optimized for collaboration.

As next steps, create a and push the existing local repository. Afterwards, your teammates can check out the code and help you improve your extensions and add new ones.

You can enhance your VS Code development experience by installing the Raycast extension in the marketplace. Here's a list of features provided by the extension:

• IntelliSense for image assets

• A tree view for easier navigation (commands and preferences)

• VS Code commands for creating new commands and preferences

• The possibility to attach a Node.js debugger

• VS Code commands for ray operations like build, dev, lint, or fix-lint

All published extensions are open-source and can be found in this repository. This makes it easy for multiple developers to collaborate. This guide explains how to import an extension in order to fix a bug, add a new feature or otherwise contribute to it.

Get source code

First, you need to find the source code of the extension. The easiest way to do this is to use the Fork Extension action in the Raycast's root search.

Develop the extension

After you have the source code locally, open the Terminal and navigate to the extension's folder. Once there, run npm install && npm run dev from the extension folder in your Terminal to start developing the extension.

You should see your forked extension at the top of your root search and can open its commands.

When you're done editing the extension, make sure to add yourself to the contributors section of its . If you used the Fork Extension action, this should have happened automatically.

Additionally, ensure the CHANGELOG.md file is updated with your changes; create it if it doesn't exist. Use the {PR_MERGE_DATE} placeholder for the date – see the for details.

Once everything is ready, see for instructions on validating and publishing the changes.

We all know that AI is not always reliable. This is why it's important to write evals for your AI Extension. Evals allow you to test your AI Extension and make sure it behaves as expected.

Add an Eval

The easiest way to add an eval is to first use your AI Extension. Then, once Raycast AI used your tools to finish its response, you can use the Copy Eval action to copy the eval to your clipboard.

You can then paste the eval into the evals array in the package.json file.

{
  "ai": {
    "evals": [
      {
        "input": "@todo-list what are my open todos",
        "mocks": {
          "get-todos": [
            {
              "id": "Z5lF8F-lSvGCD6e3uZwkL",
              "isCompleted": false,
              "title": "Buy oat milk"
            },
            {
              "id": "69Ag2mfaDakC3IP8XxpXU",
              "isCompleted": false,
              "title": "Play with my cat"
            }
          ]
        },
        "expected": [
          {
            "callsTool": "get-todos"
          }
        ]
      }
    ]
  }
}

Run Your Evals

To run your evals, you can use the npx ray evals command. This will run the evals and print the results to the console. You get an overview of the evals that failed and the ones that passed. From here you can start improving the names and descriptions of your tools.

Visit to learn more about the different types of evals you can write.

All published extensions are discoverable in the Raycast Store. Use the web interface or the Store command to find what you're looking for.

In-app Store

The easiest way to discover extensions is the in-app store. Open the Store command in Raycast and search for an extension. Press ⌘ ↵ to install the selected extension or press ↵ to see more details about it.

Web Store

Alternatively, you can use our . Press ⌘ K to open the command palette, search for an extension and open it.

Then press the Install Extension button in the top right corner and follow the steps in Raycast.

Use installed extensions

After an extension is installed, you can search for its commands in the root search. The extension can be further configured in the Extensions preferences tab.

Raycast provides several tools to smoothen your experience when building extensions:

• Manage Extensions Command - A Raycast command to manage your extensions, add new command, etc.

• CLI - A CLI to build, develop, and lint your extension

• ESLint - An ESLint configuration helping you follow best practices as you build your extension

• - The extension for helping you manage your forked Raycast extensions

• - A VS Code extension to enhance your development experience

All updates to an extension are made through a Pull Request - if you need to review whether the Pull Request works as expected, then you can checkout the fork within a few seconds.

Steps

1. Open a terminal window

2. Navigate to a folder where you want the repository to land

3. Run the below commands

There are a few things you'll need to find and insert manually in the snippet below

FORK_URL

Open the PR and click on the incomming ref as shown below

Now click the code button and copy the HTTPS path from the dropdown

BRANCH

You can see the branch on the above image (in this example it’s notion-quicklinks)

EXTENSION_NAME

Click the Files Changed tab to see in which directory files have been changed (in this example it’s notion)

1. That's it, the extension should now be attached in Raycast

Higher-order function which wraps a function with caching functionality using Raycast's Cache API. Allows for caching of expensive functions like paginated API calls that rarely change.

Signature

function withCache<Fn extends (...args: any) => Promise<any>>(
  fn: Fn,
  options?: {
    validate?: (data: Awaited<ReturnType<Fn>>) => boolean;
    maxAge?: number;
  },
): Fn & { clearCache: () => void };

Arguments

options is an object containing:

• options.validate: an optional function that receives the cached data and returns a boolean depending on whether the data is still valid or not.

• options.maxAge: Maximum age of cached data in milliseconds after which the data will be considered invalid

Return

Returns the wrapped function

Example

Function that shows a failure Toast for a given Error.

Signature

function showFailureToast(
  error: unknown,
  options?: {
    title?: string;
    primaryAction?: Toast.ActionOptions;
  },
): Promise<T>;

Arguments

• error is the error to report.

With a few options:

• options.title is a string describing the action that failed. By default, "Something went wrong"

• options.primaryAction is a Toast .

Return

Returns a .

Example

A function that executes a SQL query on a local SQLite database and returns the query result in JSON format.

Signature

function executeSQL<T = unknown>(databasePath: string, query: string): Promise<T[]>

Arguments

• databasePath is the path to the local SQL database.

• query is the SQL query to run on the database.

Return

Returns a Promise that resolves to an array of objects representing the query results.

Example

Hook which returns a stateful value, and a function to update it. It is similar to React's useState but the value will be kept between command runs.

Signature

function useCachedState<T>(
  key: string,
  initialState?: T,
  config?: {
    cacheNamespace?: string;
  },
): [T, (newState: T | ((prevState: T) => T)) => void];

Arguments

• key is the unique identifier of the state. This can be used to share the state across components and/or commands (hooks using the same key will share the same state, eg. updating one will update the others).

With a few options:

• initialState is the initial value of the state if there aren't any in the Cache yet.

• config.cacheNamespace is a string that can be used to namespace the key.

Example

Icon showing the favicon of a website.

A favicon (favorite icon) is a tiny icon included along with a website, which is displayed in places like the browser's address bar, page tabs, and bookmarks menu.

Signature

function getFavicon(
  url: string | URL,
  options?: {
    fallback?: Image.Fallback;
    size?: boolean;
    mask?: Image.Mask;
  },
): Image.ImageLike;

• name is a string of the subject's name.

• options.fallback is a icon in case the Favicon is not found. By default, the fallback will be Icon.Link.

• options.size is the size of the returned favicon. By default, it is 64 pixels.

• options.mask is the size of the to apply to the favicon.

Returns an that can be used where Raycast expects them.

Example

Raycast makes it easy to lint your extensions using the CLI's lint command (ray lint).

Raycast provides by default an opinionated ESLint configuration that includes everything you need to lint your Raycast extensions. The default configuration is as simple as this:

import { defineConfig } from "eslint/config";
import raycastConfig from "@raycast/eslint-config";

export default defineConfig([...raycastConfig]);

It abstracts away the different ESLint dependencies used for Raycast extensions and includes different rule-sets.

It also includes Raycast's own ESLint plugin rule-set that makes it easier for you to follow best practices when building extension. For example, there's a rule helping you follow the Title Case convention for Action components.

You can check Raycast's ESLint plugin rules directly on the repository documentation.

Customization

You're free to turn on/off rules or add new plugins as you see fit for your extensions. For example, you could add the rule for your extension:

To keep the consistency of development experiences across extensions, we don't encourage adding too many personal ESLint preferences to an extension.

Migration

Starting with version 1.48.8, the ESLint configuration is included automatically when creating a new extension using the Create Extension command. If your extension was created before this version, you can migrate following the steps outlined on the page.

This extension leverages the Git sparse-checkout feature to efficiently manage your forked extensions. Our goal is to eliminate the need for cloning the entire repository, which can exceed 20 GB in size, by enabling sparse-checkout. With this extension, you can forgo Ray CLI's commands, allowing you to use Git commands directly and regular GitHub flow for managing your extensions.

Features

• Explore full extension list

• Only fork the extension you need to save space

• Remove an extension from forked list

• Synchronize the forked repository with the upstream repository on local

Install

The extension is available on the .

Hint

Please note with this extension you no longer need to use Ray CLI's pull-contributions and publish commands. Just use Git commands or your favorite Git GUI tool to manage your forked extensions.

Raycast

Raycast itself runs outside of the App Store as "Developer ID Application", signed with the Raycast certificate and verified by Apple's

Raycast provides a built-in command to manage your extensions.

For each extensions, there are a few actions to manage them.

Add New Command

One such action is the Add New Command action.

Raycast for Teams allows you to build, share and discover extensions in a private store. The store is only accessible to members of your organization.

Create Your Organization

To get started, create your organization. Specify the name of the organization, a handle (used in links, e.g. https://raycast.com/your_org/some_extension) and optionally upload an avatar.

An extension consists of at least an entry point file (e.g. src/index.ts) and a package.json manifest file. We add a few more support files when scaffolding an extension to streamline development with modern JavaScript tooling.

The typical directory structure of a newly created extension looks like this:

The directory contains all source files, assets, and a few support files. Let's go over each of them:

Sources

Icon to represent the progress of a task, a project, something.

Signature

• progress is a number between 0 and 1 (0 meaning not started, 1 meaning finished).

Deeplinks are Raycast-specific URLs you can use to launch any command, as long as it's installed and enabled in Raycast.

They adhere to the following format:

Versioning your extensions is straightforward since we've designed the system in a way that frees you from having to deal with versioning schemes and compatibility. The model is similar to that of app stores where there's only one implicit latest version that will be updated when the extension is published in the store. Extensions are automatically updated for end users.

Development

For development, this means that you do not declare a version property in the manifest. If you wish to use API features that were added in a later version, you just update your @raycast/api npm dependency, start using the feature, and submit an extension update to the store.

Function that executes an PowerShell script.

Signature

Raycast uses React for its user interface declaration and renders the supported elements to our native UI. The API comes with a set of UI components that you can use to build your extensions. Think of it as a design system. The high-level components are the following:

• to show multiple similar items, f.e. a list of your open todos.

• similar to a List but with more legroom to show an image for each item, f.e. a collection of icons.

Icon to represent an avatar when you don't have one. The generated avatar will be generated from the initials of the name and have a colorful but consistent background.

Signature

• name is a string of the subject's name.

Utility function designed for retrieving authorization tokens within a component. It ensures that your React components have the necessary authentication state, either through OAuth or a personal access token.

The CLI is part of the @raycast/api package and is automatically installed in your extension directory during setup. To get a list of the available CLI commands, run the following command inside your extension directory:

Build

npx ray build creates an optimized production build of your extension for distribution. This command is used by our CI to publish your extension to the store.

You can use npx ray build -e dist

Before you publish your extension, take a look at how to prepare your extension for the Store. Making sure you follow the guidelines is the best way to help your extension pass the review.

Validate your extension

Open your terminal, navigate to your extension directory, and run npm run build to verify your extension. The command should complete without any errors.

Publish your extension

To share your extension with others, navigate to your extension directory, and run npm run publish to publish your extension.

You will be asked to authenticate with GitHub because the script will automatically open a pull request in our repository.

The command will squash commits and their commit messages. If you want more control, see the below.

Once the pull request is opened, you can continue pushing more commits to it by running npm run publish again.

Alternative way

If you want more control over the publishing process, you can manually do what npm run publish does. You need to open a pull request in our . For this, , add your extension to your fork, push your changes, and open a pull request into our main branch.

Waiting for review

After you opened a pull request, we'll review your extension and request changes when required. Once accepted, the pull request is merged and your extension will be automatically published to the .

Share your extension

Once your extension is published in the Raycast Store, you can share it with our community. Open the Manage Extensions command, search for your extension and press ⌘ ⌥ . to copy the link.

🚀 Now it's time to share your work! Tweet about your extension, share it with our or send it to your teammates.

When the user takes an action that has the side effect of closing Raycast (for example when copying something in the Clipboard), you can use a HUD to confirm that the action worked properly.

API Reference

showHUD

A HUD will automatically hide the main window and show a compact message at the bottom of the screen.

Signature

Example

showHUD closes the main window when called, so you can use the same options as closeMainWindow:

Parameters

Return

A Promise that resolves when the HUD is shown.

Follow these steps to get a Google client ID:

Step 1: Access Google Cloud Console

Navigate to the Google Cloud Console.

Step 2: Create a Project (if needed)

1. Click Create Project.

2. Provide a Project Name.

3. Select an optional Organization.

4. Click Create.

Step 3: Enable Required APIs

1. Go to Enabled APIs & services.

2. Click ENABLE APIS AND SERVICES.

3. Search for and enable the required API (e.g., Google Drive API).

Step 4: Configure OAuth Consent Screen

1. Click on OAuth consent screen.

2. Choose Internal or External (choose External if you intend to publish the extension in the Raycast store).

3. Enter these details:

   • App name

Step 5: Create an OAuth Client ID

1. Go to Credentials, click CREATE CREDENTIALS, then OAuth client ID

2. Choose iOS as the application type

3. Set the Bundle ID to com.raycast.

Step 6: Use Your New Client ID 🎉

Tools are a type of entry point for an extension. As opposed to a command, they don’t show up in the root search and the user can’t directly interact with them. Instead, they are functionalities that the AI can use to interact with an extension.

Types

Tool.Confirmation

A tool confirmation is used to ask the user to validate the side-effects of the tool.

You can return undefined to skip the confirmation. This is useful for tools that conditionally perform destructive actions. F.e. when moving a file, you don't need to confirm the action if the file doesn't overwrite another file.

Example

A command is typically launched, runs for a while, and then is unloaded.

Launch

When a command is launched in Raycast, the command code is executed right away. If the extension exports a default function, this function will automatically be called. If you return a React component in the exported default function, it will automatically be rendered as the root component. For commands that don't need a user interface (mode property set to "no-view" in the manifest), you can export an async function and perform API methods using async/await.

Dealing with OAuth can be tedious. So we've built a set of utilities to make that task way easier. There are two part to our utilities:

1. Authenticating with a service using or built-in providers (e.g GitHub with OAuthService.github)

2. Bringing authentication to Raycast commands using and

OAuthService, withAccessToken, and getAccessToken

Hook which asks the AI to answer a prompt and returns the corresponding to the execution of the query.

Signature

Arguments

Raycast supports arguments for your commands so that users can enter values right from Root Search before opening the command.

Arguments are configured in the manifest per command.

Example

Let's say we want a command with three arguments. Its package.json will look like this:

The command itself will receive the arguments' values via the arguments prop:

Types

Arguments

A command receives the values of its arguments via a top-level prop named arguments. It is an object with the arguments' name as keys and their values as the property's values.

Depending on the type of the argument, the type of its value will be different.

Function that executes an AppleScript script.

Signature

There are two ways to use the function.

The first one should be preferred when executing a static script.

The second one can be used to pass arguments to a script.

Arguments

• script is the script to execute.

• arguments is an array of strings to pass as arguments to the script.

With a few options:

• options.humanReadableOutput is a boolean to tell the script what form to output. By default, runAppleScript returns its results in human-readable form: strings do not have quotes around them, characters are not escaped, braces for lists and records are omitted, etc. This is generally more useful, but can introduce ambiguities. For example, the lists {"foo", "bar"} and {{"foo", {"bar"}}} would both be displayed as ‘foo, bar’. To see the results in an unambiguous form that could be recompiled into the same value, set humanReadableOutput to false.

• options.language

Return

Returns a Promise which resolves to a string by default. You can control what it returns by passing options.parseOutput.

Example

Types

ParseExecOutputHandler

A function that accepts the output of the script as an argument and returns the data the function will return.

Raycast provides a variety of templates to kickstart your extension.

Raycast provides 3 types of templates:

• Commands: These are templates for commands.

• Tools: These are templates for tools. You can select a different one for each tool that you add to your extension.

• Extension Boilerplates: These are fully built extensions designed to be tweaked by organizations for internal use.

Commands

Show Detail

Submit Form

Show Grid

Show List and Detail

Menu Bar Extra

Run Script

A example of a no-view command which shows a simple .

Show List

Show Typeahead Results

AI

Tools

Extension Boilerplates

The Raycast Team has created high-quality templates to reinforce team experiences with the Raycast API.

Run npm init raycast-extension -t <template-name> to get started with these extensions. All templates can be found on the .

Specific instructions about customizing the template can be found on the relevant . Simply customize the template as you see fit, then run npm run publish in the extension directory to allow your team to install the extension.

The Browser Extension API provides developers with deeper integration into the user's Browser via a Browser Extension.

API Reference

BrowserExtension.getContent

Get the content of an opened browser tab.

Signature

Example

Parameters

Return

A Promise that resolves with the content of the tab.

BrowserExtension.getTabs

Get the list of open browser tabs.

Signature

Example

Return

A Promise that resolves with the list of .

Types

BrowserExtension.Tab

Properties

API Reference

clearSearchBar

Clear the text in the search bar.

Signature

Parameters

Return

A Promise that resolves when the search bar is cleared.

closeMainWindow

Closes the main Raycast window.

Signature

Example

You can use the popToRootType parameter to temporarily prevent Raycast from applying the user's "Pop to Root Search" preference in Raycast; for example, when you need to interact with an external system utility and then allow the user to return back to the view command:

Parameters

Return

A Promise that resolves when the main window is closed.

popToRoot

Pops the navigation stack back to root search.

Signature

Example

Parameters

Return

A Promise that resolves when Raycast popped to root.

Types

PopToRootType

Defines the pop to root behavior when the main window is closed.

Enumeration members

Higher-order function fetching an authorization token to then access it. This makes it easier to handle OAuth in your different commands whether they're view commands, no-view commands, or menu-bar commands.

Signature

Arguments

options is an object containing:

• options.authorize: a function that initiates the OAuth token retrieval process. It returns a promise that resolves to an access token.

• options.personalAccessToken: an optional string that represents an already obtained personal access token. When options.personalAccessToken is provided, it uses that token. Otherwise, it calls options.authorize to fetch an OAuth token asynchronously.

• options.client

Return

Returns the wrapped component if used in a view command or the wrapped function if used in a no-view command.

Example

Types

WithAccessTokenParameters

WithAccessTokenComponentOrFn

Function that creates a deeplink for an extension or script command.

Signature

There are three ways to use the function.

The first one is for creating a deeplink to a command inside the current extension:

The second one is for creating a deeplink to an extension that is not the current extension:

The third one is for creating a deeplink to a script command:

Arguments

Extension

• type is the type of the deeplink. It must be DeeplinkType.Extension.

• command is the name of the command to deeplink to.

• launchType is the type of the launch.

Script command

• type is the type of the deeplink. It must be DeeplinkType.ScriptCommand.

• command is the name of the script command to deeplink to.

• arguments is an array of strings to be passed as arguments to the script command.

Return

Returns a string.

Example

Types

DeeplinkType

A type to denote whether the deeplink is for a script command or an extension.

API Reference

useNavigation

A hook that lets you push and pop view components in the navigation stack.

You most likely won't use this hook too often. To push a new component, use the . When a user presses ESC, we automatically pop to the previous component.

Signature

Example

Return

A object with and functions. Use the functions to alter the navigation stack.

Types

Navigation

Return type of the hook to perform push and pop actions.

Properties

Commands of an extension can be configured to be automatically run in the background, without the user manually opening them. Background refresh can be useful for:

• dynamically updating the subtitle of a command in Raycast root search

• refreshing menu bar commands

• other supporting functionality for your main commands

Hook that provides a high-level interface to work with Forms, and more particularly, with Form validations. It incorporates all the good practices to provide a great User Experience for your Forms.

Signature

Arguments

Bugs are unavoidable. Therefore it's important to have an easy way to discover and fix them. This guide shows you how to find problems in your extensions.

Console

Use the console for simple debugging such as logging variables, function calls, or other helpful messages. All logs are shown in the terminal during development mode. Here are a few examples:

For more, checkout the Node.js documentation.

We automatically disable console logging for store extensions.

Visual Studio Code

For more complex debugging you can install the to be able to attach a node.js debugger to the running Raycast session.

1. Activate your extension in dev mode via npm run dev or via the VSCode command Raycast: Start Development Mode

2. Start the VSCode command Raycast: Attach Debugger

3. Set your breakpoint like in any other node.js base project

Unhandled exceptions and Promise rejections

All unhandled exceptions and Promise rejections are shown with an error overlay in Raycast.

During development, we show the stack trace and add an action to jump to the error to make it easy to fix it. In production, only the error message is shown. You should for all expected errors, e.g. a failing network request.

Extension Issue Dashboard

When unhandled exceptions and Promise rejections occur in the production build of a public extension, Raycast tries to redact all potentially sensitive information they may include, and reports them to our error backend. As an extension author, or as the manager of an organisation, you can view and manage error reports for your public extensions by going to https://www.raycast.com/extension-issues, or by finding your extension in Raycast's root, Store command, or Manage Extensions command, and using the View Issues action. The dashboard should give you an overview of what issues occurred, how many times, how many users were affected, and more. Each issue additionally has a detail view, including a stack trace, breadcrumbs (typically the actions performed before the crash), extension release date, Raycast version, macOS version.

React Developer Tools

We support out-of-the-box. Use the tools to inspect and change the props of your React components, and see the results immediately in Raycast. This is especially useful for complex commands with a lot of states.

To get started, add the react-devtools to your extension. Open a terminal, navigate to your extension directory and run the following command:

Then re-build your extension with npm run dev, open the command you want to debug in Raycast, and launch the React Developer Tools with ⌘ ⌥ D. Now select one of the React components, change a prop in the right sidebar, and hit enter. You'll notice the change immediately in Raycast.

Alternative: Global installation of React Developer Tools

If you prefer to install the react-devtools globally, you can do the following:

Then you can run react-devtools from a terminal to launch the standalone DevTools app. Raycast connects automatically, and you can start debugging your component tree.

Environments

By default, extensions installed from the store run in Node production mode and development extensions in development mode. In development mode, the CLI output shows you additional errors and warnings (e.g. the infamous warning when you're missing the React key property for your list items); performance is generally better when running in production mode. You can force development extensions to run in Node production mode by going to Raycast Preferences > Advanced > "Use Node production environment".

At runtime, you can check which Node environment you're running in:

To check whether you're running the store or local development version:

This set of utilities to work with Raycast commands.

API Reference

launchCommand

Launches another command. If the command does not exist, or if it's not enabled, an error will be thrown. If the command is part of another extension, the user will be presented with a permission alert. Use this method if your command needs to open another command based on user interaction, or when an immediate background refresh should be triggered, for example when a command needs to update an associated menu-bar command.

Signature

Example

Parameters

Return

A Promise that resolves when the command has been launched. (Note that this does not indicate that the launched command has finished executing.)

updateCommandMetadata

Update the values of properties declared in the manifest of the current command. Note that currently only subtitle is supported. Pass null to clear the custom subtitle.

Signature

Example

Return

A Promise that resolves when the command's metadata have been updated.

Types

LaunchContext

Represents the passed context object of programmatic command launches.

LaunchOptions

A parameter object used to decide which command should be launched and what data (arguments, context) it should receive.

IntraExtensionLaunchOptions

The options that can be used when launching a command from the same extension.

InterExtensionLaunchOptions

The options that can be used when launching a command from a different extension.

When the user takes an important action (for example when irreversibly deleting something), you can ask for confirmation by using confirmAlert.

API Reference

General

Handle errors

Network requests can fail, permissions to files can be missing… More generally, errors happen. By default, we handle every unhandled exception or unresolved Promise and show error screens. However, you should handle the "expected" error cases for your command. You should aim not to disrupt the user's flow just because something went wrong. For example, if a network request fails but you can read the cache, show the cache. A user might not need the fresh data straight away. In most cases, it's best to show a

Use the Preferences API to make your extension configurable.

Preferences are configured in the per command or shared in the context of an extension.

Required preferences need to be set by the user before a command opens. They are a great way to make sure that the user of your extension has everything set up properly.

API Reference

In addition to the which is bundled as part of the app, we also provide a sibling package that contains a set of utilities to streamline common patterns and operations used in extensions.

Installation

This package can be installed independently using npm.

@raycast/utils has a on @raycast/api

The Window Management API provides developers with some functions to create commands with some advanced logic to move s around.

The Environment APIs are useful to get context about the setup in which your command runs. You can get information about the extension and command itself as well as Raycast. Furthermore, a few paths are injected and are helpful to construct file paths that are related to the command's assets.

API Reference