github.com/StackPointCloud/packer@v0.10.2-0.20180716202532-b28098e0f79b/website/source/docs/commands/index.html.md (about)

     1  ---
     2  description: |
     3      Packer is controlled using a command-line interface. All interaction with
     4      Packer is done via the `packer` tool. Like many other command-line tools, the
     5      `packer` tool takes a subcommand to execute, and that subcommand may have
     6      additional options as well. Subcommands are executed with `packer SUBCOMMAND`,
     7      where "SUBCOMMAND" is the actual command you wish to execute.
     8  layout: docs
     9  page_title: Commands
    10  sidebar_current: 'docs-commands'
    11  ---
    12  
    13  # Packer Commands (CLI)
    14  
    15  Packer is controlled using a command-line interface. All interaction with Packer
    16  is done via the `packer` tool. Like many other command-line tools, the `packer`
    17  tool takes a subcommand to execute, and that subcommand may have additional
    18  options as well. Subcommands are executed with `packer SUBCOMMAND`, where
    19  "SUBCOMMAND" is the actual command you wish to execute.
    20  
    21  If you run `packer` by itself, help will be displayed showing all available
    22  subcommands and a brief synopsis of what they do. In addition to this, you can
    23  run any `packer` command with the `-h` flag to output more detailed help for a
    24  specific subcommand.
    25  
    26  In addition to the documentation available on the command-line, each command is
    27  documented on this website. You can find the documentation for a specific
    28  subcommand using the navigation to the left.
    29  
    30  ## Machine-Readable Output
    31  
    32  By default, the output of Packer is very human-readable. It uses nice
    33  formatting, spacing, and colors in order to make Packer a pleasure to use.
    34  However, Packer was built with automation in mind. To that end, Packer supports
    35  a fully machine-readable output setting, allowing you to use Packer in automated
    36  environments.
    37  
    38  Because the machine-readable output format was made with Unix tools in mind, it
    39  is `awk`/`sed`/`grep`/etc. friendly and provides a familiar interface without
    40  requiring you to learn a new format.
    41  
    42  ### Enabling Machine-Readable Output
    43  
    44  The machine-readable output format can be enabled by passing the
    45  `-machine-readable` flag to any Packer command. This immediately enables all
    46  output to become machine-readable on stdout. Logging, if enabled, continues to
    47  appear on stderr. An example of the output is shown below:
    48  
    49  ``` text
    50  $ packer -machine-readable version
    51  1498365963,,version,1.0.2
    52  1498365963,,version-prelease,
    53  1498365963,,version-commit,3ead2750b+CHANGES
    54  1498365963,,ui,say,Packer v1.0.2
    55  ```
    56  
    57  The format will be covered in more detail later. But as you can see, the output
    58  immediately becomes machine-friendly. Try some other commands with the
    59  `-machine-readable` flag to see!
    60  
    61  ~> The `-machine-readable` flag is designed for automated environments and is
    62  mutually-exclusive with the `-debug` flag, which is designed for interactive
    63  environments.
    64  
    65  ### Format for Machine-Readable Output
    66  
    67  The machine readable format is a line-oriented, comma-delimited text format.
    68  This makes it more convenient to parse using standard Unix tools such as `awk` or
    69  `grep` in addition to full programming languages like Ruby or Python.
    70  
    71  The format is:
    72  
    73  ``` text
    74  timestamp,target,type,data...
    75  ```
    76  
    77  Each component is explained below:
    78  
    79  -   `timestamp` is a Unix timestamp in UTC of when the message was printed.
    80  
    81  -   `target` is the target of the following output. This is empty if the message
    82      is related to Packer globally. Otherwise, this is generally a build name so
    83      you can relate output to a specific build while parallel builds are running.
    84  
    85  -   `type` is the type of machine-readable message being outputted. There are a
    86      set of standard types which are covered later, but each component of Packer
    87      (builders, provisioners, etc.) may output their own custom types as well,
    88      allowing the machine-readable output to be infinitely flexible.
    89  
    90  -   `data` is zero or more comma-separated values associated with the prior type.
    91      The exact amount and meaning of this data is type-dependent, so you must read
    92      the documentation associated with the type to understand fully.
    93  
    94  Within the format, if data contains a comma, it is replaced with
    95  `%!(PACKER_COMMA)`. This was preferred over an escape character such as `\'`
    96  because it is more friendly to tools like `awk`.
    97  
    98  Newlines within the format are replaced with their respective standard escape
    99  sequence. Newlines become a literal `\n` within the output. Carriage returns
   100  become a literal `\r`.
   101  
   102  ### Machine-Readable Message Types
   103  
   104  The set of machine-readable message types can be found in the
   105  [machine-readable format](/docs/commands/index.html) complete
   106  documentation section. This section contains documentation on all the message
   107  types exposed by Packer core as well as all the components that ship with
   108  Packer by default.
   109  
   110  ## Autocompletion
   111  
   112  The `packer` command features opt-in subcommand autocompletion that you can
   113  enable for your shell with `packer -autocomplete-install`. After doing so,
   114  you can invoke a new shell and use the feature.
   115  
   116  For example, assume a tab is typed at the end of each prompt line:
   117  
   118  ```
   119  $ packer p
   120  plugin  push    
   121  $ packer push -
   122  -name       -sensitive  -token      -var        -var-file
   123  ```