System Utilities

This set of utilities exposes some of Raycast's native functionality to allow deep integration into the user's setup. For example, you can use the Application APIs to check if a desktop application is installed and then provide an action to deep-link into it.

API Reference

getApplications

Returns all applications that can open the file or URL.

Signature

async function getApplications(path?: PathLike): Promise<Application[]>;

Example

Find Application

import { getApplications, Application } from "@raycast/api";

// it is a lot more reliable to get an app by its bundle ID than its path
async function findApplication(bundleId: string): Application | undefined {
  const installedApplications = await getApplications();
  return installedApplications.filter((application) => application.bundleId == bundleId);
}

List Installed Applications

import { getApplications } from "@raycast/api";

export default async function Command() {
  const installedApplications = await getApplications();
  console.log("The following applications are installed on your Mac:");
  console.log(installedApplications.map((a) => a.name).join(", "));
}

Parameters

Name	Description	Type
path	The path of the file or folder to get the applications for. If no path is specified, all installed applications are returned.	"fs".PathLike

Return

An array of Application.

getDefaultApplication

Returns the default application that the file or URL would be opened with.

Signature

async function getDefaultApplication(path: PathLike): Promise<Application>;

Example

import { getDefaultApplication } from "@raycast/api";

export default async function Command() {
  const defaultApplication = await getDefaultApplication(__filename);
  console.log(`Default application for JavaScript is: ${defaultApplication.name}`);
}

Parameters

Name	Description	Type
path*	The path of the file or folder to get the default application for.	"fs".PathLike

Return

A Promise that resolves with the default Application that would open the file or URL. If no application was found, the promise will be rejected.

getFrontmostApplication

Returns the frontmost application.

Signature

async function getFrontmostApplication(): Promise<Application>;

Example

import { getFrontmostApplication } from "@raycast/api";

export default async function Command() {
  const frontmostApplication = await getFrontmostApplication();
  console.log(`The frontmost application is: ${frontmostApplication.name}`);
}

Return

A Promise that resolves with the frontmost Application. If no application was found, the promise will be rejected.

showInFinder

Shows a file or directory in the Finder.

Signature

async function showInFinder(path: PathLike): Promise<void>;

Example

import { showInFinder } from "@raycast/api";
import { homedir } from "os";
import { join } from "path";

export default async function Command() {
  await showInFinder(join(homedir(), "Downloads"));
}

Parameters

Name	Description	Type
path*	The path to show in the Finder.	"fs".PathLike

Return

A Promise that resolves when the item is revealed in the Finder.

trash

Moves a file or directory to the Trash.

Signature

async function trash(path: PathLike | PathLike[]): Promise<void>;

Example

import { trash } from "@raycast/api";
import { writeFile } from "fs/promises";
import { homedir } from "os";
import { join } from "path";

export default async function Command() {
  const file = join(homedir(), "Desktop", "yolo.txt");
  await writeFile(file, "I will be deleted soon!");
  await trash(file);
}

Parameters

Name	Description	Type
path*	The item or items to move to the trash.	"fs".PathLike or "fs".PathLike[]

Return

A Promise that resolves when all files are moved to the trash.

open

Opens a target with the default application or specified application.

Signature

async function open(target: string, application?: Application | string): Promise<void>;

Example

import { open } from "@raycast/api";

export default async function Command() {
  await open("https://www.raycast.com", "com.google.Chrome");
}

Parameters

Name	Description	Type
target*	The file, folder or URL to open.	string
application	The application name to use for opening the file. If no application is specified, the default application as determined by the system is used to open the specified file. Note that you can use the application name, app identifier, or absolute path to the app.	string or Application

Return

A Promise that resolves when the target has been opened.

captureException

Report the provided exception to the Developer Hub. This helps in handling failures gracefully while staying informed about the occurrence of the failure.

Signature

function captureException(exception: unknown): void;

Example

import { open, captureException, showToast, Toast } from "@raycast/api";

export default async function Command() {
  const url = "https://www.raycast.com";
  const app = "Google Chrome";
  try {
    await open(url, app);
  } catch (e: unknown) {
    captureException(e);
    await showToast({
      style: Toast.Style.Failure,
      title: `Could not open ${url} in ${app}.`,
    });
  }
}

Parameters

Name	Description	Type
exception*	The exception you want to report.	unknown

captureMemorySnapshot

Records JavaScript heap statistics with a label to help investigate an extension's memory usage. Add checkpoints before and after operations such as loading a large response, parsing JSON, or preparing list items to see where heap usage grows.

The function only records measurements when memory reporting is enabled. When reporting is disabled, it does nothing, so you can leave useful checkpoints in your code. A measurement contains heap statistics rather than a heap dump of individual objects.

Signature

function captureMemorySnapshot(label: string): void;

Example

This helper records heap usage before and after parsing a JSON response:

import { captureMemorySnapshot } from "@raycast/api";

export function parseResponse(text: string): unknown {
  captureMemorySnapshot("Before parsing response");
  const result: unknown = JSON.parse(text);
  captureMemorySnapshot("After parsing response");
  return result;
}

Investigating an out-of-memory error

1. After a view command reports Command Out of Memory, open its action panel and choose Reload with Memory Reporting. This enables reporting for the next run of the command.

2. Repeat the steps that caused the error. Raycast records your checkpoints along with automatic measurements around initialization and callbacks. Development commands also collect periodic samples while reporting is enabled.

3. On the error screen, inspect Memory Diagnostics to see the latest, peak, and recent measurements. Use the labels to identify the operations associated with increased heap usage, then add more checkpoints to narrow down the cause.

Parameters

Name	Description	Type
label*	A descriptive name for this checkpoint, such as "After parsing response".	string

Return

Returns void. Measurements are sent to Raycast for diagnostics; they aren't returned to the extension.

Types

Application

An object that represents a locally installed application on the system.

It can be used to open files or folders in a specific application. Use getApplications or getDefaultApplication to get applications that can open a specific file or folder.

Properties

Property	Description	Type
name*	The display name of the application.	string
path*	The absolute path to the application bundle, e.g. /Applications/Raycast.app,	string
bundleId	The macOS bundle identifier of the application, e.g. com.raycast.macos.	string
localizedName	The localized name of the application.	string
windowsAppId	The Windows App ID of the application.	string

PathLike

PathLike: string | Buffer | URL;

Supported path types.