Skip to main content
Raycast provides templates for popular programming languages to help you get started quickly. Each template includes the basic structure, required metadata, and language-specific examples.

Available Templates

The script-commands repository includes templates for:

Bash

Shell scripting for system automation

Python

Python 3 scripts with package support

JavaScript

Node.js scripts with npm packages

Swift

Native macOS scripting with Swift

Ruby

Ruby scripts with gem support

PHP

PHP scripting for web tasks

AppleScript

Native macOS automation

C#

.NET scripting for cross-platform tasks

Using Templates

1

Download Template

Download the template file from the templates directory or copy the content below.
2

Remove .template Extension

Rename the file to remove .template. from the filename:
# From:
script-command.template.sh

# To:
my-script.sh
Scripts with .template. in the filename won’t appear in Raycast.
3

Customize Metadata

Update the metadata parameters with your script’s information:
  • Change the title
  • Set the appropriate mode
  • Add your icon and package name
  • Include your author information
4

Write Your Logic

Replace the placeholder code with your script logic.
5

Make Executable

Ensure the script is executable (Unix-based systems):
chmod +x my-script.sh

Template Reference

Bash Template

#!/bin/bash

# Raycast Script Command Template
#
# Duplicate this file and remove ".template" from the filename to get started.
# See full documentation here: https://github.com/raycast/script-commands
#
# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title My First Script
# @raycast.mode fullOutput
# @raycast.packageName Raycast Scripts
#
# Optional parameters:
# @raycast.icon 🤖
# @raycast.currentDirectoryPath ~
# @raycast.needsConfirmation false
#
# Documentation:
# @raycast.description Write a nice and descriptive summary about your script command here 
# @raycast.author Your name
# @raycast.authorURL An URL for one of your social medias

echo "Hello from My First Script"
Source: script-command.template.sh
Bash scripts are the most common and don’t require additional dependencies. Use ShellCheck to validate your scripts.

Python Template

#!/usr/bin/env python3

# Raycast Script Command Template
#
# Dependency: This script requires Python 3
# Install Python 3: https://www.python.org/downloads/release
#
# Duplicate this file and remove ".template" from the filename to get started.
# See full documentation here: https://github.com/raycast/script-commands
#
# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title My First Script
# @raycast.mode fullOutput
# @raycast.packageName Raycast Scripts
#
# Optional parameters:
# @raycast.icon 🤖
# @raycast.currentDirectoryPath ~
# @raycast.needsConfirmation false
#
# Documentation:
# @raycast.description Write a nice and descriptive summary about your script command here 
# @raycast.author Your name
# @raycast.authorURL An URL for one of your social medias

print("Hello World!")
Source: script-command.template.py

JavaScript (Node.js) Template

#!/usr/bin/env node

// Raycast Script Command Template
//
// Dependency: This script requires Nodejs.
// Install Node: https://nodejs.org/en/download/
//
// Duplicate this file and remove ".template" from the filename to get started.
// See full documentation here: https://github.com/raycast/script-commands
//
// Required parameters:
// @raycast.schemaVersion 1
// @raycast.title My First Script
// @raycast.mode fullOutput
// @raycast.packageName Raycast Scripts
//
// Optional parameters:
// @raycast.icon 🤖
// @raycast.argument1 { "type": "text", "placeholder": "js, css, html", "optional": true}
// @raycast.argument2 { "type": "text", "placeholder": "query" }
//
// Documentation:
// @raycast.description Write a nice and descriptive summary about your script command here 
// @raycast.author Your name
// @raycast.authorURL An URL for one of your social medias

/*
	ABOUT THIS TEMPLATE:
	
	This template is meant to be a quick starting point for creating a script command using Nodejs.
	
	This template demonstrates the following ideas:
	
	* Extracting passed arguments.
	* Using both required and optional arguments
	* URI Encoding
	* Outputting result to Raycast
	* Opening a url using exec and the unix open command
	* Use of destructuring
	* Use of template literals

*/

const { exec } = require('child_process')

// Use destructuring to grab arguments.
// Use slice to start from position 3.
let [topic, query] = process.argv.slice(2)
let uri = `https://developer.mozilla.org/search?topic=${topic}&q=${encodeURIComponent(query)}`

// console.log() displays output in fullOutput mode.
console.log(`The arguments are: \n   ${process.argv.join('\n   ')}\n`)
console.log(`Your topic is "${topic}"`)
console.log(`Your query is "${query}"`)
console.log(`Your query uri encoded is "${encodeURIComponent(query)}"`)
console.log(`The uri is "${uri}"`)

// Uncomment the exec line below to open this query in your web browser.
// Use double quotes around the uri to avoid processing issues.
//exec(`open "${uri}"`)
Source: script-command.template.js
The JavaScript template includes detailed comments demonstrating argument handling, URI encoding, and browser integration.

Swift Template

#!/usr/bin/swift

// Raycast Script Command Template
// 
// Duplicate this file and remove ".template" from the filename to get started.
// See full documentation here: https://github.com/raycast/script-commands
//
// Required parameters:
// @raycast.schemaVersion 1
// @raycast.title My First Script
// @raycast.mode fullOutput
// @raycast.packageName Raycast Scripts
//
// Optional parameters:
// @raycast.icon 🤖
// @raycast.currentDirectoryPath ~
// @raycast.needsConfirmation false
//
// Documentation:
// @raycast.description Write a nice and descriptive summary about your script command here
// @raycast.author Your name
// @raycast.authorURL An URL for one of your social medias

print("Hello from My First Script")
Source: script-command.template.swift

Ruby Template

#!/usr/bin/env ruby

# Raycast Script Command Template
#
# Dependency: This script requires Ruby
# Install Ruby: http://www.ruby-lang.org/
#
# Duplicate this file and remove ".template" from the filename to get started.
# See full documentation here: https://github.com/raycast/script-commands
#
# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title My First Script
# @raycast.mode fullOutput
# @raycast.packageName Raycast Scripts
#
# Optional parameters:
# @raycast.icon 🤖
# @raycast.currentDirectoryPath ~
# @raycast.needsConfirmation false
# @raycast.argument1 { "type": "text", "placeholder": "Placeholder text" }
#
# Documentation:
# @raycast.description Write a nice and descriptive summary about your script command here 
# @raycast.author Your name
# @raycast.authorURL An URL for one of your social medias

# If accepting an argument:
# arg1 = ARGV[0]

puts "Hello World!"
Source: script-command.template.rb

PHP Template

#!/usr/bin/env php

# Raycast Script Command Template
#
# Dependency: This script requires PHP
# Install PHP: http://www.https://www.php.net/
#
# Duplicate this file and remove ".template" from the filename to get started.
# See full documentation here: https://github.com/raycast/script-commands
#
# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title My First Script
# @raycast.mode fullOutput
# @raycast.packageName Raycast Scripts
#
# Optional parameters:
# @raycast.icon 🤖
# @raycast.currentDirectoryPath ~
# @raycast.needsConfirmation false
#
# Documentation:
# @raycast.description Write a nice and descriptive summary about your script command here 
# @raycast.author Your name
# @raycast.authorURL An URL for one of your social medias

<?php

print("Hello World!");
Source: script-command.template.php

AppleScript Template

#!/usr/bin/osascript

# Raycast Script Command Template
#
# Duplicate this file and remove ".template" from the filename to get started.
# See full documentation here: https://github.com/raycast/script-commands
#
# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title My First Script
# @raycast.mode fullOutput
# @raycast.packageName Raycast Scripts
#
# Optional parameters:
# @raycast.icon 🤖
# @raycast.currentDirectoryPath ~
# @raycast.needsConfirmation false
# @raycast.argument1 { "type": "text", "placeholder": "Arg1" }
#
# Documentation:
# @raycast.description Write a nice and descriptive summary about your script command here 
# @raycast.author Your name
# @raycast.authorURL An URL for one of your social medias

on run argv
  log "Hello from My First Script: " & ( item 1 of argv )
end run
Source: script-command.template.applescript
AppleScript is perfect for automating macOS applications and system tasks. Access arguments via the argv parameter in the run handler.

C# (.NET) Template

#!/usr/bin/env dotnet

// Raycast Script Command Template
//
// Dependency: This script requires .NET 10
// Install .NET: https://dotnet.microsoft.com/
//
// Duplicate this file and remove ".template" from the filename to get started.
// See full documentation here: https://github.com/raycast/script-commands
//
// Required parameters:
// @raycast.schemaVersion 1
// @raycast.title My First Script
// @raycast.mode fullOutput
// @raycast.packageName Raycast Scripts
//
// Optional parameters:
// @raycast.icon 🤖
// @raycast.currentDirectoryPath ~
// @raycast.needsConfirmation false
//
// Documentation:
// @raycast.description Write a nice and descriptive summary about your script command here
// @raycast.author Your name
// @raycast.authorURL An URL for one of your social medias

Console.WriteLine("Hello World!");
Source: script-command.template.cs

Choosing a Language

Select your language based on your needs:
LanguageBest ForDependencies
BashSystem automation, file operations, simple tasksNone (built-in)
PythonData processing, API calls, complex logicPython 3
JavaScriptWeb APIs, JSON processing, npm packagesNode.js
SwiftNative macOS features, performance-critical tasksXcode Command Line Tools
RubyText processing, web scraping, automationRuby
PHPWeb tasks, API integrationPHP
AppleScriptmacOS app automation, UI scriptingNone (built-in)
C#Cross-platform tasks, .NET libraries.NET SDK

Template Best Practices

1

Start with Required Metadata

Always include the three required parameters: schemaVersion, title, and mode.
2

Add Dependencies in Comments

Document any external dependencies at the top of your script:
# Dependency: requires jq (https://stedolan.github.io/jq/)
# Install via Homebrew: `brew install jq`
3

Use Appropriate Mode

Choose the output mode that matches your script’s purpose:
  • fullOutput for detailed information
  • compact for status messages
  • silent for background tasks
  • inline for live dashboards
4

Include Documentation

Add description, author, and authorURL for better discoverability.
5

Test Thoroughly

Run your script multiple times with different inputs before sharing.

Quick Template Commands

Download all templates at once:
# Clone the repository
git clone https://github.com/raycast/script-commands.git

# Navigate to templates
cd script-commands/templates

# Copy a template
cp script-command.template.sh ~/my-scripts/my-script.sh

# Make it executable
chmod +x ~/my-scripts/my-script.sh
Or download individual templates:
# Bash
curl -O https://raw.githubusercontent.com/raycast/script-commands/master/templates/script-command.template.sh

# Python
curl -O https://raw.githubusercontent.com/raycast/script-commands/master/templates/script-command.template.py

# JavaScript
curl -O https://raw.githubusercontent.com/raycast/script-commands/master/templates/script-command.template.js

Community Examples

Browse real-world examples in the commands directory organized by category:
  • Apps: Integration with third-party applications
  • Browsing: Web searches and URL handlers
  • Communication: Slack, email, messaging
  • Conversions: Data format conversions
  • Developer Utils: Git, Docker, development tools
  • Media: Music, video, image processing
  • Navigation: File and folder shortcuts
  • System: macOS system configuration
  • Web Searches: Quick search commands
When copying community scripts, check the comments at the top for any required dependencies or configuration steps.

Next Steps

Script Basics

Learn the fundamentals of Script Commands

Metadata Reference

Explore all metadata parameters

Output Modes

Understand different output presentation modes

Arguments

Add custom input fields to your scripts

Build docs developers (and LLMs) love