jeans/etcher
jeans/etcher
1
0
Fork 0
mirror of https://github.com/balena-io/etcher.git synced 2025-07-23 11:16:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(CLI.md): write the CLI.md document (#511)

Browse Source 
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>
This commit is contained in:
Juan Cruz Viotti 2016-06-22 17:06:06 -04:00 committed by GitHub
parent 2f3118e4c3
commit a93c28ab20
1 changed files with 61 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/CLI.md Normal file
View File

@ -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.