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
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
- Subcommands in a plugin’s command are separated by dashes (
-) in its filename. For example, a plugin named
streamnative-this-commandwould 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_commandby running the following commmand:
- On Linux and macOS, any file extension is supported as long as the file is executable.
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
$PATHis 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
- Look for the plugin with the longest possible name,
- Treat the last dash-separated value as an argument and try to find the next longest possible name,
pulsarctl-example-arg1plugin 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
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
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.
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.
Here is an example plugin written in bash script to print a message. The plugin is saved in a file named
if [[ $1 == "args" ]]
echo "I am the args of the pulsarctl-foo"
echo "I am a plugin named pulsarctl-foo"
To use the above plugin, simply make the file
chmod +x ./pulsarctl-foo
and place it anywhere in your
mv pulsarctl-foo /usr/local/bin
You may now invoke your plugin as a kubectl command:
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