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.
