Functions

Utility functions for UI, navigation, and system integration

SuperCmd provides all Raycast API functions for window management, notifications, navigation, and system operations.

UI & Feedback

showToast

showToast

Show toast notifications with actions

Display toast notifications to provide feedback to users.

Type Signature:

function showToast(options: Toast.Options): Promise<Toast>;
function showToast(style: Toast.Style, title: string, message?: string): Promise<Toast>;

interface Toast.Options {
  title: string;
  message?: string;
  style?: Toast.Style; // 'success' | 'failure' | 'animated'
  primaryAction?: {
    title: string;
    onAction?: () => void;
    shortcut?: Keyboard.Shortcut;
  };
  secondaryAction?: {
    title: string;
    onAction?: () => void;
    shortcut?: Keyboard.Shortcut;
  };
}

Example:

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

await showToast({
  style: Toast.Style.Success,
  title: 'Task completed',
  message: 'Your file has been saved',
  primaryAction: {
    title: 'Open File',
    onAction: () => open(filePath),
    shortcut: { modifiers: ['cmd'], key: 'o' },
  },
});

Interactive Features:

• Press ⌘T to show toast actions menu
• Actions can have keyboard shortcuts
• Toasts auto-dismiss after 3s (6s with actions)
• Only one toast shown at a time

---

showHUD

showHUD

Show HUD overlay message

Display a brief HUD message overlay.

Type Signature:

function showHUD(
  title: string,
  options?: {
    clearRootSearch?: boolean;
    popToRootType?: PopToRootType;
  }
): Promise<void>;

Example:

import { showHUD } from '@raycast/api';

await showHUD('Copied to clipboard!');

---

confirmAlert

confirmAlert

Show confirmation dialog

Show a confirmation alert dialog.

Type Signature:

function confirmAlert(options: Alert.Options): Promise<boolean>;

interface Alert.Options {
  title: string;
  message?: string;
  icon?: Image.ImageLike;
  primaryAction?: {
    title: string;
    onAction?: () => void;
    style?: Alert.ActionStyle; // 'default' | 'destructive' | 'cancel'
  };
  dismissAction?: {
    title: string;
    onAction?: () => void;
  };
}

Example:

import { confirmAlert } from '@raycast/api';

const confirmed = await confirmAlert({
  title: 'Delete File',
  message: 'Are you sure you want to delete this file? This cannot be undone.',
  primaryAction: {
    title: 'Delete',
    style: Alert.ActionStyle.Destructive,
  },
});

if (confirmed) {
  // Delete file
}

---

Navigation & Window Management

closeMainWindow

closeMainWindow

Close the main window

Close the main SuperCmd window.

Type Signature:

function closeMainWindow(options?: {
  clearRootSearch?: boolean;
  popToRootType?: PopToRootType;
}): Promise<void>;

Example:

import { closeMainWindow } from '@raycast/api';

await closeMainWindow({ clearRootSearch: true });

---

popToRoot

popToRoot

Navigate back to root view

Navigate back to the root view of the extension.

Type Signature:

function popToRoot(options?: {
  clearRootSearch?: boolean;
}): Promise<void>;

---

clearSearchBar

clearSearchBar

Clear the search bar text

Clear the current search bar text.

Type Signature:

function clearSearchBar(options?: {
  forceScrollToTop?: boolean;
}): Promise<void>;

---

System Integration

open

open

Open URLs, files, or applications

Open URLs, files, or launch applications.

Type Signature:

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

Example:

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

// Open URL in default browser
await open('https://example.com');

// Open URL in specific browser
await open('https://example.com', 'Safari');

// Open file
await open('/path/to/file.pdf');

// Open file in specific app
await open('/path/to/image.png', 'Preview');

---

getApplications

getApplications

Get list of installed applications

Get a list of installed applications.

Type Signature:

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

interface Application {
  name: string;
  path: string;
  bundleId?: string;
}

Example:

import { getApplications, List } from '@raycast/api';

export default function Command() {
  const [apps, setApps] = useState<Application[]>([]);
  
  useEffect(() => {
    getApplications().then(setApps);
  }, []);
  
  return (
    <List>
      {apps.map(app => (
        <List.Item key={app.path} title={app.name} />
      ))}
    </List>
  );
}

---

getDefaultApplication

getDefaultApplication

Get default application for a file

Get the default application for opening a file.

Type Signature:

function getDefaultApplication(path: string): Promise<Application>;

---

getFrontmostApplication

getFrontmostApplication

Get the currently active application

Get the frontmost (active) application.

Type Signature:

function getFrontmostApplication(): Promise<Application>;

---

showInFinder

showInFinder

Reveal file/folder in Finder

Reveal a file or folder in Finder.

Type Signature:

function showInFinder(path: string): Promise<void>;

Example:

import { showInFinder } from '@raycast/api';

await showInFinder('/Users/me/Documents/file.pdf');

---

trash

trash

Move files to trash

Move one or more files to the trash.

Type Signature:

function trash(paths: string | string[]): Promise<void>;

Example:

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

try {
  await trash('/path/to/file.txt');
  await showToast(Toast.Style.Success, 'File moved to trash');
} catch (error) {
  await showToast(Toast.Style.Failure, 'Failed to delete file');
}

---

getSelectedText

getSelectedText

Get currently selected text from active app

Get the currently selected text from the frontmost application.

Type Signature:

function getSelectedText(): Promise<string>;

May require accessibility permissions on macOS.

---

getSelectedFinderItems

getSelectedFinderItems

Get selected files in Finder

Get the currently selected items in Finder.

Type Signature:

function getSelectedFinderItems(): Promise<FileSystemItem[]>;

interface FileSystemItem {
  path: string;
}

May require accessibility permissions on macOS.

---

Extension Management

launchCommand

launchCommand

Launch another command

Launch another command from the same or different extension.

Type Signature:

function launchCommand(options: {
  name: string;
  type: LaunchType;
  extensionName?: string;
  ownerOrAuthorName?: string;
  context?: LaunchContext;
}): Promise<void>;

Example:

import { launchCommand, LaunchType } from '@raycast/api';

await launchCommand({
  name: 'search',
  type: LaunchType.UserInitiated,
  extensionName: 'my-extension',
});

---

openExtensionPreferences

openExtensionPreferences

Open extension preferences

Open the extension preferences window.

Type Signature:

function openExtensionPreferences(): Promise<void>;

---

openCommandPreferences

openCommandPreferences

Open command preferences

Open the command preferences window.

Type Signature:

function openCommandPreferences(): Promise<void>;

---

updateCommandMetadata

updateCommandMetadata

Update command metadata dynamically

Update command metadata (subtitle) at runtime.

Type Signature:

function updateCommandMetadata(metadata: {
  subtitle?: string;
}): Promise<void>;

Example:

import { updateCommandMetadata } from '@raycast/api';

await updateCommandMetadata({ subtitle: '5 items' });

---

getPreferenceValues

getPreferenceValues

Get extension preferences

Get the current extension’s preference values.

Type Signature:

function getPreferenceValues<T = PreferenceValues>(): T;

Example:

import { getPreferenceValues } from '@raycast/api';

interface Preferences {
  apiKey: string;
  showNotifications: boolean;
}

const preferences = getPreferenceValues<Preferences>();
console.log(preferences.apiKey);

---

Error Handling

captureException

captureException

Log exceptions for debugging

Capture and log exceptions for debugging.

Type Signature:

function captureException(error: Error): void;

Example:

import { captureException } from '@raycast/api';

try {
  // Some operation
} catch (error) {
  captureException(error as Error);
}