Raycast lets you control your tools with a few keystrokes and installing script commands makes it possible to execute commands from anywhere on your desktop. They are a great way to speed up every-day tasks such as converting data, opening bookmarks or triggering dev workflows. This repository contains some example scripts as well as links to our community commands and documentation to write your own ones.
✨ Looking to build richer extensions? Check out the Extensions API here.
Install Script Commands from this repository
To install new commands, follow these steps:
Choose a script from the community repo and save it into a new directory.
Scripts containing the word
.template.in the filename require some values to be set (check the troubleshouting section for more information).
Alternatively, instead of creating a new directory you can reuse the repo's
Open the Extensions tab in the Raycast preferences
Click the plus button
Add Script Directory
Select directories containing your Script Commands
💡 Hint: We recommend that you don't directly load the community script directories into Raycast to avoid potential restructuring and new script commands suddenly appearing in Raycast.
Create your own Script Commands
To write your own custom Script Commands, go over the following steps:
- Use the
Create Script Commandfunctionality in Raycast
- Write and edit your script using your favourite code editor
- Run your Script Command from the Raycast root search
💡 Hint: If you choose to write your script in
Bash, we highly recommend using the Shellcheck linter as this will ensure smooth running of your script. All scripts uploaded to GitHub will need to have been run through ShellCheck.
These parameters are available for you to customize your Script Command in Raycast. For practical examples of how these should be used, as well as best practices and supported languages, please browse our templates and community-built scripts.
|schemaVersion||Schema version to prepare for future changes in the API. Currently there is only version 1 available.||Yes||0.29+|
|title||Display name of the Script Command that is shown as title in the root search.||Yes||0.29+|
|mode||Specifies how the script is executed and how the output is presented. Details of the options for this parameter can be viewed here||Yes||0.29+|
|packageName||Display name of the package that is shown as subtitle in the root search. When not provided, the name will be inferred from the script directory name.||No||0.29+|
|icon||Icon that is displayed in the root search. Can be an emoji, a file path (relative or full) or a remote URL (only https). Supported formats for images are PNG and JPEG. Please make sure to use small icons, recommended size - 64px.||No||0.29+|
|currentDirectoryPath||Path from which the script is executed. Default is the path of the script.||No||0.29+|
|refreshTime||Specify a refresh interval for inline mode scripts in seconds, minutes, hours or days. Examples: 10s, 1m, 12h, 1d. Note that the actual times can vary depending on how the OS prioritises scheduled work. The minimum refresh interval is 10 seconds. If you have more than 10 inline commands, only the first 10 will be refreshed automatically; the rest have to be manually refreshed by navigating to them and pressing
|argument[1...3]||Custom arguments, see Passing Arguments page for detail of how to use this field||No||1.2.0+|
|author||Define an author name to be part of the script commands documentation||No|
|authorURL||Author social media, website, email or anything to help the users to get in touch||No|
|description||A brief description about the script command to be presented in the documentation||No|
You can use the standard output to present messages in Raycast. Depending on the
mode, the standard output of your scripts is differently presented.
inline modes support ANSI Escape codes allowing to color generated output by changing its background and foreground color. You can view the different output mode options as well as their various forms and color options here.
If the script exits with a status code not equal to 0, Raycast interprets it as failed and shows a toast that the script failed to run. If this script has inline or compact mode, the last line of the output will be used as an error message. Consider this example for a bash script:
if ! [[ $value =~ $regex ]] ; then echo "Invalid value provided" exit 1 else ...
Troubleshooting and FAQs
- Ensure the filename doesn't contain
- Check that all required metadata parameters are provided. See the table above which parameters are required.
- Ensure you use either
//comments for metadata parameters
- If nothing helps, try to go step by step from a template Script Command or use one of the examples in this repo.
- Ensure the filename doesn't contain
- Run your code through ShellCheck to check for syntax errors or unexpected characters
We only allow Script Commands that run in a non-login shell in this repository as agreed on in our contribution guidelines, due to any dependencies.
However, if you need to run your local script as login-shell, you can specify an argument after shebang, e.g.
#!/bin/bash -l for bash. We also append
$PATH variable so you can use your local shell commands without any additional steps. If this is not enough, you can always extend
$PATH by adding
export PATH='/some/extra/path:$PATH' at the top of your script.
We're always looking for new Script Commands or other ways to improve Raycast. If you have anything cool to show, please send us a pull request. If we screwed something up, please report a bug. Join our Slack community to brainstorm ideas with like-minded folks.