Extend the Confluent CLI with Plugins¶

Important

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.

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 the plugins.

To use plugins, you need to have Confluent CLI 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 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:
```
confluent that-command
```
```
confluent that_command
```
On Windows, the .bat, .cmd, .com, .exe, and .ps1 file extensions are supported.

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 confluent plugin list command output will have a warning message that the offending plugin will be ignored.

A plugin cannot override an existing command. Therefore, a plugin whose name exactly matches a native CLI command’s name will be ignored.
Two or more plugins cannot 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 first look for the plugin with the longest possible name, confluent-example-arg1.
Since the confluent-example-arg1 plugin is not found, the CLI will then treat the last dash-separated value as an argument and try to find the next longest possible name, confluent-example.
The CLI repeats 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.
Since confluent-example exists, the CLI invokes this plugin and passes all arguments and flags after the plugin’s name (arg1 --flag=val arg2) as arguments to the plugin process.

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.

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 that 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