# Writing and installing scripts

> Add slash commands with AppleScript or an explicitly installed scripting runtime.

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:

```applescript
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`:

```applescript
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:

```applescript
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](https://www.textualapp.com/docs/legacy/guides/writing-scripts); 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.
