Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/raycast/script-commands/llms.txt

Use this file to discover all available pages before exploring further.

Having trouble with your Script Commands? This guide covers common issues and their solutions.

​
Script Not Appearing in Raycast

If your script isn’t showing up in Raycast, check these common issues:
Problem: Scripts with .template. in the filename are intentionally ignored by Raycast.Solution:
1

Copy the template

Create a copy of your template file:
cp script.template.sh script.sh
2

Configure the script

Edit the new file and replace any placeholder values (API keys, usernames, etc.).
3

Refresh Raycast

The script should now appear in Raycast automatically.
Problem: Scripts must have all required metadata parameters to be recognized.Required parameters:
  • schemaVersion (currently only version 1)
  • title (the display name)
  • mode (silent, compact, fullOutput, or inline)
Solution:
#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title My Script Command
# @raycast.mode compact
All three parameters must be present for the script to appear in Raycast.
Problem: Metadata parameters must use the correct comment syntax for your language.Solution:Use # for Bash, Python, and AppleScript:
# @raycast.title My Command
Use // for Swift and JavaScript:
// @raycast.title My Command
Block comments (/* */) are not supported for metadata.
Problem: The directory containing your script hasn’t been added to Raycast.Solution:
1

Open Raycast preferences

Press ⌘ , in Raycast or open Preferences.
2

Navigate to Extensions

Click on the Extensions tab.
3

Add script directory

Click the + button and select “Add Script Directory”, then choose your scripts folder.

​
Shell Scripts Not Working

Bash scripts can fail for various reasons. Here’s how to debug them:
Problem: Same as above - template files are not executed.Solution: Remove .template. from the filename after configuring the script.
Problem: The script has syntax errors or unexpected characters.Solution:
1

Run ShellCheck

Use ShellCheck to identify issues:
shellcheck your-script.sh
2

Fix reported issues

ShellCheck will provide specific suggestions for each problem.
3

Test locally

Run your script from the terminal to verify it works:
bash ./your-script.sh
All scripts submitted to the community repository must pass ShellCheck validation.
Problem: The script doesn’t have a proper shebang line.Solution: Ensure the first line specifies the interpreter:
#!/bin/bash
For other languages:
#!/usr/bin/env python3

#!/usr/bin/env node
Problem: The script file isn’t executable.Solution: Make the script executable:
chmod +x your-script.sh

​
Dependency Issues

Problem: Your script depends on a tool that isn’t installed.Example error:
jq: command not found
Solution:
1

Check the script's dependencies

Look at the top of the script for dependency documentation:
# Dependency: This script requires `jq` cli installed
# Install via homebrew: `brew install jq`
2

Install the required tool

Follow the installation instructions provided in the script.
3

Verify installation

Test that the command is now available:
which jq
# Should output: /usr/local/bin/jq (or similar)
Problem: Script requires Node.js, Python, or Swift but the runtime isn’t installed.Solution:For Node.js scripts:
# Install Node.js via Homebrew
brew install node

# Verify installation
node --version
For Python scripts:
# Python usually comes with macOS, but you may need Python 3
brew install python3

# Verify installation
python3 --version
For Swift scripts:
# Install Xcode Command Line Tools
xcode-select --install

# Verify installation
swift --version

​
Path and Environment Issues

Problem: Script can’t find commands that work in your terminal.Explanation: Raycast runs scripts in a non-login shell, which has a minimal PATH.Solution:Raycast automatically includes /usr/local/bin. For other locations, add them explicitly:
#!/bin/bash

# Add custom paths
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"

# Now your command should work
my-custom-command
Problem: Script works with #!/bin/bash -l but you can’t use this in the community repo.Explanation: The community repository doesn’t allow login shells to ensure portability.Solution:Instead of relying on your shell profile, explicitly set what you need:
#!/bin/bash

# Explicitly set PATH
export PATH="/opt/homebrew/bin:$PATH"

# Set any needed environment variables
export MY_VAR="value"

# Your script logic here
For personal scripts (not in the community repo), you can use #!/bin/bash -l if needed.
Problem: Environment variables from your shell profile aren’t accessible.Solution:Set required variables at the top of your script:
#!/bin/bash

# Set environment variables
export API_URL="https://api.example.com"
export EDITOR="vim"

# Your script logic
Raycast has plans to support environment variables natively. Track progress in this issue.

​
Output and Display Issues

Problem: The script runs but you don’t see any output.Cause: Wrong output mode for your use case.Solution:Choose the appropriate mode:
  • silent mode: Shows output in HUD after Raycast closes (for quick actions)
  • compact mode: Shows last line in toast (for progress updates)
  • fullOutput mode: Shows all output (for detailed results)
  • inline mode: Shows first line in command list (for dashboard items)
# Change this to match your needs
# @raycast.mode fullOutput
Problem: Script in inline mode doesn’t update automatically.Cause: Missing or invalid refreshTime parameter.Solution:Add a valid refresh interval:
# @raycast.mode inline
# @raycast.refreshTime 30s
Valid formats:
  • 10s (seconds, minimum 10)
  • 5m (minutes)
  • 2h (hours)
  • 1d (days)
Only the first 10 inline commands are refreshed automatically. Others must be manually refreshed.
Problem: Tasks like zip or tar show lots of partial progress in compact/silent modes.Solution:Use quiet flags for commands that generate progress output:
# ❌ Will show lots of partial output
zip -r archive.zip folder/

# ✅ Quiet mode for clean output
zip -qr archive.zip folder/
echo "Archive created successfully"
Or switch to fullOutput mode:
# @raycast.mode fullOutput
Problem: ANSI color codes aren’t showing in output.Cause: Colors are only supported in inline and fullOutput modes.Solution:Use one of these modes and proper ANSI escape codes:
# @raycast.mode fullOutput

# Red text on green background
echo -e '\033[31;42mColored text\033[0m'
See the Output Modes documentation for supported color codes.

​
Error Handling

Problem: Script fails but doesn’t show why.Solution:Implement proper error handling:
#!/bin/bash

# Enable error reporting
set -e  # Exit on error
set -u  # Exit on undefined variable

# Add error checking
if ! command -v jq &> /dev/null; then
    echo "Error: jq is required. Install with: brew install jq"
    exit 1
fi

# Check command results
if ! curl -s "$API_URL" > /tmp/response.json; then
    echo "Failed to fetch data from API"
    exit 1
fi

# Success
echo "Operation completed"
Problem: Error messages aren’t helpful.Solution:Write clear, actionable error messages:
# ❌ Not helpful
echo "Error"
exit 1

# ✅ Clear and actionable
echo "Error: Configuration file not found at ~/.config/myapp/config.json"
echo "Run 'myapp init' to create the configuration file."
exit 1
For compact and inline modes, only the last line is shown in the error toast.

​
Application Control Issues

Problem: AppleScript fails because the target application isn’t installed.Solution:Document the app requirement at the top of your script:
#!/usr/bin/osascript

# Note: Spotify v1.1.0+ required
# Install via: https://www.spotify.com/download/

# @raycast.schemaVersion 1
# @raycast.title Play Spotify
And optionally check if the app is running:
tell application "System Events"
    if not (exists process "Spotify") then
        return "Spotify is not running"
    end if
end tell
Problem: macOS blocks the script from controlling other applications.Solution:
1

Open System Preferences

Go to System Preferences → Security & Privacy → Privacy
2

Add Raycast to Accessibility

In the “Accessibility” section, add Raycast to the list of allowed apps.
3

Add Raycast to Automation

In the “Automation” section, allow Raycast to control the target application.

​
Debugging Tips

​
Test from Terminal First

Always test your script from the terminal before trying it in Raycast: 
# Navigate to your script directory
cd ~/path/to/scripts

# Run the script
bash ./your-script.sh

# Or make it executable and run directly
chmod +x ./your-script.sh
./your-script.sh

​
Add Debug Output

Temporarily add debug statements to understand what’s happening: 
#!/bin/bash

# Temporary debug output
echo "Script started" >&2
echo "PATH: $PATH" >&2
echo "PWD: $PWD" >&2

# Your script logic
result=$(some-command)
echo "Result: $result" >&2

# Final output (shown in Raycast)
echo "Success"
Output to stderr (using >&2) won’t be shown in Raycast but will appear in the terminal when testing.

​
Use ShellCheck

For Bash scripts, ShellCheck catches many common issues:
1

Install ShellCheck

brew install shellcheck
2

Run analysis

shellcheck your-script.sh
3

Fix issues

ShellCheck provides detailed explanations and suggestions for each issue.

​
Check Raycast Logs

Raycast logs can provide additional information:
  1. Open Console.app
  2. Filter for “Raycast”
  3. Look for errors or warnings related to your script

​
Getting Help

If you’re still stuck:

Slack Community

Join the Raycast Slack community to ask questions and get help from other developers.

GitHub Issues

Check existing issues or create a new one for bug reports.

Feedback Command

Use the feedback command within Raycast to report issues directly to the team.

Email Support

Send an email to feedback@raycast.com for general questions.
For issues related to Script Commands specifically (not the community repository), please use the channels above rather than GitHub issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us