github.com/marksheahan/packer@v0.10.2-0.20160613200515-1acb2d6645a0/website/source/docs/extend/command.html.md (about)

     1  ---
     2  description: |
     3      Packer Commands are the components of Packer that add functionality to the
     4      `packer` application. Packer comes with a set of commands out of the box, such
     5      as `build`. Commands are invoked as `packer <COMMAND>`. Custom commands allow
     6      you to add new commands to Packer to perhaps perform new functionality.
     7  layout: docs
     8  page_title: Custom Command Development
     9  ...
    10  
    11  # Custom Command Development
    12  
    13  Packer Commands are the components of Packer that add functionality to the
    14  `packer` application. Packer comes with a set of commands out of the box, such
    15  as `build`. Commands are invoked as `packer <COMMAND>`. Custom commands allow
    16  you to add new commands to Packer to perhaps perform new functionality.
    17  
    18  Prior to reading this page, it is assumed you have read the page on [plugin
    19  development basics](/docs/extend/developing-plugins.html).
    20  
    21  Command plugins implement the `packer.Command` interface and are served using
    22  the `plugin.ServeCommand` function. Commands actually have no control over what
    23  keyword invokes the command with the `packer` binary. The keyword to invoke the
    24  command depends on how the plugin is installed and configured in the core Packer
    25  configuration.
    26  
    27  \~&gt; **Warning!** This is an advanced topic. If you're new to Packer, we
    28  recommend getting a bit more comfortable before you dive into writing plugins.
    29  
    30  ## The Interface
    31  
    32  The interface that must be implemented for a command is the `packer.Command`
    33  interface. It is reproduced below for easy reference. The actual interface in
    34  the source code contains some basic documentation as well explaining what each
    35  method should do.
    36  
    37  ``` {.go}
    38  type Command interface {
    39    Help() string
    40    Run(env Environment, args []string) int
    41    Synopsis() string
    42  }
    43  ```
    44  
    45  ### The "Help" Method
    46  
    47  The `Help` method returns long-form help. This help is most commonly shown when
    48  a command is invoked with the `--help` or `-h` option. The help should document
    49  all the available command line flags, purpose of the command, etc.
    50  
    51  Packer commands generally follow the following format for help, but it is not
    52  required. You're allowed to make the help look like anything you please.
    53  
    54  ``` {.text}
    55  Usage: packer COMMAND [options] ARGS...
    56  
    57    Brief one or two sentence about the function of the command.
    58  
    59  Options:
    60  
    61    -foo=bar                  A description of the flag.
    62    -another                  Another description.
    63  ```
    64  
    65  ### The "Run" Method
    66  
    67  `Run` is what is called when the command is actually invoked. It is given the
    68  `packer.Environment`, which has access to almost all components of the current
    69  Packer run, such as UI, builders, other plugins, etc. In addition to the
    70  environment, the remaining command line args are given. These command line args
    71  have already been stripped of the command name, so they can be passed directly
    72  into something like the standard Go `flag` package for command-line flag
    73  parsing.
    74  
    75  The return value of `Run` is the exit status for the command. If everything ran
    76  successfully, this should be 0. If any errors occurred, it should be any
    77  positive integer.
    78  
    79  ### The "Synopsis" Method
    80  
    81  The `Synopsis` method should return a short single-line description of what the
    82  command does. This is used when `packer` is invoked on its own in order to show
    83  a brief summary of the commands that Packer supports.
    84  
    85  The synopsis should be no longer than around 50 characters, since it is already
    86  appearing on a line with other text.