Raycast

December 17, 2025 2 min read

Raycast Configuration Reference

Core Features

Feature	Purpose	Access
Script Commands	Custom scripts (Bash, Python, Node.js)	Extensions → Script Commands
Quicklinks	Fast access to URLs, files, folders	Create Quicklink command
Snippets	Text expansion with keywords	Create Snippet command
Extensions	React/TypeScript apps	Raycast Store or custom
AI Commands	Custom AI prompts	Raycast AI (Pro)

Script Commands

Custom scripts that run from Raycast. Supports Bash, Python, Node.js, Swift, AppleScript.

Setup

Create a scripts folder: mkdir ~/scripts
Raycast → Settings → Extensions → Script Commands → Add Directories
Run “Reload Script Directories” command

Script Template

#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title My Command
# @raycast.mode silent

# Optional parameters:
# @raycast.icon 🚀
# @raycast.packageName My Tools
# @raycast.description What this script does
# @raycast.author Your Name

# Optional arguments (max 3):
# @raycast.argument1 { "type": "text", "placeholder": "query" }

echo "Hello $1"

Required Parameters

Parameter	Description
`@raycast.schemaVersion`	Always `1`
`@raycast.title`	Command name in Raycast
`@raycast.mode`	Output mode (see below)

Modes

Mode	Behavior
`silent`	Runs silently, no output shown
`compact`	Shows toast notification
`fullOutput`	Opens separate view with output
`inline`	Shows output in root search

Optional Parameters

Parameter	Description
`@raycast.icon`	Emoji or image path
`@raycast.packageName`	Group name (subtitle)
`@raycast.description`	Command description
`@raycast.refreshTime`	Auto-refresh for inline mode (`10s`, `1m`, `1h`, `1d`)

Arguments

Up to 3 arguments, accessed as $1, $2, $3:

# @raycast.argument1 { "type": "text", "placeholder": "Search term" }
# @raycast.argument2 { "type": "dropdown", "placeholder": "Engine", "data": [{"title": "Google", "value": "google"}, {"title": "DuckDuckGo", "value": "ddg"}] }

Type	Description
`text`	Standard text input
`password`	Masked input for secrets
`dropdown`	Selection from options

Option	Description
`placeholder`	Input hint text
`optional`	`true` to make optional
`percentEncoded`	URL-encode the value
`data`	Array of `{title, value}` for dropdown

Quicklinks

Fast shortcuts to URLs, files, or folders.

Create

Search “Create Quicklink” in Raycast
Enter URL/path with optional {query} placeholder
Assign name, icon, and optional hotkey

Dynamic Placeholders

https://google.com/search?q={query}
https://github.com/search?q={argument name="search"}

Placeholder	Description
`{query}`	User input
`{argument name="x"}`	Named argument
`{clipboard}`	Current clipboard
`{selection}`	Selected text

Snippets

Text expansion triggered by keywords.

Create

Search “Create Snippet” in Raycast
Enter text content
Set keyword for auto-expansion (e.g., !email)

Placeholders

Placeholder	Description
`{cursor}`	Cursor position after expansion
`{clipboard}`	Paste clipboard content
`{date}`	Current date
`{date +2d}`	Date + 2 days
`{time}`	Current time

Extensions

Full React/TypeScript applications.

Quick Start

# In Raycast: "Create Extension" command
# Then in terminal:
cd my-extension
npm install && npm run dev

Project Structure

my-extension/
├── package.json          # Manifest with commands, preferences
├── src/
│   └── index.tsx         # Main entry point
└── assets/               # Icons and images

package.json Commands

{
  "name": "my-extension",
  "title": "My Extension",
  "commands": [
    {
      "name": "index",
      "title": "My Command",
      "subtitle": "My Extension",
      "description": "Does something useful",
      "mode": "view"
    }
  ]
}

Keyboard Shortcuts

Global

Shortcut	Action
`⌥ Space`	Open Raycast (default)
`⌘ ,`	Open Preferences
`⌘ K`	Show actions for selected item
`⌘ ⇧ ,`	Open extension preferences

In Raycast

Shortcut	Action
`↑/↓`	Navigate results
`↵`	Execute command
`⌘ ↵`	Execute with options
`⎋`	Close/go back
`Tab`	Autocomplete

Settings & Data

Export/Import

Export: Search “Export Settings & Data” → creates .rayconfig file
Import: Search “Import Settings & Data” → select .rayconfig file

Includes: extensions, hotkeys, aliases, snippets, quicklinks, preferences

Preferences Location

~/Library/Application Support/com.raycast.macos/

Quick Reference

Feature	Location	Format
Scripts	`~/scripts/` (custom)	`.sh`, `.py`, `.js`, etc.
Extensions	`~/Library/...`	React/TypeScript
Quicklinks	In-app	URL/path
Snippets	In-app	Text + keyword
Settings	Raycast Preferences	GUI
Export	`.rayconfig` file	JSON

dev