raycast

name: Raycast description: Generate Raycast script commands. USE WHEN raycast, raycast script, script command, productivity script, mac automation. Creates shell scripts with Raycast metadata.

Raycast Script Commands

Generate lightweight shell/TypeScript scripts that extend Raycast's functionality. Unlike full extensions (React/TypeScript apps), Script Commands are simple scripts defined by metadata comments - no build step required.

Workflow Routing

Default Script Location

Scripts are created in: ~/code/scripts/raycast/

Metadata Reference

Required Parameters

Optional Parameters

Mode Types

• silent - Runs in background, shows HUD toast with last line
• compact - Shows toast with last line while running
• fullOutput - Shows full output in separate view (supports ANSI colors)
• inline - Displays in Raycast root search (requires refreshTime, supports ANSI colors)

Note: Long-running tasks are not suitable for compact, silent, or inline modes. Use fullOutput for commands that take time to complete.

Argument Format

# @raycast.argument1 { "type": "text", "placeholder": "Search query" }
# @raycast.argument2 { "type": "dropdown", "placeholder": "Select option", "data": [{"title": "Option 1", "value": "opt1"}] }

Argument types: text, password, dropdown Options: optional, percentEncoded

Note: The secure option is deprecated - use type: "password" instead.

Constraints & Limitations

• refreshTime minimum: 10 seconds
• Maximum inline commands: 10 displayed simultaneously
• Maximum arguments: 3 per script
• Execution environment: Scripts run in a non-login shell

ANSI Color Support

The fullOutput and inline modes support ANSI escape codes for colored output.

Foreground Colors

Background Colors

Error Handling

• A non-zero exit code triggers a failure toast in Raycast
• In inline and compact modes, the last output line is used as the error message
• Always provide meaningful error messages before exiting with non-zero status

Error Handling Pattern

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title Example with Error Handling
# @raycast.mode compact

if ! command -v required_tool &> /dev/null; then
    echo "Error: required_tool is not installed"
    exit 1
fi

result=$(required_tool --action 2>&1) || {
    echo "Failed: $result"
    exit 1
}

echo "Success: $result"

Template File Convention

Files with .template. in the name (e.g., api-lookup.template.sh) indicate scripts that require user configuration before use (API keys, custom paths, etc.). Users should copy and rename the file, filling in their values.

Supported Languages

• Bash (default)
• Python
• TypeScript/Node
• Ruby
• Swift
• AppleScript

Examples

Quick Command (silent mode)

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title Toggle WiFi
# @raycast.mode silent
# @raycast.icon 📶

networksetup -setairportpower en0 $(networksetup -getairportpower en0 | grep -q On && echo off || echo on)
echo "WiFi toggled"

Interactive Script (with arguments)

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title Open URL
# @raycast.mode silent
# @raycast.icon 🌐
# @raycast.argument1 { "type": "text", "placeholder": "URL" }

open "$1"

Status Display (inline mode)

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title Battery Status
# @raycast.mode inline
# @raycast.refreshTime 5m
# @raycast.icon 🔋

pmset -g batt | grep -Eo "\d+%" | head -1

Colored Output (fullOutput mode)

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title System Status
# @raycast.mode fullOutput
# @raycast.icon 💻

echo -e "\033[32m✓ CPU:\033[0m $(sysctl -n machdep.cpu.brand_string)"
echo -e "\033[32m✓ Memory:\033[0m $(system_profiler SPHardwareDataType | awk '/Memory:/ {print $2, $3}')"
echo -e "\033[34mℹ Uptime:\033[0m $(uptime | awk -F'( |,|:)+' '{print $6,$7}')"