### Install @raycast/utils
Source: https://developers.raycast.com/utilities/getting-started
Installs the @raycast/utils package as a dependency for your Raycast extension. This package provides utility functions to streamline common patterns and operations.
```bash
npm install --save @raycast/utils
```
--------------------------------
### Develop and Publish Extension
Source: https://developers.raycast.com/teams/getting-started
Commands to build and publish a Raycast extension. `npm run dev` starts the development server, while `npm run publish` builds and deploys the extension to your private store.
```bash
npm run dev
```
```bash
npm run publish
```
--------------------------------
### Raycast AI APIs for Content Generation
Source: https://developers.raycast.com/ai/getting-started
Leverage Raycast's AI APIs to generate various types of content, such as summaries and translations. An example usage involves the `AI.ask(...)` function within a Quick Capture command to summarize website content.
```APIDOC
AI.ask(prompt: str, ...)
- Generates content based on the provided prompt.
- Example: Used in Notion extension's Quick Capture command to summarize websites.
```
--------------------------------
### Raycast API Introduction and Basics
Source: https://context7_llms
Guides for starting with the Raycast API, building your first extension, contributing to existing ones, and preparing extensions for the Raycast Store.
```APIDOC
Introduction:
Start building your perfect tools with the Raycast API.
Getting Started:
Covers the prerequisites you need to start building extensions.
Create Your First Extension:
Learn how to build your first extension and use it in Raycast.
Contribute to an Extension:
Learn how to import an extension to collaborate with others.
Prepare an Extension for Store:
Learn how to get through review process quickly.
Publish an Extension:
Learn how to share your extension with our community.
Debug an Extension:
Covers how to find and fix bugs in your extension.
Install an Extension:
Learn how to find and use extensions from the Raycast Store.
Review an Extension in a Pull Request:
Learn how to review a contribution from a Pull Request opened by a contributor.
```
--------------------------------
### Publish Raycast Extension
Source: https://developers.raycast.com/teams/getting-started
Run this command in the extension folder to verify, build, and publish the extension to your private Raycast extension store. The extension will only be accessible to members of your organization.
```Shell
npm run publish
```
--------------------------------
### Raycast Utils API Reference
Source: https://developers.raycast.com/utilities/getting-started
This section details various functions and hooks available in the @raycast/utils package. It covers utilities for caching, running scripts, creating deep links, managing forms, and handling data fetching with pagination and optimistic updates. It also includes OAuth utilities for authentication.
```APIDOC
getFavicon
- Respects user's setting for favicon provider.
- Note: 'Apple' provider isn't supported due to native API reliance.
runPowerShellScript
- Function to execute PowerShell scripts.
withCache
- Function to add caching capabilities.
executeSQL
- Function to execute SQL queries.
createDeeplink
- Function to create deep links.
showFailureToast
- Function to display a failure toast message.
useFrecencySorting
- Hook for frecency-based sorting.
runAppleScript
- Function to execute AppleScript.
useLocalStorage
- Hook for using local storage.
useStreamJSON
- Hook for streaming and parsing JSON data.
useFetch
- Hook for fetching data, with support for pagination, optimistic updates, and custom result mapping.
- Options include `mapResult`, `timeout`, `failureToastOptions`.
useCachedPromise
- Hook similar to `usePromise` but with caching, supporting pagination and optimistic updates.
- Options include `failureToastOptions`.
usePromise
- Hook for handling asynchronous operations, supporting optimistic updates and pagination.
- Options include `failureToastOptions`.
useForm
- Hook for managing form state, including a `reset` function.
OAuthService
- Utilities for handling OAuth authentication flows.
- Supports custom `tokenResponseParser` and `tokenRefreshResponseParser`.
- Includes built-in configurations for Slack, Google, Jira, and Zoom.
- `withAccessToken` utility for securing requests.
```
--------------------------------
### Introduce useAI hook (v1.6.0)
Source: https://developers.raycast.com/utilities/getting-started
The new useAI hook has been added, likely for integrating AI functionalities within Raycast extensions.
```typescript
useAI(): AIHook
```
--------------------------------
### Build and Run Raycast Extension
Source: https://developers.raycast.com/basics/create-your-first-extension
Instructions for building and running a Raycast extension in development mode. This involves installing dependencies and starting a development server that supports hot reloading.
```bash
npm install && npm run dev
```
--------------------------------
### Install @raycast/eslint-config
Source: https://developers.raycast.com/misc/migration/v1.48.8
Installs the new ESLint configuration package as a development dependency.
```sh
npm install @raycast/eslint-config --save-dev
```
--------------------------------
### AI Extension Instructions in package.json
Source: https://developers.raycast.com/ai/learn-core-concepts-of-ai-extensions
An example of how to define AI-specific instructions within the `package.json` file. These instructions guide the AI's behavior for the entire extension.
```json
{
"ai": {
"instructions": "When you don't know the user's first name, ask for it."
}
}
```
--------------------------------
### Introduce useExec and useForm hooks (v1.2.0)
Source: https://developers.raycast.com/utilities/getting-started
Two new hooks, useExec for executing shell commands and useForm for managing form states, have been added to the utilities.
```typescript
useExec(command: string): UseExecResult
useForm(): UseFormResult
```
--------------------------------
### Introduce useSQL hook (v1.4.0)
Source: https://developers.raycast.com/utilities/getting-started
The useSQL hook is now available, presumably for interacting with SQL databases or executing SQL queries within Raycast extensions.
```typescript
useSQL(): SQLHook
```
--------------------------------
### List All Installed Applications
Source: https://developers.raycast.com/api-reference/utilities
This example shows how to retrieve and log the names of all applications installed on the system using the `getApplications` function.
```typescript
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(", "));
}
```
--------------------------------
### Example: Fetching Brew Package Info
Source: https://developers.raycast.com/utilities/react-hooks/useexec
Demonstrates how to use the useExec hook to fetch installed package information using the brew command and display it in a Raycast List.
```TypeScript
import { List } from "@raycast/api";
import { useExec } from "@raycast/utils";
import { cpus } from "os";
import { useMemo } from "react";
const brewPath = cpus()[0].model.includes("Apple") ? "/opt/homebrew/bin/brew" : "/usr/local/bin/brew";
export default function Command() {
const { isLoading, data } = useExec(brewPath, ["info", "--json=v2", "--installed"]);
const results = useMemo(() => JSON.parse(data || "{}").formulae || [], [data]);
return (
{results.map((item) => (
))}
);
}
```
--------------------------------
### Install Extension via Web Store
Source: https://developers.raycast.com/basics/install-an-extension
Find and install extensions using the Raycast web store. Browse the store, select an extension, and follow the on-screen instructions to complete the installation within Raycast.
```APIDOC
Install Extension from Web Store:
- Navigate to the Raycast web store (raycast.com/store).
- Search for an extension.
- Click the 'Install Extension' button.
- Follow the prompts within Raycast to complete installation.
```
--------------------------------
### Raycast AI Extensions for Natural Language Interaction
Source: https://developers.raycast.com/ai/getting-started
Develop AI Extensions to enable natural language interactions within Raycast's AI Chat, AI Commands, and Quick AI features. These extensions allow users to manage tasks or retrieve information through conversational interfaces, as demonstrated by the Linear extension.
```APIDOC
AI Extension Development
- Enables natural language interactions in Quick AI, AI Chat, and AI Commands.
- Example: Linear extension allows managing issues and priorities via chat.
```
--------------------------------
### Raycast Extension Naming Conventions
Source: https://developers.raycast.com/basics/prepare-an-extension-for-store
Follows Apple Style Guide for extension and command titles. Emphasizes clarity, noun-based titles, and avoiding generic names. Provides examples for good and bad naming practices.
```APIDOC
Extension Title:
- Use clear, descriptive titles visible in the Store and preferences.
- Aim for noun-based titles (e.g., 'Emoji Search').
- Avoid generic names if the extension has few commands (e.g., 'Notion Search' instead of 'Notion').
- Consider adding context if it aids understanding (e.g., 'Airport - Discover Testflight Apps').
Command Title:
- Typically '' or ''.
- Avoid articles (e.g., 'Search Emoji' instead of 'Search an Emoji').
- Be specific about the action (e.g., 'Search Packages' instead of 'NPM').
Command Subtitle:
- Use to add context, often an app or service name.
- Helps make command titles more concise.
- Subtitles are indexed for searching.
- Do not use subtitles as descriptions or if they duplicate the command title.
```
--------------------------------
### Example CHANGELOG.md Format
Source: https://developers.raycast.com/basics/prepare-an-extension-for-store
This example demonstrates the recommended format for a `CHANGELOG.md` file, including version titles, merge dates, and bulleted lists of changes. Follow this structure to ensure your version history is displayed correctly.
```markdown
# Brew Changelog
## [Added a bunch of new feedback] - {PR_MERGE_DATE}
- Improve reliability of `outdated` command
- Add action to copy formula/cask name
- Add cask name & tap to cask details
- Add Toast action to cancel current action
- Add Toast action to copy error log after failure
## [New Additions] - 2022-12-13
- Add greedy upgrade preference
- Add `upgrade` command
## [Fixes & Bits] - 2021-11-19
- Improve discovery of brew prefix
- Update Cask.installed correctly after installation
- Fix installed state after uninstalling search result
- Fix cache check after installing/uninstalling cask
- Add uninstall action to outdated action panel
## [New Commands] - 2021-11-04
Add support for searching and managing casks
## [Added Brew] - 2021-10-26
Initial version code
```
--------------------------------
### Build and Run Extension in Development Mode
Source: https://developers.raycast.com/ai/create-an-ai-extension
After adding AI tools, navigate to your extension's directory in the terminal and run these commands to install dependencies and start the extension in development mode with hot reloading.
```bash
npm install && npm run dev
```
--------------------------------
### Action.ShowInFinder Example
Source: https://developers.raycast.com/api-reference/user-interface/actions
Provides an example of using the Action.ShowInFinder component to reveal a specified file or folder in the macOS Finder. The example targets the user's Downloads directory.
```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";
import { homedir } from "os";
const DOWNLOADS_DIR = `${homedir()}/Downloads`;
export default function Command() {
return (
}
/>
);
}
```
--------------------------------
### Simple Expectation Example
Source: https://developers.raycast.com/ai/learn-core-concepts-of-ai-extensions
A basic example demonstrating how to structure an AI expectation to verify a tool call with specific arguments.
```json
{
"ai": {
"evals": [
{
"expected": [
{
"callsTool": {
"name": "greet",
"arguments": {
"name": "thomas"
}
}
}
]
}
]
}
}
```
--------------------------------
### Access Installed Extensions
Source: https://developers.raycast.com/basics/install-an-extension
Once an extension is installed, its commands can be accessed through the main Raycast search. Further configuration is available in the Extensions preferences.
```APIDOC
Use Installed Extensions:
- Search for extension commands in the root search bar.
- Configure extensions in the Extensions preferences tab.
```
--------------------------------
### Add focus method to useForm and input option to useExec (v1.3.0)
Source: https://developers.raycast.com/utilities/getting-started
This update introduces a 'focus' method to the useForm hook for managing form focus, and adds an 'input' option to the useExec hook for passing input to executed commands.
```typescript
useForm().focus(): void
useExec(command: string, options?: { input?: string }): UseExecResult
```
--------------------------------
### Install Extension via In-app Store
Source: https://developers.raycast.com/basics/install-an-extension
Discover and install extensions directly within the Raycast application. Search for an extension, then use keyboard shortcuts to install or view details.
```APIDOC
Install Extension:
- Open the Store command in Raycast.
- Search for the desired extension.
- Press `⌘` `↵` to install.
- Press `↵` to view details.
```
--------------------------------
### Raycast Extension Examples
Source: https://context7_llms
Examples demonstrating various functionalities, including data collection forms, RSS feeds, list management, and bundling multiple scripts.
```APIDOC
Doppler Share Secrets:
Uses a simple form to collect data.
Hacker News:
Shows how to show an RSS feed as a List.
Todo List:
Shows how to use lists in combination with forms.
Spotify Controls:
Shows how to bundle multiple scripts into a single extension.
```
--------------------------------
### Example Tool Confirmation
Source: https://developers.raycast.com/api-reference/tool
Provides a practical example of implementing a `Tool.Confirmation` in TypeScript for a Raycast extension. This confirmation prompts the user before greeting them.
```typescript
import { Tool } from "@raycast/api";
type Input = {
/**
* The first name of the user to greet
*/
name: string;
};
export const confirmation: Tool.Confirmation = (input) => {
return {
message: `Are you sure you want to greet ${input.name}?`,
};
};
```
--------------------------------
### Raycast Migration Guides
Source: https://context7_llms
Guides for migrating Raycast extensions between different versions.
```APIDOC
Migration Guides:
- Provides specific instructions for migrating extensions to newer Raycast versions.
- Includes details for versions like v1.28.0, v1.31.0, v1.37.0, v1.42.0, v1.48.8, v1.50.0, v1.51.0, and v1.59.0.
```
--------------------------------
### Raycast MenuBarExtra Example
Source: https://developers.raycast.com/api-reference/menu-bar-commands
A TypeScript example demonstrating how to use the MenuBarExtra component to create menu bar items with sections and actions, such as opening URLs.
```typescript
import { Icon, MenuBarExtra, open } from "@raycast/api";
const data = {
archivedBookmarks: [{ name: "Google Search", url: "www.google.com" }],
newBookmarks: [{ name: "Raycast", url: "www.raycast.com" }],
};
export default function Command() {
return (
{data?.newBookmarks.map((bookmark) => (
open(bookmark.url)} />
))}
{data?.archivedBookmarks.map((bookmark) => (
open(bookmark.url)} />
))}
);
}
```
--------------------------------
### Add getFavicon method (v1.1.0)
Source: https://developers.raycast.com/utilities/getting-started
The getFavicon method has been introduced, likely used for fetching favicons for websites.
```typescript
getFavicon(url: string): Promise
```
--------------------------------
### Handling Binary Dependencies in Raycast Extensions
Source: https://developers.raycast.com/basics/prepare-an-extension-for-store
Guidelines for downloading and using binary dependencies within Raycast extensions. Emphasizes security, integrity checks, and avoiding opaque binaries.
```English
✅ Calling known system binaries
✅ Binary downloaded or installed from a trusted location with additional integrity checking through hashes (that is, verify whether the downloaded binary really matches the expected binary)
✅ Binary extracted from an npm package and copied to assets, with traceable sources how the binary is built; note: we have yet to integrate CI actions for copying and comparing the files; meanwhile, ask a member of the Raycast team to add the binary for you
❌ Any binary with unavailable sources or unclear builds just added to the assets folder
```
--------------------------------
### Get Frontmost Application
Source: https://developers.raycast.com/api-reference/utilities
This example retrieves and logs the name of the currently active (frontmost) application using the `getFrontmostApplication` function.
```typescript
import { getFrontmostApplication } from "@raycast/api";
export default async function Command() => {
const frontmostApplication = await getFrontmostApplication();
console.log(`The frontmost application is: ${frontmostApplication.name}`);
};
```
--------------------------------
### Add reset method to useForm (v1.3.1)
Source: https://developers.raycast.com/utilities/getting-started
The useForm hook has been enhanced with a 'reset' method, allowing developers to easily reset form states.
```typescript
useForm().reset(): void
```
--------------------------------
### Dependency Management and Build Process
Source: https://developers.raycast.com/basics/prepare-an-extension-for-store
Details the process for managing dependencies using npm and ensuring reproducible builds with `package-lock.json`. It also covers running distribution builds and linting for Raycast extensions.
```bash
npm install
npm run build
npm run lint
```
--------------------------------
### AI File Configuration (JSON5)
Source: https://developers.raycast.com/ai/learn-core-concepts-of-ai-extensions
Example of configuring AI instructions in a separate `ai.json5` file, which allows for comments and more flexible syntax.
```json5
{
instructions: "When you don't know the user's first name, ask for it.",
}
```
--------------------------------
### AI File Configuration (JSON)
Source: https://developers.raycast.com/ai/learn-core-concepts-of-ai-extensions
Example of configuring AI instructions in a separate `ai.json` file.
```json
{
"instructions": "When you don't know the user's first name, ask for it."
}
```
--------------------------------
### Update getProgressIcon signature (v1.7.0)
Source: https://developers.raycast.com/utilities/getting-started
The getProgressIcon function now accepts a Color object in addition to a string for its color parameter, providing more flexibility in icon styling.
```typescript
getProgressIcon(color: Color | string): React.ReactNode
```
--------------------------------
### Get Default Application for a File
Source: https://developers.raycast.com/api-reference/utilities
This example retrieves and logs the name of the default application used to open a given file path, utilizing the `getDefaultApplication` function.
```typescript
import { getDefaultApplication } from "@raycast/api";
export default async function Command() {
const defaultApplication = await getDefaultApplication(__filename);
console.log(`Default application for JavaScript is: ${defaultApplication.name}`);
}
```
--------------------------------
### Find Application by Bundle ID
Source: https://developers.raycast.com/api-reference/utilities
This example demonstrates how to find a specific application using its bundle ID by filtering the list of all installed applications obtained via `getApplications`.
```typescript
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);
}
```
--------------------------------
### Raycast CLI Help
Source: https://developers.raycast.com/information/developer-tools/cli
Displays a list of available Raycast CLI commands. This is the entry point for understanding the CLI's capabilities.
```bash
npx ray help
```
--------------------------------
### Initialize OAuthService with PKCEClient
Source: https://developers.raycast.com/utilities/oauth/oauthservice
Demonstrates how to initialize the PKCEClient and then use it to create an instance of the OAuthService for GitHub integration.
```typescript
const client = new OAuth.PKCEClient({
redirectMethod: OAuth.RedirectMethod.Web,
providerName: "GitHub",
providerIcon: "extension_icon.png",
providerId: "github",
description: "Connect your GitHub account",
});
const github = new OAuthService({
client,
clientId: "7235fe8d42157f1f38c0",
scope: "notifications repo read:org read:user read:project",
authorizeUrl: "https://github.oauth.raycast.com/authorize",
tokenUrl: "https://github.oauth.raycast.com/token",
});
```
--------------------------------
### AI File Configuration (YAML)
Source: https://developers.raycast.com/ai/learn-core-concepts-of-ai-extensions
Example of configuring AI instructions in a separate `ai.yaml` file, offering potentially better readability for longer content.
```yaml
instructions: |
When you don't know the user's first name, ask for it.
```
--------------------------------
### Initialize PKCE Client
Source: https://developers.raycast.com/api-reference/oauth
Creates a new OAuth PKCE client instance, configuring it with a redirect method, provider name, icon, and description for the OAuth overlay.
```typescript
import { OAuth } from "@raycast/api";
const client = new OAuth.PKCEClient({
redirectMethod: OAuth.RedirectMethod.Web,
providerName: "Twitter",
providerIcon: "twitter-logo.png",
description: "Connect your Twitter account…",
});
```
--------------------------------
### Clone and Test Extension from Pull Request
Source: https://developers.raycast.com/basics/review-pullrequest
This snippet demonstrates how to clone a specific branch and directory of a forked Raycast extension repository. It then navigates into the extension's directory, installs its dependencies using npm, and starts the development server, allowing for local testing of the extension.
```bash
BRANCH="ext/soundboard"
FORK_URL="https://github.com/pernielsentikaer/raycast-extensions.git"
EXTENSION_NAME="soundboard"
git clone -n --depth=1 --filter=tree:0 -b ${BRANCH} ${FORK_URL}
cd raycast-extensions
git sparse-checkout set --no-cone "extensions/${EXTENSION_NAME}"
git checkout
cd "extensions/${EXTENSION_NAME}"
npm install && npm run dev
```
--------------------------------
### OAuth PKCEClient Initialization
Source: https://developers.raycast.com/api-reference/oauth
Shows how to initialize the OAuth.PKCEClient with specific options, including the redirect method, provider name, icon, and a description for the OAuth overlay.
```typescript
import { OAuth } from "@raycast/api";
const client = new OAuth.PKCEClient({
redirectMethod: OAuth.RedirectMethod.Web,
providerName: "Twitter",
providerIcon: "twitter-logo.png",
description: "Connect your Twitter account…",
});
```
--------------------------------
### Raycast Extension Development Prerequisites
Source: https://developers.raycast.com/basics/getting-started
Lists the essential software and knowledge required to begin developing Raycast extensions. This includes specific versions of Raycast, Node.js, and npm, as well as a foundational understanding of React and TypeScript.
```markdown
# Getting Started
## 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 [Node.js](https://nodejs.org) 22.14 or higher installed. We recommend [nvm](https://github.com/nvm-sh/nvm) to install Node.
* You have [npm](http://npmjs.com) 7 or higher
* You are familiar with [React](https://reactjs.org) and [TypeScript](https://www.typescriptlang.org). Don't worry, you don't need to be an expert. If you need some help with the basics, check out TypeScript's [Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) and React's [Getting Started](https://react.dev/learn) 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
* **Manage Extensions**: List and edit your published extensions
```
--------------------------------
### Image.URL Example
Source: https://developers.raycast.com/api-reference/user-interface/icons-and-images
Provides a simple example of using a URL as an image source in a Raycast List.Item.
```typescript
Image is a string representing a URL.
import { List } from "@raycast/api";
export default function Command() {
return (
);
}
```
--------------------------------
### Publishing Raycast Extension (Bash)
Source: https://developers.raycast.com/information/developer-tools/cli
Run `npx ray publish` to perform verification, building, and publishing steps for your Raycast extension; this command handles publishing to the public store or a private organization store based on the extension's configuration.
```bash
npx ray publish
```
--------------------------------
### Adding Screenshots with Raycast 1.37.0+
Source: https://developers.raycast.com/basics/prepare-an-extension-for-store
Raycast version 1.37.0 and later simplifies the process of capturing high-quality screenshots for your extensions. This involves setting up window capture and using a hotkey to save screenshots directly to your extension's metadata.
```markdown
In Raycast 1.37.0+ we made it easy for you to take beautiful pixel perfect screenshots of your extension with an ease.
#### How to use it?
1. Set up Window Capture in Advanced Preferences (Hotkey e.g.: `⌘⇧⌥+M`)
2. Ensure your extension is opened in development mode (Window Capture eliminates dev-related menus/icons).
3. Open the command
4. Press the hotkey, remember to tick `Save to Metadata`
```
--------------------------------
### React Suspense Example in Raycast
Source: https://developers.raycast.com/misc/migration/v1.37.0
Demonstrates how to use React Suspense within a Raycast extension. It utilizes a custom `usePromise` hook to handle asynchronous operations, such as fetching data from an API (Twitter in this example), and integrates with Raycast's `List` component to display results. The example also includes a logout action.
```jsx
import { List, Toast, showToast, ActionPanel, Action, Icon, popToRoot } from "@raycast/api";
import { useState, useCallback } from "react";
import * as twitter from "./oauth/twitter";
// a hook that suspends until a promise is resolved
import { usePromise } from "./suspense-use-promise";
const promise = async (search: string) => {
try {
await twitter.authorize();
return await twitter.fetchItems(search);
} catch (error) {
console.error(error);
showToast({ style: Toast.Style.Failure, title: String(error) });
return [];
}
};
export default function Command() {
const [search, setSearch] = useState("");
const items = usePromise(promise, [search]);
const logout = useCallback(() => {
twitter.logout();
popToRoot();
}, []);
const actionPanel = (
);
// no need to set the `isLoading` prop, Raycast will set it automatically
// until the React application isn't suspended anymore
return (
{items.map((item) => {
return (
);
})}
);
}
```
--------------------------------
### Initialize SDK with onAuthorize Callback
Source: https://developers.raycast.com/utilities/oauth
Demonstrates using the `onAuthorize` callback to initialize a third-party SDK, such as the Linear client. This allows the SDK instance to be shared across the codebase.
```tsx
import { OAuthService } from "@raycast/utils";
import { LinearClient, LinearGraphQLClient } from "@linear/sdk";
let linearClient: LinearClient | null = null;
export const linear = OAuthService.linear({
scope: "read write",
onAuthorize({ token }) {
linearClient = new LinearClient({ accessToken: token });
},
});
export function withLinearClient(Component: React.ComponentType) {
return withAccessToken(linear)(Component);
}
export function getLinearClient(): { linearClient: LinearClient; graphQLClient: LinearGraphQLClient } {
if (!linearClient) {
throw new Error("No linear client initialized");
}
return { linearClient, graphQLClient: linearClient.client };
}
```
--------------------------------
### Action.Paste Usage Example
Source: https://developers.raycast.com/api-reference/user-interface/actions
Provides an example of using Action.Paste to insert content into the front-most application. The action closes the main window after pasting.
```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";
export default function Command() {
return (
}
/>
);
}
```
--------------------------------
### Raycast Extension Categories
Source: https://developers.raycast.com/basics/prepare-an-extension-for-store
Lists and describes various categories for Raycast extensions, providing examples for each to help developers classify their extensions appropriately. Categories are case-sensitive and follow Title Case.
```APIDOC
Category Name: Applications
Description: Extensions related to specific applications.
Example: Cleanshot X – Capture and record your screen
Category Name: Communication
Description: Extensions for communication tools.
Example: Slack Status – Quickly change your Slack status.
Category Name: Data
Description: Extensions for data generation or manipulation.
Example: Random Data Generator – Generate random data using Faker library.
Category Name: Documentation
Description: Extensions that help access or search documentation.
Example: Tailwind CSS Documentation – Quickly search Tailwind CSS documentation and open it in the browser.
Category Name: Design Tools
Description: Extensions for design software or workflows.
Example: Figma File Search – Lists Figma files allowing you to search and navigate to them.
Category Name: Developer Tools
Description: Extensions useful for developers.
Example: Brew – Search and install Homebrew formulae.
Category Name: Finance
Description: Extensions related to financial management or data.
Example: Coinbase Pro – View your Coinbase Pro portfolio.
Category Name: Fun
Description: Extensions for entertainment or casual use.
Example: 8 Ball – Returns an 8 ball like answer to questions.
Category Name: Media
Description: Extensions for media consumption or management.
Example: Unsplash – Search images or collections on Unsplash, download, copy or set them as wallpaper without leaving Raycast.
Category Name: News
Description: Extensions for accessing news feeds.
Example: Hacker News – Read the latest stories of Hacker News.
Category Name: Productivity
Description: Extensions to enhance productivity.
Example: Todoist – Check your Todoist tasks and quickly create new ones.
Category Name: Security
Description: Extensions related to security tools or practices.
Example: 1Password 7 – Search, open or edit your 1Password 7 passwords from Raycast.
Category Name: System
Description: Extensions for system-level operations.
Example: Coffee – Prevent the sleep function on your mac.
Category Name: Web
Description: Extensions for web browsing or services.
Example: Wikipedia – Search Wikipedia articles and view them.
Category Name: Other
Description: For extensions that do not fit into other categories.
```
--------------------------------
### Detail.Metadata.Label Component Example
Source: https://developers.raycast.com/api-reference/user-interface/detail
Shows an example of using Detail.Metadata.Label to display a single value with an optional icon within the metadata section of a Detail view.
```typescript
import { Detail } from "@raycast/api";
// Define markdown here to prevent unwanted indentation.
const markdown = "\n";
```
--------------------------------
### Raycast API Documentation
Source: https://developers.raycast.com/api-reference/utilities
Provides details on Raycast API functions and types. Includes parameters, return values, and usage examples for functions like 'open' and 'captureException'. Defines the 'Application' type for specifying applications.
```APIDOC
#### 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
```typescript
async function open(target: string, application?: Application | string): Promise;
```
#### Example
```typescript
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`](#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
```typescript
function captureException(exception: unknown): void;
```
#### Example
```typescript
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 |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| 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`](#application) |
## 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](#getapplications) or [getDefaultApplication](#getdefaultapplication) to get applications that can open a specific file or folder.
```
--------------------------------
### Action.Trash Example
Source: https://developers.raycast.com/api-reference/user-interface/actions
Provides an example of using Action.Trash to move a file to the trash. It uses the Detail component to display a message and the ActionPanel to include the trash action.
```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";
import { homedir } from "os";
const FILE = `${homedir()}/Downloads/get-rid-of-me.txt`;
export default function Command() {
return (
}
/>
);
}
```
--------------------------------
### Nested Expectations Example
Source: https://developers.raycast.com/ai/learn-core-concepts-of-ai-extensions
Illustrates nested expectations for AI evaluations, showing how to check tool calls with nested arguments that themselves use matchers.
```json
{
"ai": {
"evals": [
{
"expected": [
{
"callsTool": {
"name": "create-comment",
"arguments": {
"issueId": "ISS-1",
"body": {
"includes": "waiting for design"
}
}
}
}
]
}
]
}
}
```
--------------------------------
### Raycast List Dropdown Example
Source: https://developers.raycast.com/api-reference/user-interface/list
Demonstrates how to create a Raycast List with a dropdown menu containing sections and items. This example showcases the structure for organizing selectable options.
```typescript
import { List } from "@raycast/api";
export default function Command() {
return (
}
>
);
}
```
--------------------------------
### Raycast Action.OpenInBrowser Example
Source: https://developers.raycast.com/api-reference/user-interface/actions
Provides an example of using the Action.OpenInBrowser component in Raycast to open a URL in the default browser. The main window is closed after the URL is opened.
```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";
export default function Command() {
return (
}
/>
);
}
```
--------------------------------
### InterExtensionLaunchOptions API Documentation
Source: https://developers.raycast.com/api-reference/command
Defines the structure for launching commands from one Raycast extension to another, including necessary identifiers and optional data payloads.
```APIDOC
InterExtensionLaunchOptions:
extensionName: string (*)
- When launching command from a different extension, the extension name (as defined in the extension's manifest) is necessary
name: string (*)
- Command name as defined in the extension's manifest
ownerOrAuthorName: string (*)
- When launching command from a different extension, the owner or author (as defined in the extension's manifest) is necessary
type: LaunchType (*)
- LaunchType.UserInitiated or LaunchType.Background
arguments: Arguments or null
- Optional object for the argument properties and values as defined in the extension's manifest, for example: { "argument1": "value1" }
context: LaunchContext or null
- Arbitrary object for custom data that should be passed to the command and accessible as LaunchProps; the object must be JSON serializable (Dates and Buffers supported)
fallbackText: string or null
- Optional string to send as fallback text to the command
```