rsh

Plugins

Rsh can be extended using plugins. Plugins behave much like Rsh's built-in commands, with the added benefit that they can be added separately from Rsh itself.

Rsh plugins are executables; Rsh launches them as needed and communicates with them over stdin, stdout, and stderropen in new window. Rsh plugins can use either JSON or MSGPACK as their communication encoding.

Adding a plugin

To add a plugin, call the register command to tell Rsh where to find it. As you do, you'll need to also tell rsh what encoding the plugin uses.

Please note that the plugin name needs to start with rsh_plugin_, Rsh uses the name prefix to detect plugins.

Linux+macOS:

> register ./my_plugins/rsh_plugin_cool

Windows:

> register .\my_plugins\rsh_plugin_cool.exe

When register is called:

  1. Rsh launches the plugin, and waits for the plugin to tell Rsh which communication encoding it should use
  2. Rsh sends it a "Signature" message over stdin
  3. The plugin responds via stdout with a message containing its signature (name, description, arguments, flags, and more)
  4. Rsh saves the plugin signature in the file at $rsh.plugin-path, so registration is persisted across multiple launches

Once registered, the plugin is available as part of your set of commands: 

> help commands | where command_type == "plugin"

Examples

Rsh's main repo contains example plugins that are useful for learning how the plugin protocol works:

Debugging

The simplest way to debug a plugin is to print to stderr; plugins' standard error streams are redirected through Rsh and displayed to the user.

Help

Rsh's plugin documentation is a work in progress. If you're unsure about something, the #plugins channel on the Rsh Discordopen in new window is a great place to ask questions!

More details

The plugin chapter in the contributor book offers more details on the intricacies of how plugins work from a software developer point of view.