Fix Windows installer build in new balena CI workers (qqjs patch)

Change-type: patch

.gitattributes

@@ -0,0 +1,12 @@
+# Set all files to use line feed endings (since we can't match only ones without an extension)
+* eol=lf
+# And then reset all the files with extensions back to default
+*.* -eol
+
+*.sh text eol=lf
+
+# lf for the docs as it's auto-generated and will otherwise trigger an uncommited error on windows
+doc/cli.markdown text eol=lf
+# crlf for the eol conversion test files
+tests/test-data/projects/docker-compose/basic/service2/file2-crlf.sh eol=crlf
+tests/test-data/projects/no-docker-compose/basic/src/windows-crlf.sh eol=crlf

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @balena-io/balena-cli

.github/ISSUE_TEMPLATE.md

@@ -1,11 +1,76 @@
-- **Cli version:**
-- **Standalone install:** yes/no
-- **Node version:**
-- **Npm version:**
-- **Operating system and architecture:**
+
+# About this issue tracker
+
+*The balena CLI (Command Line Interface) is a tool used to interact with the balena platform.
+This GitHub issue tracker is used for bug reports and feature requests regarding the CLI
+tool. General and troubleshooting questions (such as setting up your project to work with a
+balenalib base image) are encouraged to be posted to the [balena
+forums](https://forums.balena.io), which are monitored by balena's support team and where the
+community can both contribute and benefit from the answers.*
+
+*Please also check that this issue is not a duplicate. If there is another issue describing
+the same problem or feature please add comments to the existing issue.*
+
+*Thank you for your time and effort creating the issue report, and helping us improve
+the balena CLI!*
 
 ---
 
-*Please keep in mind that we try to use the issue tracker of this repository for specific bug reports & CLI feature requests. General & troubleshooting questions are encouraged to be posted to the [balena forums](https://forums.balena.io) where the community can both contribute and benefit from the answers.*
+# Expected Behavior
 
-*Before submitting this issue please check that this issue is not a duplicate. If there is another issue describing the same problem or feature please add your information to the existing issue's comments.*
+Please describe what you were expecting to happen. If applicable, please add links to
+documentation you were following, or to projects that you were trying to push/build.
+
+# Actual Behavior
+
+Please describe what actually happened instead:
+* Quoting logs and error message is useful. If possible, quote the **full** output of the
+  CLI, not just the error message.
+* Please quote the **full command line** too. Sometimes users report that they were
+  "pushing" or "building" a project, but there are several ways to do so and several
+  possible "targets" such as balenaCloud, openBalena, local balenaOS device, etc.
+  Examples:
+
+```
+balena push myApp
+balena push 192.168.0.12
+balena deploy myApp
+balena deploy myApp --build
+balena build . -a myApp
+balena build . -A armv7hf -d raspberrypi3
+```
+
+Each of the above command lines executes different code behind the scenes, so quoting the
+full command line is very helpful.
+
+Running the CLI in debug mode (`--debug` flag or `DEBUG=1` environment variable) may reveal
+additional information. The `--logs` option reveals additional information for the commands:
+
+```
+balena build . --logs
+balena deploy myApp --build --logs
+```
+
+# Steps to Reproduce the Problem
+
+This is the most important and helpful part of a bug report. If we cannot reproduce the
+problem, it is difficult to tell what the fix should be, or whether code changes have
+fixed it.
+
+1.
+1.
+1.
+
+# Specifications
+
+- **balena CLI version:** e.g. 1.2.3 (output of the `"balena version -a"` command)
+- **Cloud backend: openBalena or balenaCloud?** If unsure, it will be balenaCloud
+- **Operating system version:** e.g. Windows 10, Ubuntu 18.04, macOS 10.14.5
+- **32/64 bit OS and processor:** e.g. 32-bit Windows on 64-bit Intel processor
+- **Install method:** npm or zip package or executable installer
+- **If npm install, Node.js and npm version:** e.g. Node v8.16.0 and npm v6.4.1
+
+# Additional References
+
+If applicable, please add additional links to GitHub projects, forums.balena.io threads,
+gist.github.com, Google Drive attachments, etc.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,11 +1,26 @@
 <!-- You can remove tags that do not apply. -->
-Resolves: # <!-- Refer an issue of this repository that this PR fixes -->
-See: <url> <!-- Refer to any external resource, like a PR, document or discussion -->
-Depends-on: <url> <!-- This change depends on a PR to get merged/deployed first -->
-Change-type: major|minor|patch <!-- The change type of this PR -->
+Resolves: # <!-- Refer an issue of this repository that this PR fixes -->  
+Change-type: major|minor|patch <!-- See https://semver.org/ -->  
+Depends-on: <url> <!-- This change depends on a PR to get merged/deployed first -->  
+See: <url> <!-- Refer to any external resource, like a PR, document or discussion -->  
 
 ---
-##### Contributor checklist
-<!-- For completed items, change [ ] to [x].  -->
-- [ ] Introduces security considerations
-- [ ] Affects the development, build or deployment processes of the component
+Please check the CONTRIBUTING.md file for relevant information and some
+guidance. Keep in mind that the CLI is a cross-platform application that runs
+on Windows, macOS and Linux. Tests will be automatically run by balena CI on
+all three operating systems, but this will only help if you have added test
+code that exercises the modified or added feature code.
+
+Note that each commit message (currently only the first line) will be
+automatically copied to the CHANGELOG.md file, so try writing it in a way
+that describes the feature or fix for CLI users.
+
+If there isn't a linked issue or if the linked issue doesn't quite match the
+PR, please add a PR description to explain its purpose or the features that it
+implements. Adding PR comments to blocks of code that aren't self explanatory
+usually helps with the review process.
+
+If the PR introduces security considerations or affects the development, build
+or release process, please be sure to highlight this in the PR description.
+
+Thank you very much for your contribution!

.gitignore

@@ -12,6 +12,7 @@ lib-cov
 
 # Coverage directory used by tools like istanbul
 coverage
+.nyc_output
 
 # node-waf configuration
 .lock-wscript
@@ -24,18 +25,23 @@ build/Release
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git-
 node_modules
 
-npm-shrinkwrap.json
 package-lock.json
 .resinconf
 .balenaconf
 resinrc.yml
 balenarc.yml
 
-.idea
-.vscode
 .DS_Store
+.idea
+.nvmrc
+.vscode
 
 /tmp
 build/
 build-bin/
 build-zip/
+dist/
+
+# Ignore fast-boot cache file
+**/.fast-boot.json
+/oclif.manifest.json

.hound.yml

@@ -1,5 +1,2 @@
-coffee_script:
-  config_file: coffeelint.json
-
 javascript:
   enabled: false

.mocharc-standalone.js

@@ -0,0 +1,6 @@
+const commonConfig = require('./.mocharc.js');
+
+module.exports = {
+	...commonConfig,
+	spec: ['tests/auth/*.spec.ts', 'tests/commands/**/*.spec.ts'],
+};

.mocharc.js

@@ -0,0 +1,8 @@
+module.exports = {
+	spec: 'tests/commands/app/create.spec.ts',
+	reporter: 'spec',
+	require: 'ts-node/register/transpile-only',
+	file: './tests/config-tests',
+	timeout: 12000,
+	spec: 'tests/**/*.spec.ts',
+};

.resinci.yml

@@ -0,0 +1,20 @@
+---
+npm:
+  platforms:
+    - name: linux
+      os: ubuntu
+      architecture: x86_64
+      node_versions:
+        - "10"
+        - "12"
+        - "14"
+    - name: linux
+      os: alpine
+      architecture: x86_64
+      node_versions:
+        - "10"
+        - "12"
+        - "14"
+
+docker:
+  publish: false

.travis.yml

@@ -3,10 +3,16 @@ os:
   - linux
   - osx
 node_js:
-  - "6"
-before_install:
-- npm -g install npm@4
-script: npm run ci
+  - "10"
+matrix:
+  exclude:
+    node_js: "10"
+script:
+  - node --version
+  - npm --version
+  - npm run ci
+  # - npm run build:standalone
+  # - npm run build:installer
 notifications:
   email: false
 deploy:

CONTRIBUTING.md

@@ -0,0 +1,239 @@
+# Contributing
+
+The balena CLI is an open source project and your contribution is welcome!
+
+* Install the dependencies listed in the [NPM Installation
+  section](./INSTALL-ADVANCED.md#npm-installation) section of the installation instructions. Check
+  the section [Additional Dependencies](./INSTALL-ADVANCED.md#additional-dependencies) too.
+* Clone the `balena-cli` repository (or a [forked
+  repo](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo),
+  if you are not in the balena team), `cd` to it and run `npm install`.
+* Build the CLI with `npm run build` or `npm test`, and execute it with `./bin/balena`
+  (on a Windows command prompt, you may need to run `node .\bin\balena`).
+
+In order to ease development:
+
+* `npm run build:fast` skips some of the build steps for interactive testing, or
+* `npm run test:source` skips testing the standalone zip packages (which is rather slow)
+* `./bin/balena-dev` uses `ts-node/register` to transpile on the fly.
+
+Before opening a PR, test your changes with `npm test`. Keep compatibility in mind, as the CLI is
+meant to run on Linux, macOS and Windows. balena CI will run test code on all three platforms, but
+this will only help if you add some test cases for your new code!
+
+## Semantic versioning, commit messages and the ChangeLog
+
+When a pull request is merged, Balena's versionbot / Continuous Integration system takes care of
+automatically creating a new CLI release on both the [npm
+registry](https://www.npmjs.com/package/balena-cli) and the GitHub [releases
+page](https://github.com/balena-io/balena-cli/releases). The release version numbering adheres to
+the [Semantic Versioning's](http://semver.org/) concept of patch, minor and major releases.
+Generally, bug fixes and documentation changes are classed as patch changes, while new features are
+classed as minor changes. If a change breaks backwards compatibility, it is a major change.
+
+A new version entry is also automatically added to the
+[CHANGELOG.md](https://github.com/balena-io/balena-cli/blob/master/CHANGELOG.md) file when a pull
+request is merged. Each pull request corresponds to a single version / release. Each commit in the
+pull request becomes a bullet point entry in the Changelog. The Changelog file should not be
+manually edited.
+
+To support this automation, a commit message should be structured as follows:
+
+```text
+The first line becomes a bullet point in the CHANGELOG file
+
+Optionally, a more detailed description in one or more paragraphs.
+The detailed description can be seen with `git log`, but it is not copied
+to the CHANGELOG file.
+
+Change-type: patch|minor|major
+```
+
+Only the first line of the commit message is copied to the Changelog file. The `Change-type` footer
+must be preceded by a blank line, and indicates the commit's semver change type. When a PR consists
+of multiple commits, the commits may have different change type values. As a whole, the PR will
+produce a release of the "highest" change type. For example, two commits mixing patch and minor
+change types will produce a minor CLI release, while two commits mixing minor and major change
+types will produce a major CLI release.
+
+The commit message is parsed / checked by versionbot with the
+[resin-commit-lint](https://github.com/balena-io-modules/resin-commit-lint#resin-commit-lint)
+package.
+
+Because of the way that the Changelog file is automatically updated from commit messages, which
+become the source of "what's new" for CLI end users, we advocate "meaningful commits" and
+user-focused commit messages. A meaningful commit is one that, in isolation, introduces a fix or
+feature (or part of a fix or feature) that makes sense at the Changelog level, and which leaves the
+CLI in a non-broken state. Sometimes, in the course of preparing a single pull request, a developer
+creates several commits as a way of saving their "work in progress", which may even fail to build
+(e.g. `npm run build` fails), and which is then fixed or undone by further commits in the same PR.
+In this situation, the recommendation is to "squash" or "fixup" the work-in-progress commits into
+fewer, meaningful commits. Interactive rebase is a good tool to achieve this:
+[blog](https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history),
+[docs](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
+
+Mixing multiple distinct features or bug fixes in a single commit is discouraged, because the
+description will likely not fit in the single-line Changelog bullet point and also because it
+makes it harder to review the pull request (especially a large one) and harder to isolate and
+revert individual changes in case a bug is found later on. Create a separate commit for each
+feature / bug fix, or even separate pull requests.
+
+If you need to catch up with changes to the master branch while working on a pull request,
+use rebase instead of merge: [docs](https://git-scm.com/book/en/v2/Git-Branching-Rebasing).
+
+If `package.json` is updated for dependencies listed in the `repo.yml` file (like `balena-sdk`),
+the commit message body should also include a line in the following format:
+```
+Update balena-sdk from 12.0.0 to 12.1.0
+```
+
+This allows versionbot to produce nested Changelog entries (with expandable arrows), pulling in
+commit messages from the upstream repositories. The following npm script can be used to
+automatically produce a commit with a suitable commit message:
+```
+npm run update balena-sdk ^12.1.0
+```
+
+The script will create a new branch (only if `master` is currently checked out), run `npm update`
+with the given target version and commit the `package.json` and `npm-shrinkwrap.json` files. The
+script by default will set the `Change-type` to `patch` or `minor`, depending on the semver change
+of the updated dependency. A `major` change type can specified as an extra argument:
+```
+npm run update balena-sdk ^12.14.0 patch
+npm run update balena-sdk ^13.0.0 major
+```
+
+## Editing documentation files (README, INSTALL, Reference website...)
+
+The `doc/cli.markdown` file is automatically generated by running `npm run build:doc` (which also
+runs as part of `npm run build`). That file is then pulled by scripts in the
+[balena-io/docs](https://github.com/balena-io/docs/) GitHub repo for publishing at the [CLI
+Documentation page](https://www.balena.io/docs/reference/cli/).
+
+The content sources for the auto generation of `doc/cli.markdown` are:
+
+* [Selected
+  sections](https://github.com/balena-io/balena-cli/blob/v12.23.0/automation/capitanodoc/capitanodoc.ts#L199-L204)
+  of the README file.
+* The CLI's command documentation in source code (`lib/commands/` folder), for example:
+  * `lib/commands/push.ts`
+  * `lib/commands/env/add.ts`
+
+The README file is manually edited, but subsections are automatically extracted for inclusion in
+`doc/cli.markdown` by the `getCapitanoDoc()` function in
+[`automation/capitanodoc/capitanodoc.ts`](https://github.com/balena-io/balena-cli/blob/master/automation/capitanodoc/capitanodoc.ts).
+
+The `INSTALL*.md` and `TROUBLESHOOTING.md` files are also manually edited.
+
+## Windows
+
+The `npm run build:installer` script (which generates the `.exe` executable installer on Windows)
+specifically requires [MSYS2](https://www.msys2.org/) to be installed.  Other than that, the
+standard Command Prompt or PowerShell can be used (though MSYS2 is still handy, as it provides
+'git' and a number of common unix utilities). If changes are made to npm scripts in `package.json`,
+check that they also run on a standard Windows Command Prompt.
+
+## Updating the 'npm-shrinkwrap.json' file
+
+The `npm-shrinkwrap.json` file is used to control package dependencies, as documented at
+https://docs.npmjs.com/files/shrinkwrap.json.
+
+Changes to `npm-shrinkwrap.json` can be automatically merged by git during operations like
+`rebase`, `pull` and `cherry-pick`, but in some cases this results in suboptimal dependency
+resolution (the `node_modules` folder may end up larger than necessary, with consequences to CLI
+load time too). For this reason, the recommended way to update `npm-shrinkwrap.json` is to run
+`npm install`, possibly alongside `npm dedupe` as well. The following commands can be used to
+fix shrinkwrap issues and optimize the dependencies:
+
+```sh
+git checkout master -- npm-shrinkwrap.json
+rm -rf node_modules
+npm install  # update npm-shrinkwrap.json to satisfy changes to package.json
+npm dedupe   # deduplicate dependencies from npm-shrinkwrap.json
+npm install  # re-add optional dependencies removed by dedupe
+git add npm-shrinkwrap.json  # add it for committing (solve merge errors)
+```
+
+Note that `npm dedupe` should always be followed by `npm install`, as shown above, even if
+`npm install` had already been executed before `npm dedupe`.
+
+Optionally, these steps may be automated by installing the
+[npm-merge-driver](https://www.npmjs.com/package/npm-merge-driver):
+
+```sh
+npx npm-merge-driver install -g
+```
+
+## TypeScript and oclif
+
+The CLI currently contains a mix of plain JavaScript and
+[TypeScript](https://www.typescriptlang.org/) code. The goal is to have all code written in
+Typescript, in order to take advantage of static typing and formal programming interfaces.
+The migration towards Typescript is taking place gradually, as part of maintenance work or
+the implementation of new features.
+
+Of historical interest, the CLI was originally written in [CoffeeScript](https://coffeescript.org)
+and used the [Capitano](https://github.com/balena-io/capitano) framework. All CoffeeScript code was
+migrated to either Javascript or Typescript, and Capitano was replaced with oclif. A few file or
+variable names still refer to this legacy, for example `automation/capitanodoc/capitanodoc.ts`.
+
+## Programming style
+
+`npm run build` also runs [balena-lint](https://www.npmjs.com/package/@balena/lint), which automatically
+reformats the code. Beyond that, we have a preference for Javascript promises over callbacks, and for
+`async/await` over `.then()`.
+
+## Common gotchas
+
+One thing that most CLI bugs have in common is the absence of test cases exercising the broken
+code, so writing some test code is a great idea. Having said that, there are also some common
+gotchas to bear in mind:
+
+* Forward slashes ('/') _vs._ backslashes ('\') in file paths. The Node.js
+  [path.sep](https://nodejs.org/docs/latest-v12.x/api/path.html#path_path_sep) variable stores a
+  platform-specific path separator character: the backslash on Windows and the forward slash on
+  Linux and macOS. The
+  [path.join](https://nodejs.org/docs/latest-v12.x/api/path.html#path_path_join_paths) function
+  builds paths using such platform-specific path separator. However:
+  * Note that Windows (kernel, cmd.exe, PowerShell, many applications) accepts ***both*** forward
+    slashes and backslashes as path separators (including mixing them in a path string), so code
+    like `mypath.split(path.sep)` may fail on Windows if `mypath` contains forward slashes. The
+    [path.parse](https://nodejs.org/docs/latest-v12.x/api/path.html#path_path_parse_path) function
+    understands both forward slashes and backslashes on Windows, and the
+    [path.normalize](https://nodejs.org/docs/latest-v12.x/api/path.html#path_path_normalize_path)
+    function will _replace_ forward slashes with backslashes.
+  * In [tar](https://en.wikipedia.org/wiki/Tar_(computing)#File_format) streams sent to the Docker
+    daemon and to balenaCloud, the forward slash is the only acceptable path separator, regardless
+    of the OS where the CLI is running. Therefore, `path.sep` and `path.join` should never be used
+    when handling paths in tar streams! `path.posix.join` may be used instead of `path.join`.
+
+* Avoid using the system shell to execute external commands, for example:  
+  `child_process.exec('ssh "arg1" "arg2"');`  
+  `child_process.spawn('ssh "arg1" "arg2"', { shell: true });`  
+  Besides the usual security concerns of unsanitized strings, another problem is to get argument
+  escaping right because of the differences between the Windows 'cmd.exe' shell and the Unix
+  '/bin/sh'. For example, 'cmd.exe' doesn't recognize single quotes like '/bin/sh', and uses the
+  caret (^) instead of the backslash as the escape character. Bug territory! Most of the time,
+  it is possible to avoid relying on the shell altogether by providing a Javascript array of
+  arguments:  
+  `spawn('ssh', ['arg1', 'arg2'], { shell: false});`  
+  To allow for logging and debugging, the [which](https://www.npmjs.com/package/which) package may
+  be used to get the full path of a command before executing it, without relying on any shell:  
+  `const fullPath = await which('ssh');`  
+  `console.log(fullPath);  # 'C:\WINDOWS\System32\OpenSSH\ssh.EXE'`  
+  `spawn(fullPath, ['arg1', 'arg2'], { shell: false });`
+
+* Avoid the `instanceof` operator when testing against classes/types from external packages
+  (including base classes), because `npm install` may result in multiple versions of the same
+  package being installed (to satisfy declared dependencies) and a false negative may result when
+  comparing an object instance from one package version with a class of another package version
+  (even if the implementations are identical in both packages). For example, once we fixed a bug
+  where the test:  
+  `error instanceof BalenaApplicationNotFound`  
+  changed from true to false because `npm install` added an additional copy of the `balena-errors`
+  package to satisfy a minor `balena-sdk` version update:  
+  `$ find node_modules -name balena-errors`  
+  `node_modules/balena-errors`  
+  `node_modules/balena-sdk/node_modules/balena-errors`  
+  In the case of subclasses of `TypedError`, a string comparison may be used instead:  
+  `error.name === 'BalenaApplicationNotFound'`

INSTALL-ADVANCED.md

@@ -0,0 +1,150 @@
+# balena CLI Advanced Installation Options
+
+**These are alternative, advanced installation options. Most users would prefer the [recommended,
+streamlined installation
+instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md).**
+
+There are 3 options to choose from to install balena's CLI:
+
+* [Executable Installer](#executable-installer): the easiest method on Windows and macOS, using the
+  traditional graphical desktop application installers.
+* [Standalone Zip Package](#standalone-zip-package): these are plain zip files with the balena CLI
+  executable in them: extract and run. Available for all platforms: Linux, Windows, macOS.
+  Recommended also for scripted installation in CI (continuous integration) environments.
+* [NPM Installation](#npm-installation): recommended for Node.js developers who may be interested
+  in integrating the balena CLI in their existing projects or workflow.
+
+Some specific CLI commands have a few extra installation steps: see section [Additional
+Dependencies](#additional-dependencies).
+
+## Executable Installer
+
+This is the recommended installation option on macOS and Windows. Follow the specific OS
+instructions:
+
+* [Windows](./INSTALL-WINDOWS.md)
+* [macOS](./INSTALL-MAC.md)
+
+> Note regarding WSL ([Windows Subsystem for
+> Linux](https://docs.microsoft.com/en-us/windows/wsl/about))  
+> If you would like to use WSL, follow the [installations instructions for
+> Linux](./INSTALL-LINUX.md) rather than Windows, as WSL consists of a Linux environment.
+
+If you had previously installed the CLI using a standalone zip package, it may be a good idea to
+check your system's `PATH` environment variable for duplicate entries, as the terminal will use the
+entry that comes first. Check the [Standalone Zip Package](#standalone-zip-package) instructions
+for how to modify the PATH variable.
+
+By default, the CLI is installed to the following folders:
+
+OS  | Folders
+--- | ---
+Windows: | `C:\Program Files\balena-cli\`
+macOS:   | `/usr/local/lib/balena-cli/` <br> `/usr/local/bin/balena`
+
+## Standalone Zip Package
+
+1. Download the latest zip file from the [releases page](https://github.com/balena-io/balena-cli/releases).
+   Look for a file name that ends with the word "standalone", for example:  
+   `balena-cli-vX.Y.Z-linux-x64-standalone.zip`  ← _also for the Windows Subsystem for Linux_  
+   `balena-cli-vX.Y.Z-macOS-x64-standalone.zip`  
+   `balena-cli-vX.Y.Z-windows-x64-standalone.zip`
+
+2. Extract the zip file contents to any folder you choose. The extracted contents will include a
+   `balena-cli` folder.
+
+3. Add the `balena-cli` folder to the system's `PATH` environment variable.  
+   See instructions for:
+   [Linux](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix) |
+   [macOS](https://www.architectryan.com/2012/10/02/add-to-the-path-on-mac-os-x-mountain-lion/#.Uydjga1dXDg) |
+   [Windows](https://www.computerhope.com/issues/ch000549.htm)
+
+> * If you are using macOS 10.15 or later (Catalina, Big Sur), [check this known issue and
+>   workaround](https://github.com/balena-io/balena-cli/issues/1479).
+> * **Linux Alpine** and **Busybox:** the standalone zip package is not currently compatible with
+>   these "compact" Linux distributions, because of the alternative C libraries they ship with.
+>   For these, consider the [NPM Installation](#npm-installation) option.
+> * Note that moving the `balena` executable out of the extracted `balena-cli` folder on its own
+>   (e.g. moving it to `/usr/local/bin/balena`) will **not** work, as it depends on the other
+>   folders and files also present in the `balena-cli` folder.
+
+To update the CLI to a new version, download a new release zip file and replace the previous
+installation folder. To uninstall, simply delete the folder and edit the PATH environment variable
+as described above.
+
+## NPM Installation
+
+If you are a Node.js developer, you may wish to install the balena CLI via [npm](https://www.npmjs.com).
+The npm installation involves building native (platform-specific) binary modules, which require
+some additional development tools to be installed first:
+
+* [Node.js](https://nodejs.org/) version 10 (min **10.20.0**) or 12 (version 14 is not yet fully supported)
+  * **Linux, macOS** and **Windows Subsystem for Linux (WSL):**  
+    Installing Node via [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) is recommended.
+    When the "system" or "default" Node.js and npm packages are installed with "apt-get" in Linux
+    distributions like Ubuntu, users often report permission or compilation errors when running
+    "npm install". This [sample
+    Dockerfile](https://gist.github.com/pdcastro/5d4d96652181e7da685a32caf629dd44) shows the CLI
+    installation steps on an Ubuntu 18.04 base image.
+* [Python 2.7](https://www.python.org/), [git](https://git-scm.com/), [make](https://www.gnu.org/software/make/), [g++](https://gcc.gnu.org/)
+  * **Linux** and **Windows Subsystem for Linux (WSL):**  
+    `sudo apt-get install -y python git make g++`
+  * **macOS:** install Apple's Command Line Tools by running on a Terminal window:  
+    `xcode-select --install`
+
+On **Windows (not WSL),** the dependencies above and additional ones can be met by installing:
+
+* Node.js from the [Nodejs.org download page](https://nodejs.org/en/download/).
+* The [MSYS2 shell](https://www.msys2.org/), which provides `git`, `make`, `g++`, `ssh`, `rsync`
+  and more:
+  * `pacman -S git openssh rsync gcc make`
+  * [Set a Windows environment variable](https://www.onmsft.com/how-to/how-to-set-an-environment-variable-in-windows-10): `MSYS2_PATH_TYPE=inherit`
+  * Note that a bug in the MSYS2 launch script (`msys2_shell.cmd`) makes text-based
+    interactive CLI menus to misbehave. [Check this Github issue for a
+    workaround](https://github.com/msys2/MINGW-packages/issues/1633#issuecomment-240583890).
+* The Windows Driver Kit (WDK), which is needed to compile some native Node modules. It is **not**
+  necessary to install Visual Studio, only the WDK, which is "step 2" in the following guides:
+  * [WDK for Windows 10](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk#download-icon-step-2-install-wdk-for-windows-10-version-1903)
+  * [WDK for earlier versions of Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/other-wdk-downloads#step-2-install-the-wdk)
+* The [windows-build-tools](https://www.npmjs.com/package/windows-build-tools) npm package (which
+  provides Python 2.7 and more), by running the following command on an [administrator
+  console](https://www.howtogeek.com/194041/how-to-open-the-command-prompt-as-administrator-in-windows-8.1/):
+  
+  `npm install -g --production windows-build-tools`
+
+With these dependencies in place, the balena CLI installation command is:
+
+```sh
+$ npm install balena-cli -g --production --unsafe-perm
+```
+
+`--unsafe-perm` is required when `npm install` is executed as the root user, or on systems where
+the global install directory is not user-writable. It allows npm install steps to download and save
+prebuilt native binaries, and also allows the execution of npm scripts like `postinstall` that are
+used to patch dependencies. It is usually possible to omit `--unsafe-perm` if installing under a
+regular (non-root) user account, especially if using a user-managed node installation such as
+[nvm](https://github.com/creationix/nvm).
+
+## Additional Dependencies
+
+The `balena ssh`, `scan`, `build`, `deploy`, `preload` and `os configure` commands may require
+additional software to be installed. Check the Additional Dependencies sections for each operating
+system:
+
+* [Windows](./INSTALL-WINDOWS.md#additional-dependencies)
+* [macOS](./INSTALL-MAC.md#additional-dependencies)
+* [Linux](./INSTALL-LINUX.md#additional-dependencies)
+
+The `build` and `deploy` commands are also capable of using Docker or balenaEngine on a remote
+server, or on a balenaOS device running a [balenaOS development
+image](https://www.balena.io/docs/reference/OS/overview/2.x/#dev-vs-prod-images)). Reasons why this
+may be desirable include:
+
+* To avoid having to install Docker on the development machine / laptop.
+* To take advantage of a more powerful server (CPU, memory).
+* To build or run images "natively" on an ARM device, avoiding the need for QEMU emulation.
+
+To use a remote Docker Engine (daemon) or balenaEngine, specify the remote machine's IP address and
+port number with the `--dockerHost` and `--dockerPort` command-line options. For more details,
+check `balena help build` or the [online
+reference](https://www.balena.io/docs/reference/cli/#cli-command-reference).

INSTALL-LINUX.md

@@ -0,0 +1,66 @@
+# balena CLI Installation Instructions for Linux
+
+These instructions are for the recommended installation option. They are suitable for most Linux
+distributions, except notably for **Linux Alpine** or **Busybox**. For these distros, see [advanced
+installation options](./INSTALL-ADVANCED.md).
+
+Selected operating system: **Linux**
+
+1. Download the latest zip file from the [latest release
+   page](https://github.com/balena-io/balena-cli/releases/latest). Look for a file name that ends
+   with "-standalone.zip", for example:  
+   `balena-cli-vX.Y.Z-linux-x64-standalone.zip`
+
+2. Extract the zip file contents to any folder you choose. The extracted contents will include a
+   `balena-cli` folder.
+
+3. Add the `balena-cli` folder to the system's `PATH` environment variable. There are several
+   ways of achieving this on Linux: See this [StackOverflow post](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix). Close and reopen the terminal window
+   so that the changes to PATH can take effect.
+
+4. Check that the installation was successful by running the following commands on a
+   command terminal:  
+   * `balena version` - should print the CLI's version
+   * `balena help` - should print a list of available commands
+
+No further steps are required to run most CLI commands. The `balena ssh`, `scan`, `build`,
+`deploy` and `preload` commands may require additional software to be installed, as described
+below.
+
+To update the balena CLI to a new version, download a new release zip file and replace the previous
+installation folder. To uninstall, simply delete the folder and edit the PATH environment variable
+as described above.
+
+## Additional Dependencies
+
+### build, deploy
+
+These commands require [Docker](https://docs.docker.com/install/overview/) or
+[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote machine). Most
+users will simply follow [Docker's installation
+instructions](https://docs.docker.com/install/overview/) to install Docker on the same laptop (dev
+machine) where the balena CLI is installed. The [advanced installation
+options](./INSTALL-ADVANCED.md) document describes other possibilities.
+
+### balena ssh
+
+The `balena ssh` command requires the `ssh` command-line tool to be available. Most Linux
+distributions will already have it installed. Otherwise, `sudo apt-get install openssh-client`
+should do the trick on Debian or Ubuntu.
+
+The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
+Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
+command set can also be used to list and manage SSH keys: see `balena help -v`.
+
+### balena scan
+
+The `balena scan` command requires a multicast DNS (mDNS) service like
+[Avahi](https://en.wikipedia.org/wiki/Avahi_(software)), which is installed by default on most
+desktop Linux distributions. Otherwise, on Debian or Ubuntu, the installation command would be
+`sudo apt-get install avahi-daemon`.
+
+### balena preload
+
+Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional
+restriction that Docker must be installed on the local machine (because Docker's bind mounting
+feature is used).

INSTALL-MAC.md

@@ -0,0 +1,68 @@
+# balena CLI Installation Instructions for macOS
+
+These instructions are for the recommended installation option. Advanced users may also be
+interested in [advanced installation options](./INSTALL-ADVANCED.md).
+
+Selected operating system: **macOS**
+
+1. Download the installer from the [latest release
+   page](https://github.com/balena-io/balena-cli/releases/latest).
+   Look for a file name that ends with "-installer.pkg":  
+   `balena-cli-vX.Y.Z-macOS-x64-installer.pkg`  
+
+2. Double click the downloaded file to run the installer. After the installation completes,
+   close and re-open any open [command
+   terminal](https://www.balena.io/docs/reference/cli/#choosing-a-shell-command-promptterminal)
+   windows (so that the changes made by the installer to the PATH environment variable can take
+   effect).
+
+3. Check that the installation was successful by running the following commands on a
+   command terminal:  
+   * `balena version` - should print the CLI's version
+   * `balena help` - should print a list of available commands
+
+No further steps are required to run most CLI commands. The `balena ssh`, `build`, `deploy`
+and `preload` commands may require additional software to be installed, as described below.
+
+## Additional Dependencies
+
+### build and deploy
+
+These commands require [Docker](https://docs.docker.com/install/overview/) or
+[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote machine). Most
+users will simply follow [Docker's installation
+instructions](https://docs.docker.com/install/overview/) to install Docker on the same laptop (dev
+machine) where the balena CLI is installed. The [advanced installation
+options](./INSTALL-ADVANCED.md) document describes other possibilities.
+
+### balena ssh
+
+The `balena ssh` command requires the `ssh` command-line tool to be available. To check whether
+it is already installed, run `ssh` on a Terminal window. If it is not yet installed, the options
+include:
+
+* Download the Xcode Command Line Tools from https://developer.apple.com/downloads
+* Or, if you have Xcode installed, open Xcode, choose Preferences → General → Downloads →
+  Components → Command Line Tools → Install.
+* Or, install [Homebrew](https://brew.sh/), then `brew install openssh`
+
+The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
+Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
+command set can also be used to list and manage SSH keys: see `balena help -v`.
+
+### balena preload
+
+Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional
+restriction that Docker must be installed on the local machine (because Docker's bind mounting
+feature is used). Also, for some device types (such as the Raspberry Pi), the `preload` command
+requires Docker to support the [AUFS storage
+driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Unfortunately, Docker Desktop
+for Windows dropped support for the AUFS filesystem in Docker CE versions greater than 18.06.1. The
+present workaround is to either:
+
+* Downgrade Docker Desktop to version 18.06.1. Link: [Docker CE for
+  Mac](https://docs.docker.com/docker-for-mac/release-notes/#docker-community-edition-18061-ce-mac73-2018-08-29)
+* Install the balena CLI on a Linux machine (as Docker for Linux still supports AUFS). A Linux
+  Virtual Machine also works, but a Docker container is _not_ recommended.
+
+Long term, we are working on replacing AUFS with overlay2 for the affected device types.

INSTALL-WINDOWS.md

@@ -0,0 +1,82 @@
+# balena CLI Installation Instructions for Windows
+
+These instructions are for the recommended installation option. Advanced users may also be
+interested in [advanced installation options](./INSTALL-ADVANCED.md).
+
+Selected operating system: **Windows**
+
+1. Download the installer from the [latest release
+   page](https://github.com/balena-io/balena-cli/releases/latest).
+   Look for a file name that ends with "-installer.exe":  
+   `balena-cli-vX.Y.Z-windows-x64-installer.exe`  
+
+2. Double click the downloaded file to run the installer. After the installation completes,
+   close and re-open any open [command
+   terminal](https://www.balena.io/docs/reference/cli/#choosing-a-shell-command-promptterminal)
+   windows (so that the changes made by the installer to the PATH environment variable can take
+   effect).
+
+3. Check that the installation was successful by running the following commands on a
+   command terminal:  
+   * `balena version` - should print the CLI's version
+   * `balena help` - should print a list of available commands
+
+No further steps are required to run most CLI commands. The `balena ssh`, `scan`, `build`,
+`deploy`, `preload` and `os configure` commands may require additional software to be installed, as
+described below.
+
+## Additional Dependencies
+
+### build and deploy
+
+These commands require [Docker](https://docs.docker.com/install/overview/) or
+[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote machine). Most
+users will simply follow [Docker's installation
+instructions](https://docs.docker.com/install/overview/) to install Docker on the same laptop (dev
+machine) where the balena CLI is installed. The [advanced installation
+options](./INSTALL-ADVANCED.md) document describes other possibilities.
+
+### balena ssh
+
+The `balena ssh` command requires the `ssh` command-line tool to be available. Microsoft started
+distributing an SSH client with Windows 10, which is automatically installed through Windows
+Update. To check whether it is installed, run `ssh` on a Windows Command Prompt or PowerShell. It
+can also be [manually
+installed](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)
+if needed. For older versions of Windows, there are several ssh/OpenSSH clients provided by 3rd
+parties.
+
+The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
+Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
+command set can also be used to list and manage SSH keys: see `balena help -v`.
+
+### balena scan
+
+The `balena scan` command requires a multicast DNS (mDNS) service like Apple's Bonjour.
+Many Windows machines will already have this service installed, as it is bundled in popular
+applications such as Skype (Wikipedia lists [several others](https://en.wikipedia.org/wiki/Bonjour_(software))).
+Otherwise, Bonjour for Windows can be downloaded and installed from: https://support.apple.com/kb/DL999
+
+### balena preload
+
+Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional
+restriction that Docker must be installed on the local machine (because Docker's bind mounting
+feature is used). Also, for some device types (such as the Raspberry Pi), the `preload` command
+requires Docker to support the [AUFS storage
+driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Unfortunately, Docker Desktop
+for Windows dropped support for the AUFS filesystem in Docker CE versions greater than 18.06.1. The
+present workaround is to either:
+
+* Downgrade Docker Desktop to version 18.06.1. Link: [Docker CE for
+  Windows](https://docs.docker.com/docker-for-windows/release-notes/#docker-community-edition-18061-ce-win73-2018-08-29)
+* Install the balena CLI on a Linux machine (as Docker for Linux still supports AUFS). A Linux
+  Virtual Machine also works, but a Docker container is _not_ recommended.
+
+Long term, we are working on replacing AUFS with overlay2 for the affected device types.
+
+### balena os configure
+
+* The `balena os configure` command is currently not supported on Windows natively, but works with
+  the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL). When
+  using WSL, [install the balena CLI for
+  Linux](https://github.com/balena-io/balena-cli/blob/master/INSTALL-LINUX.md).

INSTALL.md

@@ -0,0 +1,12 @@
+# balena CLI Installation Instructions
+
+Please select your operating system:
+
+* [Windows](./INSTALL-WINDOWS.md)
+* [macOS](./INSTALL-MAC.md)
+* [Linux](./INSTALL-LINUX.md)
+
+> Note regarding WSL ([Windows Subsystem for
+> Linux](https://docs.microsoft.com/en-us/windows/wsl/about))  
+> If you would like to use WSL, follow the installations instructions for Linux
+> rather than Windows, as WSL consists of a Linux environment.

README.md

@@ -1,137 +1,176 @@
-Balena CLI
-=========
+# balena CLI
 
-> The official balena CLI tool.
+The official balena Command Line Interface.
 
 [![npm version](https://badge.fury.io/js/balena-cli.svg)](http://badge.fury.io/js/balena-cli)
 [![dependencies](https://david-dm.org/balena-io/balena-cli.svg)](https://david-dm.org/balena-io/balena-cli)
-[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/balena-io/chat)
 
-Requisites
-----------
+## About
 
-If you want to install the CLI directly through npm, you'll need the below. If this looks difficult,
-we do now have an experimental standalone binary release available, see ['Standalone install'](#standalone-install) below.
+The balena CLI is a Command Line Interface for [balenaCloud](https://www.balena.io/cloud/) or
+[openBalena](https://www.balena.io/open/). It is a software tool available for Windows, macOS and
+Linux, used through a command prompt / terminal window. It can be used interactively or invoked in
+scripts. The balena CLI builds on the [balena API](https://www.balena.io/docs/reference/api/overview/)
+and the [balena SDK](https://www.balena.io/docs/reference/sdk/node-sdk/), and can also be directly
+imported in Node.js applications. The balena CLI is an [open-source project on
+GitHub](https://github.com/balena-io/balena-cli/), and your contribution is also welcome!
 
-- [NodeJS](https://nodejs.org) (>= v6)
-- [Git](https://git-scm.com)
-- The following executables should be correctly installed in your shell environment:
-  - `ssh`: Any recent version of the OpenSSH ssh client (required by `balena sync` and `balena ssh`)
-	- if you need `ssh` to work behind the proxy you also need [`proxytunnel`](http://proxytunnel.sourceforge.net/) installed (available as `proxytunnel` package for Ubuntu, for example)
-  - `rsync`: >= 2.6.9 (required by `balena sync`)
+## Installation
 
-##### Windows Support
+Check the [balena CLI installation instructions on
+GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md).
 
-Before installing balena-cli, you'll need a working node-gyp environment. If you don't already have one you'll see native module build errors during installation. To fix this, run `npm install -g --production windows-build-tools` in an administrator console (available as 'Command Prompt (Admin)' when pressing windows+x in Windows 7+).
+## Choosing a shell (command prompt/terminal)
 
-`balena sync` and `balena ssh` have not been thoroughly tested on the standard Windows cmd.exe shell. We recommend using bash (or a similar) shell, like Bash for Windows 10 or [Git for Windows](https://git-for-windows.github.io/).
+On **Windows,** the standard Command Prompt (`cmd.exe`) and
+[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6)
+are supported. Alternative shells include:
 
-If you still want to use `cmd.exe` you will have to use a package manager like MinGW or chocolatey. For MinGW the steps are:
+* [MSYS2](https://www.msys2.org/):
+  * Install additional packages with the command:  
+    `pacman -S git openssh rsync`
+  * [Set a Windows environment variable](https://www.onmsft.com/how-to/how-to-set-an-environment-variable-in-windows-10): `MSYS2_PATH_TYPE=inherit`
+  * Note that a bug in the MSYS2 launch script (`msys2_shell.cmd`) makes text-based interactive CLI
+    menus to break. [Check this Github issue for a
+    workaround](https://github.com/msys2/MINGW-packages/issues/1633#issuecomment-240583890).
+* [MSYS](http://www.mingw.org/wiki/MSYS): select the `msys-rsync` and `msys-openssh` packages too
+* [Git for Windows](https://git-for-windows.github.io/)
+  * During the installation, you will be prompted to choose between _"Use MinTTY"_ and _"Use
+    Windows' default console window"._ Choose the latter, because of the same [MSYS2
+    bug](https://github.com/msys2/MINGW-packages/issues/1633) mentioned above (Git for Windows
+    actually uses MSYS2). For a screenshot, check this
+    [comment](https://github.com/balena-io/balena-cli/issues/598#issuecomment-556513098).
+* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
+  (WSL). In this case, a Linux distribution like Ubuntu is installed via the Microsoft Store, and a
+  balena CLI release **for Linux** should be selected. See
+  [FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using the
+  balena CLI with WSL and Docker Desktop for Windows.
 
-1. Install [MinGW](http://www.mingw.org).
-2. Install the `msys-rsync` and `msys-openssh` packages.
-3. Add MinGW to the `%PATH%` if this hasn't been done by the installer already. The location where the binaries are places is usually `C:\MinGW\msys\1.0\bin`, but it can vary if you selected a different location in the installer.
-4. Copy your SSH keys to `%homedrive%%homepath\.ssh`.
-5. If you need `ssh` to work behind the proxy you also need to install [proxytunnel](http://proxytunnel.sourceforge.net/)
+On **macOS** and **Linux,** the standard terminal window is supported. Optionally, `bash` command
+auto completion may be enabled by copying the
+[balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash)
+file to your system's `bash_completion` directory: check [Docker's command completion
+guide](https://docs.docker.com/compose/completion/) for system setup instructions.
 
-Getting Started
----------------
+## Logging in
 
-### NPM install
-
-If you've got all the requirements above, you should be able to install the CLI directly from npm. If not,
-or if you have any trouble with this, please try the new standalone install steps just below.
-
-This might require elevated privileges in some environments.
-
-```sh
-$ npm install balena-cli -g --production --unsafe-perm
-```
-
-`--unsafe-perm` is only required on systems where the global install directory is not user-writable.
-This allows npm install steps to download and save prebuilt native binaries. You may be able to omit it,
-especially if you're using a user-managed node install such as [nvm](https://github.com/creationix/nvm).
-
-In some environments, this process will need to build native modules. This may require a more complex build
-environment, and notably requires Python 2.7. If you hit any problems with this, we recommend you try the
-alternative standalone install below instead.
-
-### Standalone install
-
-If you don't have node or a working pre-gyp environment, you can still install the CLI as a standalone
-binary. **This is experimental and may not work perfectly yet in all environments**, but it seems to work
-well in initial cross-platform testing, so it may be useful, and we'd love your feedback if you hit any issues.
-
-To install the CLI as a standalone binary:
-
-* Download the latest zip for your OS from https://github.com/balena-io/balena-cli/releases.
-* Extract the contents, putting the `balena-cli` folder somewhere appropriate for your system (e.g. `C:/balena-cli`, `/usr/local/lib/balena-cli`, etc).
-* Add the `balena-cli` folder to your `PATH` ([Windows instructions](https://www.computerhope.com/issues/ch000549.htm), [Linux instructions](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix), [OSX instructions](https://stackoverflow.com/questions/22465332/setting-path-environment-variable-in-osx-permanently))
-* Running `balena` in a fresh command line should print the balena CLI help.
-
-To update in future, simply download a new release and replace the extracted folder.
-
-Have any problems, or see any unexpected behaviour? [Please file an issue!](https://github.com/balena-io/balena-cli/issues/new)
-
-### Login
+Several CLI commands require access to your balenaCloud account, for example in order to push a
+new release to your application. Those commands require creating a CLI login session by running:
 
 ```sh
 $ balena login
 ```
 
-_(Typically useful, but not strictly required for all commands)_
+## Proxy support
 
-### Run commands
+HTTP(S) proxies can be configured through any of the following methods, in precedence order
+(from higher to lower):
 
-Take a look at the full command documentation at [https://balena.io/docs/tools/cli/](https://balena.io/docs/tools/cli/#table-of-contents
-), or by running `balena help`.
+* The `BALENARC_PROXY` environment variable in URL format, with protocol (`http` or `https`),
+  host, port and optionally basic auth. Examples:
+  * `export BALENARC_PROXY='https://bob:secret@proxy.company.com:12345'`
+  * `export BALENARC_PROXY='http://localhost:8000'`
 
-### Bash completions
+* The `proxy` setting in the [CLI config
+  file](https://www.npmjs.com/package/balena-settings-client#documentation). It may be:
+  * A string in URL format, e.g. `proxy: 'http://localhost:8000'`
+  * An object in the format:
 
-Optionally you can enable tab completions for the bash shell, enabling the shell to provide additional context and automatically complete arguments to`balena`. To enable bash completions, copy the `balena-completion.bash` file to the default bash completions directory (usually `/etc/bash_completion.d/`) or append it to the end of `~/.bash_completion`.
+    ```yaml
+    proxy:
+        protocol: 'http'
+        host: 'proxy.company.com'
+        port: 12345
+        proxyAuth: 'bob:secret'
+    ```
 
-FAQ
----
+* The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as
+  `BALENARC_PROXY`.
 
-### Where is my configuration file?
+### Proxy setup for balena ssh
 
-The per-user configuration file lives in `$HOME/.balenarc.yml` or `%UserProfile%\_balenarc.yml`, in Unix based operating systems and Windows respectively.
+In order to work behind a proxy server, the `balena ssh` command requires the
+[`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) to be installed.
+`proxytunnel` is available for Linux distributions like Ubuntu/Debian (`apt install proxytunnel`),
+and for macOS through [Homebrew](https://brew.sh/). Windows support is limited to the [Windows
+Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (e.g., by installing
+Ubuntu through the Microsoft App Store).
 
-The balena CLI also attempts to read a `balenarc.yml` file in the current directory, which takes precedence over the per-user configuration file.
+Ensure that the proxy server is configured to allow proxy requests to ssh port 22, using
+SSL encryption. For example, in the case of the [Squid](http://www.squid-cache.org/) proxy
+server, it should be configured with the following rules in the `squid.conf` file:  
+`acl SSL_ports port 22`  
+`acl Safe_ports port 22`  
 
-### How do I point the balena CLI to staging?
+### Proxy exclusion
 
-The easiest way is to set the `BALENARC_BALENA_URL=balena-staging.com` environment variable.
+The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations from proxying.
 
-Alternatively, you can edit your configuration file and set `balenaUrl: balena-staging.com` to persist this setting.
+> * This feature requires CLI version 11.30.8 or later. In the case of the npm [installation
+>   option](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md), it also requires
+>   Node.js version 10.16.0 or later.
+> * To exclude a `balena ssh` target from proxying (IP address or `.local` hostname), the
+>   `--noproxy` option should be specified in addition to the `BALENARC_NO_PROXY` variable.
 
-### How do I make the balena CLI persist data in another directory?
+By default (if `BALENARC_NO_PROXY` is not defined), all [private IPv4
+addresses](https://en.wikipedia.org/wiki/Private_network) and `'*.local'` hostnames are excluded
+from proxying. Other hostnames that resolve to private IPv4 addresses are **not** excluded by
+default, because matching takes place before name resolution.
 
-The balena CLI persists your session token, as well as cached images in `$HOME/.balena` or `%UserProfile%\_balena`.
+`localhost` and `127.0.0.1` are always excluded from proxying, regardless of the value of
+BALENARC_NO_PROXY.
 
-Pointing the balena CLI to persist data in another location is necessary in certain environments, like a server, where there is no home directory, or a device running balenaOS, which erases all data after a restart.
+The format of the `BALENARC_NO_PROXY` environment variable is a comma-separated list of patterns
+that are matched against hostnames or IP addresses. For example:
 
-You can accomplish this by setting `BALENARC_DATA_DIRECTORY=/opt/balena` or adding `dataDirectory: /opt/balena` to your configuration file, replacing `/opt/balena` with your desired directory.
+```
+export BALENARC_NO_PROXY='*.local,dev*.mycompany.com,192.168.*'
+```
 
-Support
--------
+Matched patterns are excluded from proxying. Wildcard expressions are documented at
+[matcher](https://www.npmjs.com/package/matcher#usage). Matching takes place _before_ name
+resolution, so a pattern like `'192.168.*'` will **not** match a hostname that resolves to an IP
+address like `192.168.1.2`.
 
-If you're having any problems, check our [troubleshooting guide](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) and if your problem is not addressed there, please [raise an issue](https://github.com/balena-io/balena-cli/issues/new) on GitHub and the balena team will be happy to help.
+## Command reference documentation
 
-You can also get in touch with us in the balena [forums](https://forums.balena.io/).
+The full CLI command reference is available [on the web](https://www.balena.io/docs/reference/cli/
+) or by running `balena help --verbose`.
 
-Development guidelines
-----------------------
+## Support, FAQ and troubleshooting
 
-After cloning this repository and running `npm install` you can build the CLI using `npm run build`.
-You can then run the generated build using `./bin/balena`.
-In order to ease development:
-* you can build the CLI using the `npm run build:fast` variant which skips some of the build steps or
-* you can use `./bin/balena-dev` which live transpiles the sources of the CLI.
+To learn more, troubleshoot issues, or to contact us for support:
 
-In either case, before opening a PR make sure to also test your changes after doing a full build with `npm run build`.
+* Check the [masterclass tutorials](https://www.balena.io/docs/learn/more/masterclasses/overview/)
+* Check our [FAQ / troubleshooting document](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md)
+* Ask us a question through the [balenaCloud forum](https://forums.balena.io/c/balena-cloud)
 
-License
--------
+For CLI bug reports or feature requests, check the
+[CLI GitHub issues](https://github.com/balena-io/balena-cli/issues/).
 
-The project is licensed under the Apache 2.0 license.
+## Deprecation policy
+
+The balena CLI uses [semver versioning](https://semver.org/), with the concepts
+of major, minor and patch version releases.
+
+The latest release of a major version of the balena CLI will remain compatible with
+the balenaCloud backend services for at least one year from the date when the
+following major version is released. For example, balena CLI v10.17.5, as the
+latest v10 release, would remain compatible with the balenaCloud backend for one
+year from the date when v11.0.0 is released.
+
+At the end of this period, the older major version is considered deprecated and
+some of the functionality that depends on balenaCloud services may stop working
+at any time.
+Users are encouraged to regularly update the balena CLI to the latest version.
+
+## Contributing (including editing documentation files)
+
+Please have a look at the [CONTRIBUTING.md](./CONTRIBUTING.md) file for some guidance before
+submitting a pull request or updating documentation (because some files are automatically
+generated). Thank you for your help and interest!
+
+## License
+
+The project is licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).
+A copy is also available in the LICENSE file in this repository.

TROUBLESHOOTING.md

@@ -1,38 +1,52 @@
-Troubleshooting
-===============
+# balena CLI FAQ & Troubleshooting
 
-This document contains common issues related to the balena CLI, and how to fix them.
+## Where is the balena CLI's configuration file located?
 
-### After burning to an sdcard, my device doesn't boot
+The per-user configuration file lives in `$HOME/.balenarc.yml` or `%UserProfile%\_balenarc.yml`, in
+Unix based operating systems and Windows respectively.
 
-- The downloaded image is not complete (download was interrupted).
+The balena CLI also attempts to read a `balenarc.yml` file in the current directory, which takes
+precedence over the per-user configuration file.
 
-Please clean the cache (`%HOME/.balena/cache` or `C:\Users\<user>\_balena\cache`) and run the command again. In the future, the CLI will check that the image is not complete and clean the cache for you.
+## How do I point the balena CLI to the staging environment?
 
-### I get a permission error when burning to an sdcard
+Set the `BALENARC_BALENA_URL=balena-staging.com` environment variable, or add
+`balenaUrl: balena-staging.com` to the balena CLI's configuration file.
 
-- The SDCard is locked.
+## How do I make the balena CLI persist data in another directory?
 
-### I get EINVAL errors on Cygwin
+The balena CLI persists the session token, as well as cached assets, to `$HOME/.balena` or
+`%UserProfile%\_balena`. This directory can be changed by setting an environment variable,
+`BALENARC_DATA_DIRECTORY=/opt/balena`, or by adding `dataDirectory: /opt/balena` to the CLI's
+configuration file, replacing `/opt/balena` with the desired directory.
 
-The errors look something like this:
+## After burning to an SD card, my device doesn't boot
+
+Check whether the downloaded image is incomplete (download was interrupted) or corrupted.
+
+Try clearing the cache (`%HOME/.balena/cache` or `C:\Users\<user>\_balena\cache`) and running the
+command again.
+
+## I get a permission error when burning to an SD card
+
+Check whether the SD card is locked (a physical switch on the side of the card).
+
+## I get EINVAL errors on Cygwin
+
+The errors may look something like this:
 
 ```
 net.js:156
     this._handle.open(options.fd);
                  ^
 Error: EINVAL, invalid argument
-  at new Socket (net.js:156:18)
-  at process.stdin (node.js:664:19)
-  at Object.Interface.createInterface (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\node_modules\readline2\index.js:31:43)
-  at PromptUI.UI (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\lib\ui\baseUI.js:23:40)
-  at new PromptUI (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\lib\ui\prompt.js:26:8)
-  at Object.promptModule [as prompt] (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\lib\inquirer.js:27:14)
 ```
 
-- Some interactive widgets don't work on `Cygwin`. If you're running Windows, it's preferrable that you use `cmd.exe`, as `Cygwin` is [not official supported by Node.js](https://github.com/chjj/blessed/issues/56#issuecomment-42671945).
+Some interactive widgets don't work on `Cygwin`. On Windows, PowerShell or `cmd.exe` are better
+supported. Alternative shells are [listed in the README
+file](./README.md#choosing-a-shell-command-promptterminal).
 
-### I get `Invalid MBR boot signature` when configuring a device
+## I get `Invalid MBR boot signature` when configuring a device
 
 This error, accompanied with something like: `Expected 0xAA55, but saw 0x29FE` usually indicates a corrupted device operating system image in the cache, due to bad a internet connection during the download process.
 
@@ -48,12 +62,65 @@ Or in Windows:
 > del /s /q %UserProfile%\_balena\cache
 ```
 
-### I get `EACCES: permission denied` when logging in
+## I get `EACCES: permission denied` when logging in
 
-The balena CLI stores the session token in `$HOME/.balena` or `C:\Users\<user>\_balena` in UNIX based operating systems and Windows respectively. This error usually indicates that the user doesn't have permissions over that directory, which can happen if you ran the balena CLI as `root`, and thus the directory got owned by him.
+The balena CLI stores the session token in `$HOME/.balena` or `C:\Users\<user>\_balena` in UNIX based
+operating systems and Windows respectively. This error usually indicates that the user doesn't have
+permissions over that directory, which can happen if the CLI was executed as the `root` user.
 
 Try resetting the ownership by running:
 
 ```sh
 $ sudo chown -R <user> $HOME/.balena
 ```
+
+## Broken line wrapping / cursor behavior with `balena ssh`
+
+Users sometimes come across broken line wrapping or cursor behavior in text terminals, for example
+when long command lines are typed in a `balena ssh` session, or when using text editors like `vim`
+or `nano`. This is not something specific to the balena CLI, being also a commonly reported issue
+with standard remote terminal tools like `ssh` or `telnet`.  It is often a remote shell
+configuration issue (files like `/etc/profile`, `~/.bash_profile`, `~/.bash_login`, `~/.profile`
+and the like on the remote machine), including UTF-8 misconfiguration, the use of unsupported ASCII
+control characters in shell prompt formatting (e.g. the `$PS1` env var) or the output of tools or
+log files that use colored text. The issue can sometimes be fixed by simply resizing the client
+terminal window, or by running one or more of the following commands on the shell:
+
+```sh
+export TERMINAL=linux
+stty sane
+shopt -s checkwinsize
+bind 'set horizontal-scroll-mode off'
+```
+
+Terminal multiplexer tools like GNU `screen` or `tmux` are sometimes reported to fix the issues, though at other times they are reported as the _cause_ of the problem. They have their own configuration files to take into account.
+
+Further reference:
+* https://stackoverflow.com/questions/1133031/shell-prompt-line-wrapping-issue
+* https://superuser.com/questions/46948/any-way-to-fix-screens-mishandling-of-line-wrap-maybe-only-terminal-app
+* https://unix.stackexchange.com/questions/105958/terminal-prompt-not-wrapping-correctly
+* https://unix.stackexchange.com/questions/529377/terminal-long-line-wrapping
+* https://github.com/microsoft/WSL/issues/1436
+
+If nothing seems to help, consider also using a different client-side terminal application:
+* Linux: xterm, KDE Konsole, GNOME Terminal
+* Mac: Terminal, iTerm2
+* Windows: PowerShell, PuTTY, WSL (Windows Subsystem for Linux)
+
+## "Docker seems to be unavailable" error when using Windows Subsystem for Linux (WSL)
+
+When running on WSL, the recommendation is to install a CLI release for Linux, like the standalone
+zip package for Linux. However, commands like "balena build" will, by default, attempt to reach the
+Docker daemon at the Unix socket path `/var/run/docker.sock`, while Docker Desktop for Windows uses
+a Windows named pipe at `//./pipe/docker_engine` (which the Linux CLI on WSL cannot use). A
+solution is:
+
+- Open the Docker Desktop for Windows settings panel and tick the checkbox _"Expose daemon on tcp://localhost:2375 without TLS"._
+- On the WSL command line, set an env var:  
+`export DOCKER_HOST=tcp://localhost:2375`  
+Alternatively, use the command-line options `-h 127.0.0.1 -p 2375` for commands like `balena build` and `balena deploy`.
+
+Further reference:
+
+- https://techcommunity.microsoft.com/t5/Containers/WSL-Interoperability-with-Docker/ba-p/382405
+- https://forums.docker.com/t/wsl-and-docker-for-windows-cannot-connect-to-the-docker-daemon-at-tcp-localhost-2375-is-the-docker-daemon-running/63571/12

appveyor.yml

@@ -1,6 +1,8 @@
 # appveyor file
 # http://www.appveyor.com/docs/appveyor-yml
 
+image: Visual Studio 2017
+
 init:
   - git config --global core.autocrlf input
 
@@ -14,21 +16,28 @@ matrix:
 # what combinations to test
 environment:
   matrix:
-    - nodejs_version: 6
+    - nodejs_version: 10
 
 install:
   - ps: Install-Product node $env:nodejs_version x64
-  - npm install -g npm@4
   - set PATH=%APPDATA%\npm;%PATH%
-  - npm install
+  - npm config set python 'C:\Python27\python.exe'
+  - npm --version
+  # - npm install
 
 build: off
+test: off
+deploy: off
 
 test_script:
   - node --version
   - npm --version
-  - cmd: npm test
+  # - npm test
 
 deploy_script:
-  - IF "%APPVEYOR_REPO_TAG%" == "true" (npm run release)
-  - IF NOT "%APPVEYOR_REPO_TAG%" == "true" (echo 'Not tagged, skipping deploy')
+  - node --version
+  - npm --version
+  # - npm run build:standalone
+  # - npm run build:installer
+  # - IF "%APPVEYOR_REPO_TAG%" == "true" (npm run release)
+  # - IF NOT "%APPVEYOR_REPO_TAG%" == "true" (echo 'Not tagged, skipping deploy')

automation/build-bin.ts

@@ -1,36 +1,420 @@
-import * as path from 'path';
-import * as fs from 'fs-extra';
+/**
+ * @license
+ * Copyright 2019 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { JsonVersions } from '../lib/commands/version';
+
+import { run as oclifRun } from '@oclif/dev-cli';
+import * as archiver from 'archiver';
+import * as Bluebird from 'bluebird';
+import { execFile } from 'child_process';
 import * as filehound from 'filehound';
-import { exec as execPkg } from 'pkg';
+import * as fs from 'fs-extra';
+import * as _ from 'lodash';
+import * as path from 'path';
+import * as rimraf from 'rimraf';
+import * as semver from 'semver';
+import * as util from 'util';
 
-const ROOT = path.join(__dirname, '..');
+import { stripIndent } from '../lib/utils/lazy';
+import {
+	diffLines,
+	getSubprocessStdout,
+	loadPackageJson,
+	MSYS2_BASH,
+	ROOT,
+	StdOutTap,
+	whichSpawn,
+} from './utils';
 
-console.log('Building package...\n');
+export const packageJSON = loadPackageJson();
+export const version = 'v' + packageJSON.version;
+const arch = process.arch;
 
-execPkg(['--target', 'host', '--output', 'build-bin/balena', 'package.json'])
-	.then(() =>
-		fs.copy(
-			path.join(ROOT, 'node_modules', 'opn', 'xdg-open'),
-			path.join(ROOT, 'build-bin', 'xdg-open'),
-		),
-	)
-	.then(() => {
-		return filehound
-			.create()
-			.paths(path.join(ROOT, 'node_modules'))
-			.ext(['node', 'dll'])
-			.find();
-	})
-	.then(nativeExtensions => {
-		console.log(`\nCopying to build-bin:\n${nativeExtensions.join('\n')}`);
+function dPath(...paths: string[]) {
+	return path.join(ROOT, 'dist', ...paths);
+}
 
-		return nativeExtensions.map(extPath => {
-			return fs.copy(
+interface PathByPlatform {
+	[platform: string]: string;
+}
+
+const standaloneZips: PathByPlatform = {
+	linux: dPath(`balena-cli-${version}-linux-${arch}-standalone.zip`),
+	darwin: dPath(`balena-cli-${version}-macOS-${arch}-standalone.zip`),
+	win32: dPath(`balena-cli-${version}-windows-${arch}-standalone.zip`),
+};
+
+const oclifInstallers: PathByPlatform = {
+	darwin: dPath('macos', `balena-${version}.pkg`),
+	win32: dPath('win', `balena-${version}-${arch}.exe`),
+};
+
+const renamedOclifInstallers: PathByPlatform = {
+	darwin: dPath(`balena-cli-${version}-macOS-${arch}-installer.pkg`),
+	win32: dPath(`balena-cli-${version}-windows-${arch}-installer.exe`),
+};
+
+export const finalReleaseAssets: { [platform: string]: string[] } = {
+	win32: [standaloneZips['win32'], renamedOclifInstallers['win32']],
+	darwin: [standaloneZips['darwin'], renamedOclifInstallers['darwin']],
+	linux: [standaloneZips['linux']],
+};
+
+/**
+ * Given the output of `pkg` as a string (containing warning messages),
+ * diff it against previously saved output of known "safe" warnings.
+ * Throw an error if the diff is not empty.
+ */
+async function diffPkgOutput(pkgOut: string) {
+	const { monochrome } = await import('../tests/helpers');
+	const relSavedPath = path.join(
+		'tests',
+		'test-data',
+		'pkg',
+		`expected-warnings-${process.platform}.txt`,
+	);
+	const absSavedPath = path.join(ROOT, relSavedPath);
+	const ignoreStartsWith = [
+		'> pkg@',
+		'> Fetching base Node.js binaries',
+		'  fetched-',
+	];
+	const modulesRE =
+		process.platform === 'win32'
+			? /(?<=[ '])([A-Z]:)?\\.+?\\node_modules(?=\\)/
+			: /(?<=[ '])\/.+?\/node_modules(?=\/)/;
+	const buildRE =
+		process.platform === 'win32'
+			? /(?<=[ '])([A-Z]:)?\\.+\\build(?=\\)/
+			: /(?<=[ '])\/.+\/build(?=\/)/;
+
+	const cleanLines = (chunks: string | string[]) => {
+		const lines = typeof chunks === 'string' ? chunks.split('\n') : chunks;
+		return lines
+			.map((line: string) => monochrome(line)) // remove ASCII colors
+			.filter((line: string) => !/^\s*$/.test(line)) // blank lines
+			.filter((line: string) =>
+				ignoreStartsWith.every((i) => !line.startsWith(i)),
+			)
+			.map((line: string) => {
+				// replace absolute paths with relative paths
+				let replaced = line.replace(modulesRE, 'node_modules');
+				if (replaced === line) {
+					replaced = line.replace(buildRE, 'build');
+				}
+				return replaced;
+			});
+	};
+
+	pkgOut = cleanLines(pkgOut).join('\n');
+	const { readFile } = (await import('fs')).promises;
+	const expectedOut = cleanLines(await readFile(absSavedPath, 'utf8')).join(
+		'\n',
+	);
+	if (expectedOut !== pkgOut) {
+		const sep =
+			'================================================================================';
+		const diff = diffLines(expectedOut, pkgOut);
+		const msg = `pkg output does not match expected output from "${relSavedPath}"
+Diff:
+${sep}
+${diff}
+${sep}
+Check whether the new or changed pkg warnings are safe to ignore, then update
+"${relSavedPath}"
+and share the result of your investigation as comments on the pull request.
+Hint: the fix is often a matter of updating the 'pkg.scripts' or 'pkg.assets'
+sections in the CLI's 'package.json' file, or a matter of updating the
+'buildPkg' function in 'automation/build-bin.ts'.  Sometimes it requires
+patching dependencies: See for example 'patches/all/open+7.0.2.patch'.
+${sep}
+`;
+		throw new Error(msg);
+	}
+}
+
+/**
+ * Call `pkg.exec` to generate the standalone zip file, capturing its warning
+ * messages (stdout and stderr) in order to call diffPkgOutput().
+ */
+async function execPkg(...args: any[]) {
+	const { exec: pkgExec } = await import('pkg');
+	const outTap = new StdOutTap(true);
+	try {
+		outTap.tap();
+		await (pkgExec as any)(...args);
+	} catch (err) {
+		outTap.untap();
+		console.log(outTap.stdoutBuf.join(''));
+		console.error(outTap.stderrBuf.join(''));
+		throw err;
+	}
+	outTap.untap();
+	await diffPkgOutput(outTap.allBuf.join(''));
+}
+
+/**
+ * Use the 'pkg' module to create a single large executable file with
+ * the contents of 'node_modules' and the CLI's javascript code.
+ * Also copy a number of native modules (binary '.node' files) that are
+ * compiled during 'npm install' to the 'build-bin' folder, alongside
+ * the single large executable file created by pkg. (This is necessary
+ * because of a pkg limitation that does not allow binary executables
+ * to be directly executed from inside another binary executable.)
+ */
+async function buildPkg() {
+	const args = [
+		'--target',
+		'host',
+		'--output',
+		'build-bin/balena',
+		'package.json',
+	];
+	console.log('=======================================================');
+	console.log(`execPkg ${args.join(' ')}`);
+	console.log(`cwd="${process.cwd()}" ROOT="${ROOT}"`);
+	console.log('=======================================================');
+
+	await execPkg(args);
+
+	const paths: Array<[string, string[], string[]]> = [
+		// [platform, [source path], [destination path]]
+		['*', ['open', 'xdg-open'], ['xdg-open']],
+		['*', ['opn', 'xdg-open'], ['xdg-open-402']],
+		['darwin', ['denymount', 'bin', 'denymount'], ['denymount']],
+	];
+	await Promise.all(
+		paths.map(([platform, source, dest]) => {
+			if (platform === '*' || platform === process.platform) {
+				// eg copy from node_modules/open/xdg-open to build-bin/xdg-open
+				return fs.copy(
+					path.join(ROOT, 'node_modules', ...source),
+					path.join(ROOT, 'build-bin', ...dest),
+				);
+			}
+		}),
+	);
+	const nativeExtensionPaths: string[] = await filehound
+		.create()
+		.paths(path.join(ROOT, 'node_modules'))
+		.ext(['node', 'dll'])
+		.find();
+
+	console.log(`\nCopying to build-bin:\n${nativeExtensionPaths.join('\n')}`);
+
+	await Promise.all(
+		nativeExtensionPaths.map((extPath) =>
+			fs.copy(
 				extPath,
 				extPath.replace(
 					path.join(ROOT, 'node_modules'),
 					path.join(ROOT, 'build-bin'),
 				),
-			);
+			),
+		),
+	);
+}
+
+/**
+ * Run some basic tests on the built pkg executable.
+ * TODO: test more than just `balena version -j`; integrate with the
+ * existing mocha/chai CLI command testing.
+ */
+async function testPkg() {
+	const pkgBalenaPath = path.join(
+		ROOT,
+		'build-bin',
+		process.platform === 'win32' ? 'balena.exe' : 'balena',
+	);
+	console.log(`Testing standalone package "${pkgBalenaPath}"...`);
+	// Run `balena version -j`, parse its stdout as JSON, and check that the
+	// reported Node.js major version matches semver.major(process.version)
+	const stdout = await getSubprocessStdout(pkgBalenaPath, ['version', '-j']);
+	let pkgNodeVersion = '';
+	let pkgNodeMajorVersion = 0;
+	try {
+		const balenaVersions: JsonVersions = JSON.parse(stdout);
+		pkgNodeVersion = balenaVersions['Node.js'];
+		pkgNodeMajorVersion = semver.major(pkgNodeVersion);
+	} catch (err) {
+		throw new Error(stripIndent`
+			Error parsing JSON output of "balena version -j": ${err}
+			Original output: "${stdout}"`);
+	}
+	if (semver.major(process.version) !== pkgNodeMajorVersion) {
+		throw new Error(
+			`Mismatched major version: built-in pkg Node version="${pkgNodeVersion}" vs process.version="${process.version}"`,
+		);
+	}
+	console.log('Success! (standalone package test successful)');
+}
+
+/**
+ * Create the zip file for the standalone 'pkg' bundle previously created
+ * by the buildPkg() function in 'build-bin.ts'.
+ */
+async function zipPkg() {
+	const outputFile = standaloneZips[process.platform];
+	if (!outputFile) {
+		throw new Error(
+			`Standalone installer unavailable for platform "${process.platform}"`,
+		);
+	}
+	await fs.mkdirp(path.dirname(outputFile));
+	await new Promise((resolve, reject) => {
+		console.log(`Zipping standalone package to "${outputFile}"...`);
+
+		const archive = archiver('zip', {
+			zlib: { level: 7 },
 		});
+		archive.directory(path.join(ROOT, 'build-bin'), 'balena-cli');
+
+		const outputStream = fs.createWriteStream(outputFile);
+
+		outputStream.on('close', resolve);
+		outputStream.on('error', reject);
+
+		archive.on('error', reject);
+		archive.on('warning', console.warn);
+
+		archive.pipe(outputStream);
+		archive.finalize();
 	});
+}
+
+export async function buildStandaloneZip() {
+	console.log(`Building standalone zip package for CLI ${version}`);
+	try {
+		await buildPkg();
+		await testPkg();
+		await zipPkg();
+		console.log(`Standalone zip package build completed`);
+	} catch (error) {
+		console.error(`Error creating or testing standalone zip package`);
+		throw error;
+	}
+}
+
+async function renameInstallerFiles() {
+	if (await fs.pathExists(oclifInstallers[process.platform])) {
+		await fs.rename(
+			oclifInstallers[process.platform],
+			renamedOclifInstallers[process.platform],
+		);
+	}
+}
+
+/**
+ * If the CSC_LINK and CSC_KEY_PASSWORD env vars are set, digitally sign the
+ * executable installer by running the balena-io/scripts/shared/sign-exe.sh
+ * script (which must be in the PATH) using a MSYS2 bash shell.
+ */
+async function signWindowsInstaller() {
+	if (process.env.CSC_LINK && process.env.CSC_KEY_PASSWORD) {
+		const exeName = renamedOclifInstallers[process.platform];
+		const execFileAsync = util.promisify<string, string[], void>(execFile);
+
+		console.log(`Signing installer "${exeName}"`);
+		await execFileAsync(MSYS2_BASH, [
+			'sign-exe.sh',
+			'-f',
+			exeName,
+			'-d',
+			`balena-cli ${version}`,
+		]);
+	} else {
+		console.log(
+			'Skipping installer signing step because CSC_* env vars are not set',
+		);
+	}
+}
+
+/**
+ * Run the `oclif-dev pack:win` or `pack:macos` command (depending on the value
+ * of process.platform) to generate the native installers (which end up under
+ * the 'dist' folder). There are some harcoded options such as selecting only
+ * 64-bit binaries under Windows.
+ */
+export async function buildOclifInstaller() {
+	let packOS = '';
+	let packOpts = ['-r', ROOT];
+	if (process.platform === 'darwin') {
+		packOS = 'macos';
+	} else if (process.platform === 'win32') {
+		packOS = 'win';
+		packOpts = packOpts.concat('-t', 'win32-x64');
+	}
+	if (packOS) {
+		console.log(`Building oclif installer for CLI ${version}`);
+		const packCmd = `pack:${packOS}`;
+		const dirs = [path.join(ROOT, 'dist', packOS)];
+		if (packOS === 'win') {
+			dirs.push(path.join(ROOT, 'tmp', 'win*'));
+		}
+		for (const dir of dirs) {
+			console.log(`rimraf(${dir})`);
+			await Bluebird.fromCallback((cb) => rimraf(dir, cb));
+		}
+		console.log('=======================================================');
+		console.log(`oclif-dev "${packCmd}" "${packOpts.join('" "')}"`);
+		console.log(`cwd="${process.cwd()}" ROOT="${ROOT}"`);
+		console.log('=======================================================');
+		await oclifRun([packCmd].concat(...packOpts));
+		await renameInstallerFiles();
+		// The Windows installer is explicitly signed here (oclif doesn't do it).
+		// The macOS installer is automatically signed by oclif (which runs the
+		// `pkgbuild` tool), using the certificate name given in package.json
+		// (`oclif.macos.sign` section).
+		if (process.platform === 'win32') {
+			await signWindowsInstaller();
+		}
+		console.log(`oclif installer build completed`);
+	}
+}
+
+/**
+ * Wrapper around the npm `catch-uncommitted` package in order to run it
+ * conditionally, only when:
+ * - A CI env var is set (CI=true), and
+ * - The OS is not Windows. (`catch-uncommitted` fails on Windows)
+ */
+export async function catchUncommitted(): Promise<void> {
+	if (process.env.DEBUG) {
+		console.error(`[debug] CI=${process.env.CI} platform=${process.platform}`);
+	}
+	if (
+		process.env.CI &&
+		['true', 'yes', '1'].includes(process.env.CI.toLowerCase()) &&
+		process.platform !== 'win32'
+	) {
+		await whichSpawn('npx', [
+			'catch-uncommitted',
+			'--catch-no-git',
+			'--skip-node-versionbot-changes',
+			'--ignore-space-at-eol',
+		]);
+	}
+}
+
+export async function testShrinkwrap(): Promise<void> {
+	if (process.env.DEBUG) {
+		console.error(`[debug] platform=${process.platform}`);
+	}
+	if (process.platform !== 'win32') {
+		await whichSpawn(path.resolve(__dirname, 'test-lock-deduplicated.sh'));
+	}
+}

automation/capitanodoc/capitanodoc.ts

@@ -0,0 +1,210 @@
+/**
+ * @license
+ * Copyright 2019 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as path from 'path';
+import { MarkdownFileParser } from './utils';
+
+/**
+ * This is the skeleton of CLI documentation/reference web page at:
+ * https://www.balena.io/docs/reference/cli/
+ *
+ * The `getCapitanoDoc` function in this module parses README.md and adds
+ * some content to this object.
+ */
+const capitanoDoc = {
+	title: 'balena CLI Documentation',
+	introduction: '',
+	categories: [
+		{
+			title: 'API keys',
+			files: ['build/commands/api-key/generate.js'],
+		},
+		{
+			title: 'Application',
+			files: [
+				'build/commands/apps.js',
+				'build/commands/app/index.js',
+				'build/commands/app/create.js',
+				'build/commands/app/purge.js',
+				'build/commands/app/rename.js',
+				'build/commands/app/restart.js',
+				'build/commands/app/rm.js',
+			],
+		},
+		{
+			title: 'Authentication',
+			files: [
+				'build/commands/login.js',
+				'build/commands/logout.js',
+				'build/commands/whoami.js',
+			],
+		},
+		{
+			title: 'Device',
+			files: [
+				'build/commands/devices/index.js',
+				'build/commands/devices/supported.js',
+				'build/commands/device/index.js',
+				'build/commands/device/identify.js',
+				'build/commands/device/init.js',
+				'build/commands/device/move.js',
+				'build/commands/device/os-update.js',
+				'build/commands/device/public-url.js',
+				'build/commands/device/purge.js',
+				'build/commands/device/reboot.js',
+				'build/commands/device/register.js',
+				'build/commands/device/rename.js',
+				'build/commands/device/restart.js',
+				'build/commands/device/rm.js',
+				'build/commands/device/shutdown.js',
+			],
+		},
+		{
+			title: 'Environment Variables',
+			files: [
+				'build/commands/envs.js',
+				'build/commands/env/add.js',
+				'build/commands/env/rename.js',
+				'build/commands/env/rm.js',
+			],
+		},
+		{
+			title: 'Tags',
+			files: [
+				'build/commands/tags.js',
+				'build/commands/tag/rm.js',
+				'build/commands/tag/set.js',
+			],
+		},
+		{
+			title: 'Help and Version',
+			files: ['help', 'build/commands/version.js'],
+		},
+		{
+			title: 'Keys',
+			files: [
+				'build/commands/keys.js',
+				'build/commands/key/index.js',
+				'build/commands/key/add.js',
+				'build/commands/key/rm.js',
+			],
+		},
+		{
+			title: 'Logs',
+			files: ['build/commands/logs.js'],
+		},
+		{
+			title: 'Network',
+			files: [
+				'build/commands/scan.js',
+				'build/commands/ssh.js',
+				'build/commands/tunnel.js',
+			],
+		},
+		{
+			title: 'Notes',
+			files: ['build/commands/note.js'],
+		},
+		{
+			title: 'OS',
+			files: [
+				'build/commands/os/build-config.js',
+				'build/commands/os/configure.js',
+				'build/commands/os/versions.js',
+				'build/commands/os/download.js',
+				'build/commands/os/initialize.js',
+			],
+		},
+		{
+			title: 'Config',
+			files: [
+				'build/commands/config/generate.js',
+				'build/commands/config/inject.js',
+				'build/commands/config/read.js',
+				'build/commands/config/reconfigure.js',
+				'build/commands/config/write.js',
+			],
+		},
+		{
+			title: 'Preload',
+			files: ['build/commands/preload.js'],
+		},
+		{
+			title: 'Push',
+			files: ['build/commands/push.js'],
+		},
+		{
+			title: 'Settings',
+			files: ['build/commands/settings.js'],
+		},
+		{
+			title: 'Local',
+			files: [
+				'build/commands/local/configure.js',
+				'build/commands/local/flash.js',
+			],
+		},
+		{
+			title: 'Deploy',
+			files: ['build/commands/build.js', 'build/commands/deploy.js'],
+		},
+		{
+			title: 'Platform',
+			files: ['build/commands/join.js', 'build/commands/leave.js'],
+		},
+		{
+			title: 'Utilities',
+			files: ['build/commands/util/available-drives.js'],
+		},
+		{
+			title: 'Support',
+			files: ['build/commands/support.js'],
+		},
+	],
+};
+
+/**
+ * Modify and return the `capitanoDoc` object above in order to render the
+ * CLI documentation/reference web page at:
+ * https://www.balena.io/docs/reference/cli/
+ *
+ * This function parses the README.md file to extract relevant sections
+ * for the documentation web page.
+ */
+export async function getCapitanoDoc(): Promise<typeof capitanoDoc> {
+	const readmePath = path.join(__dirname, '..', '..', 'README.md');
+	const mdParser = new MarkdownFileParser(readmePath);
+	const sections: string[] = await Promise.all([
+		mdParser.getSectionOfTitle('About').then((sectionLines: string) => {
+			// delete the title of the 'About' section for the web page
+			const match = /^(#+)\s+.+?\n\s*([^]*)/.exec(sectionLines);
+			if (!match || match.length < 3) {
+				throw new Error(`Error parsing section title`);
+			}
+			// match[1] has the title, match[2] has the rest
+			return match && match[2];
+		}),
+		mdParser.getSectionOfTitle('Installation'),
+		mdParser.getSectionOfTitle('Choosing a shell (command prompt/terminal)'),
+		mdParser.getSectionOfTitle('Logging in'),
+		mdParser.getSectionOfTitle('Proxy support'),
+		mdParser.getSectionOfTitle('Support, FAQ and troubleshooting'),
+		mdParser.getSectionOfTitle('Deprecation policy'),
+	]);
+	capitanoDoc.introduction = sections.join('\n');
+	return capitanoDoc;
+}

automation/capitanodoc/doc-types.d.ts

@@ -1,4 +1,22 @@
-import { CommandDefinition } from 'capitano';
+/**
+ * @license
+ * Copyright 2019 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Command as OclifCommandClass } from '@oclif/command';
+
+type OclifCommand = typeof OclifCommandClass;
 
 export interface Document {
 	title: string;
@@ -8,7 +26,7 @@ export interface Document {
 
 export interface Category {
 	title: string;
-	commands: CommandDefinition[];
+	commands: OclifCommand[];
 }
 
-export { CommandDefinition as Command };
+export { OclifCommand };

automation/capitanodoc/index.ts

@@ -1,34 +1,108 @@
-import capitanodoc = require('../../capitanodoc');
-import * as _ from 'lodash';
+/**
+ * @license
+ * Copyright 2019 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 import * as path from 'path';
+import { getCapitanoDoc } from './capitanodoc';
+import { Category, Document, OclifCommand } from './doc-types';
 import * as markdown from './markdown';
-import { Document, Category } from './doc-types';
+import { stripIndent } from '../../lib/utils/lazy';
 
-const result = <Document>{};
-result.title = capitanodoc.title;
-result.introduction = capitanodoc.introduction;
-result.categories = [];
+/**
+ * Generates the markdown document (as a string) for the CLI documentation
+ * page on the web: https://www.balena.io/docs/reference/cli/
+ */
+export async function renderMarkdown(): Promise<string> {
+	const capitanodoc = await getCapitanoDoc();
+	const result: Document = {
+		title: capitanodoc.title,
+		introduction: capitanodoc.introduction,
+		categories: [],
+	};
 
-for (let commandCategory of capitanodoc.categories) {
-	const category = <Category>{};
-	category.title = commandCategory.title;
-	category.commands = [];
+	for (const commandCategory of capitanodoc.categories) {
+		const category: Category = {
+			title: commandCategory.title,
+			commands: [],
+		};
 
-	for (let file of commandCategory.files) {
-		// tslint:disable-next-line:no-var-requires
-		const actions: any = require(path.join(process.cwd(), file));
-
-		if (actions.signature) {
-			category.commands.push(_.omit(actions, 'action'));
-		} else {
-			for (let actionName of Object.keys(actions)) {
-				const actionCommand = actions[actionName];
-				category.commands.push(_.omit(actionCommand, 'action'));
-			}
+		for (const jsFilename of commandCategory.files) {
+			category.commands.push(...importOclifCommands(jsFilename));
 		}
+		result.categories.push(category);
 	}
 
-	result.categories.push(category);
+	return markdown.render(result);
 }
 
-console.log(markdown.render(result));
+// Help is now managed via a plugin
+// This fake command allows capitanodoc to include help in docs
+class FakeHelpCommand {
+	description = stripIndent`
+		List balena commands, or get detailed help for a specific command.
+
+		List balena commands, or get detailed help for a specific command.
+	`;
+
+	examples = [
+		'$ balena help',
+		'$ balena help apps',
+		'$ balena help os download',
+	];
+
+	args = [
+		{
+			name: 'command',
+			description: 'command to show help for',
+		},
+	];
+
+	usage = 'help [command]';
+
+	flags = {
+		verbose: {
+			description: 'show additional commands',
+			char: '-v',
+		},
+	};
+}
+
+function importOclifCommands(jsFilename: string): OclifCommand[] {
+	// TODO: Currently oclif commands with no `usage` overridden will cause
+	//  an error when parsed.  This should be improved so that `usage` does not have
+	//  to be overridden if not necessary.
+
+	const command: OclifCommand =
+		jsFilename === 'help'
+			? ((new FakeHelpCommand() as unknown) as OclifCommand)
+			: (require(path.join(process.cwd(), jsFilename)).default as OclifCommand);
+
+	return [command];
+}
+
+/**
+ * Print the CLI docs markdown to stdout.
+ * See package.json for how the output is redirected to a file.
+ */
+async function printMarkdown() {
+	try {
+		console.log(await renderMarkdown());
+	} catch (error) {
+		console.error(error);
+		process.exit(1);
+	}
+}
+
+printMarkdown();

automation/capitanodoc/markdown.ts

@@ -1,76 +1,128 @@
-import * as _ from 'lodash';
+/**
+ * @license
+ * Copyright 2019 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { flagUsages } from '@oclif/parser';
 import * as ent from 'ent';
-import * as utils from './utils';
-import { Document, Category, Command } from './doc-types';
+import * as _ from 'lodash';
 
-export function renderCommand(command: Command) {
-	let result = `## ${ent.encode(command.signature)}\n\n${command.help}\n`;
+import { getManualSortCompareFunction } from '../../lib/utils/helpers';
+import { capitanoizeOclifUsage } from '../../lib/utils/oclif-utils';
+import { Category, Document, OclifCommand } from './doc-types';
 
-	if (!_.isEmpty(command.options)) {
-		result += '\n### Options';
+function renderOclifCommand(command: OclifCommand): string[] {
+	const result = [`## ${ent.encode(command.usage || '')}`];
+	const description = (command.description || '')
+		.split('\n')
+		.slice(1) // remove the first line, which oclif uses as help header
+		.join('\n')
+		.trim();
+	result.push(description);
 
-		for (let option of command.options!) {
-			result += `\n\n#### ${utils.parseSignature(option)}\n\n${
-				option.description
-			}`;
-		}
-
-		result += '\n';
+	if (!_.isEmpty(command.examples)) {
+		result.push('Examples:', command.examples!.map((v) => `\t${v}`).join('\n'));
 	}
 
-	return result;
-}
-
-export function renderCategory(category: Category) {
-	let result = `# ${category.title}\n`;
-
-	for (let command of category.commands) {
-		result += `\n${renderCommand(command)}`;
-	}
-
-	return result;
-}
-
-function getAnchor(command: Command) {
-	return (
-		'#' +
-		command.signature
-			.replace(/\s/g, '-')
-			.replace(/</g, '-')
-			.replace(/>/g, '-')
-			.replace(/\[/g, '-')
-			.replace(/\]/g, '-')
-			.replace(/-+/g, '-')
-			.replace(/\.\.\./g, '')
-			.replace(/\|/g, '')
-			.toLowerCase()
-	);
-}
-
-export function renderToc(categories: Category[]) {
-	let result = `# Table of contents\n`;
-
-	for (let category of categories) {
-		result += `\n- ${category.title}\n\n`;
-
-		for (let command of category.commands) {
-			result += `\t- [${ent.encode(command.signature)}](${getAnchor(
-				command,
-			)})\n`;
+	if (!_.isEmpty(command.args)) {
+		result.push('### Arguments');
+		for (const arg of command.args!) {
+			result.push(`#### ${arg.name.toUpperCase()}`, arg.description || '');
 		}
 	}
 
+	if (!_.isEmpty(command.flags)) {
+		result.push('### Options');
+		for (const [name, flag] of Object.entries(command.flags!)) {
+			if (name === 'help') {
+				continue;
+			}
+			flag.name = name;
+			const flagUsage = flagUsages([flag])
+				.map(([usage, _description]) => usage)
+				.join()
+				.trim();
+			result.push(`#### ${flagUsage}`);
+			result.push(flag.description || '');
+		}
+	}
 	return result;
 }
 
+function renderCategory(category: Category): string[] {
+	const result = [`# ${category.title}`];
+	for (const command of category.commands) {
+		result.push(...renderOclifCommand(command));
+	}
+	return result;
+}
+
+function getAnchor(cmdSignature: string): string {
+	return `#${_.trim(cmdSignature.replace(/\W+/g, '-'), '-').toLowerCase()}`;
+}
+
+function renderToc(categories: Category[]): string[] {
+	const result = [`# CLI Command Reference`];
+
+	for (const category of categories) {
+		result.push(`- ${category.title}`);
+		result.push(
+			category.commands
+				.map((command) => {
+					const signature = capitanoizeOclifUsage(command.usage);
+					return `\t- [${ent.encode(signature)}](${getAnchor(signature)})`;
+				})
+				.join('\n'),
+		);
+	}
+	return result;
+}
+
+const manualCategorySorting: { [category: string]: string[] } = {
+	'Environment Variables': ['envs', 'env rm', 'env add', 'env rename'],
+	OS: [
+		'os versions',
+		'os download',
+		'os build config',
+		'os configure',
+		'os initialize',
+	],
+};
+
+function sortCommands(doc: Document): void {
+	for (const category of doc.categories) {
+		if (category.title in manualCategorySorting) {
+			category.commands = category.commands.sort(
+				getManualSortCompareFunction<OclifCommand, string>(
+					manualCategorySorting[category.title],
+					(cmd: OclifCommand, x: string) =>
+						(cmd.usage || '').toString().replace(/\W+/g, ' ').includes(x),
+				),
+			);
+		}
+	}
+}
+
 export function render(doc: Document) {
-	let result = `# ${doc.title}\n\n${doc.introduction}\n\n${renderToc(
-		doc.categories,
-	)}`;
-
-	for (let category of doc.categories) {
-		result += `\n${renderCategory(category)}`;
+	sortCommands(doc);
+	const result = [
+		`# ${doc.title}`,
+		doc.introduction,
+		...renderToc(doc.categories),
+	];
+	for (const category of doc.categories) {
+		result.push(...renderCategory(category));
 	}
-
-	return result;
+	return result.join('\n\n');
 }

automation/capitanodoc/utils.ts

@@ -1,6 +1,24 @@
-import { OptionDefinition } from 'capitano';
-import * as _ from 'lodash';
+/**
+ * @license
+ * Copyright 2019 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { OptionDefinition } from 'capitano';
 import * as ent from 'ent';
+import * as fs from 'fs';
+import * as readline from 'readline';
 
 export function getOptionPrefix(signature: string) {
 	if (signature.length > 1) {
@@ -14,14 +32,14 @@ export function getOptionSignature(signature: string) {
 	return `${getOptionPrefix(signature)}${signature}`;
 }
 
-export function parseSignature(option: OptionDefinition) {
+export function parseCapitanoOption(option: OptionDefinition): string {
 	let result = getOptionSignature(option.signature);
 
-	if (_.isArray(option.alias)) {
-		for (let alias of option.alias) {
+	if (Array.isArray(option.alias)) {
+		for (const alias of option.alias) {
 			result += `, ${getOptionSignature(alias)}`;
 		}
-	} else if (_.isString(option.alias)) {
+	} else if (typeof option.alias === 'string') {
 		result += `, ${getOptionSignature(option.alias)}`;
 	}
 
@@ -31,3 +49,88 @@ export function parseSignature(option: OptionDefinition) {
 
 	return ent.encode(result);
 }
+
+export class MarkdownFileParser {
+	constructor(public mdFilePath: string) {}
+
+	/**
+	 * Extract the lines of a markdown document section with the given title.
+	 * For example, consider this sample markdown document:
+	 * ```
+	 *     # balena CLI
+	 *
+	 *     ## Introduction
+	 *     Lorem ipsum dolor sit amet, consectetur adipiscing elit,
+	 *
+	 *     ## Getting Started
+	 *     sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+	 *
+	 *     ### Prerequisites
+	 *     - Foo
+	 *     - Bar
+	 *
+	 *     ## Support
+	 *     Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
+	 * ```
+	 *
+	 * Calling getSectionOfTitle('Getting Started') for the markdown doc above
+	 * returns everything from line '## Getting Started' (included) to line
+	 * '## Support' (excluded). This method counts the number of '#' characters
+	 * to determine that subsections should be included as part of the parent
+	 * section.
+	 *
+	 * @param title The section title without '#' chars, eg. 'Getting Started'
+	 */
+	public async getSectionOfTitle(
+		title: string,
+		includeSubsections = true,
+	): Promise<string> {
+		let foundSectionLines: string[];
+		let foundSectionLevel = 0;
+
+		const rl = readline.createInterface({
+			input: fs.createReadStream(this.mdFilePath),
+			crlfDelay: Infinity,
+		});
+
+		rl.on('line', (line) => {
+			// try to match a line like "## Getting Started", where the number
+			// of '#' characters is the sectionLevel ('##' -> 2), and the
+			// sectionTitle is "Getting Started"
+			const match = /^(#+)\s+(.+)/.exec(line);
+			if (match) {
+				const sectionLevel = match[1].length;
+				const sectionTitle = match[2];
+
+				// If the target section had already been found: append a line, or end it
+				if (foundSectionLines) {
+					if (!includeSubsections || sectionLevel <= foundSectionLevel) {
+						// end previously found section
+						rl.close();
+					}
+				} else if (sectionTitle === title) {
+					// found the target section
+					foundSectionLevel = sectionLevel;
+					foundSectionLines = [];
+				}
+			}
+			if (foundSectionLines) {
+				foundSectionLines.push(line);
+			}
+		});
+
+		return await new Promise((resolve, reject) => {
+			rl.on('close', () => {
+				if (foundSectionLines) {
+					resolve(foundSectionLines.join('\n'));
+				} else {
+					reject(
+						new Error(
+							`Markdown section not found: title="${title}" file="${this.mdFilePath}"`,
+						),
+					);
+				}
+			});
+		});
+	}
+}

automation/check-doc.js

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const stripIndent = require('common-tags/lib/stripIndent');
+const _ = require('lodash');
+const { promises: fs } = require('fs');
+const path = require('path');
+const simplegit = require('simple-git/promise');
+
+const ROOT = path.normalize(path.join(__dirname, '..'));
+
+/**
+ * Compare the timestamp of cli.markdown with the timestamp of staged files,
+ * issuing an error if cli.markdown is older.
+ * If cli.markdown does not require updating and the developer cannot run
+ * `npm run build` on their laptop, the error message suggests a workaround
+ * using `touch`.
+ */
+async function checkBuildTimestamps() {
+	const git = simplegit(ROOT);
+	const docFile = path.join(ROOT, 'doc', 'cli.markdown');
+	const [docStat, gitStatus] = await Promise.all([
+		fs.stat(docFile),
+		git.status(),
+	]);
+	const stagedFiles = _.uniq([
+		...gitStatus.created,
+		...gitStatus.staged,
+		...gitStatus.renamed.map((o) => o.to),
+	])
+		// select only staged files that start with lib/ or typings/
+		.filter((f) => f.match(/^(lib|typings)[/\\]/))
+		.map((f) => path.join(ROOT, f));
+
+	const fStats = await Promise.all(stagedFiles.map((f) => fs.stat(f)));
+	fStats.forEach((fStat, index) => {
+		if (fStat.mtimeMs > docStat.mtimeMs) {
+			const fPath = stagedFiles[index];
+			throw new Error(stripIndent`
+				--------------------------------------------------------------------------------
+				ERROR: at least one staged file: "${fPath}"
+				has a more recent modification timestamp than the documentation file:
+				"${docFile}"
+
+				This probably means that \`npm run build\` or \`npm test\` have not been executed,
+				and this error can be fixed by doing so. Running \`npm run build\` or \`npm test\`
+				before commiting is required in order to update the CLI markdown documentation
+				(in case any command-line options were updated, added or removed) and also to
+				catch Typescript type check errors sooner and reduce overall waiting time, given
+				that the CI build/tests are currently rather lengthy.
+
+				If you need/wish to bypass this check without running \`npm run build\`, run:
+				  npx touch -am "${docFile}"
+				and then try again.
+				--------------------------------------------------------------------------------
+			`);
+		}
+	});
+}
+
+async function run() {
+	try {
+		await checkBuildTimestamps();
+	} catch (err) {
+		console.error(err.message);
+		process.exitCode = 1;
+	}
+}
+
+run();

automation/check-npm-version.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Check that semver v1 is greater than or equal to semver v2.
+ *
+ * We don't `require('semver')` to allow this script to be run as a npm
+ * 'preinstall' hook, at which point no dependencies have been installed.
+ */
+function parseSemver(version) {
+	const match = /v?(\d+)\.(\d+).(\d+)/.exec(version);
+	if (match == null) {
+		throw new Error(`Invalid semver version: ${version}`);
+	}
+	const [, major, minor, patch] = match;
+	return [parseInt(major, 10), parseInt(minor, 10), parseInt(patch, 10)];
+}
+
+function semverGte(v1, v2) {
+	let v1Array = parseSemver(v1);
+	let v2Array = parseSemver(v2);
+	for (let i = 0; i < 3; i++) {
+		if (v1Array[i] < v2Array[i]) {
+			return false;
+		} else if (v1Array[i] > v2Array[i]) {
+			return true;
+		}
+	}
+	return true;
+}
+
+function checkNpmVersion() {
+	const execSync = require('child_process').execSync;
+	const npmVersion = execSync('npm --version').toString().trim();
+	const requiredVersion = '6.9.0';
+	if (!semverGte(npmVersion, requiredVersion)) {
+		// In case you take issue with the error message below:
+		//   "At this point, however, your 'npm-shrinkwrap.json' file has
+		//    already been damaged"
+		// ... and think: "why not add the check to the 'preinstall' hook?",
+		// the reason is that it would unnecessarily prevent end users from
+		// using npm v6.4.1 that ships with Node 8.  (It is OK for the
+		// shrinkwrap file to get damaged if it is not going to be reused.)
+		console.error(`\
+-------------------------------------------------------------------------------
+Error: npm version '${npmVersion}' detected. Please upgrade to npm v${requiredVersion} or later
+because of a bug that causes the 'npm-shrinkwrap.json' file to be damaged.
+At this point, however, your 'npm-shrinkwrap.json' file has already been
+damaged. Please revert it to the master branch state with a command such as:
+"git checkout master -- npm-shrinkwrap.json"
+Then re-run "npm install" using npm version ${requiredVersion} or later.
+-------------------------------------------------------------------------------`);
+		process.exit(1);
+	}
+}
+
+checkNpmVersion();

automation/custom-types.d.ts

@@ -1,38 +0,0 @@
-declare module 'pkg' {
-	export function exec(args: string[]): Promise<void>;
-}
-
-declare module 'filehound' {
-	export function create(): FileHound;
-
-	export interface FileHound {
-		paths(paths: string[]): FileHound;
-		paths(...paths: string[]): FileHound;
-		ext(extensions: string[]): FileHound;
-		ext(...extensions: string[]): FileHound;
-		find(): Promise<string[]>;
-	}
-}
-
-declare module 'publish-release' {
-	interface PublishOptions {
-		token: string;
-		owner: string;
-		repo: string;
-		tag: string;
-		name: string;
-		reuseRelease?: boolean;
-		assets: string[];
-	}
-
-	interface Release {
-		html_url: string;
-	}
-
-	let publishRelease: (
-		args: PublishOptions,
-		callback: (e: Error, release: Release) => void,
-	) => void;
-
-	export = publishRelease;
-}

automation/deploy-bin.ts

@@ -1,67 +1,252 @@
-import * as Promise from 'bluebird';
-import * as path from 'path';
-import * as os from 'os';
-import * as fs from 'fs-extra';
-import * as mkdirp from 'mkdirp';
-import * as publishRelease from 'publish-release';
-import * as archiver from 'archiver';
-import * as packageJSON from '../package.json';
+/**
+ * @license
+ * Copyright 2019 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 
-const publishReleaseAsync = Promise.promisify(publishRelease);
-const mkdirpAsync = Promise.promisify<string | null, string>(mkdirp);
+import * as Bluebird from 'bluebird';
+import * as _ from 'lodash';
+import * as semver from 'semver';
+
+import { finalReleaseAssets, version } from './build-bin';
 
 const { GITHUB_TOKEN } = process.env;
-const ROOT = path.join(__dirname, '..');
 
-const version = 'v' + packageJSON.version;
-const outputFile = path.join(
-	ROOT,
-	'build-zip',
-	`balena-cli-${version}-${os.platform()}-${os.arch()}.zip`,
-);
-
-mkdirpAsync(path.dirname(outputFile))
-	.then(
-		() =>
-			new Promise((resolve, reject) => {
-				console.log('Zipping build...');
-
-				let archive = archiver('zip', {
-					zlib: { level: 7 },
-				});
-				archive.directory(path.join(ROOT, 'build-bin'), 'balena-cli');
-
-				let outputStream = fs.createWriteStream(outputFile);
-
-				outputStream.on('close', resolve);
-				outputStream.on('error', reject);
-
-				archive.on('error', reject);
-				archive.on('warning', console.warn);
-
-				archive.pipe(outputStream);
-				archive.finalize();
-			}),
-	)
-	.then(() => {
-		console.log('Build zipped');
-		console.log('Publishing build...');
-
-		return publishReleaseAsync({
-			token: <string>GITHUB_TOKEN,
+/**
+ * Create or update a release in GitHub's releases page, uploading the
+ * installer files (standalone zip + native oclif installers).
+ */
+export async function createGitHubRelease() {
+	console.log(`Publishing release ${version} to GitHub`);
+	const publishRelease = await import('publish-release');
+	const ghRelease = await Bluebird.fromCallback(
+		publishRelease.bind(null, {
+			token: GITHUB_TOKEN || '',
 			owner: 'balena-io',
 			repo: 'balena-cli',
 			tag: version,
 			name: `balena-CLI ${version}`,
 			reuseRelease: true,
-			assets: [outputFile],
-		});
-	})
-	.then(release => {
-		console.log(`Release ${version} successful: ${release.html_url}`);
-	})
-	.catch(err => {
+			assets: finalReleaseAssets[process.platform],
+		}),
+	);
+	console.log(`Release ${version} successful: ${ghRelease.html_url}`);
+}
+
+/**
+ * Top-level function to create a CLI release in GitHub's releases page:
+ * call zipStandaloneInstaller(), rename the files as we'd like them to
+ * display on the releases page, and call createGitHubRelease() to upload
+ * the files.
+ */
+export async function release() {
+	try {
+		await createGitHubRelease();
+	} catch (err) {
 		console.error('Release failed');
 		console.error(err);
 		process.exit(1);
+	}
+}
+
+/** Return a cached Octokit instance, creating a new one as needed. */
+const getOctokit = _.once(function () {
+	const Octokit = (require('@octokit/rest') as typeof import('@octokit/rest')).Octokit.plugin(
+		(require('@octokit/plugin-throttling') as typeof import('@octokit/plugin-throttling'))
+			.throttling,
+	);
+	return new Octokit({
+		auth: GITHUB_TOKEN,
+		throttle: {
+			onRateLimit: (retryAfter: number, options: any) => {
+				console.warn(
+					`Request quota exhausted for request ${options.method} ${options.url}`,
+				);
+				// retries 3 times
+				if (options.request.retryCount < 3) {
+					console.log(`Retrying after ${retryAfter} seconds!`);
+					return true;
+				}
+			},
+			onAbuseLimit: (_retryAfter: number, options: any) => {
+				// does not retry, only logs a warning
+				console.warn(
+					`Abuse detected for request ${options.method} ${options.url}`,
+				);
+			},
+		},
 	});
+});
+
+/**
+ * Extract pagination information (current page, total pages, ordinal number)
+ * from the 'link' response header (example below), using the parse-link-header
+ * npm package:
+ * "link": "<https://api.github.com/repositories/187370853/releases?per_page=2&page=2>; rel=\"next\",
+ *          <https://api.github.com/repositories/187370853/releases?per_page=2&page=3>; rel=\"last\""
+ *
+ * @param response Octokit response object (including response.headers.link)
+ * @param perPageDefault Default per_page pagination value if missing in URL
+ * @return Object where 'page' is the current page number (1-based),
+ * 'pages' is the total number of pages, and 'ordinal' is the ordinal number
+ * (3rd, 4th, 5th...) of the first item in the current page.
+ */
+function getPageNumbers(
+	response: any,
+	perPageDefault: number,
+): { page: number; pages: number; ordinal: number } {
+	const res = { page: 1, pages: 1, ordinal: 1 };
+	if (!response.headers.link) {
+		return res;
+	}
+	const parse = require('parse-link-header') as typeof import('parse-link-header');
+	const parsed = parse(response.headers.link);
+	if (parsed == null) {
+		throw new Error(`Failed to parse link header: '${response.headers.link}'`);
+	}
+	let perPage = perPageDefault;
+	if (parsed.next) {
+		if (parsed.next.per_page) {
+			perPage = parseInt(parsed.next.per_page, 10);
+		}
+		res.page = parseInt(parsed.next.page, 10) - 1;
+		res.pages = parseInt(parsed.last.page, 10);
+	} else {
+		if (parsed.prev.per_page) {
+			perPage = parseInt(parsed.prev.per_page, 10);
+		}
+		res.page = res.pages = parseInt(parsed.prev.page, 10) + 1;
+	}
+	res.ordinal = (res.page - 1) * perPage + 1;
+	return res;
+}
+
+/**
+ * Iterate over every GitHub release in the given owner/repo, check whether
+ * its tag_name matches against the affectedVersions semver spec, and if so
+ * replace its release description (body) with the given newDescription value.
+ * @param owner GitHub repo owner, e.g. 'balena-io' or 'pdcastro'
+ * @param repo GitHub repo, e.g. 'balena-cli'
+ * @param affectedVersions Semver spec, e.g. '2.6.1 - 7.10.9 || 8.0.0'
+ * @param newDescription New release description (body)
+ * @param editID Short string present in newDescription, e.g. '[AA101]', that
+ * can be searched to determine whether that release has already been updated.
+ */
+async function updateGitHubReleaseDescriptions(
+	owner: string,
+	repo: string,
+	affectedVersions: string,
+	newDescription: string,
+	editID: string,
+) {
+	const perPage = 30;
+	const octokit = getOctokit();
+	const options = await octokit.repos.listReleases.endpoint.merge({
+		owner,
+		repo,
+		per_page: perPage,
+	});
+	let errCount = 0;
+	for await (const response of octokit.paginate.iterator(options)) {
+		const { page: thisPage, pages: totalPages, ordinal } = getPageNumbers(
+			response,
+			perPage,
+		);
+		let i = 0;
+		for (const cliRelease of response.data) {
+			const prefix = `[#${ordinal + i++} pg ${thisPage}/${totalPages}]`;
+			if (!cliRelease.id) {
+				console.error(
+					`${prefix} Error: missing release ID (errCount=${++errCount})`,
+				);
+				continue;
+			}
+			const skipMsg = `${prefix} skipping release "${cliRelease.tag_name}" (${cliRelease.id})`;
+			if (cliRelease.draft === true) {
+				console.info(`${skipMsg}: draft release`);
+				continue;
+			} else if (cliRelease.body && cliRelease.body.includes(editID)) {
+				console.info(`${skipMsg}: already updated`);
+				continue;
+			} else if (!semver.satisfies(cliRelease.tag_name, affectedVersions)) {
+				console.info(`${skipMsg}: outside version range`);
+				continue;
+			} else {
+				const updatedRelease = {
+					owner,
+					repo,
+					release_id: cliRelease.id,
+					body: newDescription,
+				};
+				let oldBodyPreview = cliRelease.body;
+				if (oldBodyPreview) {
+					oldBodyPreview = oldBodyPreview.replace(/\s+/g, ' ').trim();
+					if (oldBodyPreview.length > 12) {
+						oldBodyPreview = oldBodyPreview.substring(0, 9) + '...';
+					}
+				}
+				console.info(
+					`${prefix} updating release "${cliRelease.tag_name}" (${cliRelease.id}) old body="${oldBodyPreview}"`,
+				);
+				try {
+					await octokit.repos.updateRelease(updatedRelease);
+				} catch (err) {
+					console.error(
+						`${skipMsg}: Error: ${err.message} (count=${++errCount})`,
+					);
+					continue;
+				}
+			}
+		}
+	}
+}
+
+/**
+ * Add a warning description to CLI releases affected by a mixpanel tracking
+ * security issue (#1359). This function can be executed "manually" with the
+ * following command line:
+ *
+ * npx ts-node --type-check -P automation/tsconfig.json automation/run.ts fix1359
+ */
+export async function updateDescriptionOfReleasesAffectedByIssue1359() {
+	// Run only on Linux/Node10, instead of all platform/Node combinations.
+	// (It could have been any other platform, as long as it only runs once.)
+	if (process.platform !== 'linux' || semver.major(process.version) !== 10) {
+		return;
+	}
+	const owner = 'balena-io';
+	const repo = 'balena-cli';
+	const affectedVersions =
+		'2.6.1 - 7.10.9 || 8.0.0 - 8.1.0 || 9.0.0 - 9.15.6 || 10.0.0 - 10.17.5 || 11.0.0 - 11.7.2';
+	const editID = '[AA100]';
+	let newDescription = `
+		Please note: the "login" command in this release is affected by a
+		security issue fixed in versions
+		[7.10.10](https://github.com/balena-io/balena-cli/releases/tag/v7.10.10),
+		[8.1.1](https://github.com/balena-io/balena-cli/releases/tag/v8.1.1),
+		[9.15.7](https://github.com/balena-io/balena-cli/releases/tag/v9.15.7),
+		[10.17.6](https://github.com/balena-io/balena-cli/releases/tag/v10.17.6),
+		[11.7.3](https://github.com/balena-io/balena-cli/releases/tag/v11.7.3)
+		and later. If you need to use this version, avoid passing your password,
+		keys or tokens as command-line arguments. ${editID}`;
+	// remove line breaks and collapse white space
+	newDescription = newDescription.replace(/\s+/g, ' ').trim();
+	await updateGitHubReleaseDescriptions(
+		owner,
+		repo,
+		affectedVersions,
+		newDescription,
+		editID,
+	);
+}

automation/run.ts

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * Copyright 2019 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as _ from 'lodash';
+
+import {
+	buildOclifInstaller,
+	buildStandaloneZip,
+	catchUncommitted,
+	testShrinkwrap,
+} from './build-bin';
+import {
+	release,
+	updateDescriptionOfReleasesAffectedByIssue1359,
+} from './deploy-bin';
+import { fixPathForMsys, ROOT, runUnderMsys } from './utils';
+
+// DEBUG set to falsy for negative values else is truthy
+process.env.DEBUG = ['0', 'no', 'false', '', undefined].includes(
+	process.env.DEBUG?.toLowerCase(),
+)
+	? ''
+	: '1';
+
+function exitWithError(error: Error | string): never {
+	console.error(`Error: ${error}`);
+	process.exit(1);
+}
+
+/**
+ * Trivial command-line parser. Check whether the command-line argument is one
+ * of the following strings, then call the appropriate functions:
+ *     'build:installer'   (to build a native oclif installer)
+ * 	   'build:standalone'  (to build a standalone pkg package)
+ *     'release'           (to create/update a GitHub release)
+ *
+ * In the case of 'build:installer', also call runUnderMsys() to switch the
+ * shell from cmd.exe to MSYS2 bash.exe.
+ *
+ * @param args Arguments to parse (default is process.argv.slice(2))
+ */
+export async function run(args?: string[]) {
+	args = args || process.argv.slice(2);
+	console.log(`automation/run.ts process.argv=[${process.argv}]\n`);
+	console.log(`automation/run.ts args=[${args}]`);
+	if (_.isEmpty(args)) {
+		return exitWithError('missing command-line arguments');
+	}
+	const commands: { [cmd: string]: () => void | Promise<void> } = {
+		'build:installer': buildOclifInstaller,
+		'build:standalone': buildStandaloneZip,
+		'catch-uncommitted': catchUncommitted,
+		'test-shrinkwrap': testShrinkwrap,
+		fix1359: updateDescriptionOfReleasesAffectedByIssue1359,
+		release,
+	};
+	for (const arg of args) {
+		if (!commands.hasOwnProperty(arg)) {
+			return exitWithError(`command unknown: ${arg}`);
+		}
+	}
+
+	// If runUnderMsys() is called to re-execute this script under MSYS2,
+	// the current working dir becomes the MSYS2 homedir, so we change back.
+	process.chdir(ROOT);
+
+	// The BUILD_TMP env var is used as an alternative location for oclif
+	// (patched) to copy/extract the CLI files, run npm install and then
+	// create the NSIS executable installer for Windows. This was necessary
+	// to avoid issues with a 260-char limit on Windows paths (possibly a
+	// limitation of some library used by NSIS), as the "current working dir"
+	// provided by balena CI is a rather long path to start with.
+	if (process.platform === 'win32' && !process.env.BUILD_TMP) {
+		const randID = (await import('crypto'))
+			.randomBytes(6)
+			.toString('base64')
+			.replace(/\+/g, '-')
+			.replace(/\//g, '_'); // base64url (RFC 4648)
+		process.env.BUILD_TMP = `C:\\tmp\\${randID}`;
+	}
+
+	for (const arg of args) {
+		try {
+			if (arg === 'build:installer' && process.platform === 'win32') {
+				// ensure running under MSYS2
+				if (!process.env.MSYSTEM) {
+					process.env.MSYS2_PATH_TYPE = 'inherit';
+					await runUnderMsys([
+						fixPathForMsys(process.argv[0]),
+						fixPathForMsys(process.argv[1]),
+						arg,
+					]);
+					continue;
+				}
+				if (process.env.MSYS2_PATH_TYPE !== 'inherit') {
+					throw new Error(
+						'the MSYS2_PATH_TYPE env var must be set to "inherit"',
+					);
+				}
+			}
+			const cmdFunc = commands[arg];
+			await cmdFunc();
+		} catch (err) {
+			return exitWithError(`"${arg}": ${err}`);
+		}
+	}
+}
+
+run();

automation/test-lock-deduplicated.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+set -e
+
+cp npm-shrinkwrap.json npm-shrinkwrap.json.old
+npm i
+npm dedupe
+npm i
+
+if ! diff -q npm-shrinkwrap.json npm-shrinkwrap.json.old > /dev/null; then
+  rm npm-shrinkwrap.json.old
+  echo "** npm-shrinkwrap.json was not deduplicated or not fully committed - FAIL **";
+  echo "** Please run 'npm ci', followed by 'npm dedupe' **";
+  exit 1;
+fi
+
+rm npm-shrinkwrap.json.old

automation/tsconfig.json

@@ -1,16 +0,0 @@
-{
-	"compilerOptions": {
-		"module": "commonjs",
-		"target": "es2015",
-		"strict": true,
-		"noUnusedLocals": true,
-		"noUnusedParameters": true,
-		"preserveConstEnums": true,
-		"removeComments": true,
-		"sourceMap": true
-	},
-	"include": [
-		"./**/*.ts",
-		"../typings/*.d.ts"
-	]
-}

automation/update-module.ts

@@ -0,0 +1,140 @@
+import { exec } from 'child_process';
+import * as semver from 'semver';
+
+const changeTypes = ['major', 'minor', 'patch'] as const;
+
+const validateChangeType = (maybeChangeType: string = 'minor') => {
+	maybeChangeType = maybeChangeType.toLowerCase();
+	switch (maybeChangeType) {
+		case 'patch':
+		case 'minor':
+		case 'major':
+			return maybeChangeType;
+		default:
+			console.error(`Invalid change type: '${maybeChangeType}'`);
+			return process.exit(1);
+	}
+};
+
+const compareSemverChangeType = (oldVersion: string, newVersion: string) => {
+	const oldSemver = semver.parse(oldVersion)!;
+	const newSemver = semver.parse(newVersion)!;
+
+	for (const changeType of changeTypes) {
+		if (oldSemver[changeType] !== newSemver[changeType]) {
+			return changeType;
+		}
+	}
+};
+
+const run = async (cmd: string) => {
+	console.info(`Running '${cmd}'`);
+	return new Promise<{ stdout: string; stderr: string }>((resolve, reject) => {
+		const p = exec(cmd, { encoding: 'utf8' }, (err, stdout, stderr) => {
+			if (err) {
+				reject(err);
+				return;
+			}
+			resolve({ stdout, stderr });
+		});
+		p.stdout.pipe(process.stdout);
+		p.stderr.pipe(process.stderr);
+	});
+};
+
+const getVersion = async (module: string): Promise<string> => {
+	const { stdout } = await run(`npm ls --json --depth 0 ${module}`);
+	return JSON.parse(stdout).dependencies[module].version;
+};
+
+interface Upstream {
+	repo: string;
+	url: string;
+	module?: string;
+}
+
+const getUpstreams = async () => {
+	const fs = await import('fs');
+	const repoYaml = fs.readFileSync(__dirname + '/../repo.yml', 'utf8');
+
+	const yaml = await import('js-yaml');
+	const { upstream } = yaml.safeLoad(repoYaml) as {
+		upstream: Upstream[];
+	};
+
+	return upstream;
+};
+
+const printUsage = (upstreams: Upstream[], upstreamName: string) => {
+	console.error(
+		`
+Usage: npm run update ${upstreamName} $version [$changeType=minor]
+
+Upstream names: ${upstreams.map(({ repo }) => repo).join(', ')}
+`,
+	);
+	return process.exit(1);
+};
+
+// TODO: Drop the wrapper function once we move to TS 3.8,
+// which will support top level await.
+async function main() {
+	const upstreams = await getUpstreams();
+
+	if (process.argv.length < 3) {
+		return printUsage(upstreams, '$upstreamName');
+	}
+
+	const upstreamName = process.argv[2];
+
+	const upstream = upstreams.find((v) => v.repo === upstreamName);
+
+	if (!upstream) {
+		console.error(
+			`Invalid upstream name '${upstreamName}', valid options: ${upstreams
+				.map(({ repo }) => repo)
+				.join(', ')}`,
+		);
+		return process.exit(1);
+	}
+
+	if (process.argv.length < 4) {
+		printUsage(upstreams, upstreamName);
+	}
+
+	const packageName = upstream.module || upstream.repo;
+
+	const oldVersion = await getVersion(packageName);
+	await run(`npm install ${packageName}@${process.argv[3]}`);
+	const newVersion = await getVersion(packageName);
+	if (newVersion === oldVersion) {
+		console.error(`Already on version '${newVersion}'`);
+		return process.exit(1);
+	}
+
+	console.log(`Updated ${upstreamName} from ${oldVersion} to ${newVersion}`);
+	const semverChangeType = compareSemverChangeType(oldVersion, newVersion);
+
+	const changeType = process.argv[4]
+		? // if the caller specified a change type, use that one
+		  validateChangeType(process.argv[4])
+		: // use the same change type as in the dependency, but avoid major bumps
+		semverChangeType && semverChangeType !== 'major'
+		? semverChangeType
+		: 'minor';
+	console.log(`Using Change-type: ${changeType}`);
+
+	let { stdout: currentBranch } = await run('git rev-parse --abbrev-ref HEAD');
+	currentBranch = currentBranch.trim();
+	console.log(`Currenty on branch: '${currentBranch}'`);
+	if (currentBranch === 'master') {
+		await run(`git checkout -b "update-${upstreamName}-${newVersion}"`);
+	}
+
+	await run(`git add package.json npm-shrinkwrap.json`);
+	await run(
+		`git commit --message "Update ${upstreamName} to ${newVersion}" --message "Update ${upstreamName} from ${oldVersion} to ${newVersion}" --message "Change-type: ${changeType}"`,
+	);
+}
+
+main();

automation/utils.ts

@@ -0,0 +1,237 @@
+/**
+ * @license
+ * Copyright 2019-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { spawn } from 'child_process';
+import * as _ from 'lodash';
+import * as path from 'path';
+import * as shellEscape from 'shell-escape';
+
+export const MSYS2_BASH = 'C:\\msys64\\usr\\bin\\bash.exe';
+export const ROOT = path.join(__dirname, '..');
+
+/** Tap and buffer this process' stdout and stderr */
+export class StdOutTap {
+	public stdoutBuf: string[] = [];
+	public stderrBuf: string[] = [];
+	public allBuf: string[] = []; // both stdout and stderr
+
+	protected origStdoutWrite: typeof process.stdout.write;
+	protected origStderrWrite: typeof process.stdout.write;
+
+	constructor(protected printDots = false) {}
+
+	tap() {
+		this.origStdoutWrite = process.stdout.write;
+		this.origStderrWrite = process.stderr.write;
+
+		process.stdout.write = (chunk: string, ...args: any[]): boolean => {
+			this.stdoutBuf.push(chunk);
+			this.allBuf.push(chunk);
+			const str = this.printDots ? '.' : chunk;
+			return this.origStdoutWrite.call(process.stdout, str, ...args);
+		};
+
+		process.stderr.write = (chunk: string, ...args: any[]): boolean => {
+			this.stderrBuf.push(chunk);
+			this.allBuf.push(chunk);
+			const str = this.printDots ? '.' : chunk;
+			return this.origStderrWrite.call(process.stderr, str, ...args);
+		};
+	}
+
+	untap() {
+		process.stdout.write = this.origStdoutWrite;
+		process.stderr.write = this.origStderrWrite;
+		if (this.printDots) {
+			console.error('');
+		}
+	}
+}
+
+/**
+ * Diff strings by line, using the 'diff' npm package:
+ * https://www.npmjs.com/package/diff
+ */
+export function diffLines(str1: string, str2: string): string {
+	const { diffTrimmedLines } = require('diff');
+	const diffObjs = diffTrimmedLines(str1, str2);
+	const prefix = (chunk: string, char: string) =>
+		chunk
+			.split('\n')
+			.map((line: string) => `${char} ${line}`)
+			.join('\n');
+	const diffStr = diffObjs
+		.map((part: any) => {
+			return part.added
+				? prefix(part.value, '+')
+				: part.removed
+				? prefix(part.value, '-')
+				: prefix(part.value, ' ');
+		})
+		.join('\n');
+	return diffStr;
+}
+
+export function loadPackageJson() {
+	return require(path.join(ROOT, 'package.json'));
+}
+
+/**
+ * Convert e.g. 'C:\myfolder' -> '/C/myfolder' so that the path can be given
+ * as argument to "unix tools" like 'tar' under MSYS or MSYS2 on Windows.
+ */
+export function fixPathForMsys(p: string): string {
+	return p.replace(/\\/g, '/').replace(/^([a-zA-Z]):/, '/$1');
+}
+
+/**
+ * Run the MSYS2 bash.exe shell in a child process (child_process.spawn()).
+ * The given argv arguments are escaped using the 'shell-escape' package,
+ * so that backslashes in Windows paths, and other bash-special characters,
+ * are preserved. If argv is not provided, defaults to process.argv, to the
+ * effect that this current (parent) process is re-executed under MSYS2 bash.
+ * This is useful to change the default shell from cmd.exe to MSYS2 bash on
+ * Windows.
+ * @param argv Arguments to be shell-escaped and given to MSYS2 bash.exe.
+ */
+export async function runUnderMsys(argv?: string[]) {
+	const newArgv = argv || process.argv;
+	await new Promise((resolve, reject) => {
+		const args = ['-lc', shellEscape(newArgv)];
+		const child = spawn(MSYS2_BASH, args, { stdio: 'inherit' });
+		child.on('close', (code) => {
+			if (code) {
+				console.log(`runUnderMsys: child process exited with code ${code}`);
+				reject(code);
+			} else {
+				resolve();
+			}
+		});
+	});
+}
+
+/**
+ * Run the executable at execPath as a child process, and resolve a promise
+ * to the executable's stdout output as a string. Reject the promise if
+ * anything is printed to stderr, or if the child process exits with a
+ * non-zero exit code.
+ * @param execPath Executable path
+ * @param args Command-line argument for the executable
+ */
+export async function getSubprocessStdout(
+	execPath: string,
+	args: string[],
+): Promise<string> {
+	const child = spawn(execPath, args);
+	return new Promise((resolve, reject) => {
+		let stdout = '';
+		child.stdout.on('error', reject);
+		child.stderr.on('error', reject);
+		child.stdout.on('data', (data: Buffer) => {
+			try {
+				stdout = data.toString();
+			} catch (err) {
+				reject(err);
+			}
+		});
+		child.stderr.on('data', (data: Buffer) => {
+			try {
+				const stderr = data.toString();
+
+				// ignore any debug lines, but ensure that we parse
+				// every line provided to the stderr stream
+				const lines = _.filter(
+					stderr.trim().split(/\r?\n/),
+					(line) => !line.startsWith('[debug]'),
+				);
+				if (lines.length > 0) {
+					reject(
+						new Error(`"${execPath}": non-empty stderr "${lines.join('\n')}"`),
+					);
+				}
+			} catch (err) {
+				reject(err);
+			}
+		});
+		child.on('exit', (code: number) => {
+			if (code) {
+				reject(new Error(`"${execPath}": non-zero exit code "${code}"`));
+			} else {
+				resolve(stdout);
+			}
+		});
+	});
+}
+
+/**
+ * Error handling wrapper around the npm `which` package:
+ * "Like the unix which utility. Finds the first instance of a specified
+ * executable in the PATH environment variable. Does not cache the results,
+ * so hash -r is not needed when the PATH changes."
+ *
+ * @param program Basename of a program, for example 'ssh'
+ * @returns The program's full path, e.g. 'C:\WINDOWS\System32\OpenSSH\ssh.EXE'
+ */
+export async function which(program: string): Promise<string> {
+	const whichMod = await import('which');
+	let programPath: string;
+	try {
+		programPath = await whichMod(program);
+	} catch (err) {
+		if (err.code === 'ENOENT') {
+			throw new Error(`'${program}' program not found. Is it installed?`);
+		}
+		throw err;
+	}
+	return programPath;
+}
+
+/**
+ * Call which(programName) and spawn() with the given arguments. Throw an error
+ * if the process exit code is not zero.
+ */
+export async function whichSpawn(
+	programName: string,
+	args?: string[],
+): Promise<void> {
+	const program = await which(programName);
+	let error: Error | undefined;
+	let exitCode: number | undefined;
+	try {
+		exitCode = await new Promise<number>((resolve, reject) => {
+			try {
+				spawn(program, args, { stdio: 'inherit' })
+					.on('error', reject)
+					.on('close', resolve);
+			} catch (err) {
+				reject(err);
+			}
+		});
+	} catch (err) {
+		error = err;
+	}
+	if (error || exitCode) {
+		const msg = [
+			`${programName} failed with exit code ${exitCode}:`,
+			`"${program}" [${args}]`,
+		];
+		if (error) {
+			msg.push(`${error}`);
+		}
+		throw new Error(msg.join('\n'));
+	}
+}

balena-completion.bash

@@ -7,7 +7,7 @@ _balena_complete()
   # Valid top-level completions
   commands="app apps build config deploy device devices env envs help key \
             keys local login logout logs note os preload quickstart settings \
-            signup ssh sync util version whoami"
+            scan ssh util version whoami"
   # Sub-completions
   app_cmds="create restart rm"
   config_cmds="generate inject read reconfigure write"
@@ -16,7 +16,7 @@ _balena_complete()
   device_public_url_cmds="disable enable status"
   env_cmds="add rename rm"
   key_cmds="add rm"
-  local_cmds="configure flash logs push scan ssh stop"
+  local_cmds="configure flash"
   os_cmds="build-config configure download initialize versions"
   util_cmds="available-drives"
 

bin/balena

@@ -1,7 +1,22 @@
 #!/usr/bin/env node
 
+// tslint:disable:no-var-requires
+
 // We boost the threadpool size as ext2fs can deadlock with some
 // operations otherwise, if the pool runs out.
 process.env.UV_THREADPOOL_SIZE = '64';
 
-require('../build/app');
+// Disable oclif registering ts-node
+process.env.OCLIF_TS_NODE = 0;
+
+// Use fast-boot to cache require lookups, speeding up startup
+require('fast-boot2').start({
+	cacheScope: __dirname + '/..',
+	cacheFile: __dirname + '/.fast-boot.json',
+});
+
+// Set the desired es version for downstream modules that support it
+require('@balena/es-version').set('es2018');
+
+// Run the CLI
+require('../build/app').run();

bin/balena-dev

@@ -1,15 +1,74 @@
 #!/usr/bin/env node
 
 // ****************************************************************************
-// THIS IS FOR DEV PERROSES ONLY AND WILL NOT BE PART OF THE PUBLISHED PACKAGE
+// THIS IS FOR DEV PURPOSES ONLY AND WILL NOT BE PART OF THE PUBLISHED PACKAGE
 // Before opening a PR you should build and test your changes using bin/balena
 // ****************************************************************************
 
+// tslint:disable:no-var-requires
+
 // We boost the threadpool size as ext2fs can deadlock with some
 // operations otherwise, if the pool runs out.
 process.env.UV_THREADPOOL_SIZE = '64';
 
-process.env['TS_NODE_PROJECT'] = require('path').dirname(__dirname);
-require('coffeescript/register');
-require('ts-node/register');
-require('../lib/app');
+const path = require('path');
+const rootDir = path.join(__dirname, '..');
+
+// Allow balena-dev to work with oclif by temporarily
+// pointing oclif config options to lib/ instead of build/
+modifyOclifPaths();
+// Undo changes on exit
+process.on('exit', function () {
+	modifyOclifPaths(true);
+});
+// Undo changes in case of ctrl-v
+process.on('SIGINT', function () {
+	modifyOclifPaths(true);
+});
+
+// Use fast-boot to cache require lookups, speeding up startup
+require('fast-boot2').start({
+	cacheScope: __dirname + '/..',
+	cacheFile: '.fast-boot.json',
+});
+
+// Set the desired es version for downstream modules that support it
+require('@balena/es-version').set('es2018');
+
+// Note: before ts-node v6.0.0, 'transpile-only' (no type checking) was the
+// default option. We upgraded ts-node and found that adding 'transpile-only'
+// was necessary to avoid a mysterious 'null' error message. On the plus side,
+// it is supposed to run faster. We still benefit from type checking when
+// running 'npm run build'.
+require('ts-node').register({
+	project: path.join(rootDir, 'tsconfig.json'),
+	transpileOnly: true,
+});
+require('../lib/app').run();
+
+// Modify package.json oclif paths from build/ -> lib/, or vice versa
+function modifyOclifPaths(revert) {
+	const fs = require('fs');
+	const packageJsonPath = path.join(rootDir, 'package.json');
+
+	const packageJson = fs.readFileSync(packageJsonPath, 'utf8');
+	const packageObj = JSON.parse(packageJson);
+
+	if (!packageObj.oclif) {
+		return;
+	}
+
+	let oclifSectionText = JSON.stringify(packageObj.oclif);
+	if (!revert) {
+		oclifSectionText = oclifSectionText.replace(/\/build\//g, '/lib/');
+	} else {
+		oclifSectionText = oclifSectionText.replace(/\/lib\//g, '/build/');
+	}
+
+	packageObj.oclif = JSON.parse(oclifSectionText);
+	fs.writeFileSync(
+		packageJsonPath,
+		`${JSON.stringify(packageObj, null, 2)}\n`,
+		'utf8',
+	);
+}

capitanodoc.ts

@@ -1,155 +0,0 @@
-export = {
-	title: 'Balena CLI Documentation',
-	introduction: `\
-This tool allows you to interact with the balena api from the comfort of your command line.
-
-Please make sure your system meets the requirements as specified in the [README](https://github.com/balena-io/balena-cli).
-
-## Install the CLI
-
-### Npm install
-
-The best supported way to install the CLI is from npm:
-
-	$ npm install balena-cli -g --production --unsafe-perm
-
-\`--unsafe-perm\` is only required on systems where the global install directory is not user-writable.
-This allows npm install steps to download and save prebuilt native binaries. You may be able to omit it,
-especially if you're using a user-managed node install such as [nvm](https://github.com/creationix/nvm).
-
-### Standalone install
-
-Alternatively, if you don't have a node or pre-gyp environment, you can still install the CLI as a standalone
-binary. **This is in experimental and may not work perfectly yet in all environments**, but works well in
-initial cross-platform testing, so it may be useful, and we'd love your feedback if you hit any issues.
-
-To install the CLI as a standalone binary:
-
-* Download the latest zip for your OS from https://github.com/balena-io/balena-cli/releases.
-* Extract the contents, putting the \`balena-cli\` folder somewhere appropriate for your system (e.g. \`C:/balena-cli\`, \`/usr/local/lib/balena-cli\`, etc).
-* Add the \`balena-cli\` folder to your \`PATH\`. (
-[Windows instructions](https://www.computerhope.com/issues/ch000549.htm),
-[Linux instructions](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix),
-[OSX instructions](https://stackoverflow.com/questions/22465332/setting-path-environment-variable-in-osx-permanently))
-* Running \`balena\` in a fresh command line should print the balena CLI help.
-
-To update in future, simply download a new release and replace the extracted folder.
-
-Have any problems, or see any unexpected behaviour? Please file an issue!
-
-## Getting started
-
-Once you have the CLI installed, you'll need to log in, so it can access everything in your balena account.
-
-To authenticate yourself, run:
-
-	$ balena login
-
-You now have access to all the commands referenced below.
-
-## Proxy support
-
-The CLI does support HTTP(S) proxies.
-
-You can configure the proxy using several methods (in order of their precedence):
-
-* set the \`BALENARC_PROXY\` environment variable in the URL format (with protocol, host, port, and optionally the basic auth),
-* use the [balena config file](https://www.npmjs.com/package/balena-settings-client#documentation) (project-specific or user-level)
-and set the \`proxy\` setting. This can be:
-	* a string in the URL format,
-	* or an object following [this format](https://www.npmjs.com/package/global-tunnel-ng#options), which allows more control,
-* or set the conventional \`https_proxy\` / \`HTTPS_PROXY\` / \`http_proxy\` / \`HTTP_PROXY\`
-environment variable (in the same standard URL format).\
-`,
-
-	categories: [
-		{
-			title: 'Api keys',
-			files: ['build/actions/api-key.js'],
-		},
-		{
-			title: 'Application',
-			files: ['build/actions/app.js'],
-		},
-		{
-			title: 'Authentication',
-			files: ['build/actions/auth.js'],
-		},
-		{
-			title: 'Device',
-			files: ['build/actions/device.js'],
-		},
-		{
-			title: 'Environment Variables',
-			files: ['build/actions/environment-variables.js'],
-		},
-		{
-			title: 'Help',
-			files: ['build/actions/help.js'],
-		},
-		{
-			title: 'Information',
-			files: ['build/actions/info.js'],
-		},
-		{
-			title: 'Keys',
-			files: ['build/actions/keys.js'],
-		},
-		{
-			title: 'Logs',
-			files: ['build/actions/logs.js'],
-		},
-		{
-			title: 'Sync',
-			files: ['build/actions/sync.js'],
-		},
-		{
-			title: 'SSH',
-			files: ['build/actions/ssh.js'],
-		},
-		{
-			title: 'Notes',
-			files: ['build/actions/notes.js'],
-		},
-		{
-			title: 'OS',
-			files: ['build/actions/os.js'],
-		},
-		{
-			title: 'Config',
-			files: ['build/actions/config.js'],
-		},
-		{
-			title: 'Preload',
-			files: ['build/actions/preload.js'],
-		},
-		{
-			title: 'Push',
-			files: ['build/actions/push.js'],
-		},
-		{
-			title: 'Settings',
-			files: ['build/actions/settings.js'],
-		},
-		{
-			title: 'Wizard',
-			files: ['build/actions/wizard.js'],
-		},
-		{
-			title: 'Local',
-			files: ['build/actions/local/index.js'],
-		},
-		{
-			title: 'Deploy',
-			files: ['build/actions/build.js', 'build/actions/deploy.js'],
-		},
-		{
-			title: 'Platform',
-			files: ['build/actions/join.js', 'build/actions/leave.js'],
-		},
-		{
-			title: 'Utilities',
-			files: ['build/actions/util.js'],
-		},
-	],
-};

coffeelint.json

@@ -1,127 +0,0 @@
-{
-    "coffeescript_error": {
-        "level": "error"
-    },
-    "arrow_spacing": {
-        "name": "arrow_spacing",
-        "level": "error"
-    },
-    "no_tabs": {
-        "name": "no_tabs",
-        "level": "ignore"
-    },
-    "no_trailing_whitespace": {
-        "name": "no_trailing_whitespace",
-        "level": "error",
-        "allowed_in_comments": false,
-        "allowed_in_empty_lines": false
-    },
-    "max_line_length": {
-        "name": "max_line_length",
-        "value": 120,
-        "level": "error",
-        "limitComments": true
-    },
-    "line_endings": {
-        "name": "line_endings",
-        "level": "ignore",
-        "value": "unix"
-    },
-    "no_trailing_semicolons": {
-        "name": "no_trailing_semicolons",
-        "level": "error"
-    },
-    "indentation": {
-        "name": "indentation",
-        "value": 1,
-        "level": "error"
-    },
-    "camel_case_classes": {
-        "name": "camel_case_classes",
-        "level": "error"
-    },
-    "colon_assignment_spacing": {
-        "name": "colon_assignment_spacing",
-        "level": "error",
-        "spacing": {
-            "left": 0,
-            "right": 1
-        }
-    },
-    "no_implicit_braces": {
-        "name": "no_implicit_braces",
-        "level": "ignore",
-        "strict": false
-    },
-    "no_plusplus": {
-        "name": "no_plusplus",
-        "level": "ignore"
-    },
-    "no_throwing_strings": {
-        "name": "no_throwing_strings",
-        "level": "error"
-    },
-    "no_backticks": {
-        "name": "no_backticks",
-        "level": "error"
-    },
-    "no_implicit_parens": {
-        "name": "no_implicit_parens",
-        "strict": false,
-        "level": "ignore"
-    },
-    "no_empty_param_list": {
-        "name": "no_empty_param_list",
-        "level": "error"
-    },
-    "no_stand_alone_at": {
-        "name": "no_stand_alone_at",
-        "level": "ignore"
-    },
-    "space_operators": {
-        "name": "space_operators",
-        "level": "error"
-    },
-    "duplicate_key": {
-        "name": "duplicate_key",
-        "level": "error"
-    },
-    "empty_constructor_needs_parens": {
-        "name": "empty_constructor_needs_parens",
-        "level": "ignore"
-    },
-    "cyclomatic_complexity": {
-        "name": "cyclomatic_complexity",
-        "value": 10,
-        "level": "ignore"
-    },
-    "newlines_after_classes": {
-        "name": "newlines_after_classes",
-        "value": 3,
-        "level": "ignore"
-    },
-    "no_unnecessary_fat_arrows": {
-        "name": "no_unnecessary_fat_arrows",
-        "level": "error"
-    },
-    "missing_fat_arrows": {
-        "name": "missing_fat_arrows",
-        "level": "ignore"
-    },
-    "non_empty_constructor_needs_parens": {
-        "name": "non_empty_constructor_needs_parens",
-        "level": "ignore"
-    },
-    "no_unnecessary_double_quotes": {
-        "name": "no_unnecessary_double_quotes",
-        "level": "error"
-    },
-    "no_debugger": {
-        "name": "no_debugger",
-        "level": "warn"
-    },
-    "no_interpolation_in_single_quotes": {
-        "name": "no_interpolation_in_single_quotes",
-        "level": "error"
-    }
-}

gulpfile.coffee

@@ -1,40 +0,0 @@
-path = require('path')
-gulp = require('gulp')
-coffee = require('gulp-coffee')
-inlinesource = require('gulp-inline-source')
-mocha = require('gulp-mocha')
-shell = require('gulp-shell')
-packageJSON = require('./package.json')
-
-OPTIONS =
-	files:
-		coffee: [ 'lib/**/*.coffee', 'gulpfile.coffee' ]
-		app: 'lib/**/*.coffee'
-		tests: 'tests/**/*.spec.coffee'
-		pages: 'lib/auth/pages/*.ejs'
-	directories:
-		build: 'build/'
-
-gulp.task 'pages', ->
-	gulp.src(OPTIONS.files.pages)
-		.pipe(inlinesource())
-		.pipe(gulp.dest('build/auth/pages'))
-
-gulp.task 'coffee', ->
-	gulp.src(OPTIONS.files.app)
-		.pipe(coffee(bare: true, header: true))
-		.pipe(gulp.dest(OPTIONS.directories.build))
-
-gulp.task 'test', ->
-	gulp.src(OPTIONS.files.tests, read: false)
-		.pipe(mocha({
-			reporter: 'spec'
-		}))
-
-gulp.task 'build', [
-	'coffee',
-	'pages'
-]
-
-gulp.task 'watch', [ 'build' ], ->
-	gulp.watch([ OPTIONS.files.coffee ], [ 'build' ])

gulpfile.js

@@ -0,0 +1,15 @@
+const gulp = require('gulp');
+const inlinesource = require('gulp-inline-source');
+
+const OPTIONS = {
+	files: {
+		pages: 'lib/auth/pages/*.ejs',
+	},
+};
+
+gulp.task('pages', () =>
+	gulp
+		.src(OPTIONS.files.pages)
+		.pipe(inlinesource())
+		.pipe(gulp.dest('build/auth/pages')),
+);

lib/actions/api-key.ts

@@ -1,36 +0,0 @@
-import { CommandDefinition } from 'capitano';
-import { stripIndent } from 'common-tags';
-
-export const generate: CommandDefinition<{
-	name: string;
-}> = {
-	signature: 'api-key generate <name>',
-	description: 'Generate a new API key with the given name',
-	help: stripIndent`
-		This command generates a new API key for the current user, with the given
-		name. The key will be logged to the console.
-
-		This key can be used to log into the CLI using 'balena login --token <key>',
-		or to authenticate requests to the API with an 'Authorization: Bearer <key>' header.
-
-		Examples:
-
-			$ balena api-key generate "Jenkins Key"
-	`,
-	async action(params, _options, done) {
-		const balena = (await import('balena-sdk')).fromSharedOptions();
-
-		balena.models.apiKey
-			.create(params.name)
-			.then(key => {
-				console.log(stripIndent`
-					Registered api key '${params.name}':
-
-					${key}
-
-					This key will not be shown again, so please save it now.
-				`);
-			})
-			.finally(done);
-	},
-};

lib/actions/app.coffee

@@ -1,161 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-commandOptions = require('./command-options')
-
-exports.create =
-	signature: 'app create <name>'
-	description: 'create an application'
-	help: '''
-		Use this command to create a new balena application.
-
-		You can specify the application device type with the `--type` option.
-		Otherwise, an interactive dropdown will be shown for you to select from.
-
-		You can see a list of supported device types with
-
-			$ balena devices supported
-
-		Examples:
-
-			$ balena app create MyApp
-			$ balena app create MyApp --type raspberry-pi
-	'''
-	options: [
-		{
-			signature: 'type'
-			parameter: 'type'
-			description: 'application device type (Check available types with `balena devices supported`)'
-			alias: 't'
-		}
-	]
-	permission: 'user'
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-
-		patterns = require('../utils/patterns')
-
-		# Validate the the application name is available
-		# before asking the device type.
-		# https://github.com/balena-io/balena-cli/issues/30
-		balena.models.application.has(params.name).then (hasApplication) ->
-			if hasApplication
-				patterns.exitWithExpectedError('You already have an application with that name!')
-
-		.then ->
-			return options.type or patterns.selectDeviceType()
-		.then (deviceType) ->
-			return balena.models.application.create({
-				name: params.name
-				deviceType
-			})
-		.then (application) ->
-			console.info("Application created: #{application.app_name} (#{application.device_type}, id #{application.id})")
-		.nodeify(done)
-
-exports.list =
-	signature: 'apps'
-	description: 'list all applications'
-	help: '''
-		Use this command to list all your applications.
-
-		Notice this command only shows the most important bits of information for each app.
-		If you want detailed information, use balena app <name> instead.
-
-		Examples:
-
-			$ balena apps
-	'''
-	permission: 'user'
-	primary: true
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		visuals = require('resin-cli-visuals')
-
-		balena.models.application.getAll().then (applications) ->
-			console.log visuals.table.horizontal applications, [
-				'id'
-				'app_name'
-				'device_type'
-				'online_devices'
-				'devices_length'
-			]
-		.nodeify(done)
-
-exports.info =
-	signature: 'app <name>'
-	description: 'list a single application'
-	help: '''
-		Use this command to show detailed information for a single application.
-
-		Examples:
-
-			$ balena app MyApp
-	'''
-	permission: 'user'
-	primary: true
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		visuals = require('resin-cli-visuals')
-
-		balena.models.application.get(params.name).then (application) ->
-			console.log visuals.table.vertical application, [
-				"$#{application.app_name}$"
-				'id'
-				'device_type'
-				'git_repository'
-				'commit'
-			]
-		.nodeify(done)
-
-exports.restart =
-	signature: 'app restart <name>'
-	description: 'restart an application'
-	help: '''
-		Use this command to restart all devices that belongs to a certain application.
-
-		Examples:
-
-			$ balena app restart MyApp
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		balena.models.application.restart(params.name).nodeify(done)
-
-exports.remove =
-	signature: 'app rm <name>'
-	description: 'remove an application'
-	help: '''
-		Use this command to remove a balena application.
-
-		Notice this command asks for confirmation interactively.
-		You can avoid this by passing the `--yes` boolean option.
-
-		Examples:
-
-			$ balena app rm MyApp
-			$ balena app rm MyApp --yes
-	'''
-	options: [ commandOptions.yes ]
-	permission: 'user'
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		patterns = require('../utils/patterns')
-
-		patterns.confirm(options.yes, 'Are you sure you want to delete the application?').then ->
-			balena.models.application.remove(params.name)
-		.nodeify(done)

lib/actions/auth.coffee

@@ -1,210 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-exports.login	=
-	signature: 'login'
-	description: 'login to balena'
-	help: '''
-		Use this command to login to your balena account.
-
-		This command will prompt you to login using the following login types:
-
-		- Web authorization: open your web browser and prompt you to authorize the CLI
-		from the dashboard.
-
-		- Credentials: using email/password and 2FA.
-
-		- Token: using a session token or API key from the preferences page.
-
-		Examples:
-
-			$ balena login
-			$ balena login --web
-			$ balena login --token "..."
-			$ balena login --credentials
-			$ balena login --credentials --email johndoe@gmail.com --password secret
-	'''
-	options: [
-		{
-			signature: 'token'
-			description: 'session token or API key'
-			parameter: 'token'
-			alias: 't'
-		}
-		{
-			signature: 'web'
-			description: 'web-based login'
-			boolean: true
-			alias: 'w'
-		}
-		{
-			signature: 'credentials'
-			description: 'credential-based login'
-			boolean: true
-			alias: 'c'
-		}
-		{
- 			signature: 'email'
- 			parameter: 'email'
- 			description: 'email'
- 			alias: [ 'e', 'u' ]
- 		}
- 		{
- 			signature: 'password'
- 			parameter: 'password'
- 			description: 'password'
- 			alias: 'p'
- 		}
-	]
-	primary: true
-	action: (params, options, done) ->
-		_ = require('lodash')
-		Promise = require('bluebird')
-		balena = require('balena-sdk').fromSharedOptions()
-		auth = require('../auth')
-		form = require('resin-cli-form')
-		patterns = require('../utils/patterns')
-		messages = require('../utils/messages')
-
-		login = (options) ->
-			if options.token?
-				return Promise.try ->
-					return options.token if _.isString(options.token)
-					return form.ask
-						message: 'Session token or API key from the preferences page'
-						name: 'token'
-						type: 'input'
-				.then(balena.auth.loginWithToken)
-				.tap ->
-					balena.auth.whoami()
-					.then (username) ->
-						if !username
-							patterns.exitWithExpectedError('Token authentication failed')
-			else if options.credentials
-				return patterns.authenticate(options)
-			else if options.web
-				console.info('Connecting to the web dashboard')
-				return auth.login()
-
-			return patterns.askLoginType().then (loginType) ->
-
-				if loginType is 'register'
-					{ runCommand } = require('../utils/helpers')
-					return runCommand('signup')
-
-				options[loginType] = true
-				return login(options)
-
-		balena.settings.get('balenaUrl').then (balenaUrl) ->
-			console.log(messages.balenaAsciiArt)
-			console.log("\nLogging in to #{balenaUrl}")
-			return login(options)
-		.then(balena.auth.whoami)
-		.tap (username) ->
-			console.info("Successfully logged in as: #{username}")
-			console.info """
-
-				Find out about the available commands by running:
-
-				  $ balena help
-
-				#{messages.reachingOut}
-			"""
-		.nodeify(done)
-
-exports.logout =
-	signature: 'logout'
-	description: 'logout from balena'
-	help: '''
-		Use this command to logout from your balena account.o
-
-		Examples:
-
-			$ balena logout
-	'''
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		balena.auth.logout().nodeify(done)
-
-exports.signup =
-	signature: 'signup'
-	description: 'signup to balena'
-	help: '''
-		Use this command to signup for a balena account.
-
-		If signup is successful, you'll be logged in to your new user automatically.
-
-		Examples:
-
-			$ balena signup
-			Email: johndoe@acme.com
-			Password: ***********
-
-			$ balena whoami
-			johndoe
-	'''
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		form = require('resin-cli-form')
-		validation = require('../utils/validation')
-
-		balena.settings.get('balenaUrl').then (balenaUrl) ->
-			console.log("\nRegistering to #{balenaUrl}")
-
-			form.run [
-				message: 'Email:'
-				name: 'email'
-				type: 'input'
-				validate: validation.validateEmail
-			,
-				message: 'Password:'
-				name: 'password'
-				type: 'password',
-				validate: validation.validatePassword
-			]
-
-		.then(balena.auth.register)
-		.then(balena.auth.loginWithToken)
-		.nodeify(done)
-
-exports.whoami =
-	signature: 'whoami'
-	description: 'get current username and email address'
-	help: '''
-		Use this command to find out the current logged in username and email address.
-
-		Examples:
-
-			$ balena whoami
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		balena = require('balena-sdk').fromSharedOptions()
-		visuals = require('resin-cli-visuals')
-
-		Promise.props
-			username: balena.auth.whoami()
-			email: balena.auth.getEmail()
-			url: balena.settings.get('balenaUrl')
-		.then (results) ->
-			console.log visuals.table.vertical results, [
-				'$account information$'
-				'username'
-				'email'
-				'url'
-			]
-		.nodeify(done)

lib/actions/build.coffee

@@ -1,145 +0,0 @@
-# Imported here because it's needed for the setup
-# of this action
-Promise = require('bluebird')
-dockerUtils = require('../utils/docker')
-compose = require('../utils/compose')
-
-###
-Opts must be an object with the following keys:
-
-	app: the app this build is for (optional)
-	arch: the architecture to build for
-	deviceType: the device type to build for
-	buildEmulated
-	buildOpts: arguments to forward to docker build command
-###
-buildProject = (docker, logger, composeOpts, opts) ->
-	compose.loadProject(
-		logger
-		composeOpts.projectPath
-		composeOpts.projectName
-	)
-	.then (project) ->
-		appType = opts.app?.application_type?[0]
-		if appType? and project.descriptors.length > 1 and not appType.supports_multicontainer
-			logger.logWarn(
-				'Target application does not support multiple containers.\n' +
-				'Continuing with build, but you will not be able to deploy.'
-			)
-
-		compose.buildProject(
-			docker
-			logger
-			project.path
-			project.name
-			project.composition
-			opts.arch
-			opts.deviceType
-			opts.buildEmulated
-			opts.buildOpts
-			composeOpts.inlineLogs
-		)
-	.then ->
-		logger.logSuccess('Build succeeded!')
-	.tapCatch (e) ->
-		logger.logError('Build failed')
-
-module.exports =
-	signature: 'build [source]'
-	description: 'Build a single image or a multicontainer project locally'
-	primary: true
-	help: '''
-		Use this command to build an image or a complete multicontainer project
-		with the provided docker daemon.
-
-		You must provide either an application or a device-type/architecture
-		pair to use the balena Dockerfile pre-processor
-		(e.g. Dockerfile.template -> Dockerfile).
-
-		This command will look into the given source directory (or the current working
-		directory if one isn't specified) for a compose file. If one is found, this
-		command will build each service defined in the compose file. If a compose file
-		isn't found, the command will look for a Dockerfile, and if yet that isn't found,
-		it will try to generate one.
-
-		Examples:
-
-			$ balena build
-			$ balena build ./source/
-			$ balena build --deviceType raspberrypi3 --arch armhf --emulated
-			$ balena build --application MyApp ./source/
-			$ balena build --docker '/var/run/docker.sock'
-			$ balena build --dockerHost my.docker.host --dockerPort 2376 --ca ca.pem --key key.pem --cert cert.pem
-	'''
-	options: dockerUtils.appendOptions compose.appendOptions [
-		{
-			signature: 'arch'
-			parameter: 'arch'
-			description: 'The architecture to build for'
-			alias: 'A'
-		},
-		{
-			signature: 'deviceType'
-			parameter: 'deviceType'
-			description: 'The type of device this build is for'
-			alias: 'd'
-		},
-		{
-			signature: 'application'
-			parameter: 'application'
-			description: 'The target balena application this build is for'
-			alias: 'a'
-		},
-	]
-	action: (params, options, done) ->
-		# compositions with many services trigger misleading warnings
-		require('events').defaultMaxListeners = 1000
-
-		{ exitWithExpectedError } = require('../utils/patterns')
-		helpers = require('../utils/helpers')
-		Logger = require('../utils/logger')
-
-		logger = new Logger()
-
-		logger.logDebug('Parsing input...')
-
-		Promise.try ->
-			# `build` accepts `[source]` as a parameter, but compose expects it
-			# as an option. swap them here
-			options.source ?= params.source
-			delete params.source
-
-			{ application, arch, deviceType } = options
-
-			if (not (arch? and deviceType?) and not application?) or (application? and (arch? or deviceType?))
-				exitWithExpectedError('You must specify either an application or an arch/deviceType pair to build for')
-
-			if arch? and deviceType?
-				[ undefined, arch, deviceType ]
-			else
-				Promise.join(
-					helpers.getApplication(application)
-					helpers.getArchAndDeviceType(application)
-					(app, { arch, device_type }) ->
-						app.arch = arch
-						app.device_type = device_type
-						return app
-				)
-				.then (app) ->
-					[ app, app.arch, app.device_type ]
-
-		.then ([ app, arch, deviceType ]) ->
-			Promise.join(
-				dockerUtils.getDocker(options)
-				dockerUtils.generateBuildOpts(options)
-				compose.generateOpts(options)
-				(docker, buildOpts, composeOpts) ->
-					buildProject(docker, logger, composeOpts, {
-						app
-						arch
-						deviceType
-						buildEmulated: !!options.emulated
-						buildOpts
-					})
-			)
-		.asCallback(done)

lib/actions/command-options.ts

@@ -1,134 +0,0 @@
-/*
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-import _ = require('lodash');
-
-export const yes = {
-	signature: 'yes',
-	description: 'confirm non interactively',
-	boolean: true,
-	alias: 'y',
-};
-
-export const optionalApplication = {
-	signature: 'application',
-	parameter: 'application',
-	description: 'application name',
-	alias: ['a', 'app'],
-};
-
-export const application = _.defaults(
-	{ required: 'You have to specify an application' },
-	optionalApplication,
-);
-
-export const optionalDevice = {
-	signature: 'device',
-	parameter: 'device',
-	description: 'device uuid',
-	alias: 'd',
-};
-
-export const optionalDeviceApiKey = {
-	signature: 'deviceApiKey',
-	description:
-		'custom device key - note that this is only supported on balenaOS 2.0.3+',
-	parameter: 'device-api-key',
-	alias: 'k',
-};
-
-export const optionalOsVersion = {
-	signature: 'version',
-	description: 'a balenaOS version',
-	parameter: 'version',
-};
-
-export const osVersion = _.defaults(
-	{
-		required: 'You have to specify an exact os version',
-	},
-	exports.optionalOsVersion,
-);
-
-export const booleanDevice = {
-	signature: 'device',
-	description: 'device',
-	boolean: true,
-	alias: 'd',
-};
-
-export const osVersionOrSemver = {
-	signature: 'version',
-	description: `\
-exact version number, or a valid semver range,
-or 'latest' (includes pre-releases),
-or 'default' (excludes pre-releases if at least one stable version is available),
-or 'recommended' (excludes pre-releases, will fail if only pre-release versions are available),
-or 'menu' (will show the interactive menu)\
-`,
-	parameter: 'version',
-};
-
-export const network = {
-	signature: 'network',
-	parameter: 'network',
-	description: 'network type',
-	alias: 'n',
-};
-
-export const wifiSsid = {
-	signature: 'ssid',
-	parameter: 'ssid',
-	description: 'wifi ssid, if network is wifi',
-	alias: 's',
-};
-
-export const wifiKey = {
-	signature: 'key',
-	parameter: 'key',
-	description: 'wifi key, if network is wifi',
-	alias: 'k',
-};
-
-export const forceUpdateLock = {
-	signature: 'force',
-	description: 'force action if the update lock is set',
-	boolean: true,
-	alias: 'f',
-};
-
-export const drive = {
-	signature: 'drive',
-	description: `the drive to write the image to, like \`/dev/sdb\` or \`/dev/mmcblk0\`. \
-Careful with this as you can erase your hard drive. \
-Check \`balena util available-drives\` for available options.`,
-	parameter: 'drive',
-	alias: 'd',
-};
-
-export const advancedConfig = {
-	signature: 'advanced',
-	description: 'show advanced configuration options',
-	boolean: true,
-	alias: 'v',
-};
-
-export const hostOSAccess = {
-	signature: 'host',
-	boolean: true,
-	description: 'access host OS (for devices with balenaOS >= 2.7.5)',
-	alias: 's',
-};

lib/actions/config.coffee

@@ -1,325 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-commandOptions = require('./command-options')
-{ normalizeUuidProp } = require('../utils/normalization')
-
-exports.read =
-	signature: 'config read'
-	description: 'read a device configuration'
-	help: '''
-		Use this command to read the config.json file from the mounted filesystem (e.g. SD card) of a provisioned device"
-
-		Examples:
-
-			$ balena config read --type raspberry-pi
-			$ balena config read --type raspberry-pi --drive /dev/disk2
-	'''
-	options: [
-		{
-			signature: 'type'
-			description: 'device type (Check available types with `balena devices supported`)'
-			parameter: 'type'
-			alias: 't'
-			required: 'You have to specify a device type'
-		}
-		{
-			signature: 'drive'
-			description: 'drive'
-			parameter: 'drive'
-			alias: 'd'
-		}
-	]
-	permission: 'user'
-	root: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		config = require('balena-config-json')
-		visuals = require('resin-cli-visuals')
-		umountAsync = Promise.promisify(require('umount').umount)
-		prettyjson = require('prettyjson')
-
-		Promise.try ->
-			return options.drive or visuals.drive('Select the device drive')
-		.tap(umountAsync)
-		.then (drive) ->
-			return config.read(drive, options.type)
-		.tap (configJSON) ->
-			console.info(prettyjson.render(configJSON))
-		.nodeify(done)
-
-exports.write =
-	signature: 'config write <key> <value>'
-	description: 'write a device configuration'
-	help: '''
-		Use this command to write the config.json file to the mounted filesystem (e.g. SD card) of a provisioned device
-
-		Examples:
-
-			$ balena config write --type raspberry-pi username johndoe
-			$ balena config write --type raspberry-pi --drive /dev/disk2 username johndoe
-			$ balena config write --type raspberry-pi files.network/settings "..."
-	'''
-	options: [
-		{
-			signature: 'type'
-			description: 'device type (Check available types with `balena devices supported`)'
-			parameter: 'type'
-			alias: 't'
-			required: 'You have to specify a device type'
-		}
-		{
-			signature: 'drive'
-			description: 'drive'
-			parameter: 'drive'
-			alias: 'd'
-		}
-	]
-	permission: 'user'
-	root: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		_ = require('lodash')
-		config = require('balena-config-json')
-		visuals = require('resin-cli-visuals')
-		umountAsync = Promise.promisify(require('umount').umount)
-
-		Promise.try ->
-			return options.drive or visuals.drive('Select the device drive')
-		.tap(umountAsync)
-		.then (drive) ->
-			config.read(drive, options.type).then (configJSON) ->
-				console.info("Setting #{params.key} to #{params.value}")
-				_.set(configJSON, params.key, params.value)
-				return configJSON
-			.tap ->
-				return umountAsync(drive)
-			.then (configJSON) ->
-				return config.write(drive, options.type, configJSON)
-		.tap ->
-			console.info('Done')
-		.nodeify(done)
-
-exports.inject =
-	signature: 'config inject <file>'
-	description: 'inject a device configuration file'
-	help: '''
-		Use this command to inject a config.json file to the mounted filesystem
-		(e.g. SD card or mounted balenaOS image) of a provisioned device"
-
-		Examples:
-
-			$ balena config inject my/config.json --type raspberry-pi
-			$ balena config inject my/config.json --type raspberry-pi --drive /dev/disk2
-	'''
-	options: [
-		{
-			signature: 'type'
-			description: 'device type (Check available types with `balena devices supported`)'
-			parameter: 'type'
-			alias: 't'
-			required: 'You have to specify a device type'
-		}
-		{
-			signature: 'drive'
-			description: 'drive'
-			parameter: 'drive'
-			alias: 'd'
-		}
-	]
-	permission: 'user'
-	root: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		config = require('balena-config-json')
-		visuals = require('resin-cli-visuals')
-		umountAsync = Promise.promisify(require('umount').umount)
-		readFileAsync = Promise.promisify(require('fs').readFile)
-
-		Promise.try ->
-			return options.drive or visuals.drive('Select the device drive')
-		.tap(umountAsync)
-		.then (drive) ->
-			readFileAsync(params.file, 'utf8').then(JSON.parse).then (configJSON) ->
-				return config.write(drive, options.type, configJSON)
-		.tap ->
-			console.info('Done')
-		.nodeify(done)
-
-exports.reconfigure =
-	signature: 'config reconfigure'
-	description: 'reconfigure a provisioned device'
-	help: '''
-		Use this command to reconfigure a provisioned device
-
-		Examples:
-
-			$ balena config reconfigure --type raspberry-pi
-			$ balena config reconfigure --type raspberry-pi --advanced
-			$ balena config reconfigure --type raspberry-pi --drive /dev/disk2
-	'''
-	options: [
-		{
-			signature: 'type'
-			description: 'device type (Check available types with `balena devices supported`)'
-			parameter: 'type'
-			alias: 't'
-			required: 'You have to specify a device type'
-		}
-		{
-			signature: 'drive'
-			description: 'drive'
-			parameter: 'drive'
-			alias: 'd'
-		}
-		{
-			signature: 'advanced'
-			description: 'show advanced commands'
-			boolean: true
-			alias: 'v'
-		}
-	]
-	permission: 'user'
-	root: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		config = require('balena-config-json')
-		visuals = require('resin-cli-visuals')
-		{ runCommand } = require('../utils/helpers')
-		umountAsync = Promise.promisify(require('umount').umount)
-
-		Promise.try ->
-			return options.drive or visuals.drive('Select the device drive')
-		.tap(umountAsync)
-		.then (drive) ->
-			config.read(drive, options.type).get('uuid')
-				.tap ->
-					umountAsync(drive)
-				.then (uuid) ->
-					configureCommand = "os configure #{drive} --device #{uuid}"
-					if options.advanced
-						configureCommand += ' --advanced'
-					return runCommand(configureCommand)
-		.then ->
-			console.info('Done')
-		.nodeify(done)
-
-exports.generate =
-	signature: 'config generate'
-	description: 'generate a config.json file'
-	help: '''
-		Use this command to generate a config.json for a device or application.
-
-		Calling this command with the exact version number of the targeted image is required.
-
-		This is interactive by default, but you can do this automatically without interactivity
-		by specifying an option for each question on the command line, if you know the questions
-		that will be asked for the relevant device type.
-
-		Examples:
-
-			$ balena config generate --device 7cf02a6 --version 2.12.7
-			$ balena config generate --device 7cf02a6 --version 2.12.7 --generate-device-api-key
-			$ balena config generate --device 7cf02a6 --version 2.12.7 --device-api-key <existingDeviceKey>
-			$ balena config generate --device 7cf02a6 --version 2.12.7 --output config.json
-			$ balena config generate --app MyApp --version 2.12.7
-			$ balena config generate --app MyApp --version 2.12.7 --output config.json
-			$ balena config generate --app MyApp --version 2.12.7 \
-				--network wifi --wifiSsid mySsid --wifiKey abcdefgh --appUpdatePollInterval 1
-	'''
-	options: [
-		commandOptions.osVersion
-		commandOptions.optionalApplication
-		commandOptions.optionalDevice
-		commandOptions.optionalDeviceApiKey
-		{
-			signature: 'generate-device-api-key'
-			description: 'generate a fresh device key for the device'
-			boolean: true
-		}
-		{
-			signature: 'output'
-			description: 'output'
-			parameter: 'output'
-			alias: 'o'
-		}
-		# Options for non-interactive configuration
-		{
-			signature: 'network'
-			description: 'the network type to use: ethernet or wifi'
-			parameter: 'network'
-		}
-		{
-			signature: 'wifiSsid'
-			description: 'the wifi ssid to use (used only if --network is set to wifi)'
-			parameter: 'wifiSsid'
-		}
-		{
-			signature: 'wifiKey'
-			description: 'the wifi key to use (used only if --network is set to wifi)'
-			parameter: 'wifiKey'
-		}
-		{
-			signature: 'appUpdatePollInterval'
-			description: 'how frequently (in minutes) to poll for application updates'
-			parameter: 'appUpdatePollInterval'
-		}
-	]
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(options, 'device')
-		Promise = require('bluebird')
-		writeFileAsync = Promise.promisify(require('fs').writeFile)
-		balena = require('balena-sdk').fromSharedOptions()
-		form = require('resin-cli-form')
-		prettyjson = require('prettyjson')
-
-		{ generateDeviceConfig, generateApplicationConfig } = require('../utils/config')
-		{ exitWithExpectedError } = require('../utils/patterns')
-
-		if not options.device? and not options.application?
-			exitWithExpectedError '''
-				You have to pass either a device or an application.
-
-				See the help page for examples:
-
-				  $ balena help config generate
-			'''
-
-		Promise.try ->
-			if options.device?
-				return balena.models.device.get(options.device)
-			return balena.models.application.get(options.application)
-		.then (resource) ->
-			balena.models.device.getManifestBySlug(resource.device_type)
-			.get('options')
-			.then (formOptions) ->
-				# Pass params as an override: if there is any param with exactly the same name as a
-				# required option, that value is used (and the corresponding question is not asked)
-				form.run(formOptions, override: options)
-			.then (answers) ->
-				answers.version = options.version
-
-				if resource.uuid?
-					generateDeviceConfig(resource, options.deviceApiKey || options['generate-device-api-key'], answers)
-				else
-					generateApplicationConfig(resource, answers)
-		.then (config) ->
-			if options.output?
-				return writeFileAsync(options.output, JSON.stringify(config))
-
-			console.log(prettyjson.render(config))
-		.nodeify(done)

lib/actions/deploy.coffee

@@ -1,220 +0,0 @@
-# Imported here because it's needed for the setup
-# of this action
-Promise = require('bluebird')
-dockerUtils = require('../utils/docker')
-compose = require('../utils/compose')
-
-###
-Opts must be an object with the following keys:
-
-	app: the application instance to deploy to
-	image: the image to deploy; optional
-	shouldPerformBuild
-	shouldUploadLogs
-	buildEmulated
-	buildOpts: arguments to forward to docker build command
-###
-deployProject = (docker, logger, composeOpts, opts) ->
-	_ = require('lodash')
-	doodles = require('resin-doodles')
-	sdk = require('balena-sdk').fromSharedOptions()
-
-	compose.loadProject(
-		logger
-		composeOpts.projectPath
-		composeOpts.projectName
-		opts.image
-	)
-	.then (project) ->
-		if project.descriptors.length > 1 and !opts.app.application_type?[0]?.supports_multicontainer
-			throw new Error('Target application does not support multiple containers. Aborting!')
-
-		# find which services use images that already exist locally
-		Promise.map project.descriptors, (d) ->
-			# unconditionally build (or pull) if explicitly requested
-			return d if opts.shouldPerformBuild
-			docker.getImage(d.image.tag ? d.image).inspect()
-			.return(d.serviceName)
-			.catchReturn()
-		.filter (d) -> !!d
-		.then (servicesToSkip) ->
-			# multibuild takes in a composition and always attempts to
-			# build or pull all services. we workaround that here by
-			# passing a modified composition.
-			compositionToBuild = _.cloneDeep(project.composition)
-			compositionToBuild.services = _.omit(compositionToBuild.services, servicesToSkip)
-			if _.size(compositionToBuild.services) is 0
-				logger.logInfo('Everything is up to date (use --build to force a rebuild)')
-				return {}
-			compose.buildProject(
-				docker
-				logger
-				project.path
-				project.name
-				compositionToBuild
-				opts.app.arch
-				opts.app.device_type
-				opts.buildEmulated
-				opts.buildOpts
-				composeOpts.inlineLogs
-			)
-			.then (builtImages) ->
-				_.keyBy(builtImages, 'serviceName')
-		.then (builtImages) ->
-			project.descriptors.map (d) ->
-				builtImages[d.serviceName] ? {
-					serviceName: d.serviceName,
-					name: d.image.tag ? d.image
-					logs: 'Build skipped; image for service already exists.'
-					props: {}
-				}
-		.then (images) ->
-			if opts.app.application_type?[0]?.is_legacy
-				chalk = require('chalk')
-				legacyDeploy = require('../utils/deploy-legacy')
-
-				msg = chalk.yellow('Target application requires legacy deploy method.')
-				logger.logWarn(msg)
-
-				return Promise.join(
-					docker
-					logger
-					sdk.auth.getToken()
-					sdk.auth.whoami()
-					sdk.settings.get('balenaUrl')
-					{
-						appName: opts.app.app_name
-						imageName: images[0].name
-						buildLogs: images[0].logs
-						shouldUploadLogs: opts.shouldUploadLogs
-					}
-					legacyDeploy
-				)
-				.then (releaseId) ->
-					sdk.models.release.get(releaseId, $select: [ 'commit' ])
-			Promise.join(
-				sdk.auth.getUserId()
-				sdk.auth.getToken()
-				sdk.settings.get('apiUrl')
-				(userId, auth, apiEndpoint) ->
-					compose.deployProject(
-						docker
-						logger
-						project.composition
-						images
-						opts.app.id
-						userId
-						"Bearer #{auth}"
-						apiEndpoint
-						!opts.shouldUploadLogs
-					)
-			)
-	.then (release) ->
-		logger.logSuccess('Deploy succeeded!')
-		logger.logSuccess("Release: #{release.commit}")
-		console.log()
-		console.log(doodles.getDoodle()) # Show charlie
-		console.log()
-	.tapCatch (e) ->
-		logger.logError('Deploy failed')
-
-module.exports =
-	signature: 'deploy <appName> [image]'
-	description: 'Deploy a single image or a multicontainer project to a balena application'
-	help: '''
-		Use this command to deploy an image or a complete multicontainer project
-		to an application, optionally building it first.
-
-		Usage: `deploy <appName> ([image] | --build [--source build-dir])`
-
-		Unless an image is specified, this command will look into the current directory
-		(or the one specified by --source) for a compose file. If one is found, this
-		command will deploy each service defined in the compose file, building it first
-		if an image for it doesn't exist. If a compose file isn't found, the command
-		will look for a Dockerfile, and if yet that isn't found, it will try to
-		generate one.
-
-		To deploy to an app on which you're a collaborator, use
-		`balena deploy <appOwnerUsername>/<appName>`.
-
-		Note: If building with this command, all options supported by `balena build`
-		are also supported with this command.
-
-		Examples:
-
-			$ balena deploy myApp
-			$ balena deploy myApp --build --source myBuildDir/
-			$ balena deploy myApp myApp/myImage
-	'''
-	permission: 'user'
-	primary: true
-	options: dockerUtils.appendOptions compose.appendOptions [
-		{
-			signature: 'source'
-			parameter: 'source'
-			description: 'Specify an alternate source directory; default is the working directory'
-			alias: 's'
-		},
-		{
-			signature: 'build'
-			boolean: true
-			description: 'Force a rebuild before deploy'
-			alias: 'b'
-		},
-		{
-			signature: 'nologupload'
-			description: "Don't upload build logs to the dashboard with image (if building)"
-			boolean: true
-		}
-	]
-	action: (params, options, done) ->
-		# compositions with many services trigger misleading warnings
-		require('events').defaultMaxListeners = 1000
-
-		helpers = require('../utils/helpers')
-		Logger = require('../utils/logger')
-
-		logger = new Logger()
-
-		logger.logDebug('Parsing input...')
-
-		Promise.try ->
-			{ appName, image } = params
-
-			# look into "balena build" options if appName isn't given
-			appName = options.application if not appName?
-			delete options.application
-
-			if not appName?
-				throw new Error('Please specify the name of the application to deploy')
-
-			if image? and options.build
-				throw new Error('Build option is not applicable when specifying an image')
-
-			Promise.join(
-				helpers.getApplication(appName)
-				helpers.getArchAndDeviceType(appName)
-				(app, { arch, device_type }) ->
-					app.arch = arch
-					app.device_type = device_type
-					return app
-			)
-			.then (app) ->
-				[ app, image, !!options.build, !options.nologupload ]
-
-		.then ([ app, image, shouldPerformBuild, shouldUploadLogs ]) ->
-			Promise.join(
-				dockerUtils.getDocker(options)
-				dockerUtils.generateBuildOpts(options)
-				compose.generateOpts(options)
-				(docker, buildOpts, composeOpts) ->
-					deployProject(docker, logger, composeOpts, {
-						app
-						image
-						shouldPerformBuild
-						shouldUploadLogs
-						buildEmulated: !!options.emulated
-						buildOpts
-					})
-			)
-		.asCallback(done)

lib/actions/device.coffee

@@ -1,457 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-commandOptions = require('./command-options')
-_ = require('lodash')
-{ normalizeUuidProp } = require('../utils/normalization')
-
-expandForAppName = {
-	$expand: belongs_to__application: $select: 'app_name'
-}
-
-exports.list =
-	signature: 'devices'
-	description: 'list all devices'
-	help: '''
-		Use this command to list all devices that belong to you.
-
-		You can filter the devices by application by using the `--application` option.
-
-		Examples:
-
-			$ balena devices
-			$ balena devices --application MyApp
-			$ balena devices --app MyApp
-			$ balena devices -a MyApp
-	'''
-	options: [ commandOptions.optionalApplication ]
-	permission: 'user'
-	primary: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		balena = require('balena-sdk').fromSharedOptions()
-		visuals = require('resin-cli-visuals')
-
-		Promise.try ->
-			if options.application?
-				return balena.models.device.getAllByApplication(options.application, expandForAppName)
-			return balena.models.device.getAll(expandForAppName)
-
-		.tap (devices) ->
-			devices = _.map devices, (device) ->
-				device.dashboard_url = balena.models.device.getDashboardUrl(device.uuid)
-				device.application_name = device.belongs_to__application[0].app_name
-				device.uuid = device.uuid.slice(0, 7)
-				return device
-
-			console.log visuals.table.horizontal devices, [
-				'id'
-				'uuid'
-				'device_name'
-				'device_type'
-				'application_name'
-				'status'
-				'is_online'
-				'supervisor_version'
-				'os_version'
-				'dashboard_url'
-			]
-		.nodeify(done)
-
-exports.info =
-	signature: 'device <uuid>'
-	description: 'list a single device'
-	help: '''
-		Use this command to show information about a single device.
-
-		Examples:
-
-			$ balena device 7cf02a6
-	'''
-	permission: 'user'
-	primary: true
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		visuals = require('resin-cli-visuals')
-
-		balena.models.device.get(params.uuid, expandForAppName)
-		.then (device) ->
-			balena.models.device.getStatus(device).then (status) ->
-				device.status = status
-				device.dashboard_url = balena.models.device.getDashboardUrl(device.uuid)
-				device.application_name = device.belongs_to__application[0].app_name
-				device.commit = device.is_on__commit
-
-				console.log visuals.table.vertical device, [
-					"$#{device.device_name}$"
-					'id'
-					'device_type'
-					'status'
-					'is_online'
-					'ip_address'
-					'application_name'
-					'last_seen'
-					'uuid'
-					'commit'
-					'supervisor_version'
-					'is_web_accessible'
-					'note'
-					'os_version'
-					'dashboard_url'
-				]
-		.nodeify(done)
-
-exports.supported =
-	signature: 'devices supported'
-	description: 'list all supported devices'
-	help: '''
-		Use this command to get the list of all supported devices
-
-		Examples:
-
-			$ balena devices supported
-	'''
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		visuals = require('resin-cli-visuals')
-
-		balena.models.config.getDeviceTypes().then (deviceTypes) ->
-			console.log visuals.table.horizontal deviceTypes, [
-				'slug'
-				'name'
-			]
-		.nodeify(done)
-
-exports.register =
-	signature: 'device register <application>'
-	description: 'register a device'
-	help: '''
-		Use this command to register a device to an application.
-
-		Examples:
-
-			$ balena device register MyApp
-			$ balena device register MyApp --uuid <uuid>
-	'''
-	permission: 'user'
-	options: [
-		{
-			signature: 'uuid'
-			description: 'custom uuid'
-			parameter: 'uuid'
-			alias: 'u'
-		}
-	]
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		balena = require('balena-sdk').fromSharedOptions()
-
-		Promise.join(
-			balena.models.application.get(params.application)
-			options.uuid ? balena.models.device.generateUniqueKey()
-			(application, uuid) ->
-				console.info("Registering to #{application.app_name}: #{uuid}")
-				return balena.models.device.register(application.id, uuid)
-		)
-		.get('uuid')
-		.nodeify(done)
-
-exports.remove =
-	signature: 'device rm <uuid>'
-	description: 'remove a device'
-	help: '''
-		Use this command to remove a device from balena.
-
-		Notice this command asks for confirmation interactively.
-		You can avoid this by passing the `--yes` boolean option.
-
-		Examples:
-
-			$ balena device rm 7cf02a6
-			$ balena device rm 7cf02a6 --yes
-	'''
-	options: [ commandOptions.yes ]
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		patterns = require('../utils/patterns')
-
-		patterns.confirm(options.yes, 'Are you sure you want to delete the device?').then ->
-			balena.models.device.remove(params.uuid)
-		.nodeify(done)
-
-exports.identify =
-	signature: 'device identify <uuid>'
-	description: 'identify a device with a UUID'
-	help: '''
-		Use this command to identify a device.
-
-		In the Raspberry Pi, the ACT led is blinked several times.
-
-		Examples:
-
-			$ balena device identify 23c73a1
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		balena.models.device.identify(params.uuid).nodeify(done)
-
-exports.reboot =
-	signature: 'device reboot <uuid>'
-	description: 'restart a device'
-	help: '''
-		Use this command to remotely reboot a device
-
-		Examples:
-
-			$ balena device reboot 23c73a1
-	'''
-	options: [ commandOptions.forceUpdateLock ]
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		balena.models.device.reboot(params.uuid, options).nodeify(done)
-
-exports.shutdown =
-	signature: 'device shutdown <uuid>'
-	description: 'shutdown a device'
-	help: '''
-		Use this command to remotely shutdown a device
-
-		Examples:
-
-			$ balena device shutdown 23c73a1
-	'''
-	options: [ commandOptions.forceUpdateLock ]
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		balena.models.device.shutdown(params.uuid, options).nodeify(done)
-
-exports.enableDeviceUrl =
-	signature: 'device public-url enable <uuid>'
-	description: 'enable public URL for a device'
-	help: '''
-		Use this command to enable public URL for a device
-
-		Examples:
-
-			$ balena device public-url enable 23c73a1
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		balena.models.device.enableDeviceUrl(params.uuid).nodeify(done)
-
-exports.disableDeviceUrl =
-	signature: 'device public-url disable <uuid>'
-	description: 'disable public URL for a device'
-	help: '''
-		Use this command to disable public URL for a device
-
-		Examples:
-
-			$ balena device public-url disable 23c73a1
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		balena.models.device.disableDeviceUrl(params.uuid).nodeify(done)
-
-exports.getDeviceUrl =
-	signature: 'device public-url <uuid>'
-	description: 'gets the public URL of a device'
-	help: '''
-		Use this command to get the public URL of a device
-
-		Examples:
-
-			$ balena device public-url 23c73a1
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		balena.models.device.getDeviceUrl(params.uuid).then (url) ->
-			console.log(url)
-		.nodeify(done)
-
-exports.hasDeviceUrl =
-	signature: 'device public-url status <uuid>'
-	description: 'Returns true if public URL is enabled for a device'
-	help: '''
-		Use this command to determine if public URL is enabled for a device
-
-		Examples:
-
-			$ balena device public-url status 23c73a1
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		balena.models.device.hasDeviceUrl(params.uuid).then (hasDeviceUrl) ->
-			console.log(hasDeviceUrl)
-		.nodeify(done)
-
-exports.rename =
-	signature: 'device rename <uuid> [newName]'
-	description: 'rename a balena device'
-	help: '''
-		Use this command to rename a device.
-
-		If you omit the name, you'll get asked for it interactively.
-
-		Examples:
-
-			$ balena device rename 7cf02a6
-			$ balena device rename 7cf02a6 MyPi
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		Promise = require('bluebird')
-		balena = require('balena-sdk').fromSharedOptions()
-		form = require('resin-cli-form')
-
-		Promise.try ->
-			return params.newName if not _.isEmpty(params.newName)
-
-			form.ask
-				message: 'How do you want to name this device?'
-				type: 'input'
-
-		.then(_.partial(balena.models.device.rename, params.uuid))
-		.nodeify(done)
-
-exports.move =
-	signature: 'device move <uuid>'
-	description: 'move a device to another application'
-	help: '''
-		Use this command to move a device to another application you own.
-
-		If you omit the application, you'll get asked for it interactively.
-
-		Examples:
-
-			$ balena device move 7cf02a6
-			$ balena device move 7cf02a6 --application MyNewApp
-	'''
-	permission: 'user'
-	options: [ commandOptions.optionalApplication ]
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		patterns = require('../utils/patterns')
-
-		balena.models.device.get(params.uuid, expandForAppName).then (device) ->
-			return options.application or patterns.selectApplication (application) ->
-				return _.every [
-					application.device_type is device.device_type
-					device.belongs_to__application[0].app_name isnt application.app_name
-				]
-		.tap (application) ->
-			return balena.models.device.move(params.uuid, application)
-		.then (application) ->
-			console.info("#{params.uuid} was moved to #{application}")
-		.nodeify(done)
-
-exports.init =
-	signature: 'device init'
-	description: 'initialise a device with balenaOS'
-	help: '''
-		Use this command to download the OS image of a certain application and write it to an SD Card.
-
-		Notice this command may ask for confirmation interactively.
-		You can avoid this by passing the `--yes` boolean option.
-
-		Examples:
-
-			$ balena device init
-			$ balena device init --application MyApp
-	'''
-	options: [
-		commandOptions.optionalApplication
-		commandOptions.yes
-		commandOptions.advancedConfig
-		_.assign({}, commandOptions.osVersionOrSemver, { signature: 'os-version', parameter: 'os-version' })
-		commandOptions.drive
-		{
-			signature: 'config'
-			description: 'path to the config JSON file, see `balena os build-config`'
-			parameter: 'config'
-		}
-	]
-	permission: 'user'
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		rimraf = Promise.promisify(require('rimraf'))
-		tmp = require('tmp')
-		tmpNameAsync = Promise.promisify(tmp.tmpName)
-		tmp.setGracefulCleanup()
-
-		balena = require('balena-sdk').fromSharedOptions()
-		patterns = require('../utils/patterns')
-		{ runCommand } = require('../utils/helpers')
-
-		Promise.try ->
-			return options.application if options.application?
-			return patterns.selectApplication()
-		.then(balena.models.application.get)
-		.then (application) ->
-
-			download = ->
-				tmpNameAsync().then (tempPath) ->
-					osVersion = options['os-version'] or 'default'
-					runCommand("os download #{application.device_type} --output '#{tempPath}' --version #{osVersion}")
-				.disposer (tempPath) ->
-					return rimraf(tempPath)
-
-			Promise.using download(), (tempPath) ->
-				runCommand("device register #{application.app_name}")
-					.then(balena.models.device.get)
-					.tap (device) ->
-						configureCommand = "os configure '#{tempPath}' --device #{device.uuid}"
-						if options.config
-							configureCommand += " --config '#{options.config}'"
-						else if options.advanced
-							configureCommand += ' --advanced'
-						runCommand(configureCommand)
-						.then ->
-							osInitCommand = "os initialize '#{tempPath}' --type #{application.device_type}"
-							if options.yes
-								osInitCommand += ' --yes'
-							if options.drive
-								osInitCommand += " --drive #{options.drive}"
-							runCommand(osInitCommand)
-						# Make sure the device resource is removed if there is an
-						# error when configuring or initializing a device image
-						.catch (error) ->
-							balena.models.device.remove(device.uuid).finally ->
-								throw error
-			.then (device) ->
-				console.log('Done')
-				return device.uuid
-
-		.nodeify(done)

lib/actions/environment-variables.ts

@@ -1,300 +0,0 @@
-/*
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-import { CommandDefinition } from 'capitano';
-
-import * as commandOptions from './command-options';
-import { normalizeUuidProp } from '../utils/normalization';
-import { DeviceVariable, ApplicationVariable } from 'balena-sdk';
-import { stripIndent } from 'common-tags';
-
-const getReservedPrefixes = async (): Promise<string[]> => {
-	const balena = (await import('balena-sdk')).fromSharedOptions();
-	const settings = await balena.settings.getAll();
-
-	const response = await balena.request.send({
-		baseUrl: settings.apiUrl,
-		url: '/config/vars',
-	});
-
-	return response.body.reservedNamespaces;
-};
-
-export const list: CommandDefinition<
-	{},
-	{
-		application?: string;
-		device?: string;
-		config: boolean;
-	}
-> = {
-	signature: 'envs',
-	description: 'list all environment variables',
-	help: stripIndent`
-		Use this command to list all environment variables for
-		a particular application or device.
-
-		This command lists all application/device environment variables.
-
-		If you want to see config variables, used to configure
-		balena features, use the --config option.
-
-		At the moment the CLI does not support per-service variables,
-		so the following commands will only show service-wide
-		environment variables.
-
-		Example:
-
-			$ balena envs --application MyApp
-			$ balena envs --application MyApp --config
-			$ balena envs --device 7cf02a6
-	`,
-	options: [
-		commandOptions.optionalApplication,
-		commandOptions.optionalDevice,
-
-		{
-			signature: 'config',
-			description: 'show config variables',
-			boolean: true,
-			alias: ['c', 'v', 'verbose'],
-		},
-	],
-	permission: 'user',
-	async action(_params, options, done) {
-		normalizeUuidProp(options, 'device');
-		const Bluebird = await import('bluebird');
-		const _ = await import('lodash');
-		const balena = (await import('balena-sdk')).fromSharedOptions();
-		const visuals = await import('resin-cli-visuals');
-
-		const { exitWithExpectedError } = await import('../utils/patterns');
-
-		return Bluebird.try(function(): Promise<
-			DeviceVariable[] | ApplicationVariable[]
-		> {
-			if (options.application) {
-				return balena.models.application[
-					options.config ? 'configVar' : 'envVar'
-				].getAllByApplication(options.application);
-			} else if (options.device) {
-				return balena.models.device[
-					options.config ? 'configVar' : 'envVar'
-				].getAllByDevice(options.device);
-			} else {
-				return exitWithExpectedError(
-					'You must specify an application or device',
-				);
-			}
-		})
-			.tap(function(environmentVariables) {
-				if (_.isEmpty(environmentVariables)) {
-					exitWithExpectedError('No environment variables found');
-				}
-
-				console.log(
-					visuals.table.horizontal(environmentVariables, [
-						'id',
-						'name',
-						'value',
-					]),
-				);
-			})
-			.nodeify(done);
-	},
-};
-
-export const remove: CommandDefinition<
-	{
-		id: number;
-	},
-	{
-		yes: boolean;
-		device: boolean;
-	}
-> = {
-	signature: 'env rm <id>',
-	description: 'remove an environment variable',
-	help: stripIndent`
-		Use this command to remove an environment variable from an application.
-
-		Notice this command asks for confirmation interactively.
-		You can avoid this by passing the \`--yes\` boolean option.
-
-		If you want to eliminate a device environment variable, pass the \`--device\` boolean option.
-
-		Examples:
-
-			$ balena env rm 215
-			$ balena env rm 215 --yes
-			$ balena env rm 215 --device
-	`,
-	options: [commandOptions.yes, commandOptions.booleanDevice],
-	permission: 'user',
-	async action(params, options, done) {
-		const balena = (await import('balena-sdk')).fromSharedOptions();
-		const patterns = await import('../utils/patterns');
-
-		return patterns
-			.confirm(
-				options.yes,
-				'Are you sure you want to delete the environment variable?',
-			)
-			.then(function() {
-				if (options.device) {
-					return balena.pine.delete({
-						resource: 'device_environment_variable',
-						id: params.id,
-					});
-				} else {
-					return balena.pine.delete({
-						resource: 'application_environment_variable',
-						id: params.id,
-					});
-				}
-			})
-			.nodeify(done);
-	},
-};
-
-export const add: CommandDefinition<
-	{
-		key: string;
-		value?: string;
-	},
-	{
-		application?: string;
-		device?: string;
-	}
-> = {
-	signature: 'env add <key> [value]',
-	description: 'add an environment or config variable',
-	help: stripIndent`
-		Use this command to add an enviroment or config variable to an application.
-
-		At the moment the CLI doesn't fully support multi-container applications,
-		so the following commands will set service-wide environment variables.
-
-		If value is omitted, the tool will attempt to use the variable's value
-		as defined in your host machine.
-
-		Use the \`--device\` option if you want to assign the environment variable
-		to a specific device.
-
-		If the value is grabbed from the environment, a warning message will be printed.
-		Use \`--quiet\` to remove it.
-
-		Examples:
-
-			$ balena env add EDITOR vim --application MyApp
-			$ balena env add TERM --application MyApp
-			$ balena env add EDITOR vim --device 7cf02a6
-	`,
-	options: [commandOptions.optionalApplication, commandOptions.optionalDevice],
-	permission: 'user',
-	async action(params, options, done) {
-		normalizeUuidProp(options, 'device');
-		const Bluebird = await import('bluebird');
-		const _ = await import('lodash');
-		const balena = (await import('balena-sdk')).fromSharedOptions();
-
-		const { exitWithExpectedError } = await import('../utils/patterns');
-
-		return Bluebird.try(async function() {
-			if (params.value == null) {
-				params.value = process.env[params.key];
-
-				if (params.value == null) {
-					throw new Error(`Environment value not found for key: ${params.key}`);
-				} else {
-					console.info(
-						`Warning: using ${params.key}=${
-							params.value
-						} from host environment`,
-					);
-				}
-			}
-
-			const reservedPrefixes = await getReservedPrefixes();
-			const isConfigVar = _.some(reservedPrefixes, prefix =>
-				_.startsWith(params.key, prefix),
-			);
-
-			if (options.application) {
-				return balena.models.application[
-					isConfigVar ? 'configVar' : 'envVar'
-				].set(options.application, params.key, params.value);
-			} else if (options.device) {
-				return balena.models.device[isConfigVar ? 'configVar' : 'envVar'].set(
-					options.device,
-					params.key,
-					params.value,
-				);
-			} else {
-				exitWithExpectedError('You must specify an application or device');
-			}
-		}).nodeify(done);
-	},
-};
-
-export const rename: CommandDefinition<
-	{
-		id: number;
-		value: string;
-	},
-	{
-		device: boolean;
-	}
-> = {
-	signature: 'env rename <id> <value>',
-	description: 'rename an environment variable',
-	help: stripIndent`
-		Use this command to change the value of an enviroment variable.
-
-		Pass the \`--device\` boolean option if you want to rename a device environment variable.
-
-		Examples:
-
-			$ balena env rename 376 emacs
-			$ balena env rename 376 emacs --device
-	`,
-	permission: 'user',
-	options: [commandOptions.booleanDevice],
-	async action(params, options, done) {
-		const Bluebird = await import('bluebird');
-		const balena = (await import('balena-sdk')).fromSharedOptions();
-
-		return Bluebird.try(function() {
-			if (options.device) {
-				return balena.pine.patch({
-					resource: 'device_environment_variable',
-					id: params.id,
-					body: {
-						value: params.value,
-					},
-				});
-			} else {
-				return balena.pine.patch({
-					resource: 'application_environment_variable',
-					id: params.id,
-					body: {
-						value: params.value,
-					},
-				});
-			}
-		}).nodeify(done);
-	},
-};

lib/actions/help.coffee

@@ -1,119 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-_ = require('lodash')
-capitano = require('capitano')
-columnify = require('columnify')
-messages = require('../utils/messages')
-{ exitWithExpectedError } = require('../utils/patterns')
-
-parse = (object) ->
-	return _.fromPairs _.map object, (item) ->
-
-		# Hacky way to determine if an object is
-		# a function or a command
-		if item.alias?
-			signature = item.toString()
-		else
-			signature = item.signature.toString()
-
-		return [
-			signature
-			item.description
-		]
-
-indent = (text) ->
-	text = _.map text.split('\n'), (line) ->
-		return '    ' + line
-	return text.join('\n')
-
-print = (data) ->
-	console.log indent columnify data,
-		showHeaders: false
-		minWidth: 35
-
-general = (params, options, done) ->
-	console.log('Usage: balena [COMMAND] [OPTIONS]\n')
-	console.log(messages.reachingOut)
-	console.log('\nPrimary commands:\n')
-
-	# We do not want the wildcard command
-	# to be printed in the help screen.
-	commands = _.reject capitano.state.commands, (command) ->
-		return command.hidden or command.isWildcard()
-
-	groupedCommands = _.groupBy commands, (command) ->
-		if command.primary
-			return 'primary'
-		return 'secondary'
-
-	print(parse(groupedCommands.primary))
-
-	if options.verbose
-		console.log('\nAdditional commands:\n')
-		print(parse(groupedCommands.secondary))
-	else
-		console.log('\nRun `balena help --verbose` to list additional commands')
-
-	if not _.isEmpty(capitano.state.globalOptions)
-		console.log('\nGlobal Options:\n')
-		print(parse(capitano.state.globalOptions))
-
-	return done()
-
-command = (params, options, done) ->
-	capitano.state.getMatchCommand params.command, (error, command) ->
-		return done(error) if error?
-
-		if not command? or command.isWildcard()
-			exitWithExpectedError("Command not found: #{params.command}")
-
-		console.log("Usage: #{command.signature}")
-
-		if command.help?
-			console.log("\n#{command.help}")
-		else if command.description?
-			console.log("\n#{_.capitalize(command.description)}")
-
-		if not _.isEmpty(command.options)
-			console.log('\nOptions:\n')
-			print(parse(command.options))
-
-		return done()
-
-exports.help =
-	signature: 'help [command...]'
-	description: 'show help'
-	help: '''
-		Get detailed help for an specific command.
-
-		Examples:
-
-			$ balena help apps
-			$ balena help os download
-	'''
-	primary: true
-	options: [
-		signature: 'verbose'
-		description: 'show additional commands'
-		boolean: true
-		alias: 'v'
-	]
-	action: (params, options, done) ->
-		if params.command?
-			command(params, options, done)
-		else
-			general(params, options, done)

lib/actions/index.coffee

@@ -1,42 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-module.exports =
-	wizard: require('./wizard')
-	apiKey: require('./api-key')
-	app: require('./app')
-	auth: require('./auth')
-	info: require('./info')
-	device: require('./device')
-	env: require('./environment-variables')
-	keys: require('./keys')
-	logs: require('./logs')
-	local: require('./local')
-	notes: require('./notes')
-	help: require('./help')
-	os: require('./os')
-	settings: require('./settings')
-	config: require('./config')
-	sync: require('./sync')
-	ssh: require('./ssh')
-	internal: require('./internal')
-	build: require('./build')
-	deploy: require('./deploy')
-	util: require('./util')
-	preload: require('./preload')
-	push: require('./push')
-	join: require('./join')
-	leave: require('./leave')

lib/actions/info.ts

@@ -1,30 +0,0 @@
-/*
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-import { CommandDefinition } from 'capitano';
-
-export const version: CommandDefinition = {
-	signature: 'version',
-	description: 'output the version number',
-	help: `\
-Display the balena CLI version.\
-`,
-	async action(_params, _options, done) {
-		const packageJSON = await import('../../package.json');
-		console.log(packageJSON.version);
-		return done();
-	},
-};

lib/actions/internal.coffee

@@ -1,88 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-# These are internal commands we want to be runnable from the outside
-# One use-case for this is spawning the minimal operation with root priviledges
-
-exports.osInit =
-	signature: 'internal osinit <image> <type> <config>'
-	description: 'do actual init of the device with the preconfigured os image'
-	help: '''
-		Don't use this command directly! Use `balena os initialize <image>` instead.
-	'''
-	hidden: true
-	root: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		init = require('balena-device-init')
-		helpers = require('../utils/helpers')
-
-		configPromise = Promise.try -> JSON.parse(params.config)
-		manifestPromise = helpers.getManifest(params.image, params.type)
-		Promise.join configPromise, manifestPromise, (config, manifest) ->
-			init.initialize(params.image, manifest, config)
-		.then(helpers.osProgressHandler)
-		.nodeify(done)
-
-exports.scanDevices =
-	signature: 'internal scandevices'
-	description: 'scan for local balena-enabled devices and show a picker to choose one'
-	help: '''
-		Don't use this command directly!
-	'''
-	hidden: true
-	root: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		{ forms } = require('balena-sync')
-
-		return Promise.try ->
-			forms.selectLocalBalenaOsDevice()
-			.then (hostnameOrIp) ->
-				console.error("==> Selected device: #{hostnameOrIp}")
-		.nodeify(done)
-
-exports.sudo =
-	signature: 'internal sudo <command>'
-	description: 'execute arbitrary commands in a privileged subprocess'
-	help: '''
-		Don't use this command directly!
-
-		<command> must be passed as a single argument. That means, you need to make sure
-		you enclose <command> in quotes (eg. balena internal sudo 'ls -alF') if for
-		whatever reason you invoke the command directly or, typically, pass <command>
-		as a single argument to spawn (eg. `spawn('balena', [ 'internal', 'sudo', 'ls -alF' ])`).
-
-		Furthermore, this command will naively split <command> on whitespace and directly
-		forward the parts as arguments to `sudo`, so be careful.
-	'''
-	hidden: true
-	action: (params, options, done) ->
-		os = require('os')
-		Promise = require('bluebird')
-
-		return Promise.try ->
-			if os.platform() is 'win32'
-				windosu = require('windosu')
-				windosu.exec(params.command, {})
-			else
-				{ spawn } = require('child_process')
-				{ wait } = require('rindle')
-				cmd = params.command.split(' ')
-				ps = spawn('sudo', cmd, stdio: 'inherit', env: process.env)
-				wait(ps)
-
-		.nodeify(done)

lib/actions/join.ts

@@ -1,74 +0,0 @@
-/*
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-import * as Bluebird from 'bluebird';
-import { CommandDefinition } from 'capitano';
-import { stripIndent } from 'common-tags';
-
-interface Args {
-	deviceIp?: string;
-}
-
-interface Options {
-	application?: string;
-}
-
-export const join: CommandDefinition<Args, Options> = {
-	signature: 'join [deviceIp]',
-	description:
-		'Promote a local device running balenaOS to join an application on a balena server',
-	help: stripIndent`
-		Use this command to move a local device to an application on another balena server.
-
-		For example, you could provision a device against an openBalena installation
-		where you perform end-to-end tests and then move it to balenaCloud when it's
-		ready for production.
-
-		Moving a device between applications on the same server is not supported.
-
-		If you don't specify a device hostname or IP, this command will automatically
-		scan the local network for balenaOS devices and prompt you to select one
-		from an interactive picker. This usually requires root privileges.
-
-		Examples:
-
-			$ balena join
-			$ balena join balena.local
-			$ balena join balena.local --application MyApp
-			$ balena join 192.168.1.25
-			$ balena join 192.168.1.25 --application MyApp
-	`,
-	options: [
-		{
-			signature: 'application',
-			parameter: 'application',
-			alias: 'a',
-			description: 'The name of the application the device should join',
-		},
-	],
-
-	primary: true,
-
-	async action(params, options, done) {
-		const balena = await import('balena-sdk');
-		const Logger = await import('../utils/logger');
-		const promote = await import('../utils/promote');
-		const sdk = balena.fromSharedOptions();
-		const logger = new Logger();
-		return Bluebird.try(() => {
-			return promote.join(logger, sdk, params.deviceIp, options.application);
-		}).nodeify(done);
-	},
-};

lib/actions/keys.coffee

@@ -1,123 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-commandOptions = require('./command-options')
-
-exports.list =
-	signature: 'keys'
-	description: 'list all ssh keys'
-	help: '''
-		Use this command to list all your SSH keys.
-
-		Examples:
-
-			$ balena keys
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		visuals = require('resin-cli-visuals')
-
-		balena.models.key.getAll().then (keys) ->
-			console.log visuals.table.horizontal keys, [
-				'id'
-				'title'
-			]
-		.nodeify(done)
-
-exports.info =
-	signature: 'key <id>'
-	description: 'list a single ssh key'
-	help: '''
-		Use this command to show information about a single SSH key.
-
-		Examples:
-
-			$ balena key 17
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		visuals = require('resin-cli-visuals')
-
-		balena.models.key.get(params.id).then (key) ->
-			console.log visuals.table.vertical key, [
-				'id'
-				'title'
-			]
-
-			# Since the public key string is long, it might
-			# wrap to lines below, causing the table layout to break.
-			# See https://github.com/balena-io/balena-cli/issues/151
-			console.log('\n' + key.public_key)
-		.nodeify(done)
-
-exports.remove =
-	signature: 'key rm <id>'
-	description: 'remove a ssh key'
-	help: '''
-		Use this command to remove a SSH key from balena.
-
-		Notice this command asks for confirmation interactively.
-		You can avoid this by passing the `--yes` boolean option.
-
-		Examples:
-
-			$ balena key rm 17
-			$ balena key rm 17 --yes
-	'''
-	options: [ commandOptions.yes ]
-	permission: 'user'
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		patterns = require('../utils/patterns')
-
-		patterns.confirm(options.yes, 'Are you sure you want to delete the key?').then ->
-			balena.models.key.remove(params.id)
-		.nodeify(done)
-
-exports.add =
-	signature: 'key add <name> [path]'
-	description: 'add a SSH key to balena'
-	help: '''
-		Use this command to associate a new SSH key with your account.
-
-		If `path` is omitted, the command will attempt
-		to read the SSH key from stdin.
-
-		Examples:
-
-			$ balena key add Main ~/.ssh/id_rsa.pub
-			$ cat ~/.ssh/id_rsa.pub | balena key add Main
-	'''
-	permission: 'user'
-	action: (params, options, done) ->
-		_ = require('lodash')
-		Promise = require('bluebird')
-		readFileAsync = Promise.promisify(require('fs').readFile)
-		capitano = require('capitano')
-		balena = require('balena-sdk').fromSharedOptions()
-
-		Promise.try ->
-			return readFileAsync(params.path, encoding: 'utf8') if params.path?
-
-			# TODO: should this be promisified for consistency?
-			Promise.fromNode (callback) ->
-				capitano.utils.getStdin (data) ->
-					return callback(null, data)
-
-		.then(_.partial(balena.models.key.create, params.name))
-		.nodeify(done)

lib/actions/leave.ts

@@ -1,59 +0,0 @@
-/*
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-import * as Bluebird from 'bluebird';
-import { CommandDefinition } from 'capitano';
-import { stripIndent } from 'common-tags';
-
-interface Args {
-	deviceIp?: string;
-}
-
-export const leave: CommandDefinition<Args, {}> = {
-	signature: 'leave [deviceIp]',
-	description: 'Detach a local device from its balena application',
-	help: stripIndent`
-		Use this command to make a local device leave the balena server it is
-		provisioned on. This effectively makes the device "unmanaged".
-
-		The device entry on the server is preserved after running this command,
-		so the device can subsequently re-join the server if needed.
-
-		If you don't specify a device hostname or IP, this command will automatically
-		scan the local network for balenaOS devices and prompt you to select one
-		from an interactive picker. This usually requires root privileges.
-
-		Examples:
-
-			$ balena leave
-			$ balena leave balena.local
-			$ balena leave 192.168.1.25
-	`,
-	options: [],
-
-	permission: 'user',
-	primary: true,
-
-	async action(params, _options, done) {
-		const balena = await import('balena-sdk');
-		const Logger = await import('../utils/logger');
-		const promote = await import('../utils/promote');
-		const sdk = balena.fromSharedOptions();
-		const logger = new Logger();
-		return Bluebird.try(() => {
-			return promote.leave(logger, sdk, params.deviceIp);
-		}).nodeify(done);
-	},
-};

lib/actions/local/common.coffee

@@ -1,62 +0,0 @@
-Promise = require('bluebird')
-_ = require('lodash')
-form = require('resin-cli-form')
-chalk = require('chalk')
-
-dockerUtils = require('../../utils/docker')
-{ exitWithExpectedError } = require('../../utils/patterns')
-
-exports.dockerPort = dockerPort = 2375
-exports.dockerTimeout = dockerTimeout = 2000
-
-exports.filterOutSupervisorContainer = filterOutSupervisorContainer = (container) ->
-	for name in container.Names
-		return false if (name.includes('resin_supervisor') or name.includes('balena_supervisor'))
-	return true
-
-exports.selectContainerFromDevice = Promise.method (deviceIp, filterSupervisor = false) ->
-	docker = dockerUtils.createClient(host: deviceIp, port: dockerPort, timeout: dockerTimeout)
-
-	# List all containers, including those not running
-	docker.listContainersAsync(all: true)
-	.filter (container) ->
-		return true if not filterSupervisor
-		filterOutSupervisorContainer(container)
-	.then (containers) ->
-		if _.isEmpty(containers)
-			exitWithExpectedError("No containers found in #{deviceIp}")
-
-		return form.ask
-			message: 'Select a container'
-			type: 'list'
-			choices: _.map containers, (container) ->
-				containerName = container.Names?[0] or 'Untitled'
-				shortContainerId = ('' + container.Id).substr(0, 11)
-
-				return {
-					name: "#{containerName} (#{shortContainerId})"
-					value: container.Id
-				}
-
-exports.pipeContainerStream = Promise.method ({ deviceIp, name, outStream, follow = false }) ->
-	docker = dockerUtils.createClient(host: deviceIp, port: dockerPort)
-
-	container = docker.getContainer(name)
-	container.inspectAsync()
-	.then (containerInfo) ->
-		return containerInfo?.State?.Running
-	.then (isRunning) ->
-		container.attachAsync
-			logs: not follow or not isRunning
-			stream: follow and isRunning
-			stdout: true
-			stderr: true
-	.then (containerStream) ->
-		containerStream.pipe(outStream)
-	.catch (err) ->
-		err = '' + err.statusCode
-		if err is '404'
-			return console.log(chalk.red.bold("Container '#{name}' not found."))
-		throw err
-
-exports.getSubShellCommand = require('../../utils/helpers').getSubShellCommand

lib/actions/local/configure.coffee

@@ -1,230 +0,0 @@
-###
-Copyright 2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-BOOT_PARTITION = 1
-CONNECTIONS_FOLDER = '/system-connections'
-
-getConfigurationSchema = (connnectionFileName = 'resin-wifi') ->
-	mapper: [
-		{
-			template:
-				persistentLogging: '{{persistentLogging}}'
-			domain: [
-				[ 'config_json', 'persistentLogging' ]
-			]
-		}
-		{
-			template:
-				hostname: '{{hostname}}'
-			domain: [
-				[ 'config_json', 'hostname' ]
-			]
-		}
-		{
-			template:
-				wifi:
-					ssid: '{{networkSsid}}'
-				'wifi-security':
-					psk: '{{networkKey}}'
-			domain: [
-				[ 'system_connections', connnectionFileName, 'wifi' ]
-				[ 'system_connections', connnectionFileName, 'wifi-security' ]
-			]
-		}
-	]
-	files:
-		system_connections:
-			fileset: true
-			type: 'ini'
-			location:
-				path: CONNECTIONS_FOLDER.slice(1)
-				# Reconfix still uses the older resin-image-fs, so still needs an
-				# object-based partition definition.
-				partition: BOOT_PARTITION
-		config_json:
-			type: 'json'
-			location:
-				path: 'config.json'
-				partition: BOOT_PARTITION
-
-inquirerOptions = (data) -> [
-	{
-		message: 'Network SSID'
-		type: 'input'
-		name: 'networkSsid'
-		default: data.networkSsid
-	}
-	{
-		message: 'Network Key'
-		type: 'input'
-		name: 'networkKey'
-		default: data.networkKey
-	}
-	{
-		message: 'Do you want to set advanced settings?'
-		type: 'confirm'
-		name: 'advancedSettings'
-		default: false
-	}
-	{
-		message: 'Device Hostname'
-		type: 'input'
-		name: 'hostname'
-		default: data.hostname,
-		when: (answers) ->
-			answers.advancedSettings
-	}
-	{
-		message: 'Do you want to enable persistent logging?'
-		type: 'confirm'
-		name: 'persistentLogging'
-		default: data.persistentLogging
-		when: (answers) ->
-			answers.advancedSettings
-	}
-]
-
-getConfiguration = (data) ->
-	_ = require('lodash')
-	inquirer = require('inquirer')
-
-	# `persistentLogging` can be `undefined`, so we want
-	# to make sure that case defaults to `false`
-	data = _.assign data,
-		persistentLogging: data.persistentLogging or false
-
-	inquirer.prompt(inquirerOptions(data))
-	.then (answers) ->
-		return _.merge(data, answers)
-
-# Taken from https://goo.gl/kr1kCt
-CONNECTION_FILE = '''
-	[connection]
-	id=resin-wifi
-	type=wifi
-
-	[wifi]
-	hidden=true
-	mode=infrastructure
-	ssid=My_Wifi_Ssid
-
-	[wifi-security]
-	auth-alg=open
-	key-mgmt=wpa-psk
-	psk=super_secret_wifi_password
-
-	[ipv4]
-	method=auto
-
-	[ipv6]
-	addr-gen-mode=stable-privacy
-	method=auto
-'''
-
-###
-* if the `resin-wifi` file exists (previously configured image or downloaded from the UI) it's used and reconfigured
-* if the `resin-sample.ignore` exists it's copied to `resin-wifi`
-* if the `resin-sample` exists it's reconfigured (legacy mode, will be removed eventually)
-* otherwise, the new file is created
-###
-prepareConnectionFile = (target) ->
-	_ = require('lodash')
-	imagefs = require('resin-image-fs')
-
-	imagefs.listDirectory
-		image: target
-		partition: BOOT_PARTITION
-		path: CONNECTIONS_FOLDER
-	.then (files) ->
-		# The required file already exists
-		if _.includes(files, 'resin-wifi')
-			return null
-
-		# Fresh image, new mode, accoding to https://github.com/balena-os/meta-balena/pull/770/files
-		if _.includes(files, 'resin-sample.ignore')
-			return imagefs.copy
-				image: target
-				partition: BOOT_PARTITION
-				path: "#{CONNECTIONS_FOLDER}/resin-sample.ignore"
-			,
-				image: target
-				partition: BOOT_PARTITION
-				path: "#{CONNECTIONS_FOLDER}/resin-wifi"
-			.thenReturn(null)
-
-		# Legacy mode, to be removed later
-		# We return the file name override from this branch
-		# When it is removed the following cleanup should be done:
-		# * delete all the null returns from this method
-		# * turn `getConfigurationSchema` back into the constant, with the connection filename always being `resin-wifi`
-		# * drop the final `then` from this method
-		# * adapt the code in the main listener to not receive the config from this method, and use that constant instead
-		if _.includes(files, 'resin-sample')
-			return 'resin-sample'
-
-		# In case there's no file at all (shouldn't happen normally, but the file might have been removed)
-		return imagefs.writeFile
-			image: target
-			partition: BOOT_PARTITION
-			path: "#{CONNECTIONS_FOLDER}/resin-wifi"
-		, CONNECTION_FILE
-		.thenReturn(null)
-
-	.then (connectionFileName) ->
-		return getConfigurationSchema(connectionFileName)
-
-removeHostname = (schema) ->
-	_ = require('lodash')
-	schema.mapper = _.reject schema.mapper, (mapper) ->
-		_.isEqual(Object.keys(mapper.template), ['hostname'])
-
-module.exports =
-	signature: 'local configure <target>'
-	description: '(Re)configure a balenaOS drive or image'
-	help: '''
-		Use this command to configure or reconfigure a balenaOS drive or image.
-
-		Examples:
-
-			$ balena local configure /dev/sdc
-			$ balena local configure path/to/image.img
-	'''
-	root: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		umount = require('umount')
-		umountAsync = Promise.promisify(umount.umount)
-		isMountedAsync = Promise.promisify(umount.isMounted)
-		reconfix = require('reconfix')
-		denymount = Promise.promisify(require('denymount'))
-
-		prepareConnectionFile(params.target)
-		.tap ->
-			isMountedAsync(params.target).then (isMounted) ->
-				return if not isMounted
-				umountAsync(params.target)
-		.then (configurationSchema) ->
-			denymount params.target, (cb) ->
-				reconfix.readConfiguration(configurationSchema, params.target)
-				.then(getConfiguration)
-				.then (answers) ->
-					if not answers.hostname
-						removeHostname(configurationSchema)
-					reconfix.writeConfiguration(configurationSchema, answers, params.target)
-				.asCallback(cb)
-		.then ->
-			console.log('Done!')
-		.asCallback(done)

lib/actions/local/flash.coffee

@@ -1,120 +0,0 @@
-###
-Copyright 2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the 'License');
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-	 http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an 'AS IS' BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-module.exports =
-	signature: 'local flash <image>'
-	description: 'Flash an image to a drive'
-	help: '''
-		Use this command to flash a balenaOS image to a drive.
-
-		Examples:
-
-			$ balena local flash path/to/balenaos.img
-			$ balena local flash path/to/balenaos.img --drive /dev/disk2
-			$ balena local flash path/to/balenaos.img --drive /dev/disk2 --yes
-	'''
-	options: [
-			signature: 'yes'
-			boolean: true
-			description: 'confirm non-interactively'
-			alias: 'y'
-	,
-			signature: 'drive'
-			parameter: 'drive'
-			description: 'drive'
-			alias: 'd'
-	]
-	root: true
-	action: (params, options, done) ->
-
-		_ = require('lodash')
-		os = require('os')
-		Promise = require('bluebird')
-		umountAsync = Promise.promisify(require('umount').umount)
-		fs = Promise.promisifyAll(require('fs'))
-		driveListAsync = Promise.promisify(require('drivelist').list)
-		chalk = require('chalk')
-		visuals = require('resin-cli-visuals')
-		form = require('resin-cli-form')
-		imageWrite = require('etcher-image-write')
-
-		form.run [
-			{
-				message: 'Select drive'
-				type: 'drive'
-				name: 'drive'
-			},
-			{
-				message: 'This will erase the selected drive. Are you sure?'
-				type: 'confirm'
-				name: 'yes'
-				default: false
-			}
-		],
-			override:
-				drive: options.drive
-
-				# If `options.yes` is `false`, pass `undefined`,
-				# otherwise the question will not be asked because
-				# `false` is a defined value.
-				yes: options.yes || undefined
-
-		# TODO: dedupe with the resin-device-operations
-		.then (answers) ->
-			if answers.yes isnt true
-				console.log(chalk.red.bold('Aborted image flash'))
-				process.exit(0)
-
-			driveListAsync().then (drives) ->
-				selectedDrive = _.find(drives, device: answers.drive)
-
-				if not selectedDrive?
-					throw new Error("Drive not found: #{answers.drive}")
-
-				return selectedDrive
-		.then (selectedDrive) ->
-			progressBars =
-				write: new visuals.Progress('Flashing')
-				check: new visuals.Progress('Validating')
-
-			umountAsync(selectedDrive.device).then ->
-				Promise.props
-					imageSize: fs.statAsync(params.image).get('size'),
-					imageStream: Promise.resolve(fs.createReadStream(params.image))
-					driveFileDescriptor: fs.openAsync(selectedDrive.raw, 'rs+')
-			.then (results) ->
-				imageWrite.write
-					fd: results.driveFileDescriptor
-					device: selectedDrive.raw
-					size: selectedDrive.size
-				,
-					stream: results.imageStream,
-					size: results.imageSize
-				,
-					check: true
-			.then (writer) ->
-				new Promise (resolve, reject) ->
-					writer.on 'progress', (state) ->
-						progressBars[state.type].update(state)
-					writer.on('error', reject)
-					writer.on('done', resolve)
-			.then ->
-				if (os.platform() is 'win32') and selectedDrive.mountpoint?
-					ejectAsync = Promise.promisify(require('removedrive').eject)
-					return ejectAsync(selectedDrive.mountpoint)
-
-				return umountAsync(selectedDrive.device)
-		.asCallback(done)

lib/actions/local/index.coffee

@@ -1,23 +0,0 @@
-###
-Copyright 2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-exports.configure = require('./configure')
-exports.flash = require('./flash')
-exports.logs = require('./logs')
-exports.scan = require('./scan')
-exports.ssh = require('./ssh')
-exports.push = require('./push')
-exports.stop = require('./stop')

lib/actions/local/logs.coffee

@@ -1,66 +0,0 @@
-###
-Copyright 2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-	 http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-# A function to reliably execute a command
-# in all supported operating systems, including
-# different Windows environments like `cmd.exe`
-# and `Cygwin` should be encapsulated in a
-# re-usable package.
-#
-module.exports =
-	signature: 'local logs [deviceIp]'
-	description: 'Get or attach to logs of a running container on a balenaOS device'
-	help: '''
-
-		Examples:
-
-			$ balena local logs
-			$ balena local logs -f
-			$ balena local logs 192.168.1.10
-			$ balena local logs 192.168.1.10 -f
-			$ balena local logs 192.168.1.10 -f --app-name myapp
-	'''
-	options: [
-			signature: 'follow'
-			boolean: true
-			description: 'follow log'
-			alias: 'f'
-	,
-			signature: 'app-name'
-			parameter: 'name'
-			description: 'name of container to get logs from'
-			alias: 'a'
-	]
-	root: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		{ forms } = require('balena-sync')
-		{ selectContainerFromDevice, pipeContainerStream } = require('./common')
-
-		Promise.try ->
-			if not params.deviceIp?
-				return forms.selectLocalBalenaOsDevice()
-			return params.deviceIp
-		.then (@deviceIp) =>
-			if not options['app-name']?
-				return selectContainerFromDevice(@deviceIp)
-			return options['app-name']
-		.then (appName) =>
-			pipeContainerStream
-				deviceIp: @deviceIp
-				name: appName
-				outStream: process.stdout
-				follow: options['follow']

lib/actions/local/push.coffee

@@ -1,78 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-# Loads '.balena-sync.yml' configuration from 'source' directory.
-# Returns the configuration object on success
-#
-
-_ = require('lodash')
-
-balenaPush = require('balena-sync').capitano('balena-toolbox')
-
-# TODO: This is a temporary workaround to reuse the existing `rdt push`
-# capitano frontend in `balena local push`.
-
-balenaPushHelp = '''
-	Warning: 'balena local push' requires an openssh-compatible client and 'rsync' to
-	be correctly installed in your shell environment. For more information (including
-	Windows support) please check the README here: https://github.com/balena-io/balena-cli
-
-	Use this command to push your local changes to a container on a LAN-accessible balenaOS device on the fly.
-
-	If `Dockerfile` or any file in the 'build-triggers' list is changed,
-	a new container will be built and run on your device.
-	If not, changes will simply be synced with `rsync` into the application container.
-
-	After every 'balena local push' the updated settings will be saved in
-	'<source>/.balena-sync.yml' and will be used in later invocations. You can
-	also change any option by editing '.balena-sync.yml' directly.
-
-	Here is an example '.balena-sync.yml' :
-
-		$ cat $PWD/.balena-sync.yml
-		local_balenaos:
-			app-name: local-app
-			build-triggers:
-				- Dockerfile: file-hash-abcdefabcdefabcdefabcdefabcdefabcdef
-				- package.json: file-hash-abcdefabcdefabcdefabcdefabcdefabcdef
-			environment:
-				- MY_VARIABLE=123
-
-
-	Command line options have precedence over the ones saved in '.balena-sync.yml'.
-
-	If '.gitignore' is found in the source directory then all explicitly listed files will be
-	excluded when using rsync to update the container. You can choose to change this default behavior with the
-	'--skip-gitignore' option.
-
-	Examples:
-
-		$ balena local push
-		$ balena local push --app-name test-server --build-triggers package.json,requirements.txt
-		$ balena local push --force-build
-		$ balena local push --force-build --skip-logs
-		$ balena local push --ignore lib/
-		$ balena local push --verbose false
-		$ balena local push 192.168.2.10 --source . --destination /usr/src/app
-		$ balena local push 192.168.2.10 -s /home/user/balenaProject -d /usr/src/app --before 'echo Hello' --after 'echo Done'
-'''
-
-
-module.exports = _.assign balenaPush,
-	signature: 'local push [deviceIp]'
-	help: balenaPushHelp
-	primary: true
-	root: true

lib/actions/local/scan.coffee

@@ -1,100 +0,0 @@
-###
-Copyright 2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-	 http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-dockerInfoProperties = [
-	'Containers'
-	'ContainersRunning'
-	'ContainersPaused'
-	'ContainersStopped'
-	'Images'
-	'Driver'
-	'SystemTime'
-	'KernelVersion'
-	'OperatingSystem'
-	'Architecture'
-]
-
-dockerVersionProperties = [
-	'Version'
-	'ApiVersion'
-]
-
-module.exports =
-	signature: 'local scan'
-	description: 'Scan for balenaOS devices in your local network'
-	help: '''
-
-		Examples:
-
-			$ balena local scan
-			$ balena local scan --timeout 120
-			$ balena local scan --verbose
-	'''
-	options: [
-		signature: 'verbose'
-		boolean: true
-		description: 'Display full info'
-		alias: 'v'
-	,
-		signature: 'timeout'
-		parameter: 'timeout'
-		description: 'Scan timeout in seconds'
-		alias: 't'
-	]
-	primary: true
-	root: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		_ = require('lodash')
-		prettyjson = require('prettyjson')
-		{ discover } = require('balena-sync')
-		{ SpinnerPromise } = require('resin-cli-visuals')
-		{ dockerPort, dockerTimeout } = require('./common')
-		dockerUtils = require('../../utils/docker')
-		{ exitWithExpectedError } = require('../../utils/patterns')
-
-		if options.timeout?
-			options.timeout *= 1000
-
-		Promise.try ->
-			new SpinnerPromise
-				promise: discover.discoverLocalBalenaOsDevices(options.timeout)
-				startMessage: 'Scanning for local balenaOS devices..'
-				stopMessage: 'Reporting scan results'
-		.filter ({ address }) ->
-			Promise.try ->
-				docker = dockerUtils.createClient(host: address, port: dockerPort, timeout: dockerTimeout)
-				docker.pingAsync()
-			.return(true)
-			.catchReturn(false)
-		.tap (devices) ->
-			if _.isEmpty(devices)
-				exitWithExpectedError('Could not find any balenaOS devices in the local network')
-		.map ({ host, address }) ->
-			docker = dockerUtils.createClient(host: address, port: dockerPort, timeout: dockerTimeout)
-			Promise.props
-				dockerInfo: docker.infoAsync().catchReturn('Could not get Docker info')
-				dockerVersion: docker.versionAsync().catchReturn('Could not get Docker version')
-			.then ({ dockerInfo, dockerVersion }) ->
-
-				if not options.verbose
-					dockerInfo = _.pick(dockerInfo, dockerInfoProperties) if _.isObject(dockerInfo)
-					dockerVersion = _.pick(dockerVersion, dockerVersionProperties) if _.isObject(dockerVersion)
-
-				return { host, address, dockerInfo, dockerVersion }
-		.then (devicesInfo) ->
-			console.log(prettyjson.render(devicesInfo, noColor: true))
-		.nodeify(done)

lib/actions/local/ssh.coffee

@@ -1,114 +0,0 @@
-###
-Copyright 2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-	 http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-{ hostOSAccess } = require('../command-options')
-_ = require('lodash')
-
-localHostOSAccessOption = _.cloneDeep(hostOSAccess)
-localHostOSAccessOption.description = 'get a shell into the host OS'
-
-module.exports =
-	signature: 'local ssh [deviceIp]'
-	description: 'Get a shell into a balenaOS device'
-	help: '''
-		Warning: 'balena local ssh' requires an openssh-compatible client to be correctly
-		installed in your shell environment. For more information (including Windows
-		support) please check the README here: https://github.com/balena-io/balena-cli
-
-		Use this command to get a shell into the running application container of
-		your device.
-
-		The '--host' option will get you a shell into the Host OS of the balenaOS device.
-		No option will return a list of containers to enter or you can explicitly select
-		one by passing its name to the --container option
-
-		Examples:
-
-			$ balena local ssh
-			$ balena local ssh --host
-			$ balena local ssh --container chaotic_water
-			$ balena local ssh --container chaotic_water --port 22222
-			$ balena local ssh --verbose
-	'''
-	options: [
-			signature: 'verbose'
-			boolean: true
-			description: 'increase verbosity'
-			alias: 'v'
-	,
-	localHostOSAccessOption,
-			signature: 'container'
-			parameter: 'container'
-			default: null
-			description: 'name of container to access'
-			alias: 'c'
-	,
-			signature: 'port'
-			parameter: 'port'
-			description: 'ssh port number (default: 22222)'
-			alias: 'p'
-	]
-	root: true
-	action: (params, options, done) ->
-		child_process = require('child_process')
-		Promise = require 'bluebird'
-		_ = require('lodash')
-		{ forms } = require('balena-sync')
-
-		{ selectContainerFromDevice, getSubShellCommand } = require('./common')
-		{ exitWithExpectedError } = require('../../utils/patterns')
-
-		if (options.host is true and options.container?)
-			exitWithExpectedError('Please pass either --host or --container option')
-
-		if not options.port?
-			options.port = 22222
-
-		verbose = if options.verbose then '-vvv' else ''
-
-		Promise.try ->
-			if not params.deviceIp?
-				return forms.selectLocalBalenaOsDevice()
-			return params.deviceIp
-		.then (deviceIp) ->
-			_.assign(options, { deviceIp })
-
-			return if options.host
-
-			if not options.container?
-				return selectContainerFromDevice(deviceIp)
-
-			return options.container
-		.then (container) ->
-
-			command = "ssh \
-				#{verbose} \
-				-t \
-				-p #{options.port} \
-				-o LogLevel=ERROR \
-				-o StrictHostKeyChecking=no \
-				-o UserKnownHostsFile=/dev/null \
-				 root@#{options.deviceIp}"
-
-			if not options.host
-				shellCmd = '''/bin/sh -c $"'if [ -e /bin/bash ]; then exec /bin/bash; else exec /bin/sh; fi'"'''
-				dockerCmd = "'$(if [ -f /usr/bin/balena ]; then echo \"balena\"; else echo \"docker\"; fi)'"
-				command += " #{dockerCmd} exec -ti #{container} #{shellCmd}"
-
-			subShellCommand = getSubShellCommand(command)
-			child_process.spawn subShellCommand.program, subShellCommand.args,
-				stdio: 'inherit'
-		.nodeify(done)

lib/actions/local/stop.coffee

@@ -1,79 +0,0 @@
-###
-Copyright 2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-	 http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-# A function to reliably execute a command
-# in all supported operating systems, including
-# different Windows environments like `cmd.exe`
-# and `Cygwin` should be encapsulated in a
-# re-usable package.
-#
-module.exports =
-	signature: 'local stop [deviceIp]'
-	description: 'Stop a running container on a balenaOS device'
-	help: '''
-
-		Examples:
-
-			$ balena local stop
-			$ balena local stop --app-name myapp
-			$ balena local stop --all
-			$ balena local stop 192.168.1.10
-			$ balena local stop 192.168.1.10 --app-name myapp
-	'''
-	options: [
-			signature: 'all'
-			boolean: true
-			description: 'stop all containers'
-	,
-			signature: 'app-name'
-			parameter: 'name'
-			description: 'name of container to stop'
-			alias: 'a'
-	]
-	root: true
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		chalk = require('chalk')
-		{ forms, config, BalenaLocalDockerUtils } = require('balena-sync')
-		{ selectContainerFromDevice, filterOutSupervisorContainer } = require('./common')
-
-		Promise.try ->
-			if not params.deviceIp?
-				return forms.selectLocalBalenaOsDevice()
-			return params.deviceIp
-		.then (@deviceIp) =>
-			@docker = new BalenaLocalDockerUtils(@deviceIp)
-
-			if options.all
-				# Only list running containers
-				return @docker.docker.listContainersAsync(all: false)
-				.filter(filterOutSupervisorContainer)
-				.then (containers) =>
-					Promise.map containers, ({ Names, Id }) =>
-						console.log(chalk.yellow.bold("* Stopping container #{Names[0]}"))
-						@docker.stopContainer(Id)
-
-			ymlConfig = config.load()
-			@appName = options['app-name'] ? ymlConfig['local_balenaos']?['app-name']
-			@docker.checkForRunningContainer(@appName)
-			.then (isRunning) =>
-				if not isRunning
-					return selectContainerFromDevice(@deviceIp, true)
-
-				console.log(chalk.yellow.bold("* Stopping container #{@appName}"))
-				return @appName
-			.then (runningContainerName) =>
-				@docker.stopContainer(runningContainerName)

lib/actions/logs.coffee

@@ -1,61 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-{ normalizeUuidProp } = require('../utils/normalization')
-
-module.exports =
-	signature: 'logs <uuid>'
-	description: 'show device logs'
-	help: '''
-		Use this command to show logs for a specific device.
-
-		By default, the command prints all log messages and exit.
-
-		To continuously stream output, and see new logs in real time, use the `--tail` option.
-
-		Examples:
-
-			$ balena logs 23c73a1
-			$ balena logs 23c73a1
-	'''
-	options: [
-		{
-			signature: 'tail'
-			description: 'continuously stream output'
-			boolean: true
-			alias: 't'
-		}
-	]
-	permission: 'user'
-	primary: true
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		balena = require('balena-sdk').fromSharedOptions()
-		moment = require('moment')
-
-		printLine = (line) ->
-			timestamp = moment(line.timestamp).format('DD.MM.YY HH:mm:ss (ZZ)')
-			console.log("#{timestamp} #{line.message}")
-
-		if options.tail
-			balena.logs.subscribe(params.uuid, { count: 100 }).then (logs) ->
-				logs.on('line', printLine)
-				logs.on('error', done)
-			.catch(done)
-		else
-			balena.logs.history(params.uuid)
-			.each(printLine)
-			.catch(done)

lib/actions/notes.coffee

@@ -1,55 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-{ normalizeUuidProp } = require('../utils/normalization')
-
-exports.set =
-	signature: 'note <|note>'
-	description: 'set a device note'
-	help: '''
-		Use this command to set or update a device note.
-
-		If note command isn't passed, the tool attempts to read from `stdin`.
-
-		To view the notes, use $ balena device <uuid>.
-
-		Examples:
-
-			$ balena note "My useful note" --device 7cf02a6
-			$ cat note.txt | balena note --device 7cf02a6
-	'''
-	options: [
-		signature: 'device'
-		parameter: 'device'
-		description: 'device uuid'
-		alias: [ 'd', 'dev' ]
-		required: 'You have to specify a device'
-	]
-	permission: 'user'
-	action: (params, options, done) ->
-		normalizeUuidProp(options, 'device')
-		Promise = require('bluebird')
-		_ = require('lodash')
-		balena = require('balena-sdk').fromSharedOptions()
-
-		{ exitWithExpectedError } = require('../utils/patterns')
-
-		Promise.try ->
-			if _.isEmpty(params.note)
-				exitWithExpectedError('Missing note content')
-
-			balena.models.device.note(options.device, params.note)
-		.nodeify(done)

lib/actions/os.coffee

@@ -1,386 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-commandOptions = require('./command-options')
-_ = require('lodash')
-{ normalizeUuidProp } = require('../utils/normalization')
-
-formatVersion = (v, isRecommended) ->
-	result = "v#{v}"
-	if isRecommended
-		result += ' (recommended)'
-	return result
-
-resolveVersion = (deviceType, version) ->
-	if version isnt 'menu'
-		if version[0] == 'v'
-			version = version.slice(1)
-		return Promise.resolve(version)
-
-	form = require('resin-cli-form')
-	balena = require('balena-sdk').fromSharedOptions()
-
-	balena.models.os.getSupportedVersions(deviceType)
-	.then ({ versions, recommended }) ->
-		choices = versions.map (v) ->
-			value: v
-			name: formatVersion(v, v is recommended)
-
-		return form.ask
-			message: 'Select the OS version:'
-			type: 'list'
-			choices: choices
-			default: recommended
-
-exports.versions =
-	signature: 'os versions <type>'
-	description: 'show the available balenaOS versions for the given device type'
-	help: '''
-		Use this command to show the available balenaOS versions for a certain device type.
-		Check available types with `balena devices supported`
-
-		Example:
-
-			$ balena os versions raspberrypi3
-	'''
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-
-		balena.models.os.getSupportedVersions(params.type)
-		.then ({ versions, recommended }) ->
-			versions.forEach (v) ->
-				console.log(formatVersion(v, v is recommended))
-
-exports.download =
-	signature: 'os download <type>'
-	description: 'download an unconfigured os image'
-	help: '''
-		Use this command to download an unconfigured os image for a certain device type.
-		Check available types with `balena devices supported`
-
-		If version is not specified the newest stable (non-pre-release) version of OS
-		is downloaded if available, or the newest version otherwise (if all existing
-		versions for the given device type are pre-release).
-
-		You can pass `--version menu` to pick the OS version from the interactive menu
-		of all available versions.
-
-		Examples:
-
-			$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img
-			$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 1.24.1
-			$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version ^1.20.0
-			$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version latest
-			$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version default
-			$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version menu
-	'''
-	permission: 'user'
-	options: [
-		{
-			signature: 'output'
-			description: 'output path'
-			parameter: 'output'
-			alias: 'o'
-			required: 'You have to specify the output location'
-		}
-		commandOptions.osVersionOrSemver
-	]
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		unzip = require('unzip2')
-		fs = require('fs')
-		rindle = require('rindle')
-		manager = require('balena-image-manager')
-		visuals = require('resin-cli-visuals')
-
-		console.info("Getting device operating system for #{params.type}")
-
-		displayVersion = ''
-		Promise.try ->
-			if not options.version
-				console.warn('OS version is not specified, using the default version:
-					the newest stable (non-pre-release) version if available,
-					or the newest version otherwise (if all existing
-					versions for the given device type are pre-release).')
-				return 'default'
-			return resolveVersion(params.type, options.version)
-		.then (version) ->
-			if version isnt 'default'
-				displayVersion = " #{version}"
-			return manager.get(params.type, version)
-		.then (stream) ->
-			bar = new visuals.Progress("Downloading Device OS#{displayVersion}")
-			spinner = new visuals.Spinner("Downloading Device OS#{displayVersion} (size unknown)")
-
-			stream.on 'progress', (state) ->
-				if state?
-					bar.update(state)
-				else
-					spinner.start()
-
-			stream.on 'end', ->
-				spinner.stop()
-
-			# We completely rely on the `mime` custom property
-			# to make this decision.
-			# The actual stream should be checked instead.
-			if stream.mime is 'application/zip'
-				output = unzip.Extract(path: options.output)
-			else
-				output = fs.createWriteStream(options.output)
-
-			return rindle.wait(stream.pipe(output)).return(options.output)
-		.tap (output) ->
-			console.info('The image was downloaded successfully')
-		.nodeify(done)
-
-buildConfig = (image, deviceType, advanced = false) ->
-	Promise = require('bluebird')
-	form = require('resin-cli-form')
-	helpers = require('../utils/helpers')
-
-	Promise.resolve(helpers.getManifest(image, deviceType))
-	.get('options')
-	.then (questions) ->
-		if not advanced
-			advancedGroup = _.find questions,
-				name: 'advanced'
-				isGroup: true
-
-			if advancedGroup?
-				override = helpers.getGroupDefaults(advancedGroup)
-
-		return form.run(questions, { override })
-
-exports.buildConfig =
-	signature: 'os build-config <image> <device-type>'
-	description: 'build the OS config and save it to the JSON file'
-	help: '''
-		Use this command to prebuild the OS config once and skip the interactive part of `balena os configure`.
-
-		Example:
-
-			$ balena os build-config ../path/rpi3.img raspberrypi3 --output rpi3-config.json
-			$ balena os configure ../path/rpi3.img 7cf02a6 --config "$(cat rpi3-config.json)"
-	'''
-	permission: 'user'
-	options: [
-		commandOptions.advancedConfig
-		{
-			signature: 'output'
-			description: 'the path to the output JSON file'
-			alias: 'o'
-			required: 'the output path is required'
-			parameter: 'output'
-		}
-	]
-	action: (params, options, done) ->
-		fs = require('fs')
-		Promise = require('bluebird')
-		writeFileAsync = Promise.promisify(fs.writeFile)
-
-		buildConfig(params.image, params['device-type'], options.advanced)
-		.then (answers) ->
-			writeFileAsync(options.output, JSON.stringify(answers, null, 4))
-		.nodeify(done)
-
-exports.configure =
-	signature: 'os configure <image>'
-	description: 'configure an os image'
-	help: '''
-		Use this command to configure a previously downloaded operating system image for
-		the specific device or for an application generally.
-
-		This command will try to automatically determine the operating system version in order
-		to correctly configure the image. It may fail to do so however, in which case you'll
-		have to call this command again with the exact version number of the targeted image.
-
-		Note that device api keys are only supported on balenaOS 2.0.3+.
-
-		This command still supports the *deprecated* format where the UUID and optionally device key
-		are passed directly on the command line, but the recommended way is to pass either an --app or
-		--device argument. The deprecated format will be remove in a future release.
-
-		Examples:
-
-			$ balena os configure ../path/rpi.img --device 7cf02a6
-			$ balena os configure ../path/rpi.img --device 7cf02a6 --device-api-key <existingDeviceKey>
-			$ balena os configure ../path/rpi.img --app MyApp
-			$ balena os configure ../path/rpi.img --app MyApp --version 2.12.7
-	'''
-	permission: 'user'
-	options: [
-		commandOptions.advancedConfig
-		commandOptions.optionalApplication
-		commandOptions.optionalDevice
-		commandOptions.optionalDeviceApiKey
-		commandOptions.optionalOsVersion
-		{
-			signature: 'config'
-			description: 'path to the config JSON file, see `balena os build-config`'
-			parameter: 'config'
-		}
-	]
-	action: (params, options, done) ->
-		normalizeUuidProp(options, 'device')
-		fs = require('fs')
-		Promise = require('bluebird')
-		readFileAsync = Promise.promisify(fs.readFile)
-		balena = require('balena-sdk').fromSharedOptions()
-		init = require('balena-device-init')
-		helpers = require('../utils/helpers')
-		patterns = require('../utils/patterns')
-		{ generateDeviceConfig, generateApplicationConfig } = require('../utils/config')
-
-		if _.filter([
-			options.device
-			options.application
-		]).length != 1
-			patterns.exitWithExpectedError '''
-				To configure an image, you must provide exactly one of:
-
-				* A device, with --device <uuid>
-				* An application, with --app <appname>
-
-				See the help page for examples:
-
-				  $ balena help os configure
-			'''
-
-		uuid = options.device
-		deviceApiKey = options.deviceApiKey
-
-		console.info('Configuring operating system image')
-
-		configurationResourceType = if uuid then 'device' else 'application'
-
-		balena.models[configurationResourceType].get(uuid || options.application)
-		.then (appOrDevice) ->
-			manifestPromise = helpers.getManifest(params.image, appOrDevice.device_type)
-			answersPromise = Promise.try ->
-				if options.config
-					return readFileAsync(options.config, 'utf8')
-						.then(JSON.parse)
-				return buildConfig(params.image, appOrDevice.device_type, options.advanced)
-			Promise.join answersPromise, manifestPromise, (answers, manifest) ->
-				answers.version = options.version
-
-				if not answers.version?
-					answers.version = Promise.resolve(helpers.getOsVersion(params.image, manifest)).tap (version) ->
-						if not version?
-							throw new Error(
-								'Could not read OS version from the image. ' +
-								'Please specify the version manually with the ' +
-								'--version argument to this command.'
-							)
-
-				Promise.props(answers).then (answers) ->
-					(if configurationResourceType == 'device'
-						generateDeviceConfig(appOrDevice, deviceApiKey, answers)
-					else
-						generateApplicationConfig(appOrDevice, answers)
-					)
-					.then (config) ->
-						init.configure(params.image, manifest, config, answers)
-		.then(helpers.osProgressHandler)
-		.nodeify(done)
-
-INIT_WARNING_MESSAGE = '''
-	Note: Initializing the device may ask for administrative permissions
-	because we need to access the raw devices directly.
-'''
-
-exports.initialize =
-	signature: 'os initialize <image>'
-	description: 'initialize an os image'
-	help: """
-		Use this command to initialize a device with previously configured operating system image.
-
-		#{INIT_WARNING_MESSAGE}
-
-		Examples:
-
-			$ balena os initialize ../path/rpi.img --type 'raspberry-pi'
-	"""
-	permission: 'user'
-	options: [
-		commandOptions.yes
-		{
-			signature: 'type'
-			description: 'device type (Check available types with `balena devices supported`)'
-			parameter: 'type'
-			alias: 't'
-			required: 'You have to specify a device type'
-		}
-		commandOptions.drive
-	]
-	action: (params, options, done) ->
-		Promise = require('bluebird')
-		umountAsync = Promise.promisify(require('umount').umount)
-		form = require('resin-cli-form')
-		patterns = require('../utils/patterns')
-		helpers = require('../utils/helpers')
-
-		console.info("""
-			Initializing device
-
-			#{INIT_WARNING_MESSAGE}
-		""")
-		Promise.resolve(helpers.getManifest(params.image, options.type))
-			.then (manifest) ->
-				return manifest.initialization?.options
-			.then (questions) ->
-				return form.run questions,
-					override:
-						drive: options.drive
-			.tap (answers) ->
-				return if not answers.drive?
-				patterns.confirm(
-					options.yes
-					"This will erase #{answers.drive}. Are you sure?"
-					"Going to erase #{answers.drive}."
-				)
-					.return(answers.drive)
-					.then(umountAsync)
-			.tap (answers) ->
-				return helpers.sudo([
-					'internal'
-					'osinit'
-					params.image
-					options.type
-					JSON.stringify(answers)
-				])
-			.then (answers) ->
-				return if not answers.drive?
-
-				# TODO: balena local makes use of ejectAsync, see below
-				# DO we need this / should we do that here?
-
-				# getDrive = (drive) ->
-				# 	driveListAsync().then (drives) ->
-				# 		selectedDrive = _.find(drives, device: drive)
-
-				# 		if not selectedDrive?
-				# 			throw new Error("Drive not found: #{drive}")
-
-				# 		return selectedDrive
-				# if (os.platform() is 'win32') and selectedDrive.mountpoint?
-				# 	ejectAsync = Promise.promisify(require('removedrive').eject)
-				# 	return ejectAsync(selectedDrive.mountpoint)
-
-				umountAsync(answers.drive).tap ->
-					console.info("You can safely remove #{answers.drive} now")
-		.nodeify(done)

lib/actions/preload.coffee

@@ -1,302 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-dockerUtils = require('../utils/docker')
-
-LATEST = 'latest'
-
-allDeviceTypes = undefined
-
-getDeviceTypes = ->
-	Bluebird = require('bluebird')
-	_ = require('lodash')
-	if allDeviceTypes != undefined
-		return Bluebird.resolve(allDeviceTypes)
-	balena = require('balena-sdk').fromSharedOptions()
-	balena.models.config.getDeviceTypes()
-	.then (deviceTypes) ->
-		_.sortBy(deviceTypes, 'name')
-	.tap (dt) ->
-		allDeviceTypes = dt
-
-getDeviceTypesWithSameArch = (deviceTypeSlug) ->
-	_ = require('lodash')
-
-	getDeviceTypes()
-	.then (deviceTypes) ->
-		deviceType = _.find(deviceTypes, slug: deviceTypeSlug)
-		_(deviceTypes).filter(arch: deviceType.arch).map('slug').value()
-
-getApplicationsWithSuccessfulBuilds = (deviceType) ->
-	preload = require('balena-preload')
-	balena = require('balena-sdk').fromSharedOptions()
-
-	getDeviceTypesWithSameArch(deviceType)
-	.then (deviceTypes) ->
-		balena.pine.get
-			resource: 'my_application'
-			options:
-				$filter:
-					device_type:
-						$in: deviceTypes
-					owns__release:
-						$any:
-							$alias: 'r'
-							$expr:
-								r:
-									status: 'success'
-				$expand: preload.applicationExpandOptions
-				$select: [ 'id', 'app_name', 'device_type', 'commit', 'should_track_latest_release' ]
-				$orderby: 'app_name asc'
-
-selectApplication = (deviceType) ->
-	visuals = require('resin-cli-visuals')
-	form = require('resin-cli-form')
-	{ exitWithExpectedError } = require('../utils/patterns')
-
-	applicationInfoSpinner = new visuals.Spinner('Downloading list of applications and releases.')
-	applicationInfoSpinner.start()
-
-	getApplicationsWithSuccessfulBuilds(deviceType)
-	.then (applications) ->
-		applicationInfoSpinner.stop()
-		if applications.length == 0
-			exitWithExpectedError("You have no apps with successful releases for a '#{deviceType}' device type.")
-		form.ask
-			message: 'Select an application'
-			type: 'list'
-			choices: applications.map (app) ->
-				name: app.app_name
-				value: app
-
-selectApplicationCommit = (releases) ->
-	form = require('resin-cli-form')
-	{ exitWithExpectedError } = require('../utils/patterns')
-
-	if releases.length == 0
-		exitWithExpectedError('This application has no successful releases.')
-	DEFAULT_CHOICE = { 'name': LATEST, 'value': LATEST }
-	choices = [ DEFAULT_CHOICE ].concat releases.map (release) ->
-		name: "#{release.end_timestamp} - #{release.commit}"
-		value: release.commit
-	return form.ask
-		message: 'Select a release'
-		type: 'list'
-		default: LATEST
-		choices: choices
-
-offerToDisableAutomaticUpdates = (application, commit) ->
-	Promise = require('bluebird')
-	balena = require('balena-sdk').fromSharedOptions()
-	form = require('resin-cli-form')
-
-	if commit == LATEST or not application.should_track_latest_release
-		return Promise.resolve()
-	message = '''
-
-		This application is set to automatically update all devices to the latest available version.
-		This might be unexpected behaviour: with this enabled, the preloaded device will still
-		download and install the latest release once it is online.
-
-		Do you want to disable automatic updates for this application?
-
-		Warning: To re-enable this requires direct api calls,
-		see https://balena.io/docs/reference/api/resources/device/#set-device-to-release
-	'''
-	form.ask
-		message: message,
-		type: 'confirm'
-	.then (update) ->
-		if not update
-			return
-		balena.pine.patch
-			resource: 'application'
-			id: application.id
-			body:
-				should_track_latest_release: false
-
-module.exports =
-	signature: 'preload <image>'
-	description: '(beta) preload an app on a disk image (or Edison zip archive)'
-	help: '''
-		Warning: "balena preload" requires Docker to be correctly installed in
-		your shell environment. For more information (including Windows support)
-		please check the README here: https://github.com/balena-io/balena-cli .
-
-		Use this command to preload an application to a local disk image (or
-		Edison zip archive) with a built release from balena.
-
-		Examples:
-
-			$ balena preload balena.img --app 1234 --commit e1f2592fc6ee949e68756d4f4a48e49bff8d72a0 --splash-image image.png
-			$ balena preload balena.img
-	'''
-	permission: 'user'
-	primary: true
-	options: dockerUtils.appendConnectionOptions [
-		{
-			signature: 'app'
-			parameter: 'appId'
-			description: 'id of the application to preload'
-			alias: 'a'
-		}
-		{
-			signature: 'commit'
-			parameter: 'hash'
-			description: '''
-				the commit hash for a specific application release to preload, use "latest" to specify the latest release
-				(ignored if no appId is given)
-			'''
-			alias: 'c'
-		}
-		{
-			signature: 'splash-image'
-			parameter: 'splashImage.png'
-			description: 'path to a png image to replace the splash screen'
-			alias: 's'
-		}
-		{
-			signature: 'dont-check-arch'
-			boolean: true
-			description: 'Disables check for matching architecture in image and application'
-		}
-		{
-			signature: 'pin-device-to-release'
-			boolean: true
-			description: 'Pin the preloaded device to the preloaded release on provision'
-			alias: 'p'
-		}
-	]
-	action: (params, options, done) ->
-		_ = require('lodash')
-		Promise = require('bluebird')
-		balena = require('balena-sdk').fromSharedOptions()
-		preload = require('balena-preload')
-		visuals = require('resin-cli-visuals')
-		nodeCleanup = require('node-cleanup')
-		{ exitWithExpectedError } = require('../utils/patterns')
-
-		progressBars = {}
-
-		progressHandler = (event) ->
-			progressBar = progressBars[event.name]
-			if not progressBar
-				progressBar = progressBars[event.name] = new visuals.Progress(event.name)
-			progressBar.update(percentage: event.percentage)
-
-		spinners = {}
-
-		spinnerHandler = (event) ->
-			spinner = spinners[event.name]
-			if not spinner
-				spinner = spinners[event.name] = new visuals.Spinner(event.name)
-			if event.action == 'start'
-				spinner.start()
-			else
-				console.log()
-				spinner.stop()
-
-		options.image = params.image
-		options.appId = options.app
-		delete options.app
-
-		options.splashImage = options['splash-image']
-		delete options['splash-image']
-
-		options.dontCheckArch = options['dont-check-arch'] || false
-		delete options['dont-check-arch']
-		if options.dontCheckArch and not options.appId
-			exitWithExpectedError('You need to specify an app id if you disable the architecture check.')
-
-		options.pinDevice = options['pin-device-to-release'] || false
-		delete options['pin-device-to-release']
-
-		# Get a configured dockerode instance
-		dockerUtils.getDocker(options)
-		.then (docker) ->
-
-			preloader = new preload.Preloader(
-				balena
-				docker
-				options.appId
-				options.commit
-				options.image
-				options.splashImage
-				options.proxy
-				options.dontCheckArch
-				options.pinDevice
-			)
-
-			gotSignal = false
-
-			nodeCleanup (exitCode, signal) ->
-				if signal
-					gotSignal = true
-					nodeCleanup.uninstall()  # don't call cleanup handler again
-					preloader.cleanup()
-					.then ->
-						# calling process.exit() won't inform parent process of signal
-						process.kill(process.pid, signal)
-					return false
-
-			if process.env.DEBUG
-				preloader.stderr.pipe(process.stderr)
-
-			preloader.on('progress', progressHandler)
-			preloader.on('spinner', spinnerHandler)
-
-			return new Promise (resolve, reject) ->
-				preloader.on('error', reject)
-
-				preloader.prepare()
-				.then ->
-					# If no appId was provided, show a list of matching apps
-					Promise.try ->
-						if not preloader.appId
-							selectApplication(preloader.config.deviceType)
-							.then (application) ->
-								preloader.setApplication(application)
-				.then ->
-					# Use the commit given as --commit or show an interactive commit selection menu
-					Promise.try ->
-						if options.commit
-							if options.commit == LATEST and preloader.application.commit
-								# handle `--commit latest`
-								return LATEST
-							release = _.find preloader.application.owns__release, (release) ->
-								release.commit.startsWith(options.commit)
-							if not release
-								exitWithExpectedError('There is no release matching this commit')
-							return release.commit
-						selectApplicationCommit(preloader.application.owns__release)
-					.then (commit) ->
-						if commit == LATEST
-							preloader.commit = preloader.application.commit
-						else
-							preloader.commit = commit
-
-						# Propose to disable automatic app updates if the commit is not the latest
-						offerToDisableAutomaticUpdates(preloader.application, commit)
-				.then ->
-					# All options are ready: preload the image.
-					preloader.preload()
-				.catch(balena.errors.BalenaError, exitWithExpectedError)
-				.then(resolve)
-				.catch(reject)
-			.then(done)
-			.finally ->
-				if not gotSignal
-					preloader.cleanup()

lib/actions/push.ts

@@ -1,229 +0,0 @@
-/*
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-import { CommandDefinition } from 'capitano';
-import { stripIndent } from 'common-tags';
-import { BalenaSDK } from 'balena-sdk';
-
-import { BuildError } from '../utils/device/errors';
-
-// An regex to detect an IP address, from https://www.regular-expressions.info/ip.html
-const IP_REGEX = new RegExp(
-	/\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/,
-);
-
-enum BuildTarget {
-	Cloud,
-	Device,
-}
-
-function getBuildTarget(appOrDevice: string): BuildTarget | null {
-	// First try the application regex from the api
-	if (/^[a-zA-Z0-9_-]+$/.test(appOrDevice)) {
-		return BuildTarget.Cloud;
-	}
-
-	if (IP_REGEX.test(appOrDevice)) {
-		return BuildTarget.Device;
-	}
-
-	return null;
-}
-
-async function getAppOwner(sdk: BalenaSDK, appName: string) {
-	const {
-		exitWithExpectedError,
-		selectFromList,
-	} = await import('../utils/patterns');
-	const _ = await import('lodash');
-
-	const applications = await sdk.models.application.getAll({
-		$expand: {
-			user: {
-				$select: ['username'],
-			},
-		},
-		$filter: {
-			$eq: [{ $tolower: { $: 'app_name' } }, appName.toLowerCase()],
-		},
-		$select: ['id'],
-	});
-
-	if (applications == null || applications.length === 0) {
-		exitWithExpectedError(
-			stripIndent`
-			No applications found with name: ${appName}.
-
-			This could mean that the application does not exist, or you do
-			not have the permissions required to access it.`,
-		);
-	}
-
-	if (applications.length === 1) {
-		return _.get(applications, '[0].user[0].username');
-	}
-
-	// If we got more than one application with the same name it means that the
-	// user has access to a collab app with the same name as a personal app. We
-	// present a list to the user which shows the fully qualified application
-	// name (user/appname) and allows them to select
-	const entries = _.map(applications, app => {
-		const username = _.get(app, 'user[0].username');
-		return {
-			name: `${username}/${appName}`,
-			extra: username,
-		};
-	});
-
-	const selected = await selectFromList(
-		`${
-			entries.length
-		} applications found with that name, please select the application you would like to push to`,
-		entries,
-	);
-
-	return selected.extra;
-}
-
-export const push: CommandDefinition<
-	{
-		applicationOrDevice: string;
-	},
-	{
-		source: string;
-		emulated: boolean;
-		nocache: boolean;
-	}
-> = {
-	signature: 'push <applicationOrDevice>',
-	description:
-		'Start a remote build on the balena cloud build servers or a local mode device',
-	help: stripIndent`
-		This command can be used to start a build on the remote
-		balena cloud builders, or a local mode balena device.
-
-		When building on the balena cloud the given source directory will be sent to the
-		balena builder, and the build will proceed. This can be used as a drop-in
-		replacement for git push to deploy.
-
-		When building on a local mode device, the given source directory will be built on
-		device, and the resulting containers will be run on the device. Logs will be
-		streamed back from the device as part of the same invocation.
-
-		Examples:
-
-			$ balena push myApp
-			$ balena push myApp --source <source directory>
-			$ balena push myApp -s <source directory>
-
-			$ balena push 10.0.0.1
-			$ balena push 10.0.0.1 --source <source directory>
-			$ balena push 10.0.0.1 -s <source directory>
-	`,
-	permission: 'user',
-	options: [
-		{
-			signature: 'source',
-			alias: 's',
-			description:
-				'The source that should be sent to the balena builder to be built (defaults to the current directory)',
-			parameter: 'source',
-		},
-		{
-			signature: 'emulated',
-			alias: 'e',
-			description: 'Force an emulated build to occur on the remote builder',
-			boolean: true,
-		},
-		{
-			signature: 'nocache',
-			alias: 'c',
-			description: "Don't use cache when building this project",
-			boolean: true,
-		},
-	],
-	async action(params, options, done) {
-		const sdk = (await import('balena-sdk')).fromSharedOptions();
-		const Bluebird = await import('bluebird');
-		const remote = await import('../utils/remote-build');
-		const deviceDeploy = await import('../utils/device/deploy');
-		const { exitWithExpectedError } = await import('../utils/patterns');
-
-		const appOrDevice: string | null = params.applicationOrDevice;
-		if (appOrDevice == null) {
-			exitWithExpectedError('You must specify an application or a device');
-		}
-
-		const source = options.source || '.';
-		if (process.env.DEBUG) {
-			console.log(`[debug] Using ${source} as build source`);
-		}
-
-		const buildTarget = getBuildTarget(appOrDevice);
-		switch (buildTarget) {
-			case BuildTarget.Cloud:
-				const app = appOrDevice;
-				Bluebird.join(
-					sdk.auth.getToken(),
-					sdk.settings.get('balenaUrl'),
-					getAppOwner(sdk, app),
-					(token, baseUrl, owner) => {
-						const opts = {
-							emulated: options.emulated,
-							nocache: options.nocache,
-						};
-						const args = {
-							app,
-							owner,
-							source,
-							auth: token,
-							baseUrl,
-							sdk,
-							opts,
-						};
-
-						return remote.startRemoteBuild(args);
-					},
-				).nodeify(done);
-				break;
-			case BuildTarget.Device:
-				const device = appOrDevice;
-				// TODO: Support passing a different port
-				Bluebird.resolve(
-					deviceDeploy.deployToDevice({
-						source,
-						deviceHost: device,
-					}),
-				)
-					.catch(BuildError, e => {
-						exitWithExpectedError(e.toString());
-					})
-					.nodeify(done);
-				break;
-			default:
-				exitWithExpectedError(
-					stripIndent`
-					Build target not recognised. Please provide either an application name or device address.
-
-					The only supported device addresses currently are IP addresses.
-
-					If you believe your build target should have been detected, and this is an error, please
-					create an issue.`,
-				);
-				break;
-		}
-	},
-};

lib/actions/settings.ts

@@ -1,39 +0,0 @@
-/*
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-import { CommandDefinition } from 'capitano';
-
-export const list: CommandDefinition = {
-	signature: 'settings',
-	description: 'print current settings',
-	help: `\
-Use this command to display detected settings
-
-Examples:
-
-	$ balena settings\
-`,
-	async action(_params, _options, done) {
-		const balena = (await import('balena-sdk')).fromSharedOptions();
-		const prettyjson = await import('prettyjson');
-
-		return balena.settings
-			.getAll()
-			.then(prettyjson.render)
-			.then(console.log)
-			.nodeify(done);
-	},
-};

lib/actions/ssh.coffee

@@ -1,141 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-commandOptions = require('./command-options')
-{ normalizeUuidProp } = require('../utils/normalization')
-
-module.exports =
-	signature: 'ssh [uuid]'
-	description: '(beta) get a shell into the running app container of a device'
-	help: '''
-		Warning: 'balena ssh' requires an openssh-compatible client to be correctly
-		installed in your shell environment. For more information (including Windows
-		support) please check the README here: https://github.com/balena-io/balena-cli
-
-		Use this command to get a shell into the running application container of
-		your device.
-
-		Examples:
-
-			$ balena ssh MyApp
-			$ balena ssh 7cf02a6
-			$ balena ssh 7cf02a6 --port 8080
-			$ balena ssh 7cf02a6 -v
-			$ balena ssh 7cf02a6 -s
-	'''
-	permission: 'user'
-	primary: true
-	options: [
-			signature: 'port'
-			parameter: 'port'
-			description: 'ssh gateway port'
-			alias: 'p'
-	,
-			signature: 'verbose'
-			boolean: true
-			description: 'increase verbosity'
-			alias: 'v'
-	commandOptions.hostOSAccess,
-			signature: 'noproxy'
-			boolean: true
-			description: "don't use the proxy configuration for this connection.
-				Only makes sense if you've configured proxy globally."
-	]
-	action: (params, options, done) ->
-		normalizeUuidProp(params)
-		child_process = require('child_process')
-		Promise = require('bluebird')
-		balena = require('balena-sdk').fromSharedOptions()
-		_ = require('lodash')
-		bash = require('bash')
-		hasbin = require('hasbin')
-		{ getSubShellCommand } = require('../utils/helpers')
-		patterns = require('../utils/patterns')
-
-		options.port ?= 22
-
-		verbose = if options.verbose then '-vvv' else ''
-
-		proxyConfig = global.PROXY_CONFIG
-		useProxy = !!proxyConfig and not options.noproxy
-
-		getSshProxyCommand = (hasTunnelBin) ->
-			return '' if not useProxy
-
-			if not hasTunnelBin
-				console.warn('''
-					Proxy is enabled but the `proxytunnel` binary cannot be found.
-					Please install it if you want to route the `balena ssh` requests through the proxy.
-					Alternatively you can pass `--noproxy` param to the `balena ssh` command to ignore the proxy config
-					for the `ssh` requests.
-
-					Attemmpting the unproxied request for now.
-				''')
-				return ''
-
-			tunnelOptions =
-				proxy: "#{proxyConfig.host}:#{proxyConfig.port}"
-				dest: '%h:%p'
-			{ proxyAuth } = proxyConfig
-			if proxyAuth
-				i = proxyAuth.indexOf(':')
-				_.assign tunnelOptions,
-					user: proxyAuth.substring(0, i)
-					pass: proxyAuth.substring(i + 1)
-			proxyCommand = "proxytunnel #{bash.args(tunnelOptions, '--', '=')}"
-			return "-o #{bash.args({ ProxyCommand: proxyCommand }, '', '=')}"
-
-		Promise.try ->
-			return false if not params.uuid
-			return balena.models.device.has(params.uuid)
-		.then (uuidExists) ->
-			return params.uuid if uuidExists
-			return patterns.inferOrSelectDevice()
-		.then (uuid) ->
-			console.info("Connecting to: #{uuid}")
-			balena.models.device.get(uuid)
-		.then (device) ->
-			patterns.exitWithExpectedError('Device is not online') if not device.is_online
-
-			Promise.props
-				username: balena.auth.whoami()
-				uuid: device.uuid
-				# get full uuid
-				containerId: if options.host then '' else balena.models.device.getApplicationInfo(device.uuid).get('containerId')
-				proxyUrl: balena.settings.get('proxyUrl')
-
-				hasTunnelBin: if useProxy then hasbin('proxytunnel') else null
-			.then ({ username, uuid, containerId, proxyUrl, hasTunnelBin }) ->
-				throw new Error('Did not find running application container') if not containerId?
-				Promise.try ->
-					sshProxyCommand = getSshProxyCommand(hasTunnelBin)
-
-					if options.host
-						accessCommand = "host #{uuid}"
-					else
-						accessCommand = "enter #{uuid} #{containerId}"
-
-					command = "ssh #{verbose} -t \
-						-o LogLevel=ERROR \
-						-o StrictHostKeyChecking=no \
-						-o UserKnownHostsFile=/dev/null \
-						#{sshProxyCommand} \
-						-p #{options.port} #{username}@ssh.#{proxyUrl} #{accessCommand}"
-
-					subShellCommand = getSubShellCommand(command)
-					child_process.spawn subShellCommand.program, subShellCommand.args,
-						stdio: 'inherit'
-		.nodeify(done)

lib/actions/util.coffee

@@ -1,56 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-_ = require('lodash')
-
-exports.availableDrives =
-	# TODO: dedupe with https://github.com/balena-io-modules/resin-cli-visuals/blob/master/lib/widgets/drive/index.coffee
-	signature: 'util available-drives'
-	description: 'list available drives'
-	help: """
-		Use this command to list your machine's drives usable for writing the OS image to.
-		Skips the system drives.
-	"""
-	action: ->
-		Promise = require('bluebird')
-		drivelist = require('drivelist')
-		driveListAsync = Promise.promisify(drivelist.list)
-		chalk = require('chalk')
-		visuals = require('resin-cli-visuals')
-
-		formatDrive = (drive) ->
-			size = drive.size / 1000000000
-			return {
-				device: drive.device
-				size: "#{size.toFixed(1)} GB"
-				description: drive.description
-			}
-
-		getDrives = ->
-			driveListAsync().then (drives) ->
-				return _.reject(drives, system: true)
-
-		getDrives()
-		.then (drives) ->
-			if not drives.length
-				console.error("#{chalk.red('x')} No available drives were detected, plug one in!")
-				return
-
-			console.log visuals.table.horizontal drives.map(formatDrive), [
-				'device'
-				'size'
-				'description'
-			]

lib/actions/wizard.coffee

@@ -1,74 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-exports.wizard =
-	signature: 'quickstart [name]'
-	description: 'getting started with balena'
-	help: '''
-		Use this command to run a friendly wizard to get started with balena.
-
-		The wizard will guide you through:
-
-			- Create an application.
-			- Initialise an SDCard with the balena operating system.
-			- Associate an existing project directory with your balena application.
-			- Push your project to your devices.
-
-		Examples:
-
-			$ balena quickstart
-			$ balena quickstart MyApp
-	'''
-	primary: true
-	action: (params, options, done) ->
-		balena = require('balena-sdk').fromSharedOptions()
-		patterns = require('../utils/patterns')
-		{ runCommand } = require('../utils/helpers')
-
-		balena.auth.isLoggedIn().then (isLoggedIn) ->
-			return if isLoggedIn
-			console.info('Looks like you\'re not logged in yet!')
-			console.info("Let's go through a quick wizard to get you started.\n")
-			return runCommand('login')
-		.then ->
-			return if params.name?
-			patterns.selectOrCreateApplication().tap (applicationName) ->
-				balena.models.application.has(applicationName).then (hasApplication) ->
-					return applicationName if hasApplication
-					runCommand("app create #{applicationName}")
-			.then (applicationName) ->
-				params.name = applicationName
-		.then ->
-			return runCommand("device init --application #{params.name}")
-		.tap(patterns.awaitDevice)
-		.then (uuid) ->
-			return runCommand("device #{uuid}")
-		.then ->
-			return balena.models.application.get(params.name)
-		.then (application) ->
-			console.log """
-				Your device is ready to start pushing some code!
-
-				Check our official documentation for more information:
-
-				    http://balena.io/docs/#/pages/introduction/introduction.md
-
-				Clone an example or go to an existing application directory and run:
-
-				    $ git remote add balena #{application.git_repository}
-				    $ git push balena master
-			"""
-		.nodeify(done)

lib/app.coffee

@@ -1,234 +0,0 @@
-###
-Copyright 2016-2017 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-Raven = require('raven')
-Raven.disableConsoleAlerts()
-Raven.config require('./config').sentryDsn,
-	captureUnhandledRejections: true,
-	autoBreadcrumbs: true,
-	release: require('../package.json').version
-.install (logged, error) ->
-	console.error(error)
-	process.exit(1)
-Raven.setContext
-	extra:
-		args: process.argv
-		node_version: process.version
-
-validNodeVersions = require('../package.json').engines.node
-if not require('semver').satisfies(process.version, validNodeVersions)
-	console.warn """
-	Warning: this version of Node does not match the requirements of this package.
-	This package expects #{validNodeVersions}, but you're using #{process.version}.
-	This may cause unexpected behaviour.
-
-	To upgrade your Node, visit https://nodejs.org/en/download/
-
-	"""
-
-
-# Doing this before requiring any other modules,
-# including the 'balena-sdk', to prevent any module from reading the http proxy config
-# before us
-globalTunnel = require('global-tunnel-ng')
-settings = require('balena-settings-client')
-try
-	proxy = settings.get('proxy') or null
-catch
-	proxy = null
-# Init the tunnel even if the proxy is not configured
-# because it can also get the proxy from the http(s)_proxy env var
-# If that is not set as well the initialize will do nothing
-globalTunnel.initialize(proxy)
-
-# TODO: make this a feature of capitano https://github.com/balena-io/capitano/issues/48
-global.PROXY_CONFIG = globalTunnel.proxyConfig
-
-Promise = require('bluebird')
-capitano = require('capitano')
-capitanoExecuteAsync = Promise.promisify(capitano.execute)
-
-# We don't yet use balena-sdk directly everywhere, but we set up shared
-# options correctly so we can do safely in submodules
-BalenaSdk = require('balena-sdk')
-BalenaSdk.setSharedOptions(
-	apiUrl: settings.get('apiUrl')
-	imageMakerUrl: settings.get('imageMakerUrl')
-	dataDirectory: settings.get('dataDirectory')
-	retries: 2
-)
-
-balena = BalenaSdk.fromSharedOptions()
-
-actions = require('./actions')
-errors = require('./errors')
-events = require('./events')
-update = require('./utils/update')
-{ exitWithExpectedError } = require('./utils/patterns')
-
-# Assign bluebird as the global promise library
-# stream-to-promise will produce native promises if not
-# for this module, which could wreak havoc in this
-# bluebird-only codebase.
-require('any-promise/register/bluebird')
-
-capitano.permission 'user', (done) ->
-	balena.auth.isLoggedIn().then (isLoggedIn) ->
-		if not isLoggedIn
-			exitWithExpectedError('''
-				You have to log in to continue
-
-				Run the following command to go through the login wizard:
-
-				  $ balena login
-			''')
-	.nodeify(done)
-
-capitano.command
-	signature: '*'
-	action: ->
-		capitano.execute(command: 'help')
-
-capitano.globalOption
-	signature: 'help'
-	boolean: true
-	alias: 'h'
-
-# ---------- Info Module ----------
-capitano.command(actions.info.version)
-
-# ---------- Help Module ----------
-capitano.command(actions.help.help)
-
-# ---------- Wizard Module ----------
-capitano.command(actions.wizard.wizard)
-
-# ---------- Api key module ----------
-capitano.command(actions.apiKey.generate)
-
-# ---------- App Module ----------
-capitano.command(actions.app.create)
-capitano.command(actions.app.list)
-capitano.command(actions.app.remove)
-capitano.command(actions.app.restart)
-capitano.command(actions.app.info)
-
-# ---------- Auth Module ----------
-capitano.command(actions.auth.login)
-capitano.command(actions.auth.logout)
-capitano.command(actions.auth.signup)
-capitano.command(actions.auth.whoami)
-
-# ---------- Device Module ----------
-capitano.command(actions.device.list)
-capitano.command(actions.device.supported)
-capitano.command(actions.device.rename)
-capitano.command(actions.device.init)
-capitano.command(actions.device.remove)
-capitano.command(actions.device.identify)
-capitano.command(actions.device.reboot)
-capitano.command(actions.device.shutdown)
-capitano.command(actions.device.enableDeviceUrl)
-capitano.command(actions.device.disableDeviceUrl)
-capitano.command(actions.device.getDeviceUrl)
-capitano.command(actions.device.hasDeviceUrl)
-capitano.command(actions.device.register)
-capitano.command(actions.device.move)
-capitano.command(actions.device.info)
-
-# ---------- Notes Module ----------
-capitano.command(actions.notes.set)
-
-# ---------- Keys Module ----------
-capitano.command(actions.keys.list)
-capitano.command(actions.keys.add)
-capitano.command(actions.keys.info)
-capitano.command(actions.keys.remove)
-
-# ---------- Env Module ----------
-capitano.command(actions.env.list)
-capitano.command(actions.env.add)
-capitano.command(actions.env.rename)
-capitano.command(actions.env.remove)
-
-# ---------- OS Module ----------
-capitano.command(actions.os.versions)
-capitano.command(actions.os.download)
-capitano.command(actions.os.buildConfig)
-capitano.command(actions.os.configure)
-capitano.command(actions.os.initialize)
-
-# ---------- Config Module ----------
-capitano.command(actions.config.read)
-capitano.command(actions.config.write)
-capitano.command(actions.config.inject)
-capitano.command(actions.config.reconfigure)
-capitano.command(actions.config.generate)
-
-# ---------- Settings Module ----------
-capitano.command(actions.settings.list)
-
-# ---------- Logs Module ----------
-capitano.command(actions.logs)
-
-# ---------- Sync Module ----------
-capitano.command(actions.sync)
-
-# ---------- Preload Module ----------
-capitano.command(actions.preload)
-
-# ---------- SSH Module ----------
-capitano.command(actions.ssh)
-
-# ---------- Local balenaOS Module ----------
-capitano.command(actions.local.configure)
-capitano.command(actions.local.flash)
-capitano.command(actions.local.logs)
-capitano.command(actions.local.push)
-capitano.command(actions.local.ssh)
-capitano.command(actions.local.scan)
-capitano.command(actions.local.stop)
-
-# ---------- Public utils ----------
-capitano.command(actions.util.availableDrives)
-
-# ---------- Internal utils ----------
-capitano.command(actions.internal.osInit)
-capitano.command(actions.internal.scanDevices)
-capitano.command(actions.internal.sudo)
-
-#------------ Local build and deploy -------
-capitano.command(actions.build)
-capitano.command(actions.deploy)
-
-#------------ Push/remote builds -------
-capitano.command(actions.push.push)
-
-#------------ Join/Leave -------
-capitano.command(actions.join.join)
-capitano.command(actions.leave.leave)
-
-update.notify()
-
-cli = capitano.parse(process.argv)
-runCommand = ->
-	if cli.global?.help
-		capitanoExecuteAsync(command: "help #{cli.command ? ''}")
-	else
-		capitanoExecuteAsync(cli)
-
-Promise.all([events.trackCommand(cli), runCommand()])
-.catch(errors.handle)

lib/app.ts

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * Copyright 2019-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as packageJSON from '../package.json';
+import { CliSettings } from './utils/bootstrap';
+import { onceAsync, stripIndent } from './utils/lazy';
+
+/**
+ * Sentry.io setup
+ * @see https://docs.sentry.io/error-reporting/quickstart/?platform=node
+ */
+export const setupSentry = onceAsync(async () => {
+	const config = await import('./config');
+	const Sentry = await import('@sentry/node');
+	Sentry.init({
+		dsn: config.sentryDsn,
+		release: packageJSON.version,
+	});
+	Sentry.configureScope((scope) => {
+		scope.setExtras({
+			is_pkg: !!(process as any).pkg,
+			node_version: process.version,
+			platform: process.platform,
+		});
+	});
+	return Sentry.getCurrentHub();
+});
+
+async function checkNodeVersion() {
+	const validNodeVersions = packageJSON.engines.node;
+	if (!(await import('semver')).satisfies(process.version, validNodeVersions)) {
+		console.warn(stripIndent`
+			------------------------------------------------------------------------------
+			Warning: Node version "${process.version}" does not match required versions "${validNodeVersions}".
+			This may cause unexpected behavior. To upgrade Node, visit:
+			https://nodejs.org/en/download/
+			------------------------------------------------------------------------------
+			`);
+	}
+}
+
+/** Setup balena-sdk options that are shared with imported packages */
+function setupBalenaSdkSharedOptions(settings: CliSettings) {
+	const BalenaSdk = require('balena-sdk') as typeof import('balena-sdk');
+	BalenaSdk.setSharedOptions({
+		apiUrl: settings.get<string>('apiUrl'),
+		dataDirectory: settings.get<string>('dataDirectory'),
+	});
+}
+
+/**
+ * Addresses the console warning:
+ * (node:49500) MaxListenersExceededWarning: Possible EventEmitter memory
+ * leak detected. 11 error listeners added. Use emitter.setMaxListeners() to
+ * increase limit
+ */
+export function setMaxListeners(maxListeners: number) {
+	require('events').EventEmitter.defaultMaxListeners = maxListeners;
+}
+
+/** Selected CLI initialization steps */
+async function init() {
+	if (process.env.BALENARC_NO_SENTRY) {
+		console.error(`WARN: disabling Sentry.io error reporting`);
+	} else {
+		await setupSentry();
+	}
+	checkNodeVersion();
+
+	const settings = new CliSettings();
+
+	// Proxy setup should be done early on, before loading balena-sdk
+	await (await import('./utils/proxy')).setupGlobalHttpProxy(settings);
+
+	setupBalenaSdkSharedOptions(settings);
+
+	// check for CLI updates once a day
+	(await import('./utils/update')).notify();
+}
+
+/** Execute the oclif parser and the CLI command. */
+async function oclifRun(
+	command: string[],
+	options: import('./preparser').AppOptions,
+) {
+	const { CustomMain } = await import('./utils/oclif-utils');
+	const runPromise = CustomMain.run(command).then(
+		() => {
+			if (!options.noFlush) {
+				return require('@oclif/command/flush');
+			}
+		},
+		(error) => {
+			// oclif sometimes exits with ExitError code 0 (not an error)
+			// (Avoid `error instanceof ExitError` here for the reasons explained
+			// in the CONTRIBUTING.md file regarding the `instanceof` operator.)
+			if (error.oclif?.exit === 0) {
+				return;
+			} else {
+				throw error;
+			}
+		},
+	);
+	const { trackPromise } = await import('./hooks/prerun/track');
+	await Promise.all([trackPromise, runPromise]);
+}
+
+/** CLI entrypoint. Called by the `bin/balena` and `bin/balena-dev` scripts. */
+export async function run(
+	cliArgs = process.argv,
+	options: import('./preparser').AppOptions = {},
+) {
+	try {
+		const { normalizeEnvVars, pkgExec } = await import('./utils/bootstrap');
+		normalizeEnvVars();
+
+		// The 'pkgExec' special/internal command provides a Node.js interpreter
+		// for use of the standalone zip package. See pkgExec function.
+		if (cliArgs.length > 3 && cliArgs[2] === 'pkgExec') {
+			return pkgExec(cliArgs[3], cliArgs.slice(4));
+		}
+
+		await init();
+
+		const { preparseArgs, checkDeletedCommand } = await import('./preparser');
+
+		// Look for commands that have been removed and if so, exit with a notice
+		checkDeletedCommand(cliArgs.slice(2));
+
+		const args = await preparseArgs(cliArgs);
+		await oclifRun(args, options);
+	} catch (err) {
+		await (await import('./errors')).handleError(err);
+	} finally {
+		// Windows fix: reading from stdin prevents the process from exiting
+		process.stdin.pause();
+	}
+}

lib/auth/index.coffee

@@ -1,63 +0,0 @@
-###
-Copyright 2016 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-###*
-# @module auth
-###
-
-open = require('opn')
-balena = require('balena-sdk').fromSharedOptions()
-server = require('./server')
-utils = require('./utils')
-
-###*
-# @summary Login to the balena CLI using the web dashboard
-# @function
-# @public
-#
-# @description
-# This function opens the user's default browser and points it
-# to the balena dashboard where the session token exchange will
-# take place.
-#
-# Once the the token is retrieved, it's automatically persisted.
-#
-# @fulfil {String} - session token
-# @returns {Promise}
-#
-# @example
-# auth.login().then (sessionToken) ->
-#   console.log('I\'m logged in!')
-#   console.log("My session token is: #{sessionToken}")
-###
-exports.login = ->
-	options =
-		port: 8989
-		path: '/auth'
-
-	# Needs to be 127.0.0.1 not localhost, because the ip only is whitelisted
-	# from mixed content warnings (as the target of a form in the result page)
-	callbackUrl = "http://127.0.0.1:#{options.port}#{options.path}"
-	return utils.getDashboardLoginURL(callbackUrl).then (loginUrl) ->
-
-		# Leave a bit of time for the
-		# server to get up and runing
-		setTimeout ->
-			open(loginUrl, { wait: false })
-		, 1000
-
-		return server.awaitForToken(options)
-			.tap(balena.auth.loginWithToken)

lib/auth/index.ts

@@ -0,0 +1,66 @@
+/*
+Copyright 2016-2020 Balena
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { getBalenaSdk } from '../utils/lazy';
+import { LoginServer } from './server';
+
+/**
+ * @module auth
+ */
+
+/**
+ * @summary Login to the balena CLI using the web dashboard
+ * @function
+ * @public
+ *
+ * @description
+ * This function opens the user's default browser and points it
+ * to the balena dashboard where the session token exchange will
+ * take place.
+ *
+ * Once the the token is retrieved, it's automatically persisted.
+ *
+ * @fulfil {String} - session token
+ * @returns {Promise}
+ *
+ * @example
+ * auth.login().then (sessionToken) ->
+ *   console.log('I\'m logged in!')
+ *   console.log("My session token is: #{sessionToken}")
+ */
+export async function login({ host = '127.0.0.1', port = 0 }) {
+	const utils = await import('./utils');
+
+	const loginServer = new LoginServer();
+	const {
+		host: actualHost,
+		port: actualPort,
+		urlPath,
+	} = await loginServer.start({ host, port });
+
+	const callbackUrl = `http://${actualHost}:${actualPort}${urlPath}`;
+	const loginUrl = await utils.getDashboardLoginURL(callbackUrl);
+
+	console.info(`Opening web browser for URL:\n${loginUrl}`);
+	const open = await import('open');
+	open(loginUrl, { wait: false });
+
+	const balena = getBalenaSdk();
+	const token = await loginServer.awaitForToken();
+	await balena.auth.loginWithToken(token);
+	loginServer.shutdown();
+	return token;
+}

lib/auth/pages/error.ejs

@@ -3,7 +3,7 @@
 <head>
 	<meta charset="utf-8">
 	<meta http-equiv="x-ua-compatible" content="ie=edge">
-	<title>Balena CLI - Error</title>
+	<title>balena CLI - Error</title>
 	<meta name="description" content="">
 	<meta name="viewport" content="width=device-width, initial-scale=1">
 	<link rel="stylesheet" type="text/css" href="./static/style.css" inline>
@@ -12,7 +12,8 @@
 	<div class="center">
 		<img class="icon" src="./static/images/sad.png" inline>
 		<h1>Something went wrong</h1>
-		<p>You couldn't login to the balena CLI for some reason</p>
+		<br>
+		<p>The balena CLI login was not successful.</p>
 		<br>
 		<br>
 		<a href="https://forums.balena.io/" class="button danger">Get help in our forums</a>

lib/auth/pages/success.ejs

@@ -3,7 +3,7 @@
 <head>
 	<meta charset="utf-8">
 	<meta http-equiv="x-ua-compatible" content="ie=edge">
-	<title>Balena CLI - Success</title>
+	<title>balena CLI - Success</title>
 	<meta name="description" content="">
 	<meta name="viewport" content="width=device-width, initial-scale=1">
 	<link rel="stylesheet" type="text/css" href="./static/style.css" inline>
@@ -12,10 +12,9 @@
 	<div class="center">
 		<img class="icon" src="./static/images/happy.png" inline>
 		<h1>Success!</h1>
-		<p>You successfully logged in the balena CLI</p>
 		<br>
-		<br>
-		<a href="<%= dashboardUrl %>" class="button normal">Go to the dashboard</a>
+		<p>The balena CLI login was successful.</p>
+		<p>You may now close this page and return to the command prompt.</p>
 	</div>
 </body>
 </html>

lib/auth/server.coffee

@@ -1,101 +0,0 @@
-###
-Copyright 2016 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-express = require('express')
-path = require('path')
-bodyParser = require('body-parser')
-Promise = require('bluebird')
-balena = require('balena-sdk').fromSharedOptions()
-utils = require('./utils')
-
-createServer = ({ port, isDev } = {}) ->
-	app = express()
-	app.use bodyParser.urlencoded
-		extended: true
-
-	app.set('view engine', 'ejs')
-	app.set('views', path.join(__dirname, 'pages'))
-
-	if isDev
-		app.use(express.static(path.join(__dirname, 'pages', 'static')))
-
-	server = app.listen(port)
-
-	return { app, server }
-
-###*
-# @summary Await for token
-# @function
-# @protected
-#
-# @param {Object} options - options
-# @param {String} options.path - callback path
-# @param {Number} options.port - http port
-#
-# @example
-# server.awaitForToken
-# 	path: '/auth'
-# 	port: 9001
-# .then (token) ->
-#   console.log(token)
-###
-exports.awaitForToken = (options) ->
-	{ app, server } = createServer(port: options.port)
-
-	return new Promise (resolve, reject) ->
-		closeServer = (errorMessage, successPayload) ->
-			server.close ->
-				if errorMessage
-					reject(new Error(errorMessage))
-					return
-
-				resolve(successPayload)
-
-		renderAndDone = ({ request, response, viewName, errorMessage, statusCode, token }) ->
-			return getContext(viewName)
-			.then (context) ->
-				response.status(statusCode || 200).render(viewName, context)
-				request.connection.destroy()
-				closeServer(errorMessage, token)
-
-		app.post options.path, (request, response) ->
-			token = request.body.token?.trim()
-
-			Promise.try ->
-				if not token
-					throw new Error('No token')
-				return utils.loginIfTokenValid(token)
-			.tap (loggedIn) ->
-				if not loggedIn
-					throw new Error('Invalid token')
-			.then ->
-				renderAndDone({ request, response, viewName: 'success', token })
-			.catch (error) ->
-				renderAndDone({
-					request, response, viewName: 'error',
-					statusCode: 401, errorMessage: error.message
-				})
-
-		app.use (request, response) ->
-			response.status(404).send('Not found')
-			closeServer('Unknown path or verb')
-
-exports.getContext = getContext = (viewName) ->
-	if viewName is 'success'
-		return Promise.props
-			dashboardUrl: balena.settings.get('dashboardUrl')
-
-	return Promise.resolve({})

lib/auth/server.ts

@@ -0,0 +1,148 @@
+/*
+Copyright 2016-2020 Balena
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import * as bodyParser from 'body-parser';
+import { EventEmitter } from 'events';
+import * as express from 'express';
+import type { Socket } from 'net';
+import * as path from 'path';
+
+import * as utils from './utils';
+import { ExpectedError } from '../errors';
+
+export class LoginServer extends EventEmitter {
+	protected expressApp: express.Express;
+	protected server: import('net').Server;
+	protected serverSockets: Socket[] = [];
+	protected firstError: Error;
+	protected token: string;
+
+	public readonly loginPath = '/auth';
+
+	/**
+	 * Start the HTTP server, listening on the given IP address and port number.
+	 * If the port number is 0, the OS will allocate a free port number.
+	 */
+	public async start({ host = '127.0.0.1', port = 0 } = {}): Promise<{
+		host: string;
+		port: number;
+		urlPath: string;
+	}> {
+		this.once('error', (err: Error) => {
+			this.firstError = err;
+		});
+		this.on('token', (token: string) => {
+			this.token = token;
+		});
+
+		const app = (this.expressApp = express());
+		app.use(
+			bodyParser.urlencoded({
+				extended: true,
+			}),
+		);
+
+		app.set('view engine', 'ejs');
+		app.set('views', path.join(__dirname, 'pages'));
+
+		this.server = await new Promise<import('net').Server>((resolve, reject) => {
+			const server = app.listen(port, host, (err: Error) => {
+				if (err) {
+					this.emit('error', err);
+					reject(err);
+				} else {
+					resolve(server);
+				}
+			});
+			server.on('connection', (socket) => this.serverSockets.push(socket));
+		});
+
+		this.expressApp.post(this.loginPath, async (request, response) => {
+			this.server.close(); // stop listening for new connections
+			try {
+				const token = request.body.token?.trim();
+				if (!token) {
+					throw new ExpectedError('No token');
+				}
+				const loggedIn = await utils.loginIfTokenValid(token);
+				if (!loggedIn) {
+					throw new ExpectedError('Invalid token');
+				}
+				this.emit('token', token);
+				response.status(200).render('success');
+			} catch (error) {
+				this.emit('error', error);
+				response.status(401).render('error');
+			}
+		});
+
+		this.expressApp.use((_request, response) => {
+			this.server.close(); // stop listening for new connections
+			this.emit('error', new Error('Unknown path or verb'));
+			response.status(404).send('Not found');
+		});
+
+		return this.getAddress();
+	}
+
+	public getAddress(): { host: string; port: number; urlPath: string } {
+		const info = this.server.address() as import('net').AddressInfo;
+		return {
+			host: info.address,
+			port: info.port,
+			urlPath: this.loginPath,
+		};
+	}
+
+	/**
+	 * Shut the server down.
+	 * Call this method to avoid the process hanging in some situations.
+	 */
+	public shutdown() {
+		// A Node.js `http.server` instance prevents the process from exiting for up to
+		// 2 minutes (by default) if a client keeps a HTTP connection open, and regardless
+		// of whether `server.close()` was called: the `server.close(callback)` callback
+		// takes just as long to complete. Setting `server.timeout` to some value like
+		// 3 seconds works, but then the CLI process hangs for "only" 3 seconds. Reducing
+		// the timeout to 1 second may cause authentication failure if the laptop or CI
+		// server are slow for any reason. The only reliable way around it seems to be to
+		// explicitly unref the sockets, so the event loop stops waiting for it. See:
+		// https://github.com/nodejs/node/issues/2642
+		// https://github.com/nodejs/node-v0.x-archive/issues/9066
+		//
+		this.serverSockets.forEach((s) => s.unref());
+		this.serverSockets.splice(0);
+	}
+
+	/**
+	 * Await for the user to complete login through a web browser.
+	 * Resolve to the authentication token string.
+	 *
+	 * @return Promise that resolves to the authentication token string
+	 */
+	public async awaitForToken(): Promise<string> {
+		if (this.firstError) {
+			throw this.firstError;
+		}
+		if (this.token) {
+			return this.token;
+		}
+		return new Promise<string>((resolve, reject) => {
+			this.on('error', reject);
+			this.on('token', resolve);
+		});
+	}
+}

lib/auth/utils.coffee

@@ -1,80 +0,0 @@
-###
-Copyright 2016 Balena
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-###
-
-balena = require('balena-sdk').fromSharedOptions()
-_ = require('lodash')
-url = require('url')
-Promise = require('bluebird')
-
-###*
-# @summary Get dashboard CLI login URL
-# @function
-# @protected
-#
-# @param {String} callbackUrl - callback url
-# @fulfil {String} - dashboard login url
-# @returns {Promise}
-#
-# @example
-# utils.getDashboardLoginURL('http://127.0.0.1:3000').then (url) ->
-# 	console.log(url)
-###
-exports.getDashboardLoginURL = (callbackUrl) ->
-
-	# Encode percentages signs from the escaped url
-	# characters to avoid angular getting confused.
-	callbackUrl = encodeURIComponent(callbackUrl).replace(/%/g, '%25')
-
-	balena.settings.get('dashboardUrl').then (dashboardUrl) ->
-		return url.resolve(dashboardUrl, "/login/cli/#{callbackUrl}")
-
-###*
-# @summary Log in using a token, but only if the token is valid
-# @function
-# @protected
-#
-# @description
-# This function checks that the token is not only well-structured
-# but that it also authenticates with the server successfully.
-#
-# If authenticated, the token is persisted, if not then the previous
-# login state is restored.
-#
-# @param {String} token - session token or api key
-# @fulfil {Boolean} - whether the login was successful or not
-# @returns {Promise}
-#
-# utils.loginIfTokenValid('...').then (loggedIn) ->
-#   if loggedIn
-#     console.log('Token is valid!')
-###
-exports.loginIfTokenValid = (token) ->
-	if not token? or _.isEmpty(token.trim())
-		return Promise.resolve(false)
-
-	return balena.auth.getToken()
-	.catchReturn(undefined)
-	.then (currentToken) ->
-		balena.auth.loginWithToken(token)
-			.return(token)
-			.then(balena.auth.isLoggedIn)
-			.tap (isLoggedIn) ->
-				return if isLoggedIn
-
-				if currentToken?
-					return balena.auth.loginWithToken(currentToken)
-				else
-					return balena.auth.logout()

lib/auth/utils.ts

@@ -0,0 +1,89 @@
+/*
+Copyright 2016 Balena
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import * as _ from 'lodash';
+import * as url from 'url';
+import { getBalenaSdk } from '../utils/lazy';
+
+/**
+ * @summary Get dashboard CLI login URL
+ * @function
+ * @protected
+ *
+ * @param {String} callbackUrl - callback url
+ * @fulfil {String} - dashboard login url
+ * @returns {Promise}
+ *
+ * @example
+ * utils.getDashboardLoginURL('http://127.0.0.1:3000').then (url) ->
+ * 	console.log(url)
+ */
+export const getDashboardLoginURL = (callbackUrl: string) => {
+	// Encode percentages signs from the escaped url
+	// characters to avoid angular getting confused.
+	callbackUrl = encodeURIComponent(callbackUrl).replace(/%/g, '%25');
+
+	return getBalenaSdk()
+		.settings.get('dashboardUrl')
+		.then((dashboardUrl) =>
+			url.resolve(dashboardUrl, `/login/cli/${callbackUrl}`),
+		);
+};
+
+/**
+ * @summary Log in using a token, but only if the token is valid
+ * @function
+ * @protected
+ *
+ * @description
+ * This function checks that the token is not only well-structured
+ * but that it also authenticates with the server successfully.
+ *
+ * If authenticated, the token is persisted, if not then the previous
+ * login state is restored.
+ *
+ * @param {String} token - session token or api key
+ * @fulfil {Boolean} - whether the login was successful or not
+ * @returns {Promise}
+ *
+ * utils.loginIfTokenValid('...').then (loggedIn) ->
+ *   if loggedIn
+ *     console.log('Token is valid!')
+ */
+export const loginIfTokenValid = async (token: string): Promise<boolean> => {
+	if (_.isEmpty(token?.trim())) {
+		return false;
+	}
+	const balena = getBalenaSdk();
+
+	let currentToken;
+	try {
+		currentToken = await balena.auth.getToken();
+	} catch {
+		// ignore
+	}
+
+	await balena.auth.loginWithToken(token);
+	const isLoggedIn = await balena.auth.isLoggedIn();
+	if (!isLoggedIn) {
+		if (currentToken != null) {
+			await balena.auth.loginWithToken(currentToken);
+		} else {
+			await balena.auth.logout();
+		}
+	}
+	return isLoggedIn;
+};

lib/command.ts

@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Command from '@oclif/command';
+import { InsufficientPrivilegesError } from './errors';
+
+export default abstract class BalenaCommand extends Command {
+	/**
+	 * When set to true, command will be listed in `help`,
+	 * otherwise listed in `help --verbose` with secondary commands.
+	 */
+	public static primary = false;
+
+	/**
+	 * Require elevated privileges to run.
+	 * When set to true, command will exit with an error
+	 * if executed without root on Mac/Linux
+	 * or if executed by non-Administrator on Windows.
+	 */
+	public static root = false;
+
+	/**
+	 * Require authentication to run.
+	 * When set to true, command will exit with an error
+	 * if user is not already logged in.
+	 */
+	public static authenticated = false;
+
+	/**
+	 * Accept piped input.
+	 * When set to true, command will read from stdin during init
+	 * and make contents available on member `stdin`.
+	 */
+	public static readStdin = false;
+
+	public stdin: string;
+
+	/**
+	 * Throw InsufficientPrivilegesError if not root on Mac/Linux
+	 * or non-Administrator on Windows.
+	 *
+	 * Called automatically if `root=true`.
+	 * Can be called explicitly by command implementation, if e.g.:
+	 *  - check should only be done conditionally
+	 *  - other code needs to execute before check
+	 */
+	protected static async checkElevatedPrivileges() {
+		const isElevated = await (await import('is-elevated'))();
+		if (!isElevated) {
+			throw new InsufficientPrivilegesError(
+				'You need root/admin privileges to run this command',
+			);
+		}
+	}
+
+	/**
+	 * Throw NotLoggedInError if not logged in.
+	 *
+	 * Called automatically if `authenticated=true`.
+	 * Can be called explicitly by command implementation, if e.g.:
+	 *  - check should only be done conditionally
+	 *  - other code needs to execute before check
+	 *
+	 *  Note, currently public to allow use outside of derived commands
+	 *  (as some command implementations require this. Can be made protected
+	 *  if this changes).
+	 *
+	 * @throws {NotLoggedInError}
+	 */
+	public static async checkLoggedIn() {
+		await (await import('./utils/patterns')).checkLoggedIn();
+	}
+
+	/**
+	 * Throw NotLoggedInError if not logged in when condition true.
+	 *
+	 * @param {boolean} doCheck - will check if true.
+	 * @throws {NotLoggedInError}
+	 */
+	public static async checkLoggedInIf(doCheck: boolean) {
+		if (doCheck) {
+			await this.checkLoggedIn();
+		}
+	}
+
+	/**
+	 * Read stdin contents and make available to command.
+	 *
+	 * This approach could be improved in the future to automatically set argument
+	 * values from stdin based in configuration, minimising command implementation.
+	 */
+	protected async getStdin() {
+		this.stdin = await (await import('get-stdin'))();
+	}
+
+	/**
+	 * Get a logger instance.
+	 */
+	protected static async getLogger() {
+		return (await import('./utils/logger')).getLogger();
+	}
+
+	protected async init() {
+		const ctr = this.constructor as typeof BalenaCommand;
+
+		if (ctr.root) {
+			await BalenaCommand.checkElevatedPrivileges();
+		}
+
+		if (ctr.authenticated) {
+			await BalenaCommand.checkLoggedIn();
+		}
+
+		if (ctr.readStdin) {
+			await this.getStdin();
+		}
+	}
+}

lib/commands/api-key/generate.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import Command from '../../command';
+import { ExpectedError } from '../../errors';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	name: string;
+}
+
+export default class GenerateCmd extends Command {
+	public static description = stripIndent`
+		Generate a new balenaCloud API key.
+
+		Generate a new balenaCloud API key for the current user, with the given
+		name. The key will be logged to the console.
+
+		This key can be used to log into the CLI using 'balena login --token <key>',
+		or to authenticate requests to the API with an 'Authorization: Bearer <key>' header.
+`;
+	public static examples = ['$ balena api-key generate "Jenkins Key"'];
+
+	public static args = [
+		{
+			name: 'name',
+			description: 'the API key name',
+			required: true,
+		},
+	];
+
+	public static usage = 'api-key generate <name>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(GenerateCmd);
+
+		let key;
+		try {
+			key = await getBalenaSdk().models.apiKey.create(params.name);
+		} catch (e) {
+			if (e.name === 'BalenaNotLoggedIn') {
+				throw new ExpectedError(stripIndent`
+					This command cannot be run when logged in with an API key.
+					Please login again with 'balena login' and select an alternative method.
+				`);
+			} else {
+				throw e;
+			}
+		}
+
+		console.log(stripIndent`
+			Registered api key '${params.name}':
+
+			${key}
+
+			This key will not be shown again, so please save it now.
+		`);
+	}
+}

lib/commands/app/create.ts

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import Command from '../../command';
+import { ExpectedError } from '../../errors';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import type * as BalenaSDK from 'balena-sdk';
+
+interface FlagsDef {
+	type?: string; // application device type
+	help: void;
+}
+
+interface ArgsDef {
+	name: string;
+}
+
+export default class AppCreateCmd extends Command {
+	public static description = stripIndent`
+		Create an application.
+
+		Create a new balena application.
+
+		You can specify the application device type with the \`--type\` option.
+		Otherwise, an interactive dropdown will be shown for you to select from.
+
+		You can see a list of supported device types with:
+
+		$ balena devices supported
+`;
+	public static examples = [
+		'$ balena app create MyApp',
+		'$ balena app create MyApp --type raspberry-pi',
+	];
+
+	public static args = [
+		{
+			name: 'name',
+			description: 'application name',
+			required: true,
+		},
+	];
+
+	public static usage = 'app create <name>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		type: flags.string({
+			char: 't',
+			description:
+				'application device type (Check available types with `balena devices supported`)',
+		}),
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
+			AppCreateCmd,
+		);
+
+		const balena = getBalenaSdk();
+
+		// Create application
+		const deviceType =
+			options.type ||
+			(await (await import('../../utils/patterns')).selectDeviceType());
+		let application: BalenaSDK.Application;
+		try {
+			application = await balena.models.application.create({
+				name: params.name,
+				deviceType,
+				organization: (await balena.auth.whoami())!,
+			});
+		} catch (err) {
+			// BalenaRequestError: Request error: Unique key constraint violated
+			if ((err.message || '').toLowerCase().includes('unique')) {
+				throw new ExpectedError(
+					`Error: application "${params.name}" already exists`,
+				);
+			}
+			throw err;
+		}
+		console.info(
+			`Application created: ${application.slug} (${deviceType}, id ${application.id})`,
+		);
+	}
+}

lib/commands/app/index.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, getVisuals, stripIndent } from '../../utils/lazy';
+import type { Release } from 'balena-sdk';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	name: string;
+}
+
+export default class AppCmd extends Command {
+	public static description = stripIndent`
+		Display information about a single application.
+
+		Display detailed information about a single balena application.
+`;
+	public static examples = ['$ balena app MyApp'];
+
+	public static args = [
+		{
+			name: 'name',
+			description: 'application name or numeric ID',
+			required: true,
+		},
+	];
+
+	public static usage = 'app <name>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+	public static primary = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(AppCmd);
+
+		const { getApplication } = await import('../../utils/sdk');
+
+		const application = (await getApplication(getBalenaSdk(), params.name, {
+			$expand: {
+				is_for__device_type: { $select: 'slug' },
+				should_be_running__release: { $select: 'commit' },
+			},
+		})) as ApplicationWithDeviceType & {
+			should_be_running__release: [Release?];
+		};
+
+		// @ts-expect-error
+		application.device_type = application.is_for__device_type[0].slug;
+		// @ts-expect-error
+		application.commit = application.should_be_running__release[0]?.commit;
+		console.log(
+			getVisuals().table.vertical(application, [
+				`$${application.app_name}$`,
+				'id',
+				'device_type',
+				'slug',
+				'commit',
+			]),
+		);
+	}
+}

lib/commands/app/purge.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { tryAsInteger } from '../../utils/validation';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	name: string;
+}
+
+export default class AppRestartCmd extends Command {
+	public static description = stripIndent`
+		Purge data from an application.
+
+		Purge data from all devices belonging to an application.
+		This will clear the application's /data directory.
+`;
+	public static examples = ['$ balena app purge MyApp'];
+
+	public static args = [
+		{
+			name: 'name',
+			description: 'application name or numeric ID',
+			required: true,
+		},
+	];
+
+	public static usage = 'app purge <name>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(AppRestartCmd);
+
+		const balena = getBalenaSdk();
+
+		// balena.models.application.purge only accepts a numeric id
+		// so we must first fetch the app to get it's id, if we have been given a name
+		let nameOrId = tryAsInteger(params.name);
+
+		if (typeof nameOrId === 'string') {
+			const app = await balena.models.application.get(nameOrId);
+			nameOrId = app.id;
+		}
+
+		try {
+			await balena.models.application.purge(nameOrId);
+		} catch (e) {
+			if (e.message.toLowerCase().includes('no online device(s) found')) {
+				// application.purge throws an error if no devices are online
+				// ignore in this case.
+			} else {
+				throw e;
+			}
+		}
+	}
+}

lib/commands/app/rename.ts

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import type { IArg } from '@oclif/parser/lib/args';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent, getCliForm } from '../../utils/lazy';
+import type { Application, ApplicationType, BalenaSDK } from 'balena-sdk';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	name: string;
+	newName?: string;
+}
+
+export default class AppRenameCmd extends Command {
+	public static description = stripIndent`
+		Rename an application.
+
+		Rename an application.
+
+		Note, if the \`newName\` parameter is omitted, it will be
+		prompted for interactively.
+		`;
+	public static examples = [
+		'$ balena app rename OldName',
+		'$ balena app rename OldName NewName',
+	];
+
+	public static args: Array<IArg<any>> = [
+		{
+			name: 'name',
+			description: 'application name or numeric ID',
+			required: true,
+		},
+		{
+			name: 'newName',
+			description: 'the new name for the application',
+		},
+	];
+
+	public static usage = 'app rename <name> [newName]';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(AppRenameCmd);
+
+		const { ExpectedError, instanceOf } = await import('../../errors');
+		const { getApplication } = await import('../../utils/sdk');
+		const balena = getBalenaSdk();
+
+		// Get app
+		let app;
+		try {
+			app = await getApplication(balena, params.name, {
+				$expand: {
+					application_type: {
+						$select: ['is_legacy'],
+					},
+				},
+			});
+		} catch (e) {
+			const { BalenaApplicationNotFound } = await import('balena-errors');
+			if (instanceOf(e, BalenaApplicationNotFound)) {
+				throw new ExpectedError(`Application ${params.name} not found.`);
+			} else {
+				throw e;
+			}
+		}
+
+		// Check app supports renaming
+		const appType = (app.application_type as ApplicationType[])?.[0];
+		if (appType.is_legacy) {
+			throw new ExpectedError(
+				`Application ${params.name} is of 'legacy' type, and cannot be renamed.`,
+			);
+		}
+
+		const { validateApplicationName } = await import('../../utils/validation');
+		const newName =
+			params.newName ||
+			(await getCliForm().ask({
+				message: 'Please enter the new name for this application:',
+				type: 'input',
+				validate: validateApplicationName,
+			})) ||
+			'';
+
+		try {
+			await this.renameApplication(balena, app.id, newName);
+		} catch (e) {
+			// BalenaRequestError: Request error: Unique key constraint violated
+			if ((e.message || '').toLowerCase().includes('unique')) {
+				throw new ExpectedError(
+					`Error: application ${params.name} already exists.`,
+				);
+			}
+			throw e;
+		}
+
+		console.log(`Application ${params.name} renamed to ${newName}`);
+	}
+
+	async renameApplication(balena: BalenaSDK, id: number, newName: string) {
+		return balena.pine.patch<Application>({
+			resource: 'application',
+			id,
+			body: {
+				app_name: newName,
+			},
+		});
+	}
+}

lib/commands/app/restart.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { tryAsInteger } from '../../utils/validation';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	name: string;
+}
+
+export default class AppRestartCmd extends Command {
+	public static description = stripIndent`
+		Restart an application.
+
+		Restart all devices belonging to an application.
+`;
+	public static examples = ['$ balena app restart MyApp'];
+
+	public static args = [
+		{
+			name: 'name',
+			description: 'application name or numeric ID',
+			required: true,
+		},
+	];
+
+	public static usage = 'app restart <name>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(AppRestartCmd);
+
+		await getBalenaSdk().models.application.restart(tryAsInteger(params.name));
+	}
+}

lib/commands/app/rm.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { tryAsInteger } from '../../utils/validation';
+
+interface FlagsDef {
+	yes: boolean;
+	help: void;
+}
+
+interface ArgsDef {
+	name: string;
+}
+
+export default class AppRmCmd extends Command {
+	public static description = stripIndent`
+		Remove an application.
+
+		Permanently remove a balena application.
+
+		The --yes option may be used to avoid interactive confirmation.
+`;
+	public static examples = [
+		'$ balena app rm MyApp',
+		'$ balena app rm MyApp --yes',
+	];
+
+	public static args = [
+		{
+			name: 'name',
+			description: 'application name or numeric ID',
+			required: true,
+		},
+	];
+
+	public static usage = 'app rm <name>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		yes: cf.yes,
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
+			AppRmCmd,
+		);
+
+		const patterns = await import('../../utils/patterns');
+
+		// Confirm
+		await patterns.confirm(
+			options.yes ?? false,
+			`Are you sure you want to delete application ${params.name}?`,
+		);
+
+		// Remove
+		await getBalenaSdk().models.application.remove(tryAsInteger(params.name));
+	}
+}

lib/commands/apps.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import Command from '../command';
+import * as cf from '../utils/common-flags';
+import { getBalenaSdk, getVisuals, stripIndent } from '../utils/lazy';
+import { isV12 } from '../utils/version';
+
+interface ExtendedApplication extends ApplicationWithDeviceType {
+	device_count?: number;
+	online_devices?: number;
+}
+
+interface FlagsDef {
+	help: void;
+	verbose?: boolean;
+}
+
+export default class AppsCmd extends Command {
+	public static description = stripIndent`
+		List all applications.
+
+		list all your balena applications.
+
+		For detailed information on a particular application,
+		use \`balena app <name> instead\`.
+`;
+	public static examples = ['$ balena apps'];
+
+	public static usage = 'apps';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+		verbose: flags.boolean({
+			char: 'v',
+			description: isV12()
+				? 'No-op since release v12.0.0'
+				: 'add extra columns in the tabular output (SLUG)',
+		}),
+	};
+
+	public static authenticated = true;
+	public static primary = true;
+
+	public async run() {
+		const { flags: options } = this.parse<FlagsDef, {}>(AppsCmd);
+
+		const balena = getBalenaSdk();
+
+		// Get applications
+		const applications = (await balena.models.application.getAll({
+			$select: ['id', 'app_name', 'slug'],
+			$expand: {
+				is_for__device_type: { $select: 'slug' },
+				owns__device: { $select: 'is_online' },
+			},
+		})) as ExtendedApplication[];
+
+		const _ = await import('lodash');
+		// Add extended properties
+		applications.forEach((application) => {
+			application.device_count = application.owns__device?.length ?? 0;
+			application.online_devices = _.sumBy(application.owns__device, (d) =>
+				d.is_online === true ? 1 : 0,
+			);
+			// @ts-expect-error
+			application.device_type = application.is_for__device_type[0].slug;
+		});
+
+		// Display
+		console.log(
+			getVisuals().table.horizontal(applications, [
+				'id',
+				'app_name',
+				options.verbose || isV12() ? 'slug' : '',
+				'device_type',
+				'online_devices',
+				'device_count',
+			]),
+		);
+	}
+}

lib/commands/build.ts

@@ -0,0 +1,258 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import Command from '../command';
+import { getBalenaSdk } from '../utils/lazy';
+import * as compose from '../utils/compose';
+import type { Application, ApplicationType, BalenaSDK } from 'balena-sdk';
+import { dockerignoreHelp, registrySecretsHelp } from '../utils/messages';
+import type { ComposeCliFlags, ComposeOpts } from '../utils/compose-types';
+import { buildProject, composeCliFlags } from '../utils/compose_ts';
+import type { BuildOpts, DockerCliFlags } from '../utils/docker';
+import { dockerCliFlags } from '../utils/docker';
+
+interface FlagsDef extends ComposeCliFlags, DockerCliFlags {
+	arch?: string;
+	deviceType?: string;
+	application?: string;
+	source?: string; // Not part of command profile - source param copied here.
+	help: void;
+}
+
+interface ArgsDef {
+	source?: string;
+}
+
+export default class BuildCmd extends Command {
+	public static description = `\
+Build a project locally.
+
+Use this command to build an image or a complete multicontainer project with
+the provided docker daemon in your development machine or balena device.
+(See also the \`balena push\` command for the option of building images in the
+balenaCloud build servers.)
+
+You must provide either an application or a device-type/architecture pair.
+
+This command will look into the given source directory (or the current working
+directory if one isn't specified) for a docker-compose.yml file, and if found,
+each service defined in the compose file will be built. If a compose file isn't
+found, it will look for a Dockerfile[.template] file (or alternative Dockerfile
+specified with the \`--dockerfile\` option), and if no dockerfile is found, it
+will try to generate one.
+
+${registrySecretsHelp}
+
+${dockerignoreHelp}
+`;
+	public static examples = [
+		'$ balena build --application myApp',
+		'$ balena build ./source/ --application myApp',
+		'$ balena build --deviceType raspberrypi3 --arch armv7hf --emulated',
+		'$ balena build --docker /var/run/docker.sock --application myApp   # Linux, Mac',
+		'$ balena build --docker //./pipe/docker_engine --application myApp # Windows',
+		'$ balena build --dockerHost my.docker.host --dockerPort 2376 --ca ca.pem --key key.pem --cert cert.pem -a myApp',
+	];
+
+	public static args = [
+		{
+			name: 'source',
+			description: 'path of project source directory',
+		},
+	];
+
+	public static usage = 'build [source]';
+
+	public static flags: flags.Input<FlagsDef> = {
+		arch: flags.string({
+			description: 'the architecture to build for',
+			char: 'A',
+		}),
+		deviceType: flags.string({
+			description: 'the type of device this build is for',
+			char: 'd',
+		}),
+		application: flags.string({
+			description: 'name of the target balena application this build is for',
+			char: 'a',
+		}),
+		...composeCliFlags,
+		...dockerCliFlags,
+		// NOTE: Not supporting -h for help, because of clash with -h in DockerCliFlags
+		// Revisit this in future release.
+		help: flags.help({}),
+	};
+
+	public static primary = true;
+
+	public async run() {
+		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
+			BuildCmd,
+		);
+
+		await Command.checkLoggedInIf(!!options.application);
+
+		// compositions with many services trigger misleading warnings
+		// @ts-ignore editing property that isn't typed but does exist
+		(await import('events')).defaultMaxListeners = 1000;
+
+		const sdk = getBalenaSdk();
+
+		const logger = await Command.getLogger();
+		logger.logDebug('Parsing input...');
+
+		// `build` accepts `source` as a parameter, but compose expects it as an option
+		options.source = params.source;
+		delete params.source;
+
+		await this.validateOptions(options, sdk);
+
+		const app = await this.getAppAndResolveArch(options);
+
+		const { docker, buildOpts, composeOpts } = await this.prepareBuild(options);
+
+		try {
+			await this.buildProject(docker, logger, composeOpts, {
+				app,
+				arch: options.arch!,
+				deviceType: options.deviceType!,
+				buildEmulated: options.emulated,
+				buildOpts,
+			});
+		} catch (err) {
+			logger.logError('Build failed.');
+			throw err;
+		}
+
+		logger.outputDeferredMessages();
+		logger.logSuccess('Build succeeded!');
+	}
+
+	protected async validateOptions(opts: FlagsDef, sdk: BalenaSDK) {
+		// Validate option combinations
+		if (
+			(opts.application == null &&
+				(opts.arch == null || opts.deviceType == null)) ||
+			(opts.application != null &&
+				(opts.arch != null || opts.deviceType != null))
+		) {
+			const { ExpectedError } = await import('../errors');
+			throw new ExpectedError(
+				'You must specify either an application or an arch/deviceType pair to build for',
+			);
+		}
+
+		// Validate project directory
+		const { validateProjectDirectory } = await import('../utils/compose_ts');
+		const { dockerfilePath, registrySecrets } = await validateProjectDirectory(
+			sdk,
+			{
+				dockerfilePath: opts.dockerfile,
+				noParentCheck: opts['noparent-check'] || false,
+				projectPath: opts.source || '.',
+				registrySecretsPath: opts['registry-secrets'],
+			},
+		);
+
+		opts.dockerfile = dockerfilePath;
+		opts['registry-secrets'] = registrySecrets;
+	}
+
+	protected async getAppAndResolveArch(opts: FlagsDef) {
+		if (opts.application) {
+			const { getAppWithArch } = await import('../utils/helpers');
+			const app = await getAppWithArch(opts.application);
+			opts.arch = app.arch;
+			opts.deviceType = app.is_for__device_type[0].slug;
+			return app;
+		}
+	}
+
+	protected async prepareBuild(options: FlagsDef) {
+		const { getDocker, generateBuildOpts } = await import('../utils/docker');
+		const [docker, buildOpts, composeOpts] = await Promise.all([
+			getDocker(options),
+			generateBuildOpts(options),
+			compose.generateOpts(options),
+		]);
+		return {
+			docker,
+			buildOpts,
+			composeOpts,
+		};
+	}
+
+	/**
+	 * Opts must be an object with the following keys:
+	 *   app: the app this build is for (optional)
+	 *   arch: the architecture to build for
+	 *   deviceType: the device type to build for
+	 *   buildEmulated
+	 *   buildOpts: arguments to forward to docker build command
+	 *
+	 * @param {DockerToolbelt} docker
+	 * @param {Logger} logger
+	 * @param {ComposeOpts} composeOpts
+	 * @param opts
+	 */
+	protected async buildProject(
+		docker: import('docker-toolbelt'),
+		logger: import('../utils/logger'),
+		composeOpts: ComposeOpts,
+		opts: {
+			app?: Application;
+			arch: string;
+			deviceType: string;
+			buildEmulated: boolean;
+			buildOpts: BuildOpts;
+		},
+	) {
+		const { loadProject } = await import('../utils/compose_ts');
+
+		const project = await loadProject(logger, composeOpts);
+
+		const appType = (opts.app?.application_type as ApplicationType[])?.[0];
+		if (
+			appType != null &&
+			project.descriptors.length > 1 &&
+			!appType.supports_multicontainer
+		) {
+			logger.logWarn(
+				'Target application does not support multiple containers.\n' +
+					'Continuing with build, but you will not be able to deploy.',
+			);
+		}
+
+		await buildProject({
+			docker,
+			logger,
+			projectPath: project.path,
+			projectName: project.name,
+			composition: project.composition,
+			arch: opts.arch,
+			deviceType: opts.deviceType,
+			emulated: opts.buildEmulated,
+			buildOpts: opts.buildOpts,
+			inlineLogs: composeOpts.inlineLogs,
+			convertEol: composeOpts.convertEol,
+			dockerfilePath: composeOpts.dockerfilePath,
+			nogitignore: composeOpts.nogitignore,
+			multiDockerignore: composeOpts.multiDockerignore,
+		});
+	}
+}

lib/commands/config/generate.ts

@@ -0,0 +1,257 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, getCliForm, stripIndent } from '../../utils/lazy';
+import type { PineDeferred } from 'balena-sdk';
+
+interface FlagsDef {
+	version: string; // OS version
+	application?: string;
+	app?: string; // application alias
+	device?: string;
+	deviceApiKey?: string;
+	deviceType?: string;
+	'generate-device-api-key': boolean;
+	output?: string;
+	// Options for non-interactive configuration
+	network?: string;
+	wifiSsid?: string;
+	wifiKey?: string;
+	appUpdatePollInterval?: string;
+	help: void;
+}
+
+export default class ConfigGenerateCmd extends Command {
+	public static description = stripIndent`
+		Generate a config.json file.
+
+		Generate a config.json file for a device or application.
+
+		Calling this command with the exact version number of the targeted image is required.
+
+		This command is interactive by default, but you can do this automatically without interactivity
+		by specifying an option for each question on the command line, if you know the questions
+		that will be asked for the relevant device type.
+
+		In case that you want to configure an image for an application with mixed device types,
+		you can pass the --device-type argument along with --app to specify the target device type.
+	`;
+
+	public static examples = [
+		'$ balena config generate --device 7cf02a6 --version 2.12.7',
+		'$ balena config generate --device 7cf02a6 --version 2.12.7 --generate-device-api-key',
+		'$ balena config generate --device 7cf02a6 --version 2.12.7 --device-api-key <existingDeviceKey>',
+		'$ balena config generate --device 7cf02a6 --version 2.12.7 --output config.json',
+		'$ balena config generate --app MyApp --version 2.12.7',
+		'$ balena config generate --app MyApp --version 2.12.7 --device-type fincm3',
+		'$ balena config generate --app MyApp --version 2.12.7 --output config.json',
+		'$ balena config generate --app MyApp --version 2.12.7 --network wifi --wifiSsid mySsid --wifiKey abcdefgh --appUpdatePollInterval 1',
+	];
+
+	public static usage = 'config generate';
+
+	public static flags: flags.Input<FlagsDef> = {
+		version: flags.string({
+			description: 'a balenaOS version',
+			required: true,
+		}),
+		application: flags.string({
+			description: 'application name',
+			char: 'a',
+			exclusive: ['app', 'device'],
+		}),
+		app: flags.string({
+			description: "same as '--application'",
+			exclusive: ['application', 'device'],
+		}),
+		device: flags.string({
+			description: 'device uuid',
+			char: 'd',
+			exclusive: ['application', 'app'],
+		}),
+		deviceApiKey: flags.string({
+			description:
+				'custom device key - note that this is only supported on balenaOS 2.0.3+',
+			char: 'k',
+		}),
+		deviceType: flags.string({
+			description: 'device type slug',
+		}),
+		'generate-device-api-key': flags.boolean({
+			description: 'generate a fresh device key for the device',
+		}),
+		output: flags.string({
+			description: 'path of output file',
+			char: 'o',
+		}),
+		// Options for non-interactive configuration
+		network: flags.string({
+			description: 'the network type to use: ethernet or wifi',
+			options: ['ethernet', 'wifi'],
+		}),
+		wifiSsid: flags.string({
+			description:
+				'the wifi ssid to use (used only if --network is set to wifi)',
+		}),
+		wifiKey: flags.string({
+			description:
+				'the wifi key to use (used only if --network is set to wifi)',
+		}),
+		appUpdatePollInterval: flags.string({
+			description:
+				'how frequently (in minutes) to poll for application updates',
+		}),
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { flags: options } = this.parse<FlagsDef, {}>(ConfigGenerateCmd);
+
+		const { getApplication } = await import('../../utils/sdk');
+
+		const balena = getBalenaSdk();
+
+		await this.validateOptions(options);
+
+		let resourceDeviceType: string;
+		let application: ApplicationWithDeviceType | null = null;
+		let device:
+			| (DeviceWithDeviceType & { belongs_to__application: PineDeferred })
+			| null = null;
+		if (options.device != null) {
+			const { tryAsInteger } = await import('../../utils/validation');
+			const rawDevice = await balena.models.device.get(
+				tryAsInteger(options.device),
+				{ $expand: { is_of__device_type: { $select: 'slug' } } },
+			);
+			if (!rawDevice.belongs_to__application) {
+				const { ExpectedError } = await import('../../errors');
+				throw new ExpectedError(stripIndent`
+					Device ${options.device} does not appear to belong to an accessible application.
+					Try with a different device, or use '--application' instead of '--device'.`);
+			}
+			device = rawDevice as DeviceWithDeviceType & {
+				belongs_to__application: PineDeferred;
+			};
+			resourceDeviceType = device.is_of__device_type[0].slug;
+		} else {
+			application = (await getApplication(balena, options.application!, {
+				$expand: {
+					is_for__device_type: { $select: 'slug' },
+				},
+			})) as ApplicationWithDeviceType;
+			resourceDeviceType = application.is_for__device_type[0].slug;
+		}
+
+		const deviceType = options.deviceType || resourceDeviceType;
+
+		const deviceManifest = await balena.models.device.getManifestBySlug(
+			deviceType,
+		);
+
+		// Check compatibility if application and deviceType provided
+		if (options.application && options.deviceType) {
+			const appDeviceManifest = await balena.models.device.getManifestBySlug(
+				resourceDeviceType,
+			);
+
+			const helpers = await import('../../utils/helpers');
+			if (
+				!helpers.areDeviceTypesCompatible(appDeviceManifest, deviceManifest)
+			) {
+				throw new balena.errors.BalenaInvalidDeviceType(
+					`Device type ${options.deviceType} is incompatible with application ${options.application}`,
+				);
+			}
+		}
+
+		// Prompt for values
+		// Pass params as an override: if there is any param with exactly the same name as a
+		// required option, that value is used (and the corresponding question is not asked)
+		const answers = await getCliForm().run(deviceManifest.options, {
+			override: options,
+		});
+		answers.version = options.version;
+
+		// Generate config
+		const { generateDeviceConfig, generateApplicationConfig } = await import(
+			'../../utils/config'
+		);
+
+		let config;
+		if (device) {
+			config = await generateDeviceConfig(
+				device,
+				options.deviceApiKey || options['generate-device-api-key'] || undefined,
+				answers,
+			);
+		} else if (application) {
+			answers.deviceType = deviceType;
+			config = await generateApplicationConfig(application, answers);
+		}
+
+		// Output
+		if (options.output != null) {
+			const fs = await import('fs');
+			await fs.promises.writeFile(options.output, JSON.stringify(config));
+		}
+
+		const prettyjson = await import('prettyjson');
+		console.log(prettyjson.render(config));
+	}
+
+	protected readonly missingDeviceOrAppMessage = stripIndent`
+		Either a device or an application must be specified.
+
+		See the help page for examples:
+
+		  $ balena help config generate
+  	`;
+
+	protected readonly deviceTypeNotAllowedMessage = stripIndent`
+		Specifying a different device type is only supported when
+		generating a config for an application:
+
+		* An application, with --app <appname>
+		* A specific device type, with --device-type <deviceTypeSlug>
+
+		See the help page for examples:
+
+		  $ balena help config generate
+	`;
+
+	protected async validateOptions(options: FlagsDef) {
+		const { ExpectedError } = await import('../../errors');
+
+		// Prefer options.application over options.app
+		options.application = options.application || options.app;
+		delete options.app;
+
+		if (options.device == null && options.application == null) {
+			throw new ExpectedError(this.missingDeviceOrAppMessage);
+		}
+
+		if (!options.application && options.deviceType) {
+			throw new ExpectedError(this.deviceTypeNotAllowedMessage);
+		}
+	}
+}

lib/commands/config/inject.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * Copyright 2016-2020 Balena Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { flags } from '@oclif/command';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getVisuals, stripIndent } from '../../utils/lazy';
+
+interface FlagsDef {
+	type: string;
+	drive?: string;
+	help: void;
+}
+
+interface ArgsDef {
+	file: string;
+}
+
+export default class ConfigInjectCmd extends Command {
+	public static description = stripIndent`
+		Inject a configuration file into a device or OS image.
+
+		Inject a config.json file to the mounted filesystem,
+		e.g. the SD card of a provisioned device or balenaOS image.
+	`;
+
+	public static examples = [
+		'$ balena config inject my/config.json --type raspberrypi3',
+		'$ balena config inject my/config.json --type raspberrypi3 --drive /dev/disk2',
+	];
+
+	public static args = [
+		{
+			name: 'file',
+			description: 'the path to the config.json file to inject',
+			required: true,
+		},
+	];
+
+	public static usage = 'config inject <file>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		type: flags.string({
+			description:
+				'device type (Check available types with `balena devices supported`)',
+			char: 't',
+			required: true,
+		}),
+		drive: flags.string({
+			description: 'device filesystem or OS image location',
+			char: 'd',
+		}),
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public static root = true;
+
+	public async run() {
+		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
+			ConfigInjectCmd,
+		);
+
+		const { promisify } = await import('util');
+		const umountAsync = promisify((await import('umount')).umount);
+
+		const drive =
+			options.drive || (await getVisuals().drive('Select the device/OS drive'));
+		await umountAsync(drive);
+
+		const fs = await import('fs');
+		const configJSON = JSON.parse(
+			await fs.promises.readFile(params.file, 'utf8'),
+		);
+
+		const config = await import('balena-config-json');
+		await config.write(drive, options.type, configJSON);
+
+		console.info('Done');
+	}
+}