Raycast Script Commands Tutorial: Automate macOS Workflows with Shell Scripts

What Are Script Commands?

Raycast Script Commands let you run shell scripts from the Raycast launcher. You can fuzzy-search your codebase, convert formats, manage Docker, or trigger any CLI tool — all from a single hotkey.

Unlike full extensions (which need TypeScript and React), script commands are just shell scripts with a special header. If you can write a bash script, you can build a Raycast command.

• Run shell scripts from the Raycast search bar
• Accept arguments and produce dynamic output
• Integrate with any CLI tool — git, docker, kubectl, you name it
• Share scripts as plain text — no build step needed

Raycast Setup & Permissions

Install Raycast from raycast.com (it's free). Script commands need no additional setup — Raycast reads them from a configured directory.

• Raycast installed and set as your primary launcher
• Basic shell scripting knowledge (bash, zsh, or fish)
• A directory to store your scripts (Raycast will create one for you)
• Optional: fzf, ripgrep, or other CLI tools for richer scripts

Writing Your First Shell Script

Each script starts with special header comments that Raycast parses as metadata:

#!/bin/bash
# @raycast.title Clean Git Branches
# @raycast.author Your Name
# @raycast.authorURL https://example.com
# @raycast.description Delete local branches that have been merged to main
# @raycast.icon 🧹
# @raycast.mode fullOutput
git branch --merged main | grep -v "main" | xargs git branch -d
echo "Cleaned merged branches!"

Key header fields:

• @raycast.title — name shown in the search bar
• @raycast.description — subtitle text
• @raycast.icon — emoji or image path
• @raycast.mode — compact (toast), fullOutput (window), or inline (list)

Real-World Script Recipes

Here are real-world scripts that save time every day:

• Git Branch Cleaner: Delete merged local branches in one command
• Docker Cleanup: docker system prune -af --volumes wrapped in a nice UI
• Project Opener: cd ~/projects/

  Real-World Script Recipes

  && code . — fuzzy-find a project and open it
• IP Copier: curl ifconfig.me | pbcopy — copy your public IP instantly
• SSL Checker: Verify cert expiry for any domain

Arguments example:

#!/bin/bash
# @raycast.title DNS Lookup
# @raycast.argument1 {"type":"text","placeholder":"domain.com"}
# @raycast.mode fullOutput
dig +short "
Real-World Script Recipes
" | head -5

Arguments, Output & Dynamic Data

Take script commands further with these advanced techniques:

• Use @raycast.mode inline to return a list of items the user can select — great for search scripts
• Output JSON with specific structure to render rich list items with icons and actions
• Chain commands: one script calls another via raycast://command/name deeplinks
• Use environment variables from Raycast's preferences for API keys
• Combine with fzf: pipe output through fzf for fuzzy selection, then act on the choice

Script Debugging & Fixes

Script debugging tips:

• Script not showing? Check that the file is executable: chmod +x script.sh
• Wrong output? Use @raycast.mode fullOutput to see all stdout/stderr in a window
• Path issues? Raycast runs scripts with a minimal PATH — add export PATH="/opt/homebrew/bin:$PATH" at the top
• Permission denied? System Settings → Privacy → Accessibility → add Raycast

Publishing to the Store

Script commands are just the beginning. Explore more:

• Build full extensions with TypeScript and React (see [[Raycast Extension Development]])
• Set up AI commands for quick tasks (see [[Raycast AI Commands]])
• Use clipboard history and snippets (see [[Raycast Clipboard History]])
• Window management from Raycast (see [[Raycast Window Management]])