Skip to main content
Metadata parameters customize how your Script Command appears and behaves in Raycast. All parameters are defined using special comments at the top of your script file.

​
Metadata Format

Use the appropriate comment syntax for your language: 
# @raycast.parameterName value

​
Required Parameters

These three parameters must be present in every Script Command:

​
schemaVersion

​
schemaVersion
number
required
Schema version to prepare for future changes in the API. Currently, only version 1 is available.App Version: 0.29+
# @raycast.schemaVersion 1

​
title

​
title
string
required
Display name of the Script Command shown in Raycast’s root search.App Version: 0.29+
# @raycast.title Add Note to Bear
Example: bear-add-note.sh:5

​
mode

​
mode
string
required
Specifies how the script is executed and how output is presented.Options: silent, compact, fullOutput, inlineApp Version: 0.29+
# @raycast.mode silent
See Output Modes for detailed explanations of each mode.

​
Optional Parameters

​
packageName

​
packageName
string
Display name of the package shown as a subtitle in root search. When not provided, the name is inferred from the script directory name.App Version: 0.29+
# @raycast.packageName Bear
Example: Groups related scripts together like “System”, “Web Searches”, or “Baremetrics”.

​
icon

​
icon
string
Icon displayed in the root search. Can be:
  • An emoji: 🤖
  • A file path (relative or absolute): images/bear-light.png
  • A remote URL (HTTPS only): https://example.com/icon.png
Supported formats: PNG, JPEGRecommended size: 64pxApp Version: 0.29+
# @raycast.icon 🛩

# @raycast.icon images/baremetrics.png

​
iconDark

​
iconDark
string
Icon for dark theme. If not specified, icon is used for both themes.App Version: 1.3.0+
# @raycast.icon images/bear-light.png
# @raycast.iconDark images/bear-dark.png
Example: bear-add-note.sh:11-12

​
currentDirectoryPath

​
currentDirectoryPath
string
Path from which the script is executed. Default is the path of the script.App Version: 0.29+
# @raycast.currentDirectoryPath ~

# @raycast.currentDirectoryPath ~/Projects/my-app

​
needsConfirmation

​
needsConfirmation
boolean
Shows a confirmation alert dialog before running the script. Helpful for destructive operations like “Quit All Apps” or “Empty Trash”.Default: falseApp Version: 0.30+
# @raycast.needsConfirmation true

​
refreshTime

​
refreshTime
string
Refresh interval for inline mode scripts. Specify in seconds (s), minutes (m), hours (h), or days (d).Minimum: 10 secondsExamples: 10s, 1m, 12h, 1dApp Version: 0.31+Required for inline mode
# @raycast.mode inline
# @raycast.refreshTime 10s
Example: inline-cpu-usage-percent.sh:8
If you have more than 10 inline commands, only the first 10 will refresh automatically. The rest must be manually refreshed by navigating to them and pressing Return.

​
argument1, argument2, argument3

​
argument[1-3]
JSON
Custom arguments for user input. Supports text, password, and dropdown fields.Maximum arguments: 3App Version: 1.2.0+
# @raycast.argument1 { "type": "text", "placeholder": "Title" }
See Arguments for complete documentation.

​
Documentation Parameters

These parameters are used for documentation and community sharing:

​
description

​
description
string
Brief description of what the script command does.
# @raycast.description Display CPU usage percent

​
author

​
author
string
Author name for documentation.
# @raycast.author Tanay Nistala

​
authorURL

​
authorURL
string
Author’s social media, website, or contact information.
# @raycast.authorURL https://github.com/tanaynistala

​
Complete Example

Here’s a full example combining multiple metadata parameters: 
#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Add Note
# @raycast.mode silent

# Optional parameters:
# @raycast.icon images/bear-light.png
# @raycast.iconDark images/bear-dark.png
# @raycast.packageName Bear
# @raycast.argument1 { "type": "text", "placeholder": "Title", "percentEncoded": true}
# @raycast.argument2 { "type": "text", "placeholder": "Content", "optional": true, "percentEncoded": true}

# Documentation:
# @raycast.description Add a new note to Bear.
# @raycast.author Tanay Nistala
# @raycast.authorURL https://github.com/tanaynistala

open "bear://x-callback-url/create?title=${1}&text=${2}"

echo "Note created!"
See the full example: bear-add-note.sh

​
Troubleshooting

​
Script Not Appearing in Raycast?

1

Check Filename

Ensure the filename doesn’t contain .template. Remove this from the filename once you’ve configured the script.
2

Verify Required Parameters

Confirm all three required parameters (schemaVersion, title, mode) are present.
3

Check Comment Syntax

Ensure you’re using the correct comment syntax:
  • # for Bash, Python, Ruby, PHP
  • // for JavaScript, Swift, C#
4

Start from Template

If nothing works, start from a template or copy an example from the community repository.

Build docs developers (and LLMs) love

Get started for freeTalk to us