Extend the Confluent CLI with Plugins¶

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

To use plugins, you must have Confluent CLI installed. Note that plugins may or may not be enabled by default depending on the environment you are operating in:

macOS and Linux users: Confluent CLI plugins are enabled by default. If you have a large $PATH and plugins take too long to index, you can opt out by adding "disable_plugins": true to your configuration file at $HOME/.confluent/config.json.
Windows users: Confluent CLI plugins are disabled by default. You can manually re-enable plugins in the ~/.confluent/config.json file.

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 confluent-.
Subcommands in a plugin’s command are separated by dashes (-) in its filename. For example, a plugin named confluent-this-command would define the command confluent 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 confluent-that_command by running either of the following commmands:
```
confluent that-command
```
```
confluent that_command
```
On Windows, all file extensions defined in $PATHTEXT are supported.
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 confluent 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 confluent example arg1 --flag=val arg2, the CLI will:

Look for the plugin with the longest possible name, confluent-example-arg1.
Treat the last dash-separated value as an argument and try to find the next longest possible name, confluent-example–since the confluent-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 confluent-–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 confluent-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 Confluent CLI.

Discover Plugins¶

Plugins are user-created and are not included with the Confluent CLI. Use the confluent plugin list command to search your PATH for plugin executables. This command lists plugin names alongside their file paths in the order in which they are discovered.

Disable Plugins¶

The Confluent CLI plugins feature is enabled by default. To disable the plugin feature, add the following in the configuration file, ~/.confluent/config.json:

"disable_plugins": true

Example¶

To list Kafka clusters in all environments:

Create a plugin file called confluent-kafka-cluster-list_all:

#!/bin/bash
for env_id in $(confluent environment list -o json | jq -r '.[].id');
do
  confluent kafka cluster list --environment $env_id
done

Make the plugin file executable:

sudo chmod +x confluent-kafka-cluster-list_all

Place the plugin file in your PATH.

Ensure the plugin has been discovered by the Confluent CLI:

confluent plugin list
           Plugin Name           |                    File Path
---------------------------------+--------------------------------------------------
  confluent kafka cluster        | /usr/local/bin/confluent-kafka-cluster-list_all
  list-all                       |

Execute the plugin.

confluent kafka cluster list-all
       ID      |   Name    | Type  | Provider |  Region   | Availability | Status
---------------+-----------+-------+----------+-----------+--------------+---------
    lkc-j9v1yw | cluster_0 | BASIC | aws      | us-east-1 | single-zone  | UP
       ID      |   Name    | Type  | Provider |  Region   | Availability | Status
---------------+-----------+-------+----------+-----------+--------------+---------
    lkc-rj09ok | cluster_1 | BASIC | aws      | us-east-1 | single-zone  | UP