Skip to main content
Get up and running with Script Commands quickly. This guide walks you through installation, setup, and running your first script.

​
Prerequisites

Before you begin, make sure you have:
  • Raycast version 0.29 or later installed (Download Raycast)
  • Basic familiarity with your terminal and file system

​
Installation

1

Create a script directory

First, create a directory to store your script commands. You can place this anywhere, but we recommend keeping it organized:
mkdir -p ~/raycast-scripts
cd ~/raycast-scripts
It’s better to create your own directory rather than pointing directly to community script folders. This prevents unexpected scripts from appearing in Raycast when the repository is updated.
2

Choose a script from the repository

Browse the community script commands and save one to your new directory.For your first script, let’s try a simple one. Create a file called caffeinate-status.sh:
caffeinate-status.sh
#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Caffeinate
# @raycast.mode inline
# @raycast.packageName System
# @raycast.refreshTime 30s
#
# Optional parameters:
# @raycast.icon ☕️
# @raycast.needsConfirmation false
#
# Documentation:
# @raycast.description Shows caffeinate status
# @raycast.author Yan Smaliak
# @raycast.authorURL https://github.com/ysmaliak

caffeinate_ps=$(ps aux | grep '\d caffeinate')

if [ -z "$caffeinate_ps" ]
then
    echo "Caffeinate is not active"
else
    echo "Caffeinate is running"
fi
Make the script executable:
chmod +x caffeinate-status.sh
Scripts with .template. in the filename require configuration before use. Avoid these for your first installation.
3

Add the script directory to Raycast

Now connect your script directory to Raycast:
  1. Open Raycast and navigate to Extensions (or press ⌘, for Preferences, then click Extensions)
  2. Click the + button in the top-right corner
  3. Select Add Script Directory
  4. Navigate to and select your raycast-scripts folder
  5. Click Add
Adding a script directory in Raycast
4

Run your first script

Open Raycast (⌘ Space by default) and type “Caffeinate” to find your script.Since this script uses inline mode with a 30-second refresh interval, it will display the caffeinate status directly in the search results and update automatically every 30 seconds.Press Return to pin it to your favorites for quick access.

​
Understanding Script Metadata

The script you just installed contains metadata that tells Raycast how to display and execute it. Let’s break down the key parameters:
ParameterPurposeExample
schemaVersionAPI version (currently always 1)1
titleDisplay name in RaycastCaffeinate
modeHow the script displays outputinline, compact, fullOutput, silent
packageNameCategory grouping for the scriptSystem
iconEmoji or image for visual identification☕️
refreshTimeAuto-refresh interval for inline mode30s, 5m, 1h
All metadata is defined using special comment syntax (# @raycast.parameterName value). This keeps configuration simple and readable.

​
Try More Examples

Now that you have the basics down, try these popular script commands:

Network Status

Display your current WiFi connection and internet statusMode: inline • Location: commands/system/network-status.sh

Hex to RGB

Convert hex color codes to RGB valuesMode: silent • Location: commands/conversions/hex-to-rgb.sh

Search GitHub

Quick search GitHub repositories from anywhereMode: silent • Location: commands/web-searches/search-github.sh

Copy Last Screenshot

Instantly copy your most recent screenshot to clipboardMode: silent • Location: commands/system/copy-last-screenshot.swift

​
Output Modes Explained

Script Commands support four different output modes to suit different use cases:

​
Silent Mode

Perfect for instant actions that don’t need feedback. The script runs, performs its task, and shows a brief HUD notification when complete. 
# @raycast.mode silent
Best for: Opening URLs, copying to clipboard, triggering system actions

​
Compact Mode

Shows the last line of output in a toast notification. Great for quick confirmations or status messages. 
# @raycast.mode compact
Best for: Quick status checks, simple confirmations, brief messages

​
Full Output Mode

Displays the complete script output in a dedicated window, similar to a terminal. Ideal when you need to see detailed information or logs. 
# @raycast.mode fullOutput
Best for: Detailed information, multiple items, formatted output, terminal-like interactions

​
Inline Mode

Shows the first line of output directly in the Raycast search results. Automatically refreshes based on your refreshTime setting, making it perfect for dashboard widgets. 
# @raycast.mode inline
# @raycast.refreshTime 1m
Best for: Status indicators, live data, dashboard widgets
Inline mode requires a refreshTime parameter. Without it, Raycast will default to compact mode instead.

​
Adding Custom Arguments

Many scripts accept arguments to make them more flexible. For example, the Hex to RGB converter accepts a color value: 
# @raycast.argument1 { "type": "text", "placeholder": "#RRGGBB" }
When you run this script, Raycast will prompt you to enter a hex color value before executing. Scripts can have up to 3 arguments with different types:
  • text: Free-form text input
  • password: Secure password entry
  • dropdown: Selection from predefined options
Learn more about arguments in the Creating Commands section.

​
Troubleshooting

Common causes:
  • Filename contains .template. (remove it or configure required values)
  • Missing required metadata parameters (schemaVersion, title, mode)
  • Incorrect comment syntax (must use # for shell scripts, // for others)
  • Script isn’t executable (run chmod +x script-name.sh)
Try starting with a template from the repository to ensure proper structure.
Check these common issues:
  • Script has proper shebang line (#!/bin/bash)
  • All required dependencies are installed
  • File paths are correct and accessible
  • For shell scripts, validate with ShellCheck
Raycast runs scripts in a non-login shell with limited $PATH. To fix:
  • Add full paths to commands (e.g., /usr/local/bin/npm)
  • Extend $PATH at the top of your script: export PATH='/custom/path:$PATH'
  • Use shebang arguments for login shell: #!/bin/bash -l (not recommended for community scripts)
Note that /usr/local/bin is automatically included in $PATH.
Verify:
  • refreshTime parameter is set correctly
  • Refresh interval is at least 10 seconds (minimum allowed)
  • Script returns output quickly (long-running scripts may timeout)
  • You have fewer than 10 inline scripts (only first 10 auto-refresh)
Try navigating to the script and pressing Return to manually refresh.

​
Next Steps

Create Your Own Script

Learn how to write custom script commands from scratch

Browse Community Scripts

Explore hundreds of ready-to-use scripts

Understand Output Modes

Master the different ways to display script results

Add Arguments

Make your scripts interactive with custom inputs
Need help? Join the Raycast community on Slack to connect with other users and get support.

Build docs developers (and LLMs) love

Get started for freeTalk to us