github.com/itscaro/cli@v0.0.0-20190705081621-c9db0fe93829/docs/extend/cli_plugins.md (about)

     1  ---
     2  description: "Writing Docker CLI Plugins"
     3  keywords: "docker, cli plugin"
     4  ---
     5  
     6  <!-- This file is maintained within the docker/cli GitHub
     7       repository at https://github.com/docker/cli/. Make all
     8       pull requests against that repo. If you see this file in
     9       another repository, consider it read-only there, as it will
    10       periodically be overwritten by the definitive file. Pull
    11       requests which include edits to this file in other repositories
    12       will be rejected.
    13  -->
    14  
    15  # Docker CLI Plugin Spec
    16  
    17  The `docker` CLI supports adding additional top-level subcommands as
    18  additional out-of-process commands which can be installed
    19  independently. These plugins run on the client side and should not be
    20  confused with "plugins" which run on the server.
    21  
    22  This document contains information for authors of such plugins.
    23  
    24  ## Requirements for CLI Plugins
    25  
    26  ### Naming
    27  
    28  A valid CLI plugin name consists only of lower case letters `a-z`
    29  and the digits `0-9`. The leading character must be a letter. A valid
    30  name therefore would match the regex `^[a-z][a-z0-9]*$`.
    31  
    32  The binary implementing a plugin must be named `docker-$name` where
    33  `$name` is the name of the plugin. On Windows a `.exe` suffix is
    34  mandatory.
    35  
    36  ## Required sub-commands
    37  
    38  A CLI plugin must support being invoked in at least these two ways:
    39  
    40  * `docker-$name docker-cli-plugin-metadata` -- outputs metadata about
    41    the plugin.
    42  * `docker-$name [GLOBAL OPTIONS] $name [OPTIONS AND FURTHER SUB
    43    COMMANDS]` -- the primary entry point to the plugin's functionality.
    44  
    45  A plugin may implement other subcommands but these will never be
    46  invoked by the current Docker CLI. However doing so is strongly
    47  discouraged: new subcommands may be added in the future without
    48  consideration for additional non-specified subcommands which may be
    49  used by plugins in the field.
    50  
    51  ### The `docker-cli-plugin-metadata` subcommand
    52  
    53  When invoked in this manner the plugin must produce a JSON object
    54  (and nothing else) on its standard output and exit success (0).
    55  
    56  The JSON object has the following defined keys:
    57  * `SchemaVersion` (_string_) mandatory: must contain precisely "0.1.0".
    58  * `Vendor` (_string_) mandatory: contains the name of the plugin vendor/author. May be truncated to 11 characters in some display contexts.
    59  * `ShortDescription` (_string_) optional: a short description of the plugin, suitable for a single line help message.
    60  * `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.
    61  * `URL` (_string_) optional: a pointer to the plugin's web page.
    62  
    63  A binary which does not correctly output the metadata
    64  (e.g. syntactically invalid, missing mandatory keys etc) is not
    65  considered a valid CLI plugin and will not be run.
    66  
    67  ### The primary entry point subcommand
    68  
    69  This is the entry point for actually running the plugin. It maybe have
    70  options or further subcommands.
    71  
    72  #### Required global options
    73  
    74  A plugin is required to support all of the global options of the
    75  top-level CLI, i.e. those listed by `man docker 1` with the exception
    76  of `-v`.
    77  
    78  ## Configuration
    79  
    80  Plugins are expected to make use of existing global configuration
    81  where it makes sense and likewise to consider extending the global
    82  configuration (by patching `docker/cli` to add new fields) where that
    83  is sensible.
    84  
    85  Where plugins unavoidably require specific configuration the
    86  `.plugins.«name»` key in the global `config.json` is reserved for
    87  their use. However the preference should be for shared/global
    88  configuration whenever that makes sense.
    89  
    90  ## Connecting to the docker engine
    91  
    92  For consistency plugins should prefer to dial the engine by using the
    93  `system dial-stdio` subcommand of the main Docker CLI binary.
    94  
    95  To facilitate this plugins will be executed with the
    96  `$DOCKER_CLI_PLUGIN_ORIGINAL_CLI_COMMAND` environment variable
    97  pointing back to the main Docker CLI binary.
    98  
    99  All global options (everything from after the binary name up to, but
   100  not including, the primary entry point subcommand name) should be
   101  passed back to the CLI.
   102  
   103  ## Installation
   104  
   105  Plugins distributed in packages for system wide installation on
   106  Unix(-like) systems should be installed in either
   107  `/usr/lib/docker/cli-plugins` or `/usr/libexec/docker/cli-plugins`
   108  depending on which of `/usr/lib` and `/usr/libexec` is usual on that
   109  system. System Administrators may also choose to manually install into
   110  the `/usr/local/lib` or `/usr/local/libexec` equivalents but packages
   111  should not do so.
   112  
   113  Plugins distributed on Windows for system wide installation should be
   114  installed in either `%ProgramData%\Docker\cli-plugins` or
   115  `%ProgramFiles%\Docker\cli-plugins`.
   116  
   117  User's may on all systems install plugins into `~/.docker/cli-plugins`.
   118  
   119  ## Implementing a plugin in Go
   120  
   121  When writing a plugin in Go the easiest way to meet the above
   122  requirements is to simply call the
   123  `github.com/docker/cli/cli-plugins/plugin.Run` method from your `main`
   124  function to instantiate the plugin.