Writing and installing scripts
Add slash commands with AppleScript or an explicitly installed scripting runtime.
On this page
A script adds a command to Textual's input field. A file named example.scpt, for instance, is invoked with /example; additional text becomes input to the script.
AppleScript entry point
The documented handler receives the user's input and the selected channel or query:
on textualcmd(inputString, destinationChannel)
return "This message will be sent to the selected conversation."
end textualcmd
Scripts in other languages receive the same information as command line arguments: the first argument is the selected channel or query (empty in the server console), and each word typed after the command follows as its own argument. /example one two typed in #textual gives a shell script #textual as $1, one as $2 and two as $3; shift; echo "$*" turns the typed text back into one string.
Nothing else is passed: not your nickname and not the server. A script only runs because you typed its command, so you are always the user who invoked it.
The output is handled exactly as if you had typed it into the selected conversation. Each returned line is processed as separate input: ordinary text is sent to the conversation, a line starting with / is performed as a command, and a line starting with // sends text that begins with a slash. A command may need an explicit destination. For an action with a destination, the original API uses /sme:
on textualcmd(inputString, destinationChannel)
return "/sme " & destinationChannel & " " & inputString
end textualcmd
Be clear about where output will go before testing with personal information or a command that changes channel state.
Messages only you see
Return errors and usage hints as an /echo command. /echo prints its text in your own window and nothing is sent to the server:
on textualcmd(inputString, destinationChannel)
if inputString is "" then
return "/echo Usage: /example <text>"
end if
return inputString
end textualcmd
A script in another language writes the same line to its output, for example echo "/echo Usage: /example <text>".
Installation and permissions
The original guide documents opening a .scpt file with Textual and lists separate script directories for App Store and standalone copies. Those historical paths are retained in the full scripting reference; sandbox changes mean you should verify the path used by your installed version.
A script that controls another application may need macOS Automation permission. Install only scripts you trust, and inspect their source before allowing them to read files, control apps or run shell commands.
Other languages
The original interface lists Python, Ruby, Perl, shell and PHP scripts. Support for a file extension does not mean macOS supplies its interpreter: Python 2.7 was removed in macOS 12.3, and system PHP was removed in Monterey. Install and manage the runtime your script actually needs and use a suitable interpreter path.
Make non-AppleScript scripts executable (chmod +x) and start them with a #! line. Textual ignores script files that are neither AppleScript nor executable; typing their command then goes to the server like any unknown command.
Troubleshooting
Check the command name, installed location, interpreter and permissions. When a script can't be performed or an AppleScript reports an error, Textual shows the error in the selected window and in macOS Console. Only a script's standard output is used; standard error is not shown. To output nothing, return an empty string. An iTunes-era example may also need changes for the app it is intended to automate. The original reference retains the complete input/output contract and examples for older integrations.
Keep reading
Source material
Adapted from the Textual knowledgebase, with related historical details preserved in the legacy library.
Need a hand? Contact us about this guide.