Raycast Script Commands in 2026: Getting Started on a Mac

A Raycast script command is an ordinary script file on your Mac, plus a few comment lines in its header that tell Raycast its name and how to show its output. Run Create Script Command in Raycast, pick a language, save the file in a folder Raycast watches, and the script appears in Raycast's search like any other command, ready for a hotkey.

Script commands are for the small chores you already do by hand ten times a week: opening the same three apps, making a dated notes file, checking how much disk space is left. You don't need to build a full Raycast extension or learn its developer tools. If you can write a few lines of Bash or AppleScript, or copy them, you can have a working command in five minutes. This guide covers the setup, the metadata lines that matter, the four output modes, arguments, hotkeys, and how to rescue a script that won't show up or can't find its tools.

What is a Raycast script command?

A Raycast script command is a local script file that Raycast indexes and runs from its search bar, without opening Terminal. Raycast's Script Commands manual page lists Bash, Python, Ruby, Swift, AppleScript, Node.js, PowerShell and C# among the languages you can use. Raycast reads the script's header comments (lines starting with @raycast.) to get its title, icon, output style and any inputs it should ask for.

The difference from a Raycast extension is weight. An extension is a full app built with Raycast's developer tools and shows its own lists and forms. A script command is one file you can open in any text editor, and it lives on your disk, not in the Raycast Store. When I just want one button for one job, a script command is almost always the right size.

How to create your first script command

You create a script command from inside Raycast, which writes the file and its header for you. The steps below follow Raycast's manual.

1. Make a folder for your scripts first, for example ~/Scripts/Raycast in Finder. Keeping them in one place makes them easy to back up or put in Git.
2. Tell Raycast about the folder: open Raycast's settings, go to Script Commands, click Add Script Directory and choose it.
3. Open Raycast with its hotkey, type Create Script Command and press Return.
4. Choose a language template, such as Bash, Python or AppleScript, and give the command a title.
5. Save the file into your scripts folder.
6. Open the new file in your editor (TextEdit works; a code editor is nicer), write the commands under the header, and save.
7. Search for the script's title in Raycast and press Return to run it.

Raycast picks up edits to the header without a restart, according to the manual, so you can tweak the title or mode and try again straight away.

My first one was the dullest possible job, and I still run it every workday. Every morning I opened Mail, Calendar and the team calendar in a browser tab, in that order. Now one command does it:

#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Start Workday
# @raycast.mode silent

# Optional parameters:
# @raycast.icon ☀️
# @raycast.packageName Work

open -a "Mail"
open -a "Calendar"
open "https://calendar.google.com"
echo "Workday apps are open"

The open command is built into macOS: -a opens an app by name, and a URL opens in your default browser. Because the mode is silent, Raycast closes and shows the last line, "Workday apps are open", as a small HUD message.

The metadata lines every script command needs

Every script command needs three header lines: @raycast.schemaVersion, @raycast.title and @raycast.mode. Without them the script won't appear in Raycast, and the script-commands repo puts that at the head of its troubleshooting list. Each line is a comment, so it starts with # in Bash, Python and Ruby, or // in languages that use that comment style.

The full list, with the Raycast version that added each field, is in the script-commands README. Two of the optional ones earn their place quickly. packageName keeps a growing collection readable: twelve scripts all labeled "Work" or "Finder" are far easier to scan than twelve labeled with whatever folder they sit in. And currentDirectoryPath saves you from writing full paths everywhere; Raycast's manual says it accepts absolute paths, paths relative to the script and paths starting with ~.

Which output mode should you use?

The mode decides what you see after the script runs. Raycast has four, described in the repo's output modes page, and picking the right one is most of what makes a script command feel finished.

A rule of thumb that holds up: if the script's job is to open something, use silent; if its job is to tell you something short, use compact; if the answer is longer than a line, use fullOutput. Save inline for a number you want to see without running anything.

Inline commands and refreshTime

An inline command needs @raycast.refreshTime, and if you leave it out Raycast quietly treats the script as compact instead, per the output modes page. Only 10 inline commands refresh on their own; any beyond that have to be refreshed by hand. Mark an inline command as a favorite from the Action Panel (Command-K) so it sits on Raycast's main screen. This one shows free space on the startup disk, checked every hour:

#!/bin/bash

# @raycast.schemaVersion 1
# @raycast.title Disk Space
# @raycast.mode inline
# @raycast.refreshTime 1h
# @raycast.icon 💾

df -h / | awk 'NR==2 {print $4 " free on the startup disk"}'

fullOutput for anything longer than a line

When I clear out Downloads, I want to see the biggest files first, not open Finder and sort columns. ls -lhS lists files largest first with readable sizes, and fullOutput shows the whole list:

#!/bin/bash

# @raycast.schemaVersion 1
# @raycast.title Biggest Files in Downloads
# @raycast.mode fullOutput
# @raycast.packageName Finder

ls -lhS "$HOME/Downloads" | head -20

How to add arguments to a script command

Arguments let a script ask you for something before it runs, typed straight into Raycast's search bar. A script takes as many as three, declared as @raycast.argument1, argument2 and argument3, each written as a small piece of JSON. The arguments documentation lists the fields:

• type (required): "text", "password" (masked as you type) or "dropdown". Password and dropdown need Raycast 1.64.0 or later.
• placeholder (required): the hint text shown in the empty box.
• optional: true lets the script run with the box left empty.
• percentEncoded: true makes Raycast URL-encode the value, which you want when it goes into a web address.
• data: for a dropdown, the list of choices as title and value pairs.

Inside the script, Bash reads the first argument as $1, the second as $2, and so on. I keep this one on a hotkey because I usually reach for it as a call is starting. It makes a dated Markdown file in a Meeting Notes folder with headings for decisions and follow-ups, then opens it:

#!/bin/bash

# @raycast.schemaVersion 1
# @raycast.title New Meeting Note
# @raycast.mode compact
# @raycast.packageName Work
# @raycast.argument1 { "type": "text", "placeholder": "who or what" }

dir="$HOME/Documents/Meeting Notes"
mkdir -p "$dir"
file="$dir/$(date +%Y-%m-%d) $1.md"

if [ -e "$file" ]; then
  echo "Note already exists, opening it"
else
  printf "# %s\n\n## Decisions\n\n## Follow-ups\n" "$1" > "$file"
  echo "Created $(basename "$file")"
fi

open "$file"

A dropdown suits a short list you pick from often. This header line offers three folders, and the script body is just open "$HOME/$1":

# @raycast.argument1 { "type": "dropdown", "placeholder": "folder", "data": [{"title": "Downloads", "value": "Downloads"}, {"title": "Desktop", "value": "Desktop"}, {"title": "Documents", "value": "Documents"}] }

A script whose first argument is text can also act as a fallback command, offered when a Raycast search finds nothing. Turn that on in Settings → Launcher → Fallback Commands, as the manual describes.

How to give a script command a hotkey

Any script command can have its own keyboard shortcut that works even when Raycast is closed. The steps from Raycast's manual:

1. Open Raycast and search for the script's title.
2. Press Command-K to open the Action Panel.
3. Choose Configure Command.
4. Choose Record Hotkey and press the key combination you want.

Pick combinations your apps don't already use; ones that hold Control, Option and Command together are rarely claimed. Raycast's manual also suggests making scripts safe to run twice, since a hotkey is easy to hit by accident; that's why the meeting-note script above checks whether the file exists before writing it.

Running AppleScript and Shortcuts from a script command

Script commands can drive Mac apps, not just files. AppleScript is one of the template languages, and a Bash script can call it with osascript. On a Mac the permission prompts for Accessibility, Automation and Full Disk Access go to Raycast, not Terminal, says the manual, so expect macOS to ask the first time a script controls another app. (The manual notes that on macOS 27, Accessibility appears in System Settings under the name Device Control and Data Access.)

Anything you've already built in the Shortcuts app can become a Raycast command too. Apple's command-line guide for Shortcuts shows the syntax: shortcuts run "Shortcut Name", which exits with 0 on success and 1 on an error. That means Raycast reports a failed shortcut correctly. This pairs well with the hotkeys and automations in our Siri Shortcuts on Mac guide.

For anything that deletes or sends, add @raycast.needsConfirmation true. I've hit Return on the wrong row in a launcher more than once, and one extra click is cheap insurance:

#!/bin/bash

# @raycast.schemaVersion 1
# @raycast.title Empty Trash
# @raycast.mode silent
# @raycast.packageName Finder
# @raycast.needsConfirmation true

osascript -e 'tell application "Finder" to empty trash'
echo "Trash emptied"

How to use scripts from the community repository

Raycast keeps a large collection of ready-made scripts in its public script-commands repository on GitHub, grouped by app and task. The repo's advice is to copy the ones you want into your own folder rather than pointing Raycast at the whole repository, because a reorganized repo could make commands appear or vanish without warning.

1. Find a script in the repo and download it, or copy its text into a new file in your scripts folder.
2. If the filename contains .template., open it and fill in the values it asks for (an API token, a path) before you use it.
3. Make the file executable if it isn't: in Terminal, run chmod +x followed by the file's path. Apple's shell scripting primer uses the same command to make a script runnable.
4. Read the whole script before running it. It runs with your permissions, on your files.
5. Make sure the folder is listed in Settings → Script Commands, then search for the title in Raycast.

Why isn't my script command working?

Most script command problems come down to four things: missing metadata, a file that isn't executable, a tool Raycast can't find on its PATH, or a script that fails without saying why.

The script doesn't appear in Raycast

• Check the three required lines: schemaVersion, title and mode. The repo's FAQ puts this first.
• Check the first line is a shebang such as #!/bin/bash or #!/usr/bin/env python3; Raycast's manual says scripts on a Mac run with the interpreter the shebang names.
• Check the file is executable (chmod +x) and saved inside a folder listed under Settings → Script Commands.

"Command not found" for a Homebrew tool

Raycast runs scripts in a non-login shell, so your .zshrc and its PATH changes aren't loaded, per the repo's contribution guidelines. Raycast adds /usr/local/bin to the PATH, but on Apple silicon Homebrew installs into /opt/homebrew, according to Homebrew's installation docs. Add this line near the top of the script:

export PATH="/opt/homebrew/bin:$PATH"

Use double quotes so $PATH expands. If a script really needs your full shell profile, the guidelines show the other route: add -l after the shebang, as in #!/bin/bash -l, to run it as a login shell. That pulls in everything your profile loads, which is exactly what the repo avoids for its own scripts, so I'd only reach for it when one line of PATH won't do.

The script fails without a useful message

Raycast treats any non-zero exit status as a failure and shows a toast saying the script failed. In inline and compact modes, the last line your script printed becomes the error message, per the README. So print a clear reason, then exit:

if [ -z "$1" ]; then
  echo "Add a title for the note, then run it again"
  exit 1
fi

A first set of script commands worth building

Start with the jobs you repeat daily, not the clever ones. A good first set:

• Open your morning apps and tabs (silent).
• Make a dated note from a title (compact, one text argument).
• Open a project folder from a dropdown (silent, dropdown argument).
• Show free disk space or another single number (inline, with refreshTime).
• Run a Shortcut you already rely on (silent, shortcuts run).
• Anything destructive, behind needsConfirmation.

Once a few of those are on hotkeys, the next ones suggest themselves. For bigger jobs, like timed tasks or files that sort themselves, our guides to Mac workflow automation and automating your Mac with Swift scripts pick up where script commands stop. And if Raycast itself is the open question, the Raycast alternatives comparison covers Alfred, Spotlight and the rest.