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