new repository

1 files changed, 22 insertions, 0 deletions

diff --git a/devdocs/vagrant/cli%2Fmachine-readable.html b/devdocs/vagrant/cli%2Fmachine-readable.html
new file mode 100644
index 00000000..1af06e73
--- /dev/null
+++ b/devdocs/vagrant/cli%2Fmachine-readable.html
@@ -0,0 +1,22 @@
+<h1 id="machine-readable-output">  Machine Readable Output </h1> <p>Every Vagrant command accepts a <code>--machine-readable</code> flag which enables machine readable output mode. In this mode, the output to the terminal is replaced with machine-friendly output.</p> <p>This mode makes it easy to programmatically execute Vagrant and read data out of it. This output format is protected by our <a href="../installation/backwards-compatibility">backwards compatibility</a> policy. Until Vagrant 2.0 is released, however, the machine readable output may change as we determine more use cases for it. But the backwards compatibility promise should make it safe to write client libraries to parse the output format.</p> <blockquote class="alert alert-warning"> <p><strong>Advanced topic!</strong> This is an advanced topic for use only if you want to programmatically execute Vagrant. If you are just getting started with Vagrant, you may safely skip this section.</p> </blockquote>
+<h2 id="work-in-progress">  Work-In-Progress </h2> <p>The machine-readable output is very new (released as part of Vagrant 1.4). We're still gathering use cases for it and building up the output for each of the commands. It is likely that what you may want to achieve with the machine-readable output is not possible due to missing information.</p> <p>In this case, we ask that you please <a href="https://github.com/hashicorp/vagrant/issues">open an issue</a> requesting that certain information become available. We will most likely add it!</p> <h2 id="format">  Format </h2> <p>The machine readable format is a line-oriented, comma-delimited text format. This makes it extremely easy to parse using standard Unix tools such as awk or grep in addition to full programming languages like Ruby or Python.</p> <p>The format is:</p> <div class="highlight"><pre class="highlight plaintext">timestamp,target,type,data...
+</pre></div>
+<p>Each component is explained below:</p> <ul> <li>
+<p><strong>timestamp</strong> is a Unix timestamp in UTC of when the message was printed.</p> </li> <li>
+<p><strong>target</strong> is the target of the following output. This is empty if the message is related to Vagrant globally. Otherwise, this is generally a machine name so you can relate output to a specific machine when multi-VM is in use.</p> </li> <li>
+<p><strong>type</strong> is the type of machine-readable message being outputted. There are a set of standard types which are covered later.</p> </li> <li>
+<p><strong>data</strong> is zero or more comma-separated values associated with the prior type. The exact amount and meaning of this data is type-dependent, so you must read the documentation associated with the type to understand fully.</p> </li> </ul> <p>Within the format, if data contains a comma, it is replaced with <code>%!(VAGRANT_COMMA)</code>. This was preferred over an escape character such as \' because it is more friendly to tools like awk.</p> <p>Newlines within the format are replaced with their respective standard escape sequence. Newlines become a literal <code>\n</code> within the output. Carriage returns become a literal <code>\r</code>.</p> <h2 id="types">  Types </h2> <p>This section documents all the available types that may be outputted with the machine-readable output.</p> <table class="table table-hover table-bordered mr-types"> <p><thead> <tr> <th class="mr-type">Type</th> <th>Description</th> </tr> </thead></p> 
+<tr> <td>box-name</td> <td> Name of a box installed into Vagrant. </td> </tr> 
+<tr> <td>box-provider</td> <td> Provider for an installed box. </td> </tr> 
+<tr> <td>cli-command</td> <td> A subcommand of <code>vagrant</code> that is available. </td> </tr> 
+<tr> <td>error-exit</td> <td> An error occurred that caused Vagrant to exit. This contains that error. Contains two data elements: type of error, error message. </td> </tr> 
+<tr> <td>provider-name</td> <td> The provider name of the target machine. <span class="label">targeted</span> </td> </tr> 
+<tr> <td>ssh-config</td> <td> The OpenSSH compatible SSH config for a machine. This is usually the result of the "ssh-config" command. <span class="label">targeted</span> </td> </tr> 
+<tr> <td>state</td> <td> The state ID of the target machine. <span class="label">targeted</span> </td> </tr> 
+<tr> <td>state-human-long</td> <td> Human-readable description of the state of the machine. This is the long version, and may be a paragraph or longer. <span class="label">targeted</span> </td> </tr> 
+<tr> <td>state-human-short</td> <td> Human-readable description of the state of the machine. This is the short version, limited to at most a sentence. <span class="label">targeted</span> </td> </tr> </table><div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2010&ndash;2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br>
+    <a href="https://www.vagrantup.com/docs/cli/machine-readable.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/machine-readable.html</a>
+  </p>
+</div>