Extend the Pulsar CLI with Plugins

Pulsar CLI (pulsarctl) plugins enable you to extend the capabilities of the Pulsar CLI to interact with Pulsar resources. You can create simple and complex scripting workflows using the CLI and plugins.

To use plugins, you must have pulsarctl installed.

Write a plugin

You can write a plugin in any programming or scripting language that allows you to write terminal commands.

Plugin file name

A plugin’s command name is determined by its filename. The following rules apply:

A plugin filename must begin with pulsarctl-.
Subcommands in a plugin’s command are separated by dashes (-) in its filename. For example, a plugin named streamnative-this-command would define the command streamnative this command.
To have a plugin command containing dashes (-) or underscores (_), use an underscore (_) in the plugin filenames in place of a dash (-). For example, you can invoke a plugin whose filename is streamnative-that_command by running the following commmand:
```
streamnative that_command
```
On Linux and macOS, any file extension is supported as long as the file is executable.

Naming limitations

The following limitations apply to naming plugins. If these rules are violated, the plugin list command output will have a warning message that the offending plugin will be ignored.

A plugin can’t override an existing command. Therefore, a plugin whose name exactly matches a native CLI command’s name will be ignored.
Two or more plugins can’t have the same name. The first one found on your $PATH is used. The other plugins discovered with the same name are ignored.

Plugin flags and arguments

If the user invokes a plugin and passes in additional arguments and/or flags, it is the plugin’s responsibility to validate and parse them, as the CLI will pass in arguments and flags as-is.

For example, when running pulsarctl example arg1 --flag=val arg2, the pulsarctl will:

Look for the plugin with the longest possible name, pulsarctl-example-arg1.
Treat the last dash-separated value as an argument and try to find the next longest possible name, pulsarctl-example since the pulsarctl-example-arg1 plugin is not found.
Repeat the search process until either a plugin is found or there are no more dash-separated values besides pulsarctl- meaning that no plugins matching the command have been found.
Invoke the found plugin and pass all arguments and flags after the plugin’s name (arg1 --flag=val arg2) as arguments to the plugin process, since pulsarctl-example exists.

Install a Plugin

To install and use a plugin:

Make the plugin file executable:
```
sudo chmod +x <plugin file>
```
Place the plugin file on your PATH.
Execute the plugin.
Note that plugin executables inherit the environment settings from the pulsarctl.

Discover plugins

Plugins are user-created and may or may not be included with the Pulsar CLI. Use the plugin list command to search your PATH for plugin executables. This command lists plugin names in the order in which they are discovered.

Plugin repository

You can find contributed plugins for use with the pulsarctl in StreamNative’s GitHub repository. You can also contribute a plugin for others to leverage as well. To do so, follow the steps to add a plugin.

Example plugin

Here is an example plugin written in bash script to print a message. The plugin is saved in a file named pulsarctl-foo.

#!/bin/bash

if [[ $1 == "args" ]]
then
    echo "I am the args of the pulsarctl-foo"
    exit 0
fi

echo "I am a plugin named pulsarctl-foo"

To use the above plugin, simply make the file pulsarctl-foo executable:

chmod +x ./pulsarctl-foo

and place it anywhere in your PATH:

mv pulsarctl-foo /usr/local/bin

You may now invoke your plugin as a kubectl command:

pulsarctl foo

You will see the output as follows:

I am a plugin named pulsarctl-foo

All args and flags are passed as-is to the executable:

pulsarctl foo args

You will see the output as follows:

I am the args of the pulsarctl-foo