From a93c28ab20ec5383dde379d6b6161008b212dba9 Mon Sep 17 00:00:00 2001
From: Juan Cruz Viotti <jviottidc@gmail.com>
Date: Wed, 22 Jun 2016 17:06:06 -0400
Subject: [PATCH] docs(CLI.md): write the CLI.md document (#511)

This document explains what the Etcher CLI is, how can be used, and some
peculiarities, like `--robot` and exit codes.

Signed-off-by: Juan Cruz Viotti <jviottidc@gmail.com>
---
 docs/CLI.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 docs/CLI.md

diff --git a/docs/CLI.md b/docs/CLI.md
new file mode 100644
index 00000000..b20cabb5
--- /dev/null
+++ b/docs/CLI.md
@@ -0,0 +1,61 @@
+Etcher CLI
+==========
+
+The Etcher CLI is a command-line tool that aims to provide all the benefits of the Etcher desktop application in a way that can be ran from a terminal, or even used from a script.
+
+In fact, the Etcher desktop application is simply a wrapper around the CLI, which the place where the actual writing logic takes place.
+
+Running
+-------
+
+We are not oficially releasing the Etcher CLI as a separate package yet, but you can run it locally with the following steps:
+
+- Clone the Etcher repository.
+
+```
+git clone https://github.com/resin-io/etcher
+```
+
+- Install the dependencies, using the instructions from [`CONTRIBUTING.md`](https://github.com/resin-io/etcher/blob/master/docs/CONTRIBUTING.md).
+
+- Run the Etcher CLI from `bin/etcher`.
+
+```
+./bin/etcher --help
+```
+
+Options
+-------
+
+```
+  --help, -h     show help
+  --version, -v  show version number
+  --drive, -d    drive
+  --check, -c    validate write
+  --robot, -r    parse-able output without interactivity
+  --log, -l      output log file
+  --yes, -y      confirm non-interactively
+  --unmount, -u  unmount on success
+```
+
+The robot option
+----------------
+
+The `--robot` option is very particular since it allows other applications to easily consume the output of the Etcher CLI in real-time. When using the `--robot` option, the `--yes` option is implicit, therefore you need to manually specify `--drive`.
+
+When `--robot` is used, the program will output JSON lines containing the progress state and other useful information. For example:
+
+```
+$ sudo etcher image.iso --robot --drive /dev/disk2
+{"command":"progress","data":{"type":"write","percentage":1,"eta":130,"speed":1703936}}
+...
+{"command":"progress","data":{"type":"check","percentage":100,"eta":0,"speed":17180514}}
+{"command":"done","data":{"passedValidation":true,"sourceChecksum":"27c39a5d"}}
+```
+
+The `command` property can be used to determine the action taking place, while the `data` property contains extra information related to the command.
+
+Exit codes
+----------
+
+The Etcher CLI uses certain exit codes to signal the result of the operation. These are documented in [`lib/src/exit-codes.js`](https://github.com/resin-io/etcher/blob/master/lib/src/exit-codes.js) and are also printed on the Etcher CLI help page.