Character Vault
Any Concept / Any System
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Script:Command Shell

From Roll20 Wiki

(Redirected from Script:CommandShell)
Jump to: navigation, search
API ScriptAuthor: manveti
Version: 1.3
Last Modified: 2015-07-09
Code: CommandShell
Dependencies: None
Conflicts: None

CommandShell is a framework for chat commands, intended to ease their processing and avoid command name collisions. CommandShell provides a central system for registering commands and marshalling chat commands to the appropriate callback, POSIX-style argument parsing, access control, and simple output functions.

It is recommended that this script be used in conjunction with the IsGM Auth Module, which will improve detection of messages coming from the GM. In the absence of that module, a player will only be detected as GM when sending chat as their player name (i.e. not speaking as a character).



By default, commands may only be executed by a GM. The !shell-permission command is provided to set permissions to allow or deny execution by other players, while the !help command may be used to list all available commands. By default, the !help command has world-execute permission, but that permission can be revoked like any other command.

!shell-permission <action> <command name> [player]


→ !shell-permission action


→ !help


→ add


→ remove




→ ε


Parameter Values
action Valid values are add and remove. This will add or remove permission for a specified player (or all players, if no player is specified) to use the given command. World-execute permission is stored separately from player-specific permission, so if world-execute permision is revoked, any player-specific permissions will remain.
command name The name of the command to alter permissions for. The command given must be registered to the shell. (See below)
player Optional. If set, the permission for the given player will be added or removed for the given command. If omitted, world-execute permission will be changed instead.

Registering Commands

Each usable command in a script needs to be registered in code somewhere. Commands may also be unregistered.

Registered commands can be executed by name (e.g. !mycommand). If a user attempts to execute a command for which they lack permission, they will receive an error message and execution will fail.

Shell.registerCommand(command, signature, description, callback)


The command name. Multiple commands of the same name may not be registered. Scripts may include or omit the leading exclamation mark; the shell will handle its requirement automatically.
Example syntax of the command (e.g. "!mycommand [some arguments]"). This will be used in the automatically-generated help output.
A more detailed description of the command and how to use it. This will be used in the automatically-generated help output.
The function which will be called whenever the command is invoked by a user with appropriate permission. The function should accept an array of the command arguments (e.g. ["!mycommand", "foo", "bar"]) and the original chat message object.

Utility Functions

Several utility functions are also made available by the shell.

Shell.write(message[, to[, style[, from]]])
Shell.rawWrite(message[, to[, style[, from]]])
Shell.writeAndLog(message[, to])
Shell.sendChat(speakingAs, input)
  • write sends message to the chat, preserving whitespace and angle brackets.
  • rawWrite sends message to the chat without preserving any special characters. Useful for writing HTML directly to the chat.
  • writeAndLog is equivalent to write while additionally logging message to the console.
  • writeErr is equivalent to writeAndLog(message, 'gm')
  • sendChat is a wrapper around the built-in sendChat function, which will execute CommandShell-aware API commands.
  • tokenize splits the given string around whitespace; quotes within the message may be used to preserve the whitespace. Useful for splitting an input message into command arguments.


A message to output or parse
Player or character to send message to. If not specified, the message will be visible to everyone.
Inline CSS to include in the <div> that wraps the message.
Used as first argument to sendChat. If not specified, the name "Shell" will be used instead.


v1.3 (2015-07-09)

  • Pass speakingAs through to handlers in wrapped sendChat

v1.2 (2015-06-11)

  • Add wrapper for sendChat which can execute CommandShell-aware API commands

v1.1 (2015-05-31)

  • Fix argument parsing when final token is quoted

v1.0 (2015-01-07)

  • Initial release