Inputs for Script Commands

Our number one feature request for Script Commands was inputs. With them, developers can alter the logic of a command without requiring the user to change the code of a script. We wanted to make sure that inputs fit into Raycast. This includes two important aspects:

1. It should be intuitive to adopt a command by others. No help should be required to understand the inputs.
2. It should be easy for the developer to specify inputs. They should concentrate on the solution they want to deliver.

The basics

What we came up with are typed arguments. Similar to our other parameters, they are defined in a comment at the top of a script. Here is an example:

#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Search in Google
# @raycast.mode silent

# Optional parameters:
# @raycast.icon 🔎
# @raycast.packageName Web Searches
# @raycast.argument1 { "type": "text", "placeholder": "query" }

open "https://www.google.com/search?q=${1// /%20}"

The above script command requires one argument of the type text. For now, we only support text. Later, we'll introduce more types such as URLs and enums. This is how the command looks in Raycast:

Raycast uses the placeholder of an argument to hint the user what to enter. When the script is executed, all arguments are parsed and forwarded to the script, giving the developer full flexibility to interpret them. Continuing the example from above, the text argument is used as query for a search in Google.

Advanced example

We support up to three arguments. Specify them as additional parameters:

#!/bin/bash

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

# Optional parameters:
# @raycast.icon images/things.png
# @raycast.packageName Things
# @raycast.argument1 { "type": "text", "placeholder": "Title" }
# @raycast.argument2 { "type": "text", "placeholder": "When (e.g. \"today\")" }

open "things:///add?title=${1// /%20}&when=${2// /%20}"

URL schemes are a great way to send commands to other apps. The above script uses two arguments to add a new todo to Things. The placeholder describes the usage of each argument. In this case, the first argument is the title of the new todo. The second argument is a date time string for a reminder. This is how the command looks in Raycast:

Our UI makes it clear what each argument does. A user can tab between the arguments and executes the script with ↵.

Pro mode

We made sure that Script Commands that require arguments fit into the rest of Raycast. They work especially well with aliases.

If you define an alias for your Script Command, you can type the alias, followed by a space to select the first required argument. This allows to rapidly search for something on Amazon — just type "am {your query}".

You can also assign a global hotkey to your Script Commands. When you press the hotkey, Raycast selects the first required argument and you can start typing.

Check out our public repository full of handy Script Commands. We welcome contributions and are curious to see what you build with the new arguments.

Wrapping it up

Typed arguments express the required inputs of a Script Command intuitively in Raycast. Equally, they make it easy for developers to specify what their scripts require. With additional types, we believe typed arguments lower the burden of running CLI tools.

Watch out for more to come!