Raycast Script Commands add a directory to Raycast, not an extension

Raycast loads a script directory, so one folder carries the package name

A Script Command is not installed one at a time. You point the app at a directory and every script inside it shows up in the root search, which means the directory is the unit of installation and the unit of identity. The install path is entirely inside the preferences window: open the Extensions tab, click the plus button, click Add Script Directory, then select the directories you want. What the directory buys you is the packageName. When a script leaves that field out, the subtitle in the root search is inferred from the directory name, so renaming the folder changes how every script inside it presents itself. Three top level entries carry the weight: commands/ holds community examples, templates/ holds starting points, and a folder the install instructions link as _enable-commands is offered as a folder you can reuse instead of creating a new directory.

schemaVersion, title and mode are the three fields Raycast will not start without

The metadata table separates required from optional with a column, and the required side is short. schemaVersion prepares for future API changes, and only version 1 exists today. title is the display name shown as the title in the root search. mode specifies how the script is executed and how the output is presented, which is the most consequential of the three and the least documented in this repository, since its option list lives in documentation/OUTPUTMODES.md rather than in the README. packageName, icon and iconDark are marked optional, and currentDirectoryPath is listed after them. The App Version column records when each field arrived, and it is not uniform. iconDark is marked 1.3.0+ while the earlier fields are marked 0.29+, which is a reminder that the metadata contract grew in steps.

icon takes an emoji, a local path or an https URL, and PNG or JPEG

The icon field is the most constrained optional field in the table. It can be an emoji, a file path that is either relative or full, or a remote URL, and the URL form is restricted to https only. Image formats are limited to PNG and JPEG, and the guidance is to keep icons small with a recommended size of 64px. iconDark repeats the same value for the dark theme, and if you leave it out the regular icon is used in both themes. What the table does not describe is any fallback for a remote icon that fails to load, nor a size limit for a local file. That matters because the field is optional in exactly the same way in both themes: setting one and forgetting the other is not caught by any required-field check.

currentDirectoryPath sets where the script runs, and mode decides what you see

currentDirectoryPath is documented in a single line: the path from which the script is executed, with the default being the path of the script itself. mode is the other half of the pair, and it is the field to decide before writing anything, because it governs execution and presentation together rather than only one of them. For richer extensions the README points at the Extensions API.

.template. in the filename marks a script that still needs values

The install instructions say to choose a script from the community repository and save it into a new directory, and they add a condition: scripts containing the word .template. in the filename require some values to be set, with the troubleshooting section of the same README named as the place that explains how. The naming convention is therefore the readiness flag. A file with .template. in its name is not finished, and a file without it is treated as finished, which means the convention is the only signal you get before the script runs. The same step offers an alternative to creating a new directory: reuse the repository's own folder, linked in the instructions as _enable-commands. Worth noticing before you do that, the top level of the repository lists that folder as _enabled-commands/, one letter apart from the link text the instructions use, and the link itself points at _enabled-commands.

Loading the community tree directly lets upstream changes rewrite your command list

The install steps carry an explicit warning against pointing Raycast at the community directories themselves, on the grounds of potential restructuring and new script commands suddenly appearing in Raycast. The mechanism is not mysterious: the app reads whatever is in the directory at load time, so a file that someone else moves, renames or adds becomes visible in your root search without any action from you. It also collides with the name inference described earlier, because the subtitle of a script without packageName comes from the directory name it sits in. The safer arrangement is the one the instructions lead with: copy what you want into a directory you own, then point Add Script Directory at that. Cost of that advice is that you now own updates.

ShellCheck is a submission condition, not a style suggestion

Bash authors get a linter by name: the ShellCheck extension from the VS Code marketplace, recommended to ensure smooth running of a script. The sentence that matters is the one after it, which says that all scripts uploaded to GitHub will need to have been run through ShellCheck. That turns the linter from advice into a review gate for anything you contribute here. The repository applies the same idea to its own code, and the Makefile shows the tooling: SwiftLint with a checked in config for linting and fixing, and SwiftFormat with its own config for formatting. Note the split in languages, because the primary language of this repository is Shell while the helper binary those targets operate on is built from a Swift package under Tools/Toolkit.

The Makefile builds a Swift binary called toolkit and exposes six useful targets

EXECUTABLE_NAME is set to toolkit and TOOLKIT_PATH points at Tools/Toolkit, so the repository treats its own scripts as something a small Swift program maintains. The release build runs clean first and then compiles the package, and a debug build sits beside it; both end by linking the built binary to the name toolkit at the repository root. Two targets touch documentation, one touches file permissions, and two wrap those with a commit step that goes through Tools/Toolkit/integration.sh, which is the only shell script the Makefile invokes directly.

build: clean
	swift build -c release --disable-sandbox --package-path $(TOOLKIT_PATH)
	ln -s $(EXECUTABLE_PATH_RELEASE) $(EXECUTABLE_NAME)

The docs and permissions pair reads like this:

gen-docs:
	./$(EXECUTABLE_NAME) generate-documentation
set-executable:
	./$(EXECUTABLE_NAME) set-executable

What this repository cannot offer you is a version to pin. It publishes no GitHub releases, so the only version markers anywhere in the documentation are the app versions in the metadata table. The open target also calls the Xcode application bundle by path, so even the maintainer tooling assumes a Mac with Xcode present.

Editorial conclusion

Use this repository if you want a shell script to run from the Raycast root search and you are willing to keep the script in a directory you copied, because upstream changes to the community tree will otherwise land in your command list without warning. Skip it if you want a stable release to pin, since the repository publishes no GitHub releases and versions live in the app version column of that table. Before adopting anything, run ShellCheck over a Bash script, decide the mode first, and confirm your directory name, because packageName is inferred from it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. raycast/script-commands on GitHub
5. README