Skip to main content
Script Commands let you execute scripts from anywhere on your desktop with just a few keystrokes. They’re perfect for automating everyday tasks like converting data, opening bookmarks, or triggering development workflows.

​
Creating Your First Script Command

Raycast includes a built-in creator that helps you get started quickly.
1

Use the Create Script Command

Open Raycast and search for “Create Script Command”. This will guide you through creating a new script.
2

Choose Your Language

Select from supported languages:
  • Bash
  • Python
  • JavaScript/Node.js
  • Swift
  • Ruby
  • PHP
  • AppleScript
  • C#/.NET
3

Edit Your Script

Open the generated script file in your favorite code editor and customize it.
4

Run Your Script

Return to Raycast and search for your script by its title to execute it.
If you’re writing Bash scripts, we highly recommend using ShellCheck to catch syntax errors and ensure smooth execution.

​
File Structure

A Script Command is a standard executable script file with special metadata comments at the top. Here’s the basic structure: 
#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title My First Script
# @raycast.mode fullOutput

# Optional parameters:
# @raycast.icon 🤖
# @raycast.packageName Raycast Scripts

echo "Hello from My First Script"

​
Shebang Lines

The shebang line (first line starting with #!) tells the system how to execute your script. Use the appropriate shebang for your language:
LanguageShebang
Bash#!/bin/bash
Python#!/usr/bin/env python3
JavaScript#!/usr/bin/env node
Swift#!/usr/bin/swift
Ruby#!/usr/bin/env ruby
PHP#!/usr/bin/env php
AppleScript#!/usr/bin/osascript
C#/.NET#!/usr/bin/env dotnet
For login shell execution in Bash, you can add the -l flag: #!/bin/bash -lRaycast automatically appends /usr/local/bin to the $PATH variable, but you can extend it by adding export PATH='/some/extra/path:$PATH' at the top of your script.

​
Metadata Comments

Metadata is defined using special comments:
  • Use # for Bash, Python, Ruby, and PHP
  • Use // for JavaScript, Swift, and C#
All metadata parameters start with @raycast. and follow the format: 
# @raycast.parameterName value

​
Required Metadata

Every script command must include these three parameters:
​
schemaVersion
number
required
Schema version for future API compatibility. Currently, only version 1 is available.
# @raycast.schemaVersion 1
​
title
string
required
Display name shown in Raycast’s root search.
# @raycast.title My First Script
​
mode
string
required
How the script executes and presents output. Options: silent, compact, fullOutput, or inline.
# @raycast.mode fullOutput
Learn more in Output Modes.

​
Installing Script Directories

To make your scripts available in Raycast:
1

Open Raycast Preferences

Navigate to the Extensions tab.
2

Add Script Directory

Click the plus button and select “Add Script Directory”.
3

Select Your Directory

Choose the directory containing your Script Commands.
Scripts with .template. in the filename won’t appear in Raycast. Remove this from the filename once you’ve configured any required values.

​
Error Handling

If your script exits with a non-zero status code, Raycast displays an error toast. For inline and compact modes, the last line of output becomes the error message: 
if ! [[ $value =~ $regex ]] ; then
  echo "Invalid value provided"
  exit 1
else
  # Process the value
fi

​
Next Steps

Metadata Reference

Explore all available metadata parameters

Output Modes

Learn about different output presentation modes

Arguments

Add custom input fields to your scripts

Templates

Start from ready-made templates

Build docs developers (and LLMs) love

Get started for freeTalk to us