packer-cn/website/source/docs/extend/command.html.markdown

layout
docs

Custom Command Development

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.

Prior to reading this page, it is assumed you have read the page on plugin development basics.

Command plugins implement the packer.Command interface and are served using the plugin.ServeCommand function. Commands actually have no control over what keyword invokes the command with the packer binary. The keyword to invoke the command depends on how the plugin is installed and configured in the core Packer configuration.

Warning! This is an advanced topic. If you're new to Packer, we recommend getting a bit more comfortable before you dive into writing plugins.

The Interface

The interface that must be implemented for a command is the packer.Command interface. It is reproduced below for easy reference. The reference below also contains some basic documentatin of what each of the methods are supposed to do.

type Command interface {
	// Help should return long-form help text that includes the command-line
	// usage, a brief few sentences explaining the function of the command,
	// and the complete list of flags the command accepts.
	Help() string

	// Run should run the actual command with the given environmet and
	// command-line arguments. It should return the exit status when it is
	// finished.
	Run(env Environment, args []string) int

	// Synopsis should return a one-line, short synopsis of the command.
	// This should be less than 50 characters ideally.
	Synopsis() string
}

The "Help" Method

The Help method returns long-form help. This help is most commonly shown when a command is invoked with the --help or -h option. The help should document all the available command line flags, purpose of the command, etc.

Packer commands generally follow the following format for help, but it is not required. You're allowed to make the help look like anything you please.

Usage: packer COMMAND ARGS...

  Brief one or two sentence about the function of the command.

Options:

  -foo=bar                  A description of the flag.
  -another                  Another description.

The "Run" Method

Run is what is called when the command is actually invoked. It is given the packer.Environment, which has access to almost all components of the current Packer run, such as UI, builders, other plugins, etc. In addition to the environment, the remaining command line args are given. These command line args have already been stripped of the command name, so they can be passed directly into something like the standard Go flag package for command-line flag parsing.

The return value of Run is the exit status for the command. If everything ran successfully, this should be 0. If any errors occured, it should be any positive integer.

The "Synopsis" Method

The Synopsis method should return a short single-line description of what the command does. This is used when packer is invoked on its own in order to show a brief summary of the commands that Packer supports.

The synopsis should be no longer than around 50 characters, since it is already appearing on a line with other text.