> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/tools/cli/pulsarctl/pulsarctl-overview##install-pulsarctl).

## 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:
  ```bash theme={null}
  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:

1. Look for the plugin with the longest possible name, `pulsarctl-example-arg1`.
2. 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.
3. 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.
4. 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:

1. Make the plugin file executable:

   ```bash theme={null}
   sudo chmod +x <plugin file>
   ```

2. Place the plugin file on your PATH.

3. 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](https://github.com/streamnative/pulsarctl/tree/master/plugins). You can also contribute a plugin for others to leverage as well. To do so, follow the steps to [add a plugin](https://github.com/streamnative/pulsarctl/blob/master/CONTRIBUTING.md).

## 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`.

```bash theme={null}
#!/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:

```bash theme={null}
chmod +x ./pulsarctl-foo
```

and place it anywhere in your `PATH`:

```bash theme={null}
mv pulsarctl-foo /usr/local/bin
```

You may now invoke your plugin as a kubectl command:

```bash theme={null}
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:

```bash theme={null}
pulsarctl foo args
```

You will see the output as follows:

```
I am the args of the pulsarctl-foo
```