# plugin

The `plugin` command groups subcommands for interacting with Vault's plugins and the plugin catalog

### Examples <a href="#examples" id="examples"></a>

List all available secret plugins in the catalog:

```shell-session
$ vault plugin list secret

Name            Version
----            -------
ad              v0.14.0+builtin
alicloud        v0.13.0+builtin
...
```

Register a new secret plugin to the catalog:

```shell-session
$ vault plugin register \
  -sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
  secret my-custom-plugin
Success! Registered plugin: my-custom-plugin
```

Get information about a plugin in the catalog:

```shell-session
$ vault plugin info secret my-custom-plugin
Key                   Value
---                   -----
args                  []
builtin               false
command               my-custom-plugin
deprecation_status    n/a
name                  my-custom-plugin
oci_image             n/a
runtime               n/a
sha256                33e72f3d30ff2acdbf3cf3c8fa1c8945b60dab876c4226ab25617a63c9f16cc5
version               n/a
```

### Usage <a href="#usage" id="usage"></a>

```
Usage: vault plugin <subcommand> [options] [args]

  # ...

Subcommands:
    deregister       Deregister an existing plugin in the catalog
    info             Read information about a plugin in the catalog
    list             Lists available plugins
    register         Registers a new plugin in the catalog
    reload           Reload mounted plugin backend
    reload-status    Get the status of an active or recently completed global plugin reload
```

For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar.

## plugin deregister <a href="#plugin-deregister" id="plugin-deregister"></a>

The `plugin deregister` command deregisters an existing plugin from Vault's plugin catalog. If the plugin does not exist, no error is returned. The plugin's type of "auth", "database", or "secret" must be included.

### Examples <a href="#examples" id="examples"></a>

Deregister a plugin:

```shell-session
$ vault plugin deregister auth my-custom-plugin
Success! Deregistered plugin (if it was registered): my-custom-plugin
```

### Usage <a href="#usage" id="usage"></a>

The following flags are available in addition to the standard set of flags included on all commands.

* `-version` `(string: "")` - Semantic version of the plugin to deregister. If unset, only an unversioned plugin may be deregistered.

## plugin info <a href="#plugin-info" id="plugin-info"></a>

The `plugin info` displays information about a plugin in the catalog. The plugin's type of "auth", "database", or "secret" must be included.

### deprecation\_status field <a href="#deprecation_status-field" id="deprecation_status-field"></a>

As of 1.12, all builtin plugins will have an associated Deprecation Status. This status will be reflected in the `deprecation_status` key/value pair, seen below.

### Examples <a href="#examples" id="examples"></a>

Display information about a plugin

```shell-session
$ vault plugin info -version=v1.0.0 auth my-custom-plugin

Key                   Value
---                   -----
args                  []
builtin               false
command               my-custom-plugin
deprecation_status    n/a
name                  my-custom-plugin
oci_image             n/a
runtime               n/a
sha256                04ce575260fa3a2cfc477d13ac327108c50838a03917ec4d6df38ecdc64452d1
version               v1.0.0
```

```shell-session
$ vault plugin info database postgresql-database-plugin
Key                   Value
---                   -----
args                  []
builtin               true
command               n/a
deprecation_status    supported
name                  postgresql-database-plugin
oci_image             n/a
runtime               n/a
sha256                n/a
version               n/a
```

### Usage <a href="#usage" id="usage"></a>

The following flags are available in addition to the standard set of flags included on all commands.

#### Output options <a href="#output-options" id="output-options"></a>

* `-field` `(string: "")` - Print only the field with the given name. Specifying this option will take precedence over other formatting directives. The result will not have a trailing newline making it ideal for piping to other processes.
* `-format` `(string: "table")` - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the `VAULT_FORMAT` environment variable.

#### Command options <a href="#command-options" id="command-options"></a>

* `-plugin-version` `(string: "")` - Semantic version of the plugin to read from the catalog. If unspecified, refers to the unversioned plugin registered with the same name and type, or the built-in plugin, in that order of precedence.

## plugin list <a href="#plugin-list" id="plugin-list"></a>

The `plugin list` command lists all available plugins in the plugin catalog. It can be used alone or with a type such as "auth", "database", or "secret".

### Deprecation status column <a href="#deprecation-status-column" id="deprecation-status-column"></a>

As of 1.12, all builtin plugins will have an associated Deprecation Status. This status will be reflected in the `Deprecation Status` column, seen below. All non-builtin plugins will show a `Deprecation Status` of "n/a".

### Examples <a href="#examples" id="examples"></a>

List all available plugins in the catalog.

```shell-session
$ vault plugin list
Name                                 Type        Version
----                                 ----        -------
alicloud                             auth        v0.13.0+builtin
# ...

$ vault plugin list database
Name                                 Version
----                                 -------
cassandra-database-plugin            v1.13.0+builtin.vault
# ...
```

List detailed plugin information:

```shell-session
$ vault plugin list -detailed
Name        Type    Version                  Container    Deprecation Status
----        ----    -------                  ---------    ------------------
alicloud    auth    v0.12.0+builtin          false        supported
app-id      auth    v1.12.0+builtin.vault    false        pending removal
# ...
```

### Usage <a href="#usage" id="usage"></a>

The following flags are available in addition to the standard set of flags included on all commands.

#### Output options <a href="#output-options" id="output-options"></a>

* `-format` `(string: "table")` - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the `VAULT_FORMAT` environment variable.

#### Command options <a href="#command-options" id="command-options"></a>

* `-detailed` `(bool: false)` - Print detailed information such as version and deprecation status about each plugin.

## plugin register <a href="#plugin-register" id="plugin-register"></a>

The `plugin register` command registers a new plugin in Vault's plugin catalog. The plugin's type of "auth", "database", or "secret" must be included.

### Examples <a href="#examples" id="examples"></a>

Register a plugin:

```shell-session
$ vault plugin register \
    -sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
    auth my-custom-plugin
Success! Registered plugin: my-custom-plugin
```

Register a plugin with custom args:

```shell-session
$ vault plugin register \
    -sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
    -args=--with-glibc,--with-curl-bindings \
    auth my-custom-plugin
```

### Usage <a href="#usage" id="usage"></a>

The following flags are available in addition to the standard set of flags included on all commands.

#### Output options <a href="#output-options" id="output-options"></a>

* `-format` `(string: "table")` - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the `VAULT_FORMAT` environment variable.

#### Command options <a href="#command-options" id="command-options"></a>

* `-sha256` `(string: <required>)` - SHA256 of the plugin binary or the OCI image provided. This is required for all plugins.
* `-args` `([]string: [])` - Argument to pass to the plugin when starting. This flag can be specified multiple times to specify multiple args.
* `-command` `(string: "")` - Command to spawn the plugin. This defaults to the name of the plugin if both `-oci_image` and `-command` are unspecified.
* `-env` `([]string: [])` - Environment variables to set for the plugin when starting. This flag can be specified multiple times to specify multiple environment variables.
* `-oci_image` `(string: "")` - OCI image to run. If specified, setting `-command`, `-args`, and `-env` will update the container's entrypoint, args, and environment variables (append-only) respectively.
* `-runtime` `(string: "")` - Vault plugin runtime to use if `-oci_image` is specified.
* `-version` `(string: "")` - Semantic version of the plugin. Used as the tag when specifying `-oci_image`, but any leading 'v' will automatically be trimmed.

## plugin reload <a href="#plugin-reload" id="plugin-reload"></a>

The `plugin reload` command is used to reload mounted plugin backends. Either the plugin name (`plugin`) or the desired plugin backend mounts (`mounts`) must be provided, but not both. In the case that the plugin name is provided, all mounted paths that use that plugin backend will be reloaded.

### Examples <a href="#examples" id="examples"></a>

Reload a plugin by name:

```shell-session
$ vault plugin reload -plugin my-custom-plugin
Success! Reloaded plugin: my-custom-plugin
```

Reload an auth plugin by mount:

```shell-session
$ vault plugin reload \
  -mounts auth/my-custom-plugin-1 \
  -mounts auth/my-custom-plugin-2
Success! Reloaded mounts: [auth/my-custom-plugin-1/ auth/my-custom-plugin-2/]
```

Reload a secrets plugin by mount:

```shell-session
$ vault plugin reload \
  -mounts my-custom-plugin-1 \
  -mounts my-custom-plugin-2
Success! Reloaded mounts: [my-custom-plugin-1/ my-custom-plugin-2/]
```

### Usage <a href="#usage" id="usage"></a>

The following flags are available in addition to the standard set of flags included on all commands.

#### Command options <a href="#command-options" id="command-options"></a>

* `-plugin` `(string: "")` - The name of the plugin to reload, as registered in the plugin catalog.
* `-mounts` `(array: [])` - Array or comma-separated string mount paths of the plugin backends to reload.
* `-scope` `(string: "")` - The scope of the reload. For local reloads, omit this flag. For reloads that span multiple Vault clusters, use `global`.

## plugin runtime <a href="#plugin-runtime" id="plugin-runtime"></a>

The `plugin runtime` command groups subcommands for interacting with and configuring the context within which your external plugins run.

Limited type support

Support for runtime types is currently limited to \`container\`.

Limited OS support

Support for the 'container\` runtime is currently limited to Linux.

If you register a container plugin without referencing a plugin runtime, it will use gVisor's OCI runtime `runsc` by default, with no resource limits. You can use plugin runtimes to configure other OCI-compliant runtimes such as `runc`. Vault does not come packaged with any supporting container runtimes, and you must separately install whichever you want to use.

To use a registered plugin runtime, use the `-runtime` option with the plugin registration command.

See containerized plugins for more details on running external plugins in containers.

### Examples <a href="#examples" id="examples"></a>

Register a new plugin runtime to the catalog:

```shell-session
$ vault plugin runtime register -type=container -oci_runtime=runc runc
Success! Registered plugin runtime: runc
```

List all available plugin runtimes in the catalog:

```shell-session
$ vault plugin runtime list

Name    Type         OCI Runtime    Parent Cgroup    CPU Nanos    Memory Bytes
----    ----         -----------    -------------    ---------    ------------
runc    container    runc           n/a              0            0
```

Get information about a plugin runtime in the catalog:

```shell-session
$ vault plugin runtime info -type=container runc
Key              Value
---              -----
cgroup_parent    n/a
cpu_nanos        0
memory_bytes     0
name             runc
oci_runtime      runc
type             container
```

### Usage <a href="#usage" id="usage"></a>

```
Usage: vault plugin runtime <subcommand> [options] [args]

  # ...

Subcommands:
    deregister    Deregister an existing plugin runtime in the catalog
    info          Read information about a plugin runtime in the catalog
    list          Lists available plugin runtimes
    register      Registers a new plugin runtime in the catalog
```

For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar.

## plugin runtime deregister <a href="#plugin-runtime-deregister" id="plugin-runtime-deregister"></a>

Deregister an existing plugin runtime in the catalog with the given name. Returns an error if a registered plugin references the named plugin runtime or the named runtime does not exist.

Limited type support

Support for runtime types is currently limited to \`container\`.

### Examples <a href="#examples" id="examples"></a>

Deregister a plugin:

```shell-session
$ vault plugin runtime deregister -type=container my-plugin-runtime
Success! Deregistered plugin runtime: my-plugin-runtime
```

### Usage <a href="#usage" id="usage"></a>

The following flags are available in addition to the standard set of flags included on all commands.

* `-type` `(string: <required>)` - Plugin runtime type. Vault currently only supports `container` runtime type.

## plugin runtime info <a href="#plugin-runtime-info" id="plugin-runtime-info"></a>

Displays information about a plugin runtime in the catalog with the given name. If the plugin runtime does not exist, an error is returned.

Limited type support

Support for runtime types is currently limited to \`container\`.

### Examples <a href="#examples" id="examples"></a>

Display information about a plugin

```shell-session
$ vault plugin runtime info -type=container runc
Key              Value
---              -----
cgroup_parent    n/a
cpu_nanos        0
memory_bytes     0
name             runc
oci_runtime      runc
type             container
```

### Usage <a href="#usage" id="usage"></a>

The following flags are available in addition to the standard set of flags included on all commands.

#### Output options <a href="#output-options" id="output-options"></a>

* `-field` `(string: "")` - Print information for the named field without a trailing newline. The `-field` parameter takes precedence over other formatting directives.
* `-format` `(string: "table")` - Print the output for the current command in the given format. Valid formats are `table`, `json`, or `yaml`. Use the `VAULT_FORMAT` environment variable to set your output preferences globally.

#### Command options <a href="#command-options" id="command-options"></a>

* `-type` `(string: "")` - Plugin runtime type. Vault currently only supports `container` runtime type.

## plugin list <a href="#plugin-list" id="plugin-list"></a>

List all plugin runtimes currently registered with Vault. Returns all the available plugin runtimes or an error if the set of registered runtimes is empty. Vault considers any registered plugin runtime "available", regardless of whether it is currently in use.

### Examples <a href="#examples" id="examples"></a>

List all available plugin runtimes in the catalog.

```shell-session
$ vault plugin runtime list

Name    Type         OCI Runtime    Parent Cgroup    CPU Nanos    Memory Bytes
----    ----         -----------    -------------    ---------    ------------
runc    container    runc           n/a              0            0
```

### Usage <a href="#usage" id="usage"></a>

The following flags are available in addition to the standard set of flags included on all commands.

#### Output options <a href="#output-options" id="output-options"></a>

* `-format` `(string: "table")` - Print the output for the current command in the given format. Valid formats are `table`, `json`, or `yaml`. Use the `VAULT_FORMAT` environment variable to set your output preferences globally.

#### Command options <a href="#command-options" id="command-options"></a>

* `-type` `(string: "")` - Plugin runtime type. Vault currently only supports `container` runtime type.

## plugin runtime register <a href="#plugin-runtime-register" id="plugin-runtime-register"></a>

Register a new plugin runtime in the plugin runtime catalog of your Vault instance.

Limited type support

Support for runtime types is currently limited to \`container\`.

To use a registered plugin runtime, use the `-runtime` option with the plugin registration command.

### Examples <a href="#examples" id="examples"></a>

Register a plugin runtime:

```shell-session
$ vault plugin runtime register -type=container -oci_runtime=runc runc
Success! Registered plugin runtime: runc
```

Register a plugin runtime with resource limits:

```shell-session
vault plugin runtime register \
    -type=container \
    -cpu_nanos=100000000 \
  runsc
```

### Usage <a href="#usage" id="usage"></a>

The following flags are available in addition to the standard set of flags included on all commands.

#### Command options <a href="#command-options" id="command-options"></a>

* `-type` `(string: <required>)` - Plugin runtime type. Vault currently only supports `container` as a runtime type.
* `-cgroup_parent` `(string: "")` - Parent cgroup to set for each container. Use `cgroup_parent` to control the total resource usage for a group of plugins.
* `-cpu_nanos` `(int: 0)` - CPU limit to set per container in billionths of a CPU core. Defaults to no limit.
* `-memory_bytes` `(int: 0)` - Memory limit to set per container in bytes. Defaults to no limit.
* `-oci_runtime` `(string: "")` - Open Container Initiative (OCI) compliant container runtime to use. Default is the gVisor OCI runtime, `runsc`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/vault/cli/plugin.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.