website: custom commands

website/source/docs/extend/command.html.markdown

@@ -0,0 +1,90 @@
+---
+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](/docs/extend/developing-plugins.html).
+
+<div class="alert alert-block">
+  <strong>Warning!</strong> This is an advanced topic. If you're new to Packer,
+  we recommend getting a bit more comfortable before you dive into writing
+  plugins.
+</div>
+
+## 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.
+
+<pre class="prettyprint">
+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
+}
+</pre>
+
+### 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.

website/source/layouts/docs.erb

@@ -54,7 +54,7 @@
 							<li><a href="/docs/extend/plugins.html">Packer Plugins</a></li>
 							<li><a href="/docs/extend/developing-plugins.html">Developing Plugins</a></li>
 							<li><a href="/docs/extend/builder.html">Custom Builder</a></li>
-							<li><a href="#">Custom Command</a></li>
+							<li><a href="/docs/extend/command.html">Custom Command</a></li>
 							<li><a href="#">Custom Provisioner</a></li>
 						</ul>
 					</div><!--/.well -->