# Raycast Script Commands: a directory of scripts that Raycast turns into searchable actions

> Raycast Script Commands is a repository of shell scripts plus the metadata format that makes Raycast list and run them. It suits macOS users who already live in Raycast and want small automations without building an extension.

**raycast/script-commands** — Script Commands let you tailor Raycast to your needs. Think of them as little productivity boosts throughout your day.

- Repository: https://github.com/raycast/script-commands
- Website: https://raycast.com
- Stars: 6,803 · Forks: 947
- Language: Shell
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/raycast-script-commands

## What Raycast Script Commands actually solves

Raycast is a launcher, and a launcher is only as useful as the things it can launch. The gap this repository fills is the space between a one-off shell command and a full Raycast extension. Writing an extension means a project with its own toolchain and UI code. Writing a script command means writing a script, adding a comment header, and pointing Raycast at the folder it lives in. The README frames the result as executing commands from anywhere on the desktop, with everyday examples: converting data, opening bookmarks, triggering dev workflows.

The audience is narrow and specific. You need Raycast installed, you need to be on macOS (the repository's own tooling is a Swift package built with swift build, and the Makefile opens Xcode), and you need to be willing to edit a text file. The repository ships example scripts, a community commands directory, templates, and documentation. It is not a library you import and it is not a runtime. It is a convention plus a catalogue.

## The metadata header is the whole interface

A script command is an ordinary script with a comment block at the top. Raycast reads that block, and the fields in it decide how the command appears in the root search and how its output is presented. The README's metadata table lists schemaVersion, title, mode, packageName and icon, with schemaVersion, title and mode marked required and available from app version 0.29+.

Two of those fields do most of the work. title is the display name shown as the title in the root search. packageName is the subtitle, and when you leave it out the name is inferred from the script directory, which is why folder layout matters more than it looks. icon accepts an emoji, a file path (relative or full) or a remote https URL, with PNG and JPEG as the supported image formats and 64px recommended; the README asks for small icons rather than large ones.

The mode field is where the design gets interesting, because it determines both execution and presentation. The README links to a separate document, documentation/OUTPUTMODES.md, for the options rather than listing them inline. That split is reasonable for a README but it means the single most consequential field for how your script behaves is documented somewhere else, and you should read that file before writing anything nontrivial. schemaVersion is currently fixed at version 1, which the README describes as preparation for future API changes.

## Installing a community script and running it

The README's install path is deliberately manual. You choose a script from the community repo and save it into a new directory, or reuse the repository's _enabled-commands folder. Then you open the Extensions tab in Raycast preferences, click the plus button, click Add Script Directory, and select the directory containing your script commands.

There is no install command in the README. The repository's Makefile builds the maintainers' Toolkit rather than installing anything for end users:

```bash
make build
make set-executable
```

The build target runs swift build in release configuration against Tools/Toolkit and symlinks the resulting executable, and set-executable runs the built toolkit to set the executable bit on scripts. Those targets are for working inside the repository, not for setting up Raycast on your machine.

One warning from the README: scripts whose filename contains .template. need values set before they will work, and the troubleshooting section is where that is explained.

The README also gives a recommendation that is easy to skip: do not load the community script directories directly into Raycast, because restructuring and new script commands would then appear in your launcher without your asking. Copy what you want into a directory you control. If you would rather start from scratch, Raycast has a Create Script Command action that scaffolds the file for you, and you edit it in any code editor.

## Writing your own script command

Start with the Create Script Command functionality in Raycast, then edit the result. The header is a comment block, and the required fields are the ones to get right first. The README's metadata table is the reference for the field names; it does not print a full example header in the section reproduced here, so treat the table as the source of truth for spelling and casing.

The README's advice for Bash authors is explicit: use the Shellcheck linter, and every script uploaded to the repository must have been run through ShellCheck. That is a contribution rule rather than a runtime requirement, but it is a good signal about the quality bar the maintainers expect, and it is cheap to follow locally.

The repository's own tooling is separate from your scripts. The Makefile builds a Swift executable named Toolkit from Tools/Toolkit, with targets for build, build-debug, gen-docs, gen-docs-and-commit, set-executable, set-executable-and-commit, lint, fix, format and open. gen-docs runs the built toolkit to generate documentation, and set-executable runs it to set the executable bit. If you only write script commands, you never touch any of this. It exists because the repository maintains generated documentation and executable permissions across a large number of contributed files.

## Where script commands stop being the right tool

The clearest boundary is stated by the project itself. The README asks whether you are looking to build richer extensions and points to the Extensions API repository instead. If your idea needs a persistent interface, multiple views, or anything beyond a command that runs and prints, the script command format is the wrong shape and the project says so.

There are practical limits too. The README recommends not loading the community directories directly, which means keeping your own copies in sync with upstream is your problem; nothing in the repository automates that for end users. Scripts with .template. in the filename will not run until you fill in values, so a copy-paste install can appear broken for reasons that have nothing to do with your setup.

Platform is the other constraint. The repository's build tooling is Swift and macOS-oriented, and the Makefile's open target calls /Applications/Xcode.app. The README does not document a Windows or Linux path for running script commands. If your team is not on macOS, this is not the automation layer you are looking for, regardless of how simple the script format is.

## How it compares with writing a Raycast extension

The real alternative is the Raycast Extensions API, which the README links directly. The difference is not cosmetic. An extension is a project: it has its own structure, it renders UI inside Raycast, and it can present lists, forms and detail views. A script command is a script: it runs, it produces output, and the mode field decides how that output is shown. The README's own framing puts the two side by side, with extensions described as the route for building something richer.

That makes the choice mostly about scope. If your task is "run this command and show me the result", a script command is less work and less to maintain. If your task is "let me browse, filter and act on a set of results", you will spend your time fighting the output modes instead of building the thing you wanted, and the extension API is where that work belongs. The repository also keeps a community commands directory, so before writing anything you can check whether someone has already solved it; the README links to that directory as the place to find commands created by the community.

## Licence, upkeep and upgrade cost

The repository is MIT licensed, with the LICENSE file at the top level. For script commands that means you can copy, modify and redistribute the scripts under the terms of that licence, subject to its conditions; anything you publish should keep the licence terms intact. This is a description of what the repository states, not legal advice, and if you are redistributing scripts inside a commercial product you should read the licence text yourself.

The maintenance picture is straightforward. The repository is not archived, and the last push was on 2026-09-21. It is a catalogue of scripts plus a metadata schema, and the schema is versioned: schemaVersion is currently 1, and the README describes that field as preparation for future changes in the API. That is the upgrade surface you should care about. If a future schema version arrives, script headers may need editing, and the metadata table records the app version each field requires (0.29+ for the core fields).

Your ongoing cost is mostly in the scripts you copy. Community scripts live in the repository and can be restructured, which is exactly why the README tells you not to point Raycast at those directories. Keeping your own copies means you decide when to pull changes, and you own any breakage when a script you copied depends on a tool you do not have installed.

## Conclusion

Adopt this if you use Raycast on macOS, you are comfortable writing or editing a shell script, and your automation is a single command with text or list output. Do not adopt it if you need a graphical interface, background services, or a cross-platform runner: the repository documents macOS paths, and the README points anyone wanting richer behaviour at the separate Extensions API instead. Before copying a community script, check whether its filename contains .template., because those require values to be set, and copy scripts into your own directory rather than pointing Raycast at the community folders.

## FAQ

### What are Raycast Script Commands?

They are scripts that Raycast can list and run from its root search. Each one carries a comment header with metadata such as schemaVersion, title and mode, and the README describes them as a way to execute commands from anywhere on your desktop.

### What are some basic commands in a Raycast Script Command?

The README's metadata table is the starting point: schemaVersion, title and mode are required, while packageName and icon are optional. Beyond the header, the body of the script is ordinary shell code, and the README recommends running Bash scripts through ShellCheck.

### What is the command to run a script in Raycast?

There is no single command. The README's flow is to add the script's directory through the Extensions tab in Raycast preferences using Add Script Directory, after which the script can be run from the Raycast root search.

## Sources

- [Issues](https://github.com/raycast/script-commands/issues)
- [License: MIT](https://github.com/raycast/script-commands/blob/master/LICENSE)
- [Project website](https://raycast.com)
- [raycast/script-commands on GitHub](https://github.com/raycast/script-commands)
- [README](https://github.com/raycast/script-commands/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/raycast-script-commands