Writing and installing scripts

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

Each returned line is processed as separate input. Ordinary text is sent to the selected conversation, while 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.

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.

Non-AppleScript executables need executable permissions. The old guide's claim that missing permission necessarily crashes Textual is historical; investigate the actual error and Console output for your version instead of assuming that behavior.

Troubleshooting

Check the command name, installed location, interpreter, permissions and error output in macOS Console. 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.