github.com/hashicorp/packer@v1.14.3/website/content/docs/commands/index.mdx (about)

     1  ---
     2  description: |
     3    The Packer command-line interface lets you perform Packer operations. Use the `packer` CLI command with subcommands, flags, and options to build and manage artifacts and install and manage plugins.
     4  page_title: Packer commands overview
     5  ---
     6  
     7  # Packer Commands Overview
     8  
     9  Packer is controlled using a command-line interface. All interaction with
    10  Packer is done via the `packer` tool. Like many other command-line tools, the
    11  `packer` tool takes a subcommand to execute, and that subcommand may have
    12  additional options as well. Subcommands are executed with `packer SUBCOMMAND`,
    13  where "SUBCOMMAND" is the actual command you wish to execute.
    14  
    15  If you run `packer` by itself, help will be displayed showing all available
    16  subcommands and a brief synopsis of what they do. In addition to this, you can
    17  run any `packer` command with the `-h` flag to output more detailed help for a
    18  specific subcommand.
    19  
    20  The documentation contains information about each subcommand.
    21  
    22  ## Machine-Readable Output
    23  
    24  By default, the output of Packer is very human-readable. It uses nice
    25  formatting, spacing, and colors in order to make Packer a pleasure to use.
    26  However, Packer was built with automation in mind. To that end, Packer supports
    27  a fully machine-readable output setting, allowing you to use Packer in
    28  automated environments.
    29  
    30  Because the machine-readable output format was made with Unix tools in mind, it
    31  is `awk`/`sed`/`grep`/etc. friendly and provides a familiar interface without
    32  requiring you to learn a new format.
    33  
    34  ### Enabling Machine-Readable Output
    35  
    36  The machine-readable output format can be enabled by passing the
    37  `-machine-readable` flag to any Packer command. This immediately enables all
    38  output to become machine-readable on stdout. Logging, if enabled, continues to
    39  appear on stderr. An example of the output is shown below:
    40  
    41  ```shell-session
    42  $ packer -machine-readable version
    43  1498365963,,version,1.0.2
    44  1498365963,,version-prelease,
    45  1498365963,,version-commit,3ead2750b+CHANGES
    46  1498365963,,ui,say,Packer v1.0.2
    47  ```
    48  
    49  The format will be covered in more detail later. But as you can see, the output
    50  immediately becomes machine-friendly. Try some other commands with the
    51  `-machine-readable` flag to see!
    52  
    53  ~>; The `-machine-readable` flag is designed for automated environments and
    54  is mutually-exclusive with the `-debug` flag, which is designed for interactive
    55  environments.
    56  
    57  ### Format for Machine-Readable Output
    58  
    59  The machine readable format is a line-oriented, comma-delimited text format.
    60  This makes it more convenient to parse using standard Unix tools such as `awk`
    61  or `grep` in addition to full programming languages like Ruby or Python.
    62  
    63  The format is:
    64  
    65  ```text
    66  timestamp,target,type,data...
    67  ```
    68  
    69  Each component is explained below:
    70  
    71  - `timestamp` is a Unix timestamp in UTC of when the message was printed.
    72  
    73  - `target` When you call `packer build` this can be either empty or
    74    individual build names, e.g. `amazon-ebs`. It is normally empty when builds
    75    are in progress, and the build name when artifacts of particular builds are
    76    being referred to.
    77  
    78  - `type` is the type of machine-readable message being outputted. The two
    79    most common `type`s are `ui` and `artifact`
    80  
    81  - `data` is zero or more comma-separated values associated with the prior
    82    type. The exact amount and meaning of this data is type-dependent, so you
    83    must read the documentation associated with the type to understand fully.
    84  
    85  Within the format, if data contains a comma, it is replaced with
    86  `%!(PACKER_COMMA)`. This was preferred over an escape character such as `\'`
    87  because it is more friendly to tools like `awk`.
    88  
    89  Newlines within the format are replaced with their respective standard escape
    90  sequence. Newlines become a literal `\n` within the output. Carriage returns
    91  become a literal `\r`.
    92  
    93  ### Machine-Readable Message Types
    94  
    95  Here's an incomplete list of types you may see in the machine-readable output:
    96  
    97  You'll see these data types when you run `packer build`:
    98  
    99  - `ui`: this means that the information being provided is a human-readable
   100    string that would be sent to stdout even if we aren't in machine-readable
   101    mode. There are three "data" subtypes associated with this type:
   102  
   103    - `say`: in a non-machine-readable format, this would be bolded. Normally
   104      it is used for announcements about beginning new steps in the build
   105      process
   106  
   107    - `message`: the most commonly used message type, used for basic updates
   108      during the build process.
   109  
   110    - `error`: reserved for errors
   111  
   112  - `artifact-count`: This data type tells you how many artifacts a particular
   113    build produced.
   114  
   115  - `artifact`: This data type tells you information about what Packer created
   116    during its build. An example of output follows the pattern
   117    `timestamp, buildname, artifact, artifact_number, key, value` where `key`
   118    and `value` contain information about the artifact.
   119  
   120    For example:
   121  
   122    ```text
   123      1539967803,,ui,say,\n==> Builds finished. The artifacts of successful builds are:
   124      1539967803,amazon-ebs,artifact-count,2
   125      1539967803,amazon-ebs,artifact,0,builder-id,mitchellh.amazonebs
   126      1539967803,amazon-ebs,artifact,0,id,eu-west-1:ami-04d23aca8bdd36e30
   127      1539967803,amazon-ebs,artifact,0,string,AMIs were created:\neu-west-1: ami-04d23aca8bdd36e30\n
   128      1539967803,amazon-ebs,artifact,0,files-count,0
   129      1539967803,amazon-ebs,artifact,0,end
   130      1539967803,,ui,say,--> amazon-ebs: AMIs were created:\neu-west-1: ami-04d23aca8bdd36e30\n
   131      1539967803,amazon-ebs,artifact,1,builder-id,
   132      1539967803,amazon-ebs,artifact,1,id,
   133      1539967803,amazon-ebs,artifact,1,string,
   134      1539967803,amazon-ebs,artifact,1,files-count,0
   135      2018/10/19 09:50:03 waiting for all plugin processes to complete...
   136      1539967803,amazon-ebs,artifact,1,end
   137    ```
   138  
   139  You'll see these data types when you run `packer version`:
   140  
   141  - `version`: what version of Packer is running
   142  
   143  - `version-prerelease`: Data will contain `dev` if version is prerelease, and
   144    otherwise will be blank.
   145  
   146  - `version-commit`: The git hash for the commit that the branch of Packer is
   147    currently on; most useful for Packer developers.
   148  
   149  ## Autocompletion
   150  
   151  The `packer` command features opt-in subcommand autocompletion that you can
   152  enable for your shell with `packer -autocomplete-install`. After doing so, you
   153  can invoke a new shell and use the feature.
   154  
   155  For example, assume a tab is typed at the end of each prompt line:
   156  
   157  ```shell-session
   158  $ packer p
   159  plugin  build
   160  $ packer build -
   161  -color             -debug             -except            -force             -machine-readable  -on-error          -only              -parallel          -timestamp          -var               -var-file
   162  ```