Docker CLI Plugin Spec
docker CLI supports adding additional top-level subcommands as
additional out-of-process commands which can be installed
independently. These plugins run on the client side and should not be
confused with “plugins” which run on the server.
This document contains information for authors of such plugins.
Requirements for CLI Plugins
A valid CLI plugin name consists only of lower case letters
and the digits
0-9. The leading character must be a letter. A valid
name therefore would match the regex
The binary implementing a plugin must be named
$name is the name of the plugin. On Windows a
.exe suffix is
A CLI plugin must support being invoked in at least these two ways:
docker-$name docker-cli-plugin-metadata-- outputs metadata about the plugin.
docker-$name [GLOBAL OPTIONS] $name [OPTIONS AND FURTHER SUB COMMANDS]-- the primary entry point to the plugin’s functionality.
A plugin may implement other subcommands but these will never be invoked by the current Docker CLI. However doing so is strongly discouraged: new subcommands may be added in the future without consideration for additional non-specified subcommands which may be used by plugins in the field.
When invoked in this manner the plugin must produce a JSON object (and nothing else) on its standard output and exit success (0).
The JSON object has the following defined keys:
SchemaVersion(string) mandatory: must contain precisely “0.1.0”.
Vendor(string) mandatory: contains the name of the plugin vendor/author. May be truncated to 11 characters in some display contexts.
ShortDescription(string) optional: a short description of the plugin, suitable for a single line help message.
Version(string) optional: the version of the plugin, this is considered to be an opaque string by the core and therefore has no restrictions on its syntax.
URL(string) optional: a pointer to the plugin’s web page.
A binary which does not correctly output the metadata (e.g. syntactically invalid, missing mandatory keys etc) is not considered a valid CLI plugin and will not be run.
The primary entry point subcommand
This is the entry point for actually running the plugin. It maybe have options or further subcommands.
Required global options
A plugin is required to support all of the global options of the
top-level CLI, i.e. those listed by
man docker 1 with the exception
Plugins are expected to make use of existing global configuration
where it makes sense and likewise to consider extending the global
configuration (by patching
docker/cli to add new fields) where that
Where plugins unavoidably require specific configuration the
.plugins.«name» key in the global
config.json is reserved for
their use. However the preference should be for shared/global
configuration whenever that makes sense.
Connecting to the docker engine
For consistency plugins should prefer to dial the engine by using the
system dial-stdio subcommand of the main Docker CLI binary.
To facilitate this plugins will be executed with the
$DOCKER_CLI_PLUGIN_ORIGINAL_CLI_COMMAND environment variable
pointing back to the main Docker CLI binary.
All global options (everything from after the binary name up to, but not including, the primary entry point subcommand name) should be passed back to the CLI.
Plugins distributed in packages for system wide installation on
Unix(-like) systems should be installed in either
depending on which of
/usr/libexec is usual on that
system. System Administrators may also choose to manually install into
/usr/local/libexec equivalents but packages
should not do so.
Plugins distributed on Windows for system wide installation should be
installed in either
User’s may on all systems install plugins into
Implementing a plugin in Go
When writing a plugin in Go the easiest way to meet the above
requirements is to simply call the
github.com/docker/cli/cli-plugins/plugin.Run method from your
function to instantiate the plugin.