Skip to main content
SuperCmd aims for 100% compatibility with the Raycast API. This page tracks the implementation status of all @raycast/api and @raycast/utils features.

​
Core Components

All major UI components are fully implemented:
ComponentStatusImplementation
List✅ FullFiltering, pagination, accessories, List.Item.Detail with Metadata
Detail✅ FullMarkdown rendering with Metadata (Label, Link, TagList, Separator)
Form✅ FullAll field types, DatePicker.Type enum, FilePicker, LinkAccessory, enableDrafts
Grid✅ FullGrid.Fit/Inset enums, Section with aspectRatio/columns/fit/inset
ActionPanel✅ FullSubmenu with filtering/isLoading/onOpen/shortcut
Action✅ FullAll action types including Push (onPop), CopyToClipboard (concealed)
MenuBarExtra✅ FullMenu bar integration for background commands
All components are implemented in src/renderer/src/raycast-api/ using modular runtime files.
HookStatusNotes
useNavigation✅ FullPush/pop navigation stack with onPop callbacks

​
State Management Hooks

HookStatusImplementation
useCachedState✅ FullPersistent local state backed by localStorage
usePromise✅ FullAsync execution lifecycle with mutate/revalidate
useCachedPromise✅ FullPromise caching with abortable, onWillExecute
useFetch✅ FullHTTP fetching with pagination, optimistic mutate
useForm✅ FullForm state with FormValidation enum

​
System Integration Hooks

HookStatusImplementation
useExec✅ FullCommand execution with stripFinalNewline, timeout
useSQL✅ FullSQLite queries with permissionView, full callbacks
useStreamJSON✅ FullStreaming JSON with filter/transform/dataPath/pageSize
useAI✅ FullAI streaming with onError/onData/onWillExecute
useFrecencySorting✅ FullFrecency sorting with localStorage persistence
useLocalStorage✅ FullSynchronized localStorage state with change events

​
API Functions

​
UI Functions

// All fully implemented
showToast(options: Toast.Options): Promise<Toast>
showHUD(message: string): Promise<void>
confirmAlert(options: Alert.Options): Promise<boolean>

​
Window Management

// All fully implemented
closeMainWindow(options?: { clearSearchBar?: boolean }): Promise<void>
popToRoot(options?: { clearSearchBar?: boolean }): Promise<void>
clearSearchBar(): Promise<void>

​
System Integration

FunctionStatusNotes
open✅ FullURLs and applications; supports application parameter
trash✅ FullFile deletion through main process
showInFinder✅ FullOpens Finder at file path
getSelectedText⚠️ PartialMay need macOS permissions
getSelectedFinderItems⚠️ PartialMay need macOS permissions
getApplications✅ FullApplication listing with optional directory filter
getDefaultApplication✅ FullGet default app for file path
getFrontmostApplication✅ FullActive app detection
getSelectedText and getSelectedFinderItems require macOS accessibility permissions. Users may need to grant these in System Settings.

​
Extension Management

// All fully implemented
openExtensionPreferences(): Promise<void>
openCommandPreferences(): Promise<void>
updateCommandMetadata(options: { subtitle?: string; icon?: Image.ImageLike }): Promise<void>
launchCommand(options: { name: string; type: LaunchType; ... }): Promise<void>
getPreferenceValues<T>(): T

​
Error Handling

// Fully implemented
captureException(error: Error | unknown): void  // Logs to console

​
Storage & Caching

​
LocalStorage API

// From index.tsx - Full implementation
namespace LocalStorage {
  export async function getItem<T>(key: string): Promise<T | undefined>
  export async function setItem(key: string, value: any): Promise<void>
  export async function removeItem(key: string): Promise<void>
  export async function allItems<T>(): Promise<Record<string, T>>
  export async function clear(): Promise<void>
}

​
Cache API

// From index.tsx - Full implementation
namespace Cache {
  export async function get(key: string): Promise<string | undefined>
  export async function set(key: string, value: string): Promise<void>
  export async function remove(key: string): Promise<void>
  export async function clear(): Promise<void>
}

​
Clipboard API

// From index.tsx - Full implementation
namespace Clipboard {
  export async function readText(): Promise<string | undefined>
  export async function read(): Promise<{ text?: string; file?: string }>
  export async function copy(content: string | { text?: string; file?: string; ... }): Promise<void>
  export async function paste(content: string | { text?: string; file?: string; ... }): Promise<void>
  export async function clear(): Promise<void>
}

​
AI Integration

​
AI Namespace

// From index.tsx - Full implementation
namespace AI {
  export async function ask(
    prompt: string,
    options?: {
      model?: string;
      creativity?: number | 'none' | 'low' | 'medium' | 'high' | 'maximum';
      signal?: AbortSignal;
    }
  ): Promise<string>
}
Supported backends:
  • Ollama: Local AI models
  • OpenAI: Cloud-based GPT models
  • Anthropic: Claude models
AI availability is checked via: 
environment.canAccess(AI)  // Returns boolean

​
Environment API

Full extension context is available: 
// From index.tsx
interface Environment {
  // Extension info
  extensionName: string
  commandName: string
  commandMode: 'view' | 'menu-bar' | 'no-view'
  
  // Paths
  assetsPath: string
  supportPath: string
  
  // System info
  raycastVersion: string  // Currently "1.80.0"
  appearance: 'light' | 'dark'
  theme: Theme
  
  // Feature detection
  canAccess(api: any): boolean
  
  // Launch context
  launchType: LaunchType
  launchContext?: LaunchContext
}

​
Platform-Specific APIs

​
Window Management

// From platform-runtime.ts - Full implementation
namespace WindowManagement {
  export async function getActiveWindow(): Promise<Window>
  export async function getWindowsOnActiveDesktop(): Promise<Window[]>
  export async function getDesktops(): Promise<Desktop[]>
  export async function setWindowBounds(options: SetWindowBoundsOptions): Promise<void>
  
  export enum DesktopType {
    User = 'user',
    FullScreen = 'fullscreen',
  }
}

​
AppleScript (macOS)

// From utility-runtime.ts - Full implementation
export async function runAppleScript(
  script: string,
  options?: { language?: 'AppleScript' | 'JavaScript'; humanReadableOutput?: boolean }
): Promise<string>

​
SQL Database

// From platform-runtime.ts - Full implementation
export async function executeSQL<T = unknown>(
  databasePath: string,
  query: string
): Promise<T[]>

​
Utility Functions

​
Favicon & Avatars

// From utility-runtime.ts - Full implementation
export function getFavicon(url: string, options?: { size?: number; fallback?: string }): string
export function getAvatarIcon(name: string, options?: { gradient?: boolean }): Image.ImageLike
export function getProgressIcon(progress: number, tintColor?: Color.ColorLike): Image.ImageLike

// From misc-runtime.ts - Full implementation
export function createDeeplink(options: {
  type: DeeplinkType.Extension | DeeplinkType.ScriptCommand;
  name: string;
  arguments?: Record<string, any>;
  context?: Record<string, any>;
}): string

​
Error Handling

// From utility-runtime.ts - Full implementation
export async function showFailureToast(
  error: Error | unknown,
  options?: { title?: string; primaryAction?: Action }
): Promise<Toast>

​
Caching

// From platform-runtime.ts - Full implementation
export function withCache<Fn extends (...args: any[]) => Promise<any>>(
  fn: Fn,
  options?: {
    validate?: (data: Awaited<ReturnType<Fn>>) => boolean;
    maxAge?: number;
  }
): Fn & { clearCache: () => void }

​
Icon & Image System

​
Icon Enum

Full Raycast icon mapping to Phosphor icons: 
// From icon-runtime-phosphor.tsx
export enum Icon {
  Circle,
  Checkmark,
  XMarkCircle,
  ExclamationMark,
  // ... 200+ icons mapped to Phosphor equivalents
}
See src/renderer/src/raycast-api/raycast-icon-enum.ts for the complete icon mapping (auto-generated).

​
Color Constants

// From icon-runtime-render.tsx
export enum Color {
  PrimaryText,
  SecondaryText,
  Blue,
  Green,
  Orange,
  Purple,
  Red,
  Yellow,
  Magenta,
  // ... all Raycast colors
}

​
Image Types

// From icon-runtime-render.tsx
namespace Image {
  interface FileOptions { source: string }  // File path
  interface UrlOptions { source: string; mask?: MaskType }  // URL with optional mask
  interface AssetOptions { source: string; tintColor?: Color }  // Extension asset
}

​
Stub APIs (Planned)

These APIs have typed stubs but need full implementation:

​
OAuth

// From oauth/index.ts - Basic structure in place
namespace OAuth {
  class PKCEClient {
    constructor(options: ClientOptions)
    async getTokens(): Promise<TokenResponse | undefined>
    async authorize(): Promise<TokenResponse>
    async setTokens(tokens: TokenResponse): Promise<void>
  }
  
  function withAccessToken<T>(
    options: WithAccessTokenOptions
  ): (Component: React.ComponentType<T>) => React.ComponentType<T>
}
OAuth implementation is in progress. Basic PKCE flow is functional, but provider presets need testing.

​
Browser Extension

// From platform-runtime.ts - Stub only
namespace BrowserExtension {
  async function getContent(options?: ContentOptions): Promise<string>
  async function getTabs(): Promise<Tab[]>
}
Browser extension integration requires a companion browser extension to be built. Currently returns empty defaults.

​
Platform Compatibility

Extensions can declare platform support: 
{
  "platforms": ["macOS", "Windows", "Linux"]
}
SuperCmd filters extensions based on the current platform: 
// From extension-platform.ts:38-42
export function isManifestPlatformCompatible(manifest: any): boolean {
  const supported = getManifestPlatforms(manifest);
  if (supported.length === 0) return true;  // No platform restriction
  return supported.includes(getCurrentRaycastPlatform());
}

​
TypeScript Support

Full TypeScript type definitions are provided: 
// Type exports
export type {
  Preferences,
  PreferenceValues,
  Preference,
  LaunchContext,
  LaunchProps,
  LaunchOptions,
  Application,
  FileSystemItem,
}

export enum LaunchType {
  UserInitiated = 'userInitiated',
  Background = 'background',
}

export enum PopToRootType {
  Default = 'default',
  Immediate = 'immediate',
  Suspended = 'suspended',
}

​
Testing Extensions

To verify an extension’s compatibility:
1

Check Platform Support

Verify the extension’s platforms field in package.json includes your OS
2

Review Dependencies

Check if the extension uses any APIs marked as “Stub” or “Partial” above
3

Install and Test

Install the extension and test all commands to ensure they work as expected
4

Report Issues

If you encounter incompatibilities, check the extension’s API usage and report issues with specific API calls that fail

​
API Version Tracking

SuperCmd monitors Raycast releases for API changes and updates the compatibility layer accordingly.

​
Contributing

When adding new API support:
1

Reference Official Docs

Check Raycast API Reference for official behavior
2

Implement in Runtime Modules

Add the API to the appropriate runtime file in src/renderer/src/raycast-api/
3

Add IPC Handlers if Needed

For system operations, add handlers in src/main/main.ts and src/main/preload.ts
4

Test with Real Extensions

Verify compatibility with actual Raycast extensions from the store
5

Update Documentation

Mark the API as implemented in CLAUDE.md and this compatibility page

​
Next Steps

Overview

Learn how extensions work in SuperCmd

Installing

Install and update extensions

Build docs developers (and LLMs) love

Get started for freeTalk to us