mirror of https://github.com/balena-io/etcher.git synced 2025-04-20 05:17:18 +00:00

Juan Cruz Viotti 7fa2f437c1 feat(CLI): replace --robot with an ETCHER_CLI_ROBOT env var (#1010 )

The `--robot` option of the CLI causes the program to output
machine-parseable strings, which can be easily consumed by the GUI to
update progress and other information.

The problem is that if the CLI fails to parse its command line arguments
when being called from the GUI for whatever reason, the `.fail()` Yargs
handler will be called, which doesn't output error information in the
usual "robot" format, causing the GUI to not understand the error
message.

Since the `.fail()` Yargs handler doesn't have access to the passed
options, we moved the "robot" functionality to an environment variable,
which we can easily check from there.

As a bonus, this PR refactors the whole robot logic into
`lib/shared/robot.js` and adds unit tests to it.

See: https://github.com/resin-io/etcher/issues/986
Change-Type: major
Changelog-Entry: Replace the `--robot` CLI option with an `ETCHER_CLI_ROBOT` environment variable.
Signed-off-by: Juan Cruz Viotti <jviotti@openmailbox.org>

2017-01-10 19:46:59 -04:00

2.1 KiB

Raw Permalink Blame History

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 run from a terminal, or even used from a script.

In fact, the Etcher desktop application is simply a wrapper around the CLI, which is 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 by running:

npm install

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
  --yes, -y      confirm non-interactively
  --unmount, -u  unmount on success

The robot option

Setting the ETCHER_CLI_ROBOT environment variable allows other applications to easily consume the output of the Etcher CLI in real-time When using the ETCHER_CLI_ROBOT option, the --yes option is implicit, therefore you need to manually specify --drive.

When ETCHER_CLI_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":{"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/shared/exit-codes.js and are also printed on the Etcher CLI help page.

2.1 KiB Raw Permalink Blame History