<a id="confluent-cli-plugins"></a>

# 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](install.md#cli-install). 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.

## Plugin repository

You can find contributed plugins for use with the Confluent CLI in Confluent’s dedicated [GitHub repository](https://github.com/confluentinc/cli-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/confluentinc/cli-plugins/blob/main/CONTRIBUTING.md).

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

## Install a Plugin

To install and use a plugin:

1. Make the plugin file executable:
   ```bash
   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
   Confluent CLI.

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

```json
"disable_plugins": true
```

## 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 commands:
  ```text
  confluent that-command
  ```

  ```text
  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:

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

## Example

To list Kafka clusters in all environments:

1. Create a plugin file called `confluent-kafka-cluster-list_all`:
   ```bash
   #!/bin/bash
   for env_id in $(confluent environment list -o json | jq -r '.[].id');
   do
     confluent kafka cluster list --environment $env_id
   done
   ```
2. Make the plugin file executable:
   ```bash
   sudo chmod +x confluent-kafka-cluster-list_all
   ```
3. Place the plugin file in your `PATH`.
4. Ensure the plugin has been discovered by the Confluent CLI:
   ```text
   confluent plugin list
              Plugin Name           |                    File Path
   ---------------------------------+--------------------------------------------------
     confluent kafka cluster        | /usr/local/bin/confluent-kafka-cluster-list_all
     list-all                       |
   ```
5. Execute the plugin.
   ```text
   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
   ```