github.com/aclaygray/packer@v1.3.2/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 82 - `target` When you call `packer build` this can be either empty or individual 83 build names, e.g. `amazon-ebs`. It is normally empty when builds are in 84 progress, and the build name when artifacts of particular builds are being 85 referred to. 86 87 - `type` is the type of machine-readable message being outputted. The two most 88 common `type`s are `ui` and `artifact` 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 Here's an incomplete list of types you may see in the machine-readable output: 105 106 You'll see these data types when you run `packer build`: 107 108 - `ui`: this means that the information being provided is a human-readable string 109 that would be sent to stdout even if we aren't in machine-readable mode. There 110 are three "data" subtypes associated with this type: 111 112 - `say`: in a non-machine-readable format, this would be bolded. Normally it is 113 used for anouncements about beginning new steps in the build process 114 115 - `message`: the most commonly used message type, used for basic updates during 116 the build process. 117 118 - `error`: reserved for errors 119 120 - `artifact-count`: This data type tells you how many artifacts a particular 121 build produced. 122 123 - `artifact`: This data type tells you information about what Packer created 124 during its build. An example of output follows the pattern 125 `timestamp, buildname, artifact, artifact_number, key, value` where `key` and 126 `value` contain information about the artifact. 127 128 For example: 129 130 ``` 131 1539967803,,ui,say,\n==> Builds finished. The artifacts of successful builds are: 132 1539967803,amazon-ebs,artifact-count,2 133 1539967803,amazon-ebs,artifact,0,builder-id,mitchellh.amazonebs 134 1539967803,amazon-ebs,artifact,0,id,eu-west-1:ami-04d23aca8bdd36e30 135 1539967803,amazon-ebs,artifact,0,string,AMIs were created:\neu-west-1: ami-04d23aca8bdd36e30\n 136 1539967803,amazon-ebs,artifact,0,files-count,0 137 1539967803,amazon-ebs,artifact,0,end 138 1539967803,,ui,say,--> amazon-ebs: AMIs were created:\neu-west-1: ami-04d23aca8bdd36e30\n 139 1539967803,amazon-ebs,artifact,1,builder-id, 140 1539967803,amazon-ebs,artifact,1,id, 141 1539967803,amazon-ebs,artifact,1,string, 142 1539967803,amazon-ebs,artifact,1,files-count,0 143 2018/10/19 09:50:03 waiting for all plugin processes to complete... 144 1539967803,amazon-ebs,artifact,1,end 145 ``` 146 147 You'll see these data types when you run `packer version`: 148 149 - `version`: what version of Packer is running 150 151 - `version-prerelease`: Data will contain `dev` if version is prerelease, and 152 otherwise will be blank. 153 154 - `version-commit`: The git hash for the commit that the branch of Packer is 155 currently on; most useful for Packer developers. 156 157 ## Autocompletion 158 159 The `packer` command features opt-in subcommand autocompletion that you can 160 enable for your shell with `packer -autocomplete-install`. After doing so, 161 you can invoke a new shell and use the feature. 162 163 For example, assume a tab is typed at the end of each prompt line: 164 165 ``` 166 $ packer p 167 plugin build 168 $ packer build - 169 -color -debug -except -force -machine-readable -on-error -only -parallel -timestamp -var -var-file 170 ```