Add balena update command for updating the CLI

Change-type: minor

.gitattributes

@@ -6,7 +6,7 @@
 *.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
+docs/balena-cli.md 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/actions/publish/action.yml

@@ -0,0 +1,134 @@
+---
+name: package and draft GitHub release
+# https://github.com/product-os/flowzone/tree/master/.github/actions
+inputs:
+  json:
+    description: 'JSON stringified object containing all the inputs from the calling workflow'
+    required: true
+  secrets:
+    description: 'JSON stringified object containing all the secrets from the calling workflow'
+    required: true
+  variables:
+    description: 'JSON stringified object containing all the variables from the calling workflow'
+    required: true
+
+  # --- custom environment
+  XCODE_APP_LOADER_EMAIL:
+    type: string
+    default: 'accounts+apple@balena.io'
+  NODE_VERSION:
+    type: string
+    default: '16.x'
+  VERBOSE:
+    type: string
+    default: 'true'
+
+runs:
+  # https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
+  using: 'composite'
+  steps:
+    - name: Download custom source artifact
+      uses: actions/download-artifact@v3
+      with:
+        name: custom-${{ github.event.pull_request.head.sha || github.event.head_commit.id }}-${{ runner.os }}-${{ runner.arch }}
+        path: ${{ runner.temp }}
+
+    - name: Extract custom source artifact
+      shell: pwsh
+      working-directory: .
+      run: tar -xf ${{ runner.temp }}/custom.tgz
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ inputs.NODE_VERSION }}
+        cache: npm
+
+    - name: Install additional tools
+      if: runner.os == 'Windows'
+      shell: bash
+      run: |
+        choco install yq
+
+    - name: Install additional tools
+      if: runner.os == 'macOS'
+      shell: bash
+      run: |
+        brew install coreutils
+
+    # https://www.electron.build/code-signing.html
+    # https://github.com/Apple-Actions/import-codesign-certs
+    - name: Import Apple code signing certificate
+      if: runner.os == 'macOS'
+      uses: apple-actions/import-codesign-certs@v1
+      with:
+        p12-file-base64: ${{ fromJSON(inputs.secrets).APPLE_SIGNING }}
+        p12-password: ${{ fromJSON(inputs.secrets).APPLE_SIGNING_PASSWORD }}
+
+    - name: Import Windows code signing certificate
+      if: runner.os == 'Windows'
+      shell: powershell
+      run: |
+        Set-Content -Path ${{ runner.temp }}/certificate.base64 -Value $env:WINDOWS_CERTIFICATE
+        certutil -decode ${{ runner.temp }}/certificate.base64 ${{ runner.temp }}/certificate.pfx
+        Remove-Item -path ${{ runner.temp }} -include certificate.base64
+
+        Import-PfxCertificate `
+          -FilePath ${{ runner.temp }}/certificate.pfx `
+          -CertStoreLocation Cert:\CurrentUser\My `
+          -Password (ConvertTo-SecureString -String $env:WINDOWS_CERTIFICATE_PASSWORD -Force -AsPlainText)
+
+      env:
+        WINDOWS_CERTIFICATE: ${{ fromJSON(inputs.secrets).WINDOWS_SIGNING }}
+        WINDOWS_CERTIFICATE_PASSWORD: ${{ fromJSON(inputs.secrets).WINDOWS_SIGNING_PASSWORD }}
+
+    # https://github.com/product-os/scripts/tree/master/shared
+    # https://github.com/product-os/balena-concourse/blob/master/pipelines/github-events/template.yml
+    - name: Package release
+      shell: bash
+      run: |
+        set -ea
+
+        [[ '${{ inputs.VERBOSE }}' =~ on|On|Yes|yes|true|True ]] && set -x
+
+        runner_os="$(echo "${RUNNER_OS}" | tr '[:upper:]' '[:lower:]')"
+        runner_arch="$(echo "${RUNNER_ARCH}" | tr '[:upper:]' '[:lower:]')"
+
+        if [[ $runner_os =~ darwin|macos|osx ]]; then
+            CSC_KEY_PASSWORD=${{ fromJSON(inputs.secrets).APPLE_SIGNING_PASSWORD }}
+            CSC_KEYCHAIN=signing_temp
+            CSC_LINK=${{ fromJSON(inputs.secrets).APPLE_SIGNING }}
+
+        elif [[ $runner_os =~ windows|win ]]; then
+            CSC_KEY_PASSWORD=${{ fromJSON(inputs.secrets).WINDOWS_SIGNING_PASSWORD }}
+            CSC_LINK='${{ runner.temp }}\certificate.pfx'
+
+            # patches/all/oclif.patch
+            MSYSSHELLPATH="$(which bash)"
+            MSYSTEM=MSYS
+
+            # (signtool.exe) https://github.com/actions/runner-images/blob/main/images/win/Windows2019-Readme.md#installed-windows-sdks
+            PATH="/c/Program Files (x86)/Windows Kits/10/bin/${runner_arch}:${PATH}"
+        fi
+
+        npm run package
+
+        find dist -type f -maxdepth 1
+
+      env:
+        # https://github.blog/2020-08-03-github-actions-improvements-for-fork-and-pull-request-workflows/#improvements-for-public-repository-forks
+        # https://docs.github.com/en/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks#about-workflow-runs-from-public-forks
+        CSC_FOR_PULL_REQUEST: true
+        # https://sectigo.com/resource-library/time-stamping-server
+        TIMESTAMP_SERVER: http://timestamp.sectigo.com
+        # Apple notarization (automation/build-bin.ts)
+        XCODE_APP_LOADER_EMAIL: ${{ inputs.XCODE_APP_LOADER_EMAIL }}
+        XCODE_APP_LOADER_PASSWORD: ${{ fromJSON(inputs.secrets).XCODE_APP_LOADER_PASSWORD }}
+        XCODE_APP_LOADER_TEAM_ID: ${{ inputs.XCODE_APP_LOADER_TEAM_ID }}
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        name: gh-release-${{ github.event.pull_request.head.sha || github.event.head_commit.id }}
+        path: dist
+        retention-days: 1

.github/actions/test/action.yml

@@ -0,0 +1,59 @@
+---
+name: test release
+# https://github.com/product-os/flowzone/tree/master/.github/actions
+inputs:
+  json:
+    description: "JSON stringified object containing all the inputs from the calling workflow"
+    required: true
+  secrets:
+    description: "JSON stringified object containing all the secrets from the calling workflow"
+    required: true
+  variables:
+    description: "JSON stringified object containing all the variables from the calling workflow"
+    required: true
+
+  # --- custom environment
+  NODE_VERSION:
+    type: string
+    default: '16.x'
+  VERBOSE:
+    type: string
+    default: "true"
+
+runs:
+  # https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
+  using: "composite"
+  steps:
+    # https://github.com/actions/setup-node#caching-global-packages-data
+    - name: Setup Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ inputs.NODE_VERSION }}
+        cache: npm
+
+    - name: Test release
+      shell: bash
+      run: |
+        set -ea
+
+        [[ '${{ inputs.VERBOSE }}' =~ on|On|Yes|yes|true|True ]] && set -x
+
+        if [[ -e package-lock.json ]] || [[ -e npm-shrinkwrap.json ]]; then
+            npm ci
+        else
+            npm i
+        fi
+
+        npm run build
+        npm run test
+
+    - name: Compress custom source
+      shell: pwsh
+      run: tar -acf ${{ runner.temp }}/custom.tgz .
+
+    - name: Upload custom artifact
+      uses: actions/upload-artifact@v3
+      with:
+        name: custom-${{ github.event.pull_request.head.sha || github.event.head_commit.id }}-${{ runner.os }}-${{ runner.arch }}
+        path: ${{ runner.temp }}/custom.tgz
+        retention-days: 1

.github/workflows/flowzone.yml

@@ -0,0 +1,29 @@
+name: Flowzone
+
+on:
+  pull_request:
+    types: [opened, synchronize, closed]
+    branches: [main, master]
+  pull_request_target:
+    types: [opened, synchronize, closed]
+    branches: [main, master]
+
+jobs:
+  flowzone:
+    name: Flowzone
+    uses: product-os/flowzone/.github/workflows/flowzone.yml@v4.7.1
+    # prevent duplicate workflow executions for pull_request and pull_request_target
+    if: |
+      (
+        github.event.pull_request.head.repo.full_name == github.repository &&
+        github.event_name == 'pull_request'
+      ) || (
+        github.event.pull_request.head.repo.full_name != github.repository &&
+        github.event_name == 'pull_request_target'
+      )
+    secrets: inherit
+    with:
+      custom_runs_on: '[["self-hosted","Linux","distro:focal","X64"],["self-hosted","Linux","distro:focal","ARM64"],["macos-12"],["windows-2019"]]'
+      repo_config: true
+      repo_description: "The official balena CLI tool."
+      github_prerelease: false

.mocharc.js

@@ -3,5 +3,8 @@ module.exports = {
 	require: 'ts-node/register/transpile-only',
 	file: './tests/config-tests',
 	timeout: 12000,
+	// To test only, say, 'push.spec.ts', do it as follows so that
+	// requests are authenticated:
+	// spec: ['tests/auth/*.spec.ts', 'tests/**/deploy.spec.ts'],
 	spec: 'tests/**/*.spec.ts',
 };

.resinci.yml

@@ -1,17 +0,0 @@
----
-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"

CONTRIBUTING.md

@@ -105,12 +105,12 @@ 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
+The `docs/balena-cli.md` 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:
+The content sources for the auto generation of `docs/balena-cli.md` are:
 
 * [Selected
   sections](https://github.com/balena-io/balena-cli/blob/v12.23.0/automation/capitanodoc/capitanodoc.ts#L199-L204)
@@ -120,11 +120,44 @@ The content sources for the auto generation of `doc/cli.markdown` are:
   * `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
+`docs/balena-cli.md` 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.
 
+## Patches folder
+
+The `patches` folder contains patch files created with the
+[patch-package](https://www.npmjs.com/package/patch-package) tool. Small code changes to
+third-party modules can be made by directly editing Javascript files under the `node_modules`
+folder and then running `patch-package` to create the patch files. The patch files are then
+applied immediately after `npm install`, through the `postinstall` script defined in
+`package.json`.
+
+The subfolders of the `patches` folder are documented in the
+[apply-patches.js](https://github.com/balena-io/balena-cli/blob/master/patches/apply-patches.js)
+script.
+
+To make changes to the patch files under the `patches` folder, **do not edit them directly,**
+not even for a "single character change" because the hash values in the patch files also need
+to be recomputed by `patch-packages`. Instead, edit the relevant files under `node_modules`
+directly, and then run `patch-packages` with the `--patch-dir` option to specify the subfolder
+where the patch should be saved. For example, edit `node_modules/exit-hook/index.js` and then
+run:
+
+```sh
+$ npx patch-package --patch-dir patches/all exit-hook
+```
+
+That said, these kinds of patches should be avoided in favour of creating pull requests
+upstream. Patch files create additional maintenance work over time as the patches need to be
+updated when the dependencies are updated, and they prevent the compounding community benefit
+that sharing fixes upstream have on open source projects like the balena CLI. The typical
+scenario where these patches are used is when the upstream maintainers are unresponsive or
+unwilling to merge the required fixes, the fixes are very small and specific to the balena CLI,
+and creating a fork of the upstream repo is likely to be more long-term effort than maintaining
+the patches.
+
 ## Windows
 
 Besides the regular npm installation dependencies, the `npm run build:installer` script
@@ -259,3 +292,11 @@ gotchas to bear in mind:
   `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'`
+
+## Further debugging notes
+
+* If you need to selectively run specific tests, `it.only` will not work in cases when authorization is required as part of the test cycle.  In order to target specific tests, control execution via `.mocharc.js` instead.  Here is an example of targeting the `deploy` tests.
+
+	replace: `spec: 'tests/**/*.spec.ts',`
+
+	with: `spec: ['tests/auth/*.spec.ts', 'tests/**/deploy.spec.ts'],`

INSTALL-ADVANCED.md

@@ -78,8 +78,8 @@ If you are a Node.js developer, you may wish to install the balena CLI via [npm]
 The npm installation involves building native (platform-specific) binary modules, which require
 some development tools to be installed first, as follows.
 
-> **The balena CLI currently requires Node.js version 10 (min 10.20.0) or 12.**  
-> **Versions 13 and later are not yet fully supported.**
+> **The balena CLI currently requires Node.js version 16.**  
+> **Versions 17 and later are not yet fully supported.**
 
 ### Install development tools
 
@@ -89,7 +89,7 @@ some development tools to be installed first, as follows.
 $ sudo apt-get update && sudo apt-get -y install curl python3 git make g++
 $ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
 $ . ~/.bashrc
-$ nvm install 12
+$ nvm install 16
 ```
 
 The `curl` command line above uses
@@ -106,15 +106,15 @@ recommended.
 ```sh
 $ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
 $ . ~/.bashrc
-$ nvm install 12
+$ nvm install 16
 ```
 
 #### **Windows** (not WSL)
 
 Install:
 
-* Node.js v12 from the [Nodejs.org releases page](https://nodejs.org/en/download/releases/).
   * If you'd like the ability to switch between Node.js versions, install
+- Node.js v16 from the [Nodejs.org releases page](https://nodejs.org/en/download/releases/).
     [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows)
     instead.
 * The [MSYS2 shell](https://www.msys2.org/), which provides `git`, `make`, `g++` and more:

INSTALL-LINUX.md

@@ -1,6 +1,10 @@
 # balena CLI Installation Instructions for Linux
 
-These instructions are suitable for most Linux distributions on Intel x86, except notably for **Linux Alpine** or **Busybox**. For these distros or for the ARM architecture, follow the [NPM Installation](./INSTALL-ADVANCED.md#npm-installation) method.
+These instructions are suitable for most Linux distributions on Intel x86, such as
+Ubuntu, Debian, Fedora, Arch Linux and other glibc-based distributions.
+For the ARM architecture and for Linux distributions not based on glibc, such as
+Alpine Linux, follow the [NPM Installation](./INSTALL-ADVANCED.md#npm-installation)
+method.
 
 Selected operating system: **Linux**
 

INSTALL-MAC.md

@@ -10,16 +10,14 @@ Selected operating system: **macOS**
    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).
+2. Double click on the downloaded file to run the installer and follow the installer's
+   instructions.
 
-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
+3. Check that the installation was successful:
+   - [Open the Terminal
+   app](https://support.apple.com/en-gb/guide/terminal/apd5265185d-f365-44cb-8b09-71a064a42125/mac).
+   - On the terminal prompt, type `balena version` and hit Enter. It should display
+     the version of the balena CLI that you have installed.
 
 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

INSTALL-WINDOWS.md

@@ -10,16 +10,14 @@ Selected operating system: **Windows**
    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).
+2. Double click on the downloaded file to run the installer and follow the installer's
+   instructions.
 
-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
+3. Check that the installation was successful:
+   - Click on the Windows Start Menu, type PowerShell, and then click
+     on Windows PowerShell.
+   - On the command prompt, type `balena version` and hit Enter. It should display
+     the version of the balena CLI that you have installed.
 
 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

README.md

@@ -144,7 +144,7 @@ To learn more, troubleshoot issues, or to contact us for support:
 
 * 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)
+* Ask us a question in the [balena forums](https://forums.balena.io/c/product-support)
 
 For CLI bug reports or feature requests, check the
 [CLI GitHub issues](https://github.com/balena-io/balena-cli/issues/).
@@ -156,14 +156,18 @@ 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.
+following major version is released. For example, balena CLI v11.36.0, as the
+latest v11 release, would remain compatible with the balenaCloud backend for one
+year from the date when v12.0.0 was 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.
+Half way through to that period (6 months after the release of the next major
+version), older major versions of the balena CLI will start printing a deprecation
+warning message when it is used interactively (when `stderr` is attached to a TTY
+device file). At the end of that period, older major versions will exit with an
+error message unless the `--unsupported` flag is used.  This behavior was
+introduced in CLI version 12.47.0 and is also documented by `balena help`.
+To take advantage of the latest backend features and ensure compatibility, users
+are encouraged to regularly update the balena CLI to the latest version.
 
 ## Contributing (including editing documentation files)
 

automation/build-bin.ts

@@ -17,35 +17,34 @@
 
 import type { JsonVersions } from '../lib/commands/version';
 
-import { run as oclifRun } from '@oclif/dev-cli';
+import { run as oclifRun } from 'oclif';
 import * as archiver from 'archiver';
 import * as Bluebird from 'bluebird';
 import { execFile } from 'child_process';
 import * as filehound from 'filehound';
+import { Stats } from 'fs';
 import * as fs from 'fs-extra';
+import * as klaw from 'klaw';
 import * as _ from 'lodash';
 import * as path from 'path';
 import * as rimraf from 'rimraf';
 import * as semver from 'semver';
-import * as util from 'util';
-import * as klaw from 'klaw';
-import { Stats } from 'fs';
+import { promisify } from 'util';
 
-import { stripIndent } from '../lib/utils/lazy';
+import { stripIndent } from '../build/utils/lazy';
 import {
 	diffLines,
-	getSubprocessStdout,
 	loadPackageJson,
 	ROOT,
 	StdOutTap,
 	whichSpawn,
 } from './utils';
 
+const execFileAsync = promisify(execFile);
+
 export const packageJSON = loadPackageJson();
 export const version = 'v' + packageJSON.version;
 const arch = process.arch;
-const MSYS2_BASH =
-	process.env.MSYSSHELLPATH || 'C:\\msys64\\usr\\bin\\bash.exe';
 
 function dPath(...paths: string[]) {
 	return path.join(ROOT, 'dist', ...paths);
@@ -63,7 +62,7 @@ const standaloneZips: PathByPlatform = {
 
 const oclifInstallers: PathByPlatform = {
 	darwin: dPath('macos', `balena-${version}.pkg`),
-	win32: dPath('win', `balena-${version}-${arch}.exe`),
+	win32: dPath('win32', `balena-${version}-${arch}.exe`),
 };
 
 const renamedOclifInstallers: PathByPlatform = {
@@ -88,13 +87,14 @@ async function diffPkgOutput(pkgOut: string) {
 		'tests',
 		'test-data',
 		'pkg',
-		`expected-warnings-${process.platform}.txt`,
+		`expected-warnings-${process.platform}-${arch}.txt`,
 	);
 	const absSavedPath = path.join(ROOT, relSavedPath);
 	const ignoreStartsWith = [
 		'> pkg@',
 		'> Fetching base Node.js binaries',
 		'  fetched-',
+		'prebuild-install WARN install No prebuilt binaries found',
 	];
 	const modulesRE =
 		process.platform === 'win32'
@@ -180,9 +180,18 @@ async function execPkg(...args: any[]) {
  * to be directly executed from inside another binary executable.)
  */
 async function buildPkg() {
+	// https://github.com/vercel/pkg#targets
+	let targets = `linux-${arch}`;
+	// TBC: not possible to build for macOS or Windows arm64 on x64 nodes
+	if (process.platform === 'darwin') {
+		targets = `macos-x64`;
+	}
+	if (process.platform === 'win32') {
+		targets = `win-x64`;
+	}
 	const args = [
-		'--target',
-		'host',
+		'--targets',
+		targets,
 		'--output',
 		'build-bin/balena',
 		'package.json',
@@ -246,7 +255,17 @@ async function testPkg() {
 	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 { stdout, stderr } = await execFileAsync(pkgBalenaPath, [
+		'version',
+		'-j',
+	]);
+	const { filterCliOutputForTests } = await import('../tests/helpers');
+	const filtered = filterCliOutputForTests({
+		err: stderr.split(/\r?\n/),
+		out: stdout.split(/\r?\n/),
+	});
+	stdout = filtered.out.join('\n');
+	stderr = filtered.err.join('\n');
 	let pkgNodeVersion = '';
 	let pkgNodeMajorVersion = 0;
 	try {
@@ -263,6 +282,10 @@ async function testPkg() {
 			`Mismatched major version: built-in pkg Node version="${pkgNodeVersion}" vs process.version="${process.version}"`,
 		);
 	}
+	if (filtered.err.length > 0) {
+		const err = filtered.err.join('\n');
+		throw new Error(`"${pkgBalenaPath}": non-empty stderr "${err}"`);
+	}
 	console.log('Success! (standalone package test successful)');
 }
 
@@ -295,7 +318,7 @@ async function zipPkg() {
 		archive.on('warning', console.warn);
 
 		archive.pipe(outputStream);
-		archive.finalize();
+		archive.finalize().catch(reject);
 	});
 }
 
@@ -307,6 +330,10 @@ async function signFilesForNotarization() {
 				if (!item.stats.isFile()) {
 					return;
 				}
+				if (path.basename(item.path).endsWith('.node.bak')) {
+					console.log('Removing pkg .node.bak file', item.path);
+					fs.unlinkSync(item.path);
+				}
 				if (
 					path.basename(item.path).endsWith('.zip') &&
 					path.dirname(item.path).includes('test')
@@ -405,22 +432,28 @@ async function renameInstallerFiles() {
 
 /**
  * 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.
+ * executable installer using Microsoft SignTool.exe (Sign Tool)
+ * https://learn.microsoft.com/en-us/dotnet/framework/tools/signtool-exe
  */
 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',
+		// trust ...
+		await execFileAsync('signtool.exe', [
+			'sign',
+			'-t',
+			process.env.TIMESTAMP_SERVER || 'http://timestamp.comodoca.com',
 			'-f',
-			exeName,
+			process.env.CSC_LINK,
+			'-p',
+			process.env.CSC_KEY_PASSWORD,
 			'-d',
 			`balena-cli ${version}`,
+			exeName,
 		]);
+		// ... but verify
+		await execFileAsync('signtool.exe', ['verify', '-pa', '-v', exeName]);
 	} else {
 		console.log(
 			'Skipping installer signing step because CSC_* env vars are not set',
@@ -432,18 +465,26 @@ async function signWindowsInstaller() {
  * Wait for Apple Installer Notarization to continue
  */
 async function notarizeMacInstaller(): Promise<void> {
-	const appleId = 'accounts+apple@balena.io';
-	const { notarize } = await import('electron-notarize');
-	await notarize({
-		appBundleId: 'io.balena.etcher',
-		appPath: renamedOclifInstallers.darwin,
-		appleId,
-		appleIdPassword: '@keychain:CLI_PASSWORD',
-	});
+	const teamId = process.env.XCODE_APP_LOADER_TEAM_ID || '66H43P8FRG';
+	const appleId =
+		process.env.XCODE_APP_LOADER_EMAIL || 'accounts+apple@balena.io';
+	const appleIdPassword = process.env.XCODE_APP_LOADER_PASSWORD;
+
+	if (appleIdPassword && teamId) {
+		const { notarize } = await import('@electron/notarize');
+		// https://github.com/electron/notarize#readme
+		await notarize({
+			tool: 'notarytool',
+			teamId,
+			appPath: renamedOclifInstallers.darwin,
+			appleId,
+			appleIdPassword,
+		});
+	}
 }
 
 /**
- * Run the `oclif-dev pack:win` or `pack:macos` command (depending on the value
+ * Run the `oclif 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.
@@ -473,7 +514,7 @@ export async function buildOclifInstaller() {
 			await signFilesForNotarization();
 		}
 		console.log('=======================================================');
-		console.log(`oclif-dev "${packCmd}" "${packOpts.join('" "')}"`);
+		console.log(`oclif "${packCmd}" "${packOpts.join('" "')}"`);
 		console.log(`cwd="${process.cwd()}" ROOT="${ROOT}"`);
 		console.log('=======================================================');
 		await oclifRun([packCmd].concat(...packOpts));

automation/capitanodoc/capitanodoc.ts

@@ -36,19 +36,12 @@ const capitanoDoc = {
 		{
 			title: 'Fleet',
 			files: [
-				'build/commands/apps.js',
 				'build/commands/fleets.js',
-				'build/commands/app/index.js',
 				'build/commands/fleet/index.js',
-				'build/commands/app/create.js',
 				'build/commands/fleet/create.js',
-				'build/commands/app/purge.js',
 				'build/commands/fleet/purge.js',
-				'build/commands/app/rename.js',
 				'build/commands/fleet/rename.js',
-				'build/commands/app/restart.js',
 				'build/commands/fleet/restart.js',
-				'build/commands/app/rm.js',
 				'build/commands/fleet/rm.js',
 			],
 		},
@@ -82,6 +75,14 @@ const capitanoDoc = {
 				'build/commands/device/shutdown.js',
 			],
 		},
+		{
+			title: 'Releases',
+			files: [
+				'build/commands/releases.js',
+				'build/commands/release/index.js',
+				'build/commands/release/finalize.js',
+			],
+		},
 		{
 			title: 'Environment Variables',
 			files: [

automation/capitanodoc/index.ts

@@ -101,8 +101,9 @@ async function printMarkdown() {
 		console.log(await renderMarkdown());
 	} catch (error) {
 		console.error(error);
-		process.exit(1);
+		process.exitCode = 1;
 	}
 }
 
+// tslint:disable-next-line:no-floating-promises
 printMarkdown();

automation/check-doc.ts

@@ -15,24 +15,25 @@
  * 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');
+// tslint:disable-next-line:import-blacklist
+import { stripIndent } from 'common-tags';
+import * as _ from 'lodash';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { simpleGit } from 'simple-git';
 
 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
+ * Compare the timestamp of balena-cli.md with the timestamp of staged files,
+ * issuing an error if balena-cli.md is older.
+ * If balena-cli.md 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 git = simpleGit(ROOT);
+	const docFile = path.join(ROOT, 'docs', 'balena-cli.md');
 	const [docStat, gitStatus] = await Promise.all([
 		fs.stat(docFile),
 		git.status(),
@@ -81,4 +82,5 @@ async function run() {
 	}
 }
 
+// tslint:disable-next-line:no-floating-promises
 run();

automation/check-npm-version.js

@@ -6,6 +6,8 @@
  *
  * 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.
+ *
+ * @param {string} version
  */
 function parseSemver(version) {
 	const match = /v?(\d+)\.(\d+).(\d+)/.exec(version);
@@ -16,6 +18,10 @@ function parseSemver(version) {
 	return [parseInt(major, 10), parseInt(minor, 10), parseInt(patch, 10)];
 }
 
+/**
+ * @param {string} v1
+ * @param {string} v2
+ */
 function semverGte(v1, v2) {
 	let v1Array = parseSemver(v1);
 	let v2Array = parseSemver(v2);
@@ -41,17 +47,25 @@ function checkNpmVersion() {
 		// 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(`\
--------------------------------------------------------------------------------
+		throw new 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();
+function main() {
+	try {
+		checkNpmVersion();
+	} catch (e) {
+		console.error(e.message || e);
+		process.exitCode = 1;
+	}
+}
+
+main();

automation/deploy-bin.ts

@@ -54,9 +54,7 @@ export async function release() {
 	try {
 		await createGitHubRelease();
 	} catch (err) {
-		console.error('Release failed');
-		console.error(err);
-		process.exit(1);
+		throw new Error(`Error creating GitHub release:\n${err}`);
 	}
 }
 

automation/run.ts

@@ -35,11 +35,6 @@ process.env.DEBUG = ['0', 'no', 'false', '', undefined].includes(
 	? ''
 	: '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:
@@ -49,12 +44,12 @@ function exitWithError(error: Error | string): never {
  *
  * @param args Arguments to parse (default is process.argv.slice(2))
  */
-export async function run(args?: string[]) {
+async function parse(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}]`);
+	console.error(`[debug] automation/run.ts process.argv=[${process.argv}]`);
+	console.error(`[debug] automation/run.ts args=[${args}]`);
 	if (_.isEmpty(args)) {
-		return exitWithError('missing command-line arguments');
+		throw new Error('missing command-line arguments');
 	}
 	const commands: { [cmd: string]: () => void | Promise<void> } = {
 		'build:installer': buildOclifInstaller,
@@ -66,7 +61,7 @@ export async function run(args?: string[]) {
 	};
 	for (const arg of args) {
 		if (!commands.hasOwnProperty(arg)) {
-			return exitWithError(`command unknown: ${arg}`);
+			throw new Error(`command unknown: ${arg}`);
 		}
 	}
 
@@ -90,9 +85,23 @@ export async function run(args?: string[]) {
 			const cmdFunc = commands[arg];
 			await cmdFunc();
 		} catch (err) {
-			return exitWithError(`"${arg}": ${err}`);
+			if (typeof err === 'object') {
+				err.message = `"${arg}": ${err.message}`;
+			}
+			throw err;
 		}
 	}
 }
 
+/** See jsdoc for parse() function above */
+export async function run(args?: string[]) {
+	try {
+		await parse(args);
+	} catch (e) {
+		console.error(e.message ? `Error: ${e.message}` : e);
+		process.exitCode = 1;
+	}
+}
+
+// tslint:disable-next-line:no-floating-promises
 run();

automation/update-module.ts

@@ -11,8 +11,7 @@ const validateChangeType = (maybeChangeType: string = 'minor') => {
 		case 'major':
 			return maybeChangeType;
 		default:
-			console.error(`Invalid change type: '${maybeChangeType}'`);
-			return process.exit(1);
+			throw new Error(`Invalid change type: '${maybeChangeType}'`);
 	}
 };
 
@@ -37,8 +36,8 @@ const run = async (cmd: string) => {
 			}
 			resolve({ stdout, stderr });
 		});
-		p.stdout.pipe(process.stdout);
-		p.stderr.pipe(process.stderr);
+		p.stdout?.pipe(process.stdout);
+		p.stderr?.pipe(process.stderr);
 	});
 };
 
@@ -65,24 +64,17 @@ const getUpstreams = async () => {
 	return upstream;
 };
 
-const printUsage = (upstreams: Upstream[], upstreamName: string) => {
-	console.error(
-		`
+const getUsage = (upstreams: Upstream[], upstreamName: string) => `
 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() {
+async function $main() {
 	const upstreams = await getUpstreams();
 
 	if (process.argv.length < 3) {
-		return printUsage(upstreams, '$upstreamName');
+		throw new Error(getUsage(upstreams, '$upstreamName'));
 	}
 
 	const upstreamName = process.argv[2];
@@ -90,16 +82,15 @@ async function main() {
 	const upstream = upstreams.find((v) => v.repo === upstreamName);
 
 	if (!upstream) {
-		console.error(
+		throw new Error(
 			`Invalid upstream name '${upstreamName}', valid options: ${upstreams
 				.map(({ repo }) => repo)
 				.join(', ')}`,
 		);
-		return process.exit(1);
 	}
 
 	if (process.argv.length < 4) {
-		printUsage(upstreams, upstreamName);
+		throw new Error(getUsage(upstreams, upstreamName));
 	}
 
 	const packageName = upstream.module || upstream.repo;
@@ -108,8 +99,7 @@ async function main() {
 	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);
+		throw new Error(`Already on version '${newVersion}'`);
 	}
 
 	console.log(`Updated ${upstreamName} from ${oldVersion} to ${newVersion}`);
@@ -137,4 +127,14 @@ async function main() {
 	);
 }
 
+async function main() {
+	try {
+		await $main();
+	} catch (e) {
+		console.error(e);
+		process.exitCode = 1;
+	}
+}
+
+// tslint:disable-next-line:no-floating-promises
 main();

automation/utils.ts

@@ -21,22 +21,6 @@ import * as path from 'path';
 
 export const ROOT = path.join(__dirname, '..');
 
-const nodeEngineWarn = `\
-------------------------------------------------------------------------------
-Warning: Node version "v14.x.x" does not match required versions ">=10.20.0 <13.0.0".
-This may cause unexpected behavior. To upgrade Node, visit:
-https://nodejs.org/en/download/
-------------------------------------------------------------------------------
-`;
-const nodeEngineWarnArray = nodeEngineWarn.split('\n').filter((l) => l);
-
-export function matchesNodeEngineVersionWarn(line: string) {
-	line = line.replace(/"v14\.\d{1,3}\.\d{1,3}"/, '"v14.x.x"');
-	return (
-		line === nodeEngineWarn || nodeEngineWarnArray.includes(line.trimEnd())
-	);
-}
-
 /** Tap and buffer this process' stdout and stderr */
 export class StdOutTap {
 	public stdoutBuf: string[] = [];
@@ -104,60 +88,6 @@ export function loadPackageJson() {
 	return require(path.join(ROOT, 'package.json'));
 }
 
-/**
- * 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]') && !matchesNodeEngineVersionWarn(line),
-				);
-				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
@@ -187,7 +117,7 @@ export async function which(program: string): Promise<string> {
  */
 export async function whichSpawn(
 	programName: string,
-	args?: string[],
+	args: string[] = [],
 ): Promise<void> {
 	const program = await which(programName);
 	let error: Error | undefined;

completion/_balena

@@ -8,19 +8,21 @@ _balena() {
   local context state line curcontext="$curcontext"
 
   # Valid top-level completions
-  main_commands=( apps build deploy envs fleets join keys leave login logout logs note orgs preload push scan settings ssh support tags tunnel version whoami api-key app app config device device devices env fleet fleet internal key key local os tag util )
+  main_commands=( build deploy envs fleets join keys leave login logout logs note orgs preload push releases scan settings ssh support tags tunnel version whoami api-key api-keys app block config device device devices env fleet fleet internal key key local os release release tag util )
   # Sub-completions
-  api_key_cmds=( generate )
-  app_cmds=( create purge rename restart rm )
+  api_key_cmds=( generate revoke )
+  app_cmds=( create )
+  block_cmds=( create )
   config_cmds=( generate inject read reconfigure write )
-  device_cmds=( deactivate identify init local-mode move os-update public-url purge reboot register rename restart rm shutdown )
+  device_cmds=( deactivate identify init local-mode move os-update pin public-url purge reboot register rename restart rm shutdown track-fleet )
   devices_cmds=( supported )
   env_cmds=( add rename rm )
-  fleet_cmds=( create purge rename restart rm )
+  fleet_cmds=( create pin purge rename restart rm track-latest )
   internal_cmds=( osinit )
   key_cmds=( add rm )
   local_cmds=( configure flash )
   os_cmds=( build-config configure download initialize versions )
+  release_cmds=( finalize invalidate validate )
   tag_cmds=( rm set )
 
 
@@ -46,6 +48,9 @@ _balena_sec_cmds() {
       "app")
         _describe -t app_cmds 'app_cmd' app_cmds "$@" && ret=0
       ;;
+      "block")
+        _describe -t block_cmds 'block_cmd' block_cmds "$@" && ret=0
+      ;;
       "config")
         _describe -t config_cmds 'config_cmd' config_cmds "$@" && ret=0
       ;;
@@ -73,6 +78,9 @@ _balena_sec_cmds() {
       "os")
         _describe -t os_cmds 'os_cmd' os_cmds "$@" && ret=0
       ;;
+      "release")
+        _describe -t release_cmds 'release_cmd' release_cmds "$@" && ret=0
+      ;;
       "tag")
         _describe -t tag_cmds 'tag_cmd' tag_cmds "$@" && ret=0
       ;;

completion/balena-completion.bash

@@ -7,19 +7,21 @@ _balena_complete()
   local cur prev
 
   # Valid top-level completions
-  main_commands="apps build deploy envs fleets join keys leave login logout logs note orgs preload push scan settings ssh support tags tunnel version whoami api-key app app config device device devices env fleet fleet internal key key local os tag util"
+  main_commands="build deploy envs fleets join keys leave login logout logs note orgs preload push releases scan settings ssh support tags tunnel version whoami api-key api-keys app block config device device devices env fleet fleet internal key key local os release release tag util"
   # Sub-completions
-  api_key_cmds="generate"
-  app_cmds="create purge rename restart rm"
+  api_key_cmds="generate revoke"
+  app_cmds="create"
+  block_cmds="create"
   config_cmds="generate inject read reconfigure write"
-  device_cmds="deactivate identify init local-mode move os-update public-url purge reboot register rename restart rm shutdown"
+  device_cmds="deactivate identify init local-mode move os-update pin public-url purge reboot register rename restart rm shutdown track-fleet"
   devices_cmds="supported"
   env_cmds="add rename rm"
-  fleet_cmds="create purge rename restart rm"
+  fleet_cmds="create pin purge rename restart rm track-latest"
   internal_cmds="osinit"
   key_cmds="add rm"
   local_cmds="configure flash"
   os_cmds="build-config configure download initialize versions"
+  release_cmds="finalize invalidate validate"
   tag_cmds="rm set"
 
 
@@ -40,6 +42,9 @@ _balena_complete()
       app)
         COMPREPLY=( $(compgen -W "$app_cmds" -- $cur) )
         ;;
+      block)
+        COMPREPLY=( $(compgen -W "$block_cmds" -- $cur) )
+        ;;
       config)
         COMPREPLY=( $(compgen -W "$config_cmds" -- $cur) )
         ;;
@@ -67,6 +72,9 @@ _balena_complete()
       os)
         COMPREPLY=( $(compgen -W "$os_cmds" -- $cur) )
         ;;
+      release)
+        COMPREPLY=( $(compgen -W "$release_cmds" -- $cur) )
+        ;;
       tag)
         COMPREPLY=( $(compgen -W "$tag_cmds" -- $cur) )
         ;;

doc/automated-init.md

@@ -1,112 +0,0 @@
-# Provisioning balena devices in automated (non-interactive) mode
-
-This document describes how to run the `device init` command in non-interactive mode.
-
-It requires collecting some preliminary information _once_.
-
-The final command to provision the device looks like this:
-
-```bash
-balena device init --fleet FLEET_ID --os-version OS_VERSION --drive DRIVE --config CONFIG_FILE --yes
-
-```
-
-You can run this command as many times as you need, putting the new medium (SD card / USB stick) each time.
-
-But before you can run it you need to collect the parameters and build the configuration file. Keep reading to figure out how to do it.
-
-
-## Collect all the required parameters.
-
-1. `DEVICE_TYPE`. Run
-	```bash
-	balena devices supported
-	```
-	and find the _slug_ for your target device type, like _raspberrypi3_.
-
-1. `FLEET_ID`. Create a fleet (`balena fleet create FLEET_NAME --type DEVICE_TYPE`) or find an existing one (`balena fleets`) and notice its ID.
-
-1. `OS_VERSION`. Run
-	```bash
-	balena os versions DEVICE_TYPE
-	```
-	and pick the version that you need, like _v2.0.6+rev1.prod_.
-	_Note_ that even though we support _semver ranges_ it's recommended to use the exact version when doing the automated provisioning as it
-	guarantees full compatibility between the steps.
-
-1. `DRIVE`. Plug in your target medium (SD card or the USB stick, depending on your device type) and run
-	```bash
-	balena util available-drives
-	```
-	and get the drive name, like _/dev/sdb_ or _/dev/mmcblk0_.
-	The balena CLI will not display the system drives to protect you,
-	but still please check very carefully that you've picked the correct drive as it will be erased during the provisioning process.
-
-Now we have all the parameters -- time to build the config file.
-
-## Build the config file
-
-Interactive device provisioning process often includes collecting some extra device configuration, like the networking mode and wifi credentials.
-
-To skip this interactive step we need to buid this configuration once and save it to the JSON file for later reuse.
-
-Let's say we will place it into the `CONFIG_FILE` path, like _./balena-os/raspberrypi3-config.json_.
-
-We also need to put the OS image somewhere, let's call this path `OS_IMAGE_PATH`, it can be something like _./balena-os/raspberrypi3-v2.0.6+rev1.prod.img_.
-
-1. First we need to download the OS image once. That's needed for building the config, and will speedup the subsequent operations as the downloaded OS image is placed into the local cache.
-
-	Run:
-	```bash
-	balena os download DEVICE_TYPE --output OS_IMAGE_PATH --version OS_VERSION
-	```
-
-1. Now we're ready to build the config:
-
-	```bash
-	balena os build-config OS_IMAGE_PATH DEVICE_TYPE --output CONFIG_FILE
-	```
-
-	This will run you through the interactive configuration wizard and in the end save the generated config as `CONFIG_FILE`. You can then verify it's not empty:
-
-	```bash
-	cat CONFIG_FILE
-	```
-
-## Done
-
-Now you're ready to run the command in the beginning of this guide.
-
-Please note again that all of these steps only need to be done once (unless you need to change something), and once all the parameters are collected the main init command can be run unchanged.
-
-But there are still some nuances to cover, please read below. 
-
-## Nuances
-
-### `sudo` password on *nix systems
-
-In order to write the image to the raw device we need the root permissions, this is unavoidable.
-
-To improve the security we only run the minimal subcommand with `sudo`.
-
-This means that with the default setup you're interrupted closer to the end of the device init process to enter your sudo password for this subcommand to work.
-
-There are several ways to eliminate it and make the process fully non-interactive.
-
-#### Option 1: make passwordless sudo.
-
-Obviously you shouldn't do that if the machine you're working on has access to any sensitive resources or information.
-
-But if you're using a machine dedicated to balena provisioning this can be fine, and also the simplest thing to do.
-
-#### Option 2: `NOPASSWD` directive
-
-You can configure the `balena` CLI command to be sudo-runnable without the password. Check [this post](https://askubuntu.com/questions/159007/how-do-i-run-specific-sudo-commands-without-a-password) for an example.
-
-### Extra initialization config
-
-As of June 2017 all the supported devices should not require any other interactive configuration.
-
-But by the design of our system it is _possible_ (though it doesn't look very likely it's going to happen any time soon) that some extra initialization options may be requested for the specific device types.
-
-If that is the case please raise the issue in the balena CLI repository and the maintainers will add the necessary options to build the similar JSON config for this step.

gulpfile.js

@@ -1,15 +0,0 @@
-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/app.ts

@@ -16,8 +16,14 @@
  */
 
 import * as packageJSON from '../package.json';
+import {
+	AppOptions,
+	checkDeletedCommand,
+	preparseArgs,
+	unsupportedFlag,
+} from './preparser';
 import { CliSettings } from './utils/bootstrap';
-import { onceAsync, stripIndent } from './utils/lazy';
+import { onceAsync } from './utils/lazy';
 
 /**
  * Sentry.io setup
@@ -27,6 +33,7 @@ export const setupSentry = onceAsync(async () => {
 	const config = await import('./config');
 	const Sentry = await import('@sentry/node');
 	Sentry.init({
+		autoSessionTracking: false,
 		dsn: config.sentryDsn,
 		release: packageJSON.version,
 	});
@@ -43,13 +50,8 @@ export const setupSentry = onceAsync(async () => {
 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/
-			------------------------------------------------------------------------------
-			`);
+		const { getNodeEngineVersionWarn } = await import('./utils/messages');
+		console.warn(getNodeEngineVersionWarn(process.version, validNodeVersions));
 	}
 }
 
@@ -75,11 +77,13 @@ export function setMaxListeners(maxListeners: number) {
 /** Selected CLI initialization steps */
 async function init() {
 	if (process.env.BALENARC_NO_SENTRY) {
-		console.error(`WARN: disabling Sentry.io error reporting`);
+		if (process.env.DEBUG) {
+			console.error(`WARN: disabling Sentry.io error reporting`);
+		}
 	} else {
 		await setupSentry();
 	}
-	checkNodeVersion();
+	await checkNodeVersion();
 
 	const settings = new CliSettings();
 
@@ -89,14 +93,26 @@ async function init() {
 	setupBalenaSdkSharedOptions(settings);
 
 	// check for CLI updates once a day
-	(await import('./utils/update')).notify();
+	if (!process.env.BALENARC_OFFLINE_MODE) {
+		(await import('./utils/update')).notify();
+	}
 }
 
 /** Execute the oclif parser and the CLI command. */
-async function oclifRun(
-	command: string[],
-	options: import('./preparser').AppOptions,
-) {
+async function oclifRun(command: string[], options: AppOptions) {
+	let deprecationPromise: Promise<void>;
+	// check and enforce the CLI's deprecation policy
+	if (unsupportedFlag || process.env.BALENARC_UNSUPPORTED) {
+		deprecationPromise = Promise.resolve();
+	} else {
+		const { DeprecationChecker } = await import('./deprecation');
+		const deprecationChecker = new DeprecationChecker(packageJSON.version);
+		// warnAndAbortIfDeprecated uses previously cached data only
+		await deprecationChecker.warnAndAbortIfDeprecated();
+		// checkForNewReleasesIfNeeded may query the npm registry
+		deprecationPromise = deprecationChecker.checkForNewReleasesIfNeeded();
+	}
+
 	const runPromise = (async function (shouldFlush: boolean) {
 		const { CustomMain } = await import('./utils/oclif-utils');
 		let isEEXIT = false;
@@ -130,16 +146,17 @@ async function oclifRun(
 	})(!options.noFlush);
 
 	const { trackPromise } = await import('./hooks/prerun/track');
-	await Promise.all([trackPromise, runPromise]);
+
+	await Promise.all([trackPromise, deprecationPromise, runPromise]);
 }
 
 /** CLI entrypoint. Called by the `bin/balena` and `bin/balena-dev` scripts. */
-export async function run(
-	cliArgs = process.argv,
-	options: import('./preparser').AppOptions = {},
-) {
+export async function run(cliArgs = process.argv, options: AppOptions = {}) {
 	try {
-		const { normalizeEnvVars, pkgExec } = await import('./utils/bootstrap');
+		const { setOfflineModeEnvVars, normalizeEnvVars, pkgExec } = await import(
+			'./utils/bootstrap'
+		);
+		setOfflineModeEnvVars();
 		normalizeEnvVars();
 
 		// The 'pkgExec' special/internal command provides a Node.js interpreter
@@ -150,8 +167,6 @@ export async function run(
 
 		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));
 

lib/auth/index.ts

@@ -56,7 +56,7 @@ export async function login({ host = '127.0.0.1', port = 0 }) {
 
 	console.info(`Opening web browser for URL:\n${loginUrl}`);
 	const open = await import('open');
-	open(loginUrl, { wait: false });
+	await open(loginUrl, { wait: false });
 
 	const balena = getBalenaSdk();
 	const token = await loginServer.awaitForToken();

lib/auth/utils.ts

@@ -14,57 +14,44 @@ 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
+ * Get dashboard CLI login URL
  *
- * @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)
+ * @param callbackUrl - Callback url, e.g. 'http://127.0.0.1:3000'
+ * @returns Dashboard login URL, e.g.:
+ * 'https://dashboard.balena-cloud.com/login/cli/http%253A%252F%252F127.0.0.1%253A59581%252Fauth'
  */
-export const getDashboardLoginURL = (callbackUrl: string) => {
+export async function getDashboardLoginURL(
+	callbackUrl: string,
+): Promise<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}`),
-		);
-};
+	const [{ URL }, dashboardUrl] = await Promise.all([
+		import('url'),
+		getBalenaSdk().settings.get('dashboardUrl'),
+	]);
+	return new URL(`/login/cli/${callbackUrl}`, dashboardUrl).href;
+}
 
 /**
- * @summary Log in using a token, but only if the token is valid
- * @function
- * @protected
+ * Log in using a token, but only if the token is valid.
  *
- * @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!')
+ * @param token - session token or api key
+ * @returns whether the login was successful or not
  */
-export const loginIfTokenValid = async (token: string): Promise<boolean> => {
-	if (_.isEmpty(token?.trim())) {
+export async function loginIfTokenValid(token?: string): Promise<boolean> {
+	token = (token || '').trim();
+	if (!token) {
 		return false;
 	}
 	const balena = getBalenaSdk();
@@ -86,4 +73,4 @@ export const loginIfTokenValid = async (token: string): Promise<boolean> => {
 		}
 	}
 	return isLoggedIn;
-};
+}

lib/command.ts

@@ -16,7 +16,12 @@
  */
 
 import Command from '@oclif/command';
-import { InsufficientPrivilegesError } from './errors';
+import {
+	InsufficientPrivilegesError,
+	NotAvailableInOfflineModeError,
+} from './errors';
+import { stripIndent } from './utils/lazy';
+import * as output from './framework/output';
 
 export default abstract class BalenaCommand extends Command {
 	/**
@@ -40,6 +45,13 @@ export default abstract class BalenaCommand extends Command {
 	 */
 	public static authenticated = false;
 
+	/**
+	 * Require an internet connection to run.
+	 * When set to true, command will exit with an error
+	 * if user is running in offline mode (BALENARC_OFFLINE_MODE).
+	 */
+	public static offlineCompatible = false;
+
 	/**
 	 * Accept piped input.
 	 * When set to true, command will read from stdin during init
@@ -97,6 +109,29 @@ export default abstract class BalenaCommand extends Command {
 		}
 	}
 
+	/**
+	 * Throw NotAvailableInOfflineModeError if in offline mode.
+	 *
+	 * Called automatically if `onlineOnly=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 {NotAvailableInOfflineModeError}
+	 */
+	public static checkNotUsingOfflineMode() {
+		if (process.env.BALENARC_OFFLINE_MODE) {
+			throw new NotAvailableInOfflineModeError(stripIndent`
+		This command requires an internet connection, and cannot be used in offline mode.
+		To leave offline mode, unset the BALENARC_OFFLINE_MODE environment variable.
+		`);
+		}
+	}
+
 	/**
 	 * Read stdin contents and make available to command.
 	 *
@@ -125,8 +160,15 @@ export default abstract class BalenaCommand extends Command {
 			await BalenaCommand.checkLoggedIn();
 		}
 
+		if (!ctr.offlineCompatible) {
+			BalenaCommand.checkNotUsingOfflineMode();
+		}
+
 		if (ctr.readStdin) {
 			await this.getStdin();
 		}
 	}
+
+	protected outputMessage = output.outputMessage;
+	protected outputData = output.outputData;
 }

lib/commands/api-key/revoke.ts

@@ -0,0 +1,80 @@
+/**
+ * @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';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	ids: string;
+}
+
+export default class RevokeCmd extends Command {
+	public static description = stripIndent`
+		Revoke balenaCloud API keys.
+
+		Revoke balenaCloud API keys with the given
+		comma-separated list of ids.
+
+		The given balenaCloud API keys will no longer be usable.
+`;
+	public static examples = [
+		'$ balena api-key revoke 123',
+		'$ balena api-key revoke 123,124,456',
+	];
+
+	public static args = [
+		{
+			name: 'ids',
+			description: 'the API key ids',
+			required: true,
+		},
+	];
+
+	public static usage = 'api-key revoke <ids>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(RevokeCmd);
+
+		try {
+			const apiKeyIds = params.ids.split(',');
+			if (apiKeyIds.filter((apiKeyId) => !apiKeyId.match(/^\d+$/)).length > 0) {
+				console.log('API key ids must be positive integers');
+				return;
+			}
+			await Promise.all(
+				apiKeyIds.map(
+					async (id) => await getBalenaSdk().models.apiKey.revoke(Number(id)),
+				),
+			);
+			console.log('Successfully revoked the given API keys');
+		} catch (e) {
+			throw e;
+		}
+	}
+}

lib/commands/api-keys/index.ts

@@ -0,0 +1,95 @@
+/**
+ * @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';
+
+interface FlagsDef {
+	help: void;
+	user?: void;
+	fleet?: string;
+}
+
+export default class ApiKeysCmd extends Command {
+	public static description = stripIndent`
+		Print a list of balenaCloud API keys.
+
+		Print a list of balenaCloud API keys.
+
+		Print a list of balenaCloud API keys for the current user or for a specific fleet with the \`--fleet\` option.
+`;
+	public static examples = ['$ balena api-keys'];
+
+	public static args = [];
+
+	public static usage = 'api-keys';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+		user: flags.boolean({
+			char: 'u',
+			description: 'show API keys for your user',
+		}),
+		fleet: cf.fleet,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { flags: options } = this.parse<FlagsDef, {}>(ApiKeysCmd);
+
+		try {
+			const { getApplication } = await import('../../utils/sdk');
+			const actorId = options.fleet
+				? (
+						await getApplication(getBalenaSdk(), options.fleet, {
+							$select: 'actor',
+						})
+				  ).actor
+				: await getBalenaSdk().auth.getUserActorId();
+			const keys = await getBalenaSdk().pine.get({
+				resource: 'api_key',
+				options: {
+					$select: ['id', 'created_at', 'name', 'description', 'expiry_date'],
+					$filter: {
+						is_of__actor: actorId,
+						...(options.user
+							? {
+									name: {
+										$ne: null,
+									},
+							  }
+							: {}),
+					},
+					$orderby: 'name asc',
+				},
+			});
+			const fields = ['id', 'name', 'created_at', 'description', 'expiry_date'];
+			const _ = await import('lodash');
+			console.log(
+				getVisuals().table.horizontal(
+					keys.map((key) => _.mapValues(key, (val) => val ?? 'N/a')),
+					fields,
+				),
+			);
+		} catch (e) {
+			throw e;
+		}
+	}
+}

lib/commands/app/create.ts

@@ -16,14 +16,11 @@
  */
 
 import { flags } from '@oclif/command';
-import type { Output as ParserOutput } from '@oclif/parser';
-import type { Application } from 'balena-sdk';
 
 import Command from '../../command';
 import { ExpectedError } from '../../errors';
 import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import { appToFleetCmdMsg, warnify } from '../../utils/messages';
 
 interface FlagsDef {
 	organization?: string;
@@ -35,18 +32,18 @@ interface ArgsDef {
 	name: string;
 }
 
-export class FleetCreateCmd extends Command {
+export default class AppCreateCmd extends Command {
 	public static description = stripIndent`
-		Create a fleet.
+		Create an app.
 
-		Create a new balena fleet.
+		Create a new balena app.
 
-		You can specify the organization the fleet should belong to using
+		You can specify the organization the app should belong to using
 		the \`--organization\` option. The organization's handle, not its name,
 		should be provided. Organization handles can be listed with the
 		\`balena orgs\` command.
 
-		The fleet's default device type is specified with the \`--type\` option.
+		The app's default device type is specified with the \`--type\` option.
 		The \`balena devices supported\` command can be used to list the available
 		device types.
 
@@ -58,39 +55,40 @@ export class FleetCreateCmd extends Command {
 	`;
 
 	public static examples = [
-		'$ balena fleet create MyFleet',
-		'$ balena fleet create MyFleet --organization mmyorg',
-		'$ balena fleet create MyFleet -o myorg --type raspberry-pi',
+		'$ balena app create MyApp',
+		'$ balena app create MyApp --organization mmyorg',
+		'$ balena app create MyApp -o myorg --type raspberry-pi',
 	];
 
 	public static args = [
 		{
 			name: 'name',
-			description: 'fleet name',
+			description: 'app name',
 			required: true,
 		},
 	];
 
-	public static usage = 'fleet create <name>';
+	public static usage = 'app create <name>';
 
 	public static flags: flags.Input<FlagsDef> = {
 		organization: flags.string({
 			char: 'o',
-			description: 'handle of the organization the fleet should belong to',
+			description: 'handle of the organization the app should belong to',
 		}),
 		type: flags.string({
 			char: 't',
 			description:
-				'fleet device type (Check available types with `balena devices supported`)',
+				'app device type (Check available types with `balena devices supported`)',
 		}),
 		help: cf.help,
 	};
 
 	public static authenticated = true;
 
-	public async run(parserOutput?: ParserOutput<FlagsDef, ArgsDef>) {
-		const { args: params, flags: options } =
-			parserOutput || this.parse<FlagsDef, ArgsDef>(FleetCreateCmd);
+	public async run() {
+		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
+			AppCreateCmd,
+		);
 
 		// Ascertain device type
 		const deviceType =
@@ -102,41 +100,40 @@ export class FleetCreateCmd extends Command {
 			options.organization?.toLowerCase() || (await this.getOrganization());
 
 		// Create application
-		let application: Application;
 		try {
-			application = await getBalenaSdk().models.application.create({
+			const application = await getBalenaSdk().models.application.create({
 				name: params.name,
 				deviceType,
 				organization,
+				applicationClass: 'app',
 			});
+
+			// Output
+			console.log(
+				`App created: slug "${application.slug}", device type "${deviceType}"`,
+			);
 		} catch (err) {
 			if ((err.message || '').toLowerCase().includes('unique')) {
 				// BalenaRequestError: Request error: "organization" and "app_name" must be unique.
 				throw new ExpectedError(
-					`Error: fleet "${params.name}" already exists in organization "${organization}".`,
+					`Error: An app or block or fleet with the name "${params.name}" already exists in organization "${organization}".`,
 				);
 			} else if ((err.message || '').toLowerCase().includes('unauthorized')) {
 				// BalenaRequestError: Request error: Unauthorized
 				throw new ExpectedError(
-					`Error: You are not authorized to create fleets in organization "${organization}".`,
+					`Error: You are not authorized to create apps in organization "${organization}".`,
 				);
 			}
 
 			throw err;
 		}
-
-		// Output
-		const { isV13 } = await import('../../utils/version');
-		console.log(
-			isV13()
-				? `Fleet created: slug "${application.slug}", device type "${deviceType}"`
-				: `Fleet created: ${application.slug} (${deviceType}, id ${application.id})`,
-		);
 	}
 
 	async getOrganization() {
 		const { getOwnOrganizations } = await import('../../utils/sdk');
-		const organizations = await getOwnOrganizations(getBalenaSdk());
+		const organizations = await getOwnOrganizations(getBalenaSdk(), {
+			$select: ['name', 'handle'],
+		});
 
 		if (organizations.length === 0) {
 			// User is not a member of any organizations (should not happen).
@@ -151,31 +148,3 @@ export class FleetCreateCmd extends Command {
 		}
 	}
 }
-
-export default class AppCreateCmd extends FleetCreateCmd {
-	public static description = stripIndent`
-		DEPRECATED alias for the 'fleet create' command
-
-		${appToFleetCmdMsg
-			.split('\n')
-			.map((l) => `\t\t${l}`)
-			.join('\n')}
-
-		For command usage, see 'balena help fleet create'
-	`;
-	public static examples = [];
-	public static usage = 'app create <name>';
-	public static args = FleetCreateCmd.args;
-	public static flags = FleetCreateCmd.flags;
-	public static authenticated = FleetCreateCmd.authenticated;
-	public static primary = FleetCreateCmd.primary;
-
-	public async run() {
-		// call this.parse() before deprecation message to parse '-h'
-		const parserOutput = this.parse<FlagsDef, ArgsDef>(AppCreateCmd);
-		if (process.stderr.isTTY) {
-			console.error(warnify(appToFleetCmdMsg));
-		}
-		await super.run(parserOutput);
-	}
-}

lib/commands/app/index.ts

@@ -1,124 +0,0 @@
-/**
- * @license
- * Copyright 2016-2021 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 { flags } from '@oclif/command';
-import type { Output as ParserOutput } from '@oclif/parser';
-import type { Release } from 'balena-sdk';
-
-import Command from '../../command';
-import * as cf from '../../utils/common-flags';
-import * as ca from '../../utils/common-args';
-import { getBalenaSdk, getVisuals, stripIndent } from '../../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetCmdMsg,
-	warnify,
-} from '../../utils/messages';
-
-interface FlagsDef {
-	help: void;
-}
-
-interface ArgsDef {
-	fleet: string;
-}
-
-export class FleetCmd extends Command {
-	public static description = stripIndent`
-		Display information about a single fleet.
-
-		Display detailed information about a single fleet.
-
-		${applicationIdInfo.split('\n').join('\n\t\t')}
-`;
-	public static examples = [
-		'$ balena fleet MyFleet',
-		'$ balena fleet myorg/myfleet',
-	];
-
-	public static args = [ca.fleetRequired];
-
-	public static usage = 'fleet <fleet>';
-
-	public static flags: flags.Input<FlagsDef> = {
-		help: cf.help,
-	};
-
-	public static authenticated = true;
-	public static primary = true;
-
-	public async run(parserOutput?: ParserOutput<FlagsDef, ArgsDef>) {
-		const { args: params } =
-			parserOutput || this.parse<FlagsDef, ArgsDef>(FleetCmd);
-
-		const { getApplication } = await import('../../utils/sdk');
-
-		const application = (await getApplication(getBalenaSdk(), params.fleet, {
-			$expand: {
-				is_for__device_type: { $select: 'slug' },
-				should_be_running__release: { $select: 'commit' },
-			},
-		})) as ApplicationWithDeviceType & {
-			should_be_running__release: [Release?];
-			// For display purposes:
-			device_type: string;
-			commit?: string;
-		};
-
-		application.device_type = application.is_for__device_type[0].slug;
-		application.commit = application.should_be_running__release[0]?.commit;
-
-		// Emulate table.vertical title output, but avoid uppercasing and inserting spaces
-		console.log(`== ${application.app_name}`);
-		console.log(
-			getVisuals().table.vertical(application, [
-				'id',
-				'device_type',
-				'slug',
-				'commit',
-			]),
-		);
-	}
-}
-
-export default class AppCmd extends FleetCmd {
-	public static description = stripIndent`
-		DEPRECATED alias for the 'fleet' command
-
-		${appToFleetCmdMsg
-			.split('\n')
-			.map((l) => `\t\t${l}`)
-			.join('\n')}
-
-		For command usage, see 'balena help fleet'
-	`;
-	public static examples = [];
-	public static usage = 'app <fleet>';
-	public static args = FleetCmd.args;
-	public static flags = FleetCmd.flags;
-	public static authenticated = FleetCmd.authenticated;
-	public static primary = FleetCmd.primary;
-
-	public async run() {
-		// call this.parse() before deprecation message to parse '-h'
-		const parserOutput = this.parse<FlagsDef, ArgsDef>(AppCmd);
-		if (process.stderr.isTTY) {
-			console.error(warnify(appToFleetCmdMsg));
-		}
-		await super.run(parserOutput);
-	}
-}

lib/commands/app/purge.ts

@@ -1,115 +0,0 @@
-/**
- * @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 type { flags } from '@oclif/command';
-import type { Output as ParserOutput } from '@oclif/parser';
-
-import Command from '../../command';
-import * as cf from '../../utils/common-flags';
-import * as ca from '../../utils/common-args';
-import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetCmdMsg,
-	warnify,
-} from '../../utils/messages';
-
-interface FlagsDef {
-	help: void;
-}
-
-interface ArgsDef {
-	fleet: string;
-}
-
-export class FleetPurgeCmd extends Command {
-	public static description = stripIndent`
-		Purge data from a fleet.
-
-		Purge data from all devices belonging to a fleet.
-		This will clear the fleet's '/data' directory.
-
-		${applicationIdInfo.split('\n').join('\n\t\t')}
-	`;
-
-	public static examples = [
-		'$ balena fleet purge MyFleet',
-		'$ balena fleet purge myorg/myfleet',
-	];
-
-	public static args = [ca.fleetRequired];
-
-	public static usage = 'fleet purge <fleet>';
-
-	public static flags: flags.Input<FlagsDef> = {
-		help: cf.help,
-	};
-
-	public static authenticated = true;
-
-	public async run(parserOutput?: ParserOutput<FlagsDef, ArgsDef>) {
-		const { args: params } =
-			parserOutput || this.parse<FlagsDef, ArgsDef>(FleetPurgeCmd);
-
-		const { getApplication } = await import('../../utils/sdk');
-
-		const balena = getBalenaSdk();
-
-		// balena.models.application.purge only accepts a numeric id
-		// so we must first fetch the app to get it's id,
-		const application = await getApplication(balena, params.fleet);
-
-		try {
-			await balena.models.application.purge(application.id);
-		} 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;
-			}
-		}
-	}
-}
-
-export default class AppPurgeCmd extends FleetPurgeCmd {
-	public static description = stripIndent`
-		DEPRECATED alias for the 'fleet purge' command
-
-		${appToFleetCmdMsg
-			.split('\n')
-			.map((l) => `\t\t${l}`)
-			.join('\n')}
-
-		For command usage, see 'balena help fleet purge'
-	`;
-	public static examples = [];
-	public static usage = 'app purge <fleet>';
-	public static args = FleetPurgeCmd.args;
-	public static flags = FleetPurgeCmd.flags;
-	public static authenticated = FleetPurgeCmd.authenticated;
-	public static primary = FleetPurgeCmd.primary;
-
-	public async run() {
-		// call this.parse() before deprecation message to parse '-h'
-		const parserOutput = this.parse<FlagsDef, ArgsDef>(AppPurgeCmd);
-		if (process.stderr.isTTY) {
-			console.error(warnify(appToFleetCmdMsg));
-		}
-		await super.run(parserOutput);
-	}
-}

lib/commands/app/rename.ts

@@ -1,170 +0,0 @@
-/**
- * @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 type { flags } from '@oclif/command';
-import type { Output as ParserOutput } from '@oclif/parser';
-import type { ApplicationType } from 'balena-sdk';
-
-import Command from '../../command';
-import * as cf from '../../utils/common-flags';
-import * as ca from '../../utils/common-args';
-import { getBalenaSdk, stripIndent, getCliForm } from '../../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetCmdMsg,
-	warnify,
-} from '../../utils/messages';
-
-interface FlagsDef {
-	help: void;
-}
-
-interface ArgsDef {
-	fleet: string;
-	newName?: string;
-}
-
-export class FleetRenameCmd extends Command {
-	public static description = stripIndent`
-		Rename a fleet.
-
-		Rename a fleet.
-
-		Note, if the \`newName\` parameter is omitted, it will be
-		prompted for interactively.
-
-		${applicationIdInfo.split('\n').join('\n\t\t')}
-	`;
-
-	public static examples = [
-		'$ balena fleet rename OldName',
-		'$ balena fleet rename OldName NewName',
-		'$ balena fleet rename myorg/oldname NewName',
-	];
-
-	public static args = [
-		ca.fleetRequired,
-		{
-			name: 'newName',
-			description: 'the new name for the fleet',
-		},
-	];
-
-	public static usage = 'fleet rename <fleet> [newName]';
-
-	public static flags: flags.Input<FlagsDef> = {
-		help: cf.help,
-	};
-
-	public static authenticated = true;
-
-	public async run(parserOutput?: ParserOutput<FlagsDef, ArgsDef>) {
-		const { args: params } =
-			parserOutput || this.parse<FlagsDef, ArgsDef>(FleetRenameCmd);
-
-		const { validateApplicationName } = await import('../../utils/validation');
-		const { ExpectedError } = await import('../../errors');
-
-		const balena = getBalenaSdk();
-
-		// Disambiguate target application (if params.params is a number, it could either be an ID or a numerical name)
-		const { getApplication } = await import('../../utils/sdk');
-		const application = await getApplication(balena, params.fleet, {
-			$expand: {
-				application_type: {
-					$select: ['is_legacy'],
-				},
-			},
-		});
-
-		// Check app exists
-		if (!application) {
-			throw new ExpectedError(`Error: fleet ${params.fleet} not found.`);
-		}
-
-		// Check app supports renaming
-		const appType = (application.application_type as ApplicationType[])?.[0];
-		if (appType.is_legacy) {
-			throw new ExpectedError(
-				`Fleet ${params.fleet} is of 'legacy' type, and cannot be renamed.`,
-			);
-		}
-
-		// Ascertain new name
-		const newName =
-			params.newName ||
-			(await getCliForm().ask({
-				message: 'Please enter the new name for this fleet:',
-				type: 'input',
-				validate: validateApplicationName,
-			})) ||
-			'';
-
-		// Rename
-		try {
-			await balena.models.application.rename(application.id, newName);
-		} catch (e) {
-			// BalenaRequestError: Request error: "organization" and "app_name" must be unique.
-			if ((e.message || '').toLowerCase().includes('unique')) {
-				throw new ExpectedError(`Error: fleet ${params.fleet} already exists.`);
-			}
-			throw e;
-		}
-
-		// Get application again, to be sure of results
-		const renamedApplication = await balena.models.application.get(
-			application.id,
-		);
-
-		// Output result
-		console.log(`Fleet renamed`);
-		console.log('From:');
-		console.log(`\tname: ${application.app_name}`);
-		console.log(`\tslug: ${application.slug}`);
-		console.log('To:');
-		console.log(`\tname: ${renamedApplication.app_name}`);
-		console.log(`\tslug: ${renamedApplication.slug}`);
-	}
-}
-
-export default class AppRenameCmd extends FleetRenameCmd {
-	public static description = stripIndent`
-		DEPRECATED alias for the 'fleet rename' command
-
-		${appToFleetCmdMsg
-			.split('\n')
-			.map((l) => `\t\t${l}`)
-			.join('\n')}
-
-		For command usage, see 'balena help fleet rename'
-	`;
-	public static examples = [];
-	public static usage = 'app rename <fleet> [newName]';
-	public static args = FleetRenameCmd.args;
-	public static flags = FleetRenameCmd.flags;
-	public static authenticated = FleetRenameCmd.authenticated;
-	public static primary = FleetRenameCmd.primary;
-
-	public async run() {
-		// call this.parse() before deprecation message to parse '-h'
-		const parserOutput = this.parse<FlagsDef, ArgsDef>(AppRenameCmd);
-		if (process.stderr.isTTY) {
-			console.error(warnify(appToFleetCmdMsg));
-		}
-		await super.run(parserOutput);
-	}
-}

lib/commands/app/restart.ts

@@ -1,104 +0,0 @@
-/**
- * @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 type { flags } from '@oclif/command';
-import type { Output as ParserOutput } from '@oclif/parser';
-
-import Command from '../../command';
-import * as cf from '../../utils/common-flags';
-import * as ca from '../../utils/common-args';
-import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetCmdMsg,
-	warnify,
-} from '../../utils/messages';
-
-interface FlagsDef {
-	help: void;
-}
-
-interface ArgsDef {
-	fleet: string;
-}
-
-export class FleetRestartCmd extends Command {
-	public static description = stripIndent`
-		Restart a fleet.
-
-		Restart all devices belonging to a fleet.
-
-		${applicationIdInfo.split('\n').join('\n\t\t')}
-	`;
-
-	public static examples = [
-		'$ balena fleet restart MyFleet',
-		'$ balena fleet restart myorg/myfleet',
-	];
-
-	public static args = [ca.fleetRequired];
-
-	public static usage = 'fleet restart <fleet>';
-
-	public static flags: flags.Input<FlagsDef> = {
-		help: cf.help,
-	};
-
-	public static authenticated = true;
-
-	public async run(parserOutput?: ParserOutput<FlagsDef, ArgsDef>) {
-		const { args: params } =
-			parserOutput || this.parse<FlagsDef, ArgsDef>(FleetRestartCmd);
-
-		const { getApplication } = await import('../../utils/sdk');
-
-		const balena = getBalenaSdk();
-
-		// Disambiguate application (if is a number, it could either be an ID or a numerical name)
-		const application = await getApplication(balena, params.fleet);
-
-		await balena.models.application.restart(application.id);
-	}
-}
-
-export default class AppRestartCmd extends FleetRestartCmd {
-	public static description = stripIndent`
-		DEPRECATED alias for the 'fleet restart' command
-
-		${appToFleetCmdMsg
-			.split('\n')
-			.map((l) => `\t\t${l}`)
-			.join('\n')}
-
-		For command usage, see 'balena help fleet restart'
-	`;
-	public static examples = [];
-	public static usage = 'app restart <fleet>';
-	public static args = FleetRestartCmd.args;
-	public static flags = FleetRestartCmd.flags;
-	public static authenticated = FleetRestartCmd.authenticated;
-	public static primary = FleetRestartCmd.primary;
-
-	public async run() {
-		// call this.parse() before deprecation message to parse '-h'
-		const parserOutput = this.parse<FlagsDef, ArgsDef>(AppRestartCmd);
-		if (process.stderr.isTTY) {
-			console.error(warnify(appToFleetCmdMsg));
-		}
-		await super.run(parserOutput);
-	}
-}

lib/commands/app/rm.ts

@@ -1,116 +0,0 @@
-/**
- * @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 type { flags } from '@oclif/command';
-import type { Output as ParserOutput } from '@oclif/parser';
-
-import Command from '../../command';
-import * as cf from '../../utils/common-flags';
-import * as ca from '../../utils/common-args';
-import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetCmdMsg,
-	warnify,
-} from '../../utils/messages';
-
-interface FlagsDef {
-	yes: boolean;
-	help: void;
-}
-
-interface ArgsDef {
-	fleet: string;
-}
-
-export class FleetRmCmd extends Command {
-	public static description = stripIndent`
-		Remove a fleet.
-
-		Permanently remove a fleet.
-
-		The --yes option may be used to avoid interactive confirmation.
-
-		${applicationIdInfo.split('\n').join('\n\t\t')}
-	`;
-
-	public static examples = [
-		'$ balena fleet rm MyFleet',
-		'$ balena fleet rm MyFleet --yes',
-		'$ balena fleet rm myorg/myfleet',
-	];
-
-	public static args = [ca.fleetRequired];
-
-	public static usage = 'fleet rm <fleet>';
-
-	public static flags: flags.Input<FlagsDef> = {
-		yes: cf.yes,
-		help: cf.help,
-	};
-
-	public static authenticated = true;
-
-	public async run(parserOutput?: ParserOutput<FlagsDef, ArgsDef>) {
-		const { args: params, flags: options } =
-			parserOutput || this.parse<FlagsDef, ArgsDef>(FleetRmCmd);
-
-		const { confirm } = await import('../../utils/patterns');
-		const { getApplication } = await import('../../utils/sdk');
-		const balena = getBalenaSdk();
-
-		// Confirm
-		await confirm(
-			options.yes ?? false,
-			`Are you sure you want to delete fleet ${params.fleet}?`,
-		);
-
-		// Disambiguate application (if is a number, it could either be an ID or a numerical name)
-		const application = await getApplication(balena, params.fleet);
-
-		// Remove
-		await balena.models.application.remove(application.id);
-	}
-}
-
-export default class AppRmCmd extends FleetRmCmd {
-	public static description = stripIndent`
-		DEPRECATED alias for the 'fleet rm' command
-
-		${appToFleetCmdMsg
-			.split('\n')
-			.map((l) => `\t\t${l}`)
-			.join('\n')}
-
-		For command usage, see 'balena help fleet rm'
-	`;
-	public static examples = [];
-	public static usage = 'app rm <fleet>';
-	public static args = FleetRmCmd.args;
-	public static flags = FleetRmCmd.flags;
-	public static authenticated = FleetRmCmd.authenticated;
-	public static primary = FleetRmCmd.primary;
-
-	public async run() {
-		// call this.parse() before deprecation message to parse '-h'
-		const parserOutput = this.parse<FlagsDef, ArgsDef>(AppRmCmd);
-		if (process.stderr.isTTY) {
-			console.error(warnify(appToFleetCmdMsg));
-		}
-		await super.run(parserOutput);
-	}
-}

lib/commands/apps.ts

@@ -1,134 +0,0 @@
-/**
- * @license
- * Copyright 2016-2021 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 { Output as ParserOutput } from '@oclif/parser';
-
-import Command from '../command';
-import * as cf from '../utils/common-flags';
-import { getBalenaSdk, getVisuals, stripIndent } from '../utils/lazy';
-import { appToFleetCmdMsg, warnify } from '../utils/messages';
-
-interface ExtendedApplication extends ApplicationWithDeviceType {
-	device_count?: number;
-	online_devices?: number;
-}
-
-interface FlagsDef {
-	help: void;
-	verbose?: boolean;
-}
-
-export class FleetsCmd extends Command {
-	public static description = stripIndent`
-		List all fleets.
-
-		List all your balena fleets.
-
-		For detailed information on a particular fleet, use
-		\`balena fleet <fleet>\`
-	`;
-
-	public static examples = ['$ balena fleets'];
-
-	public static usage = 'fleets';
-
-	public static flags: flags.Input<FlagsDef> = {
-		help: cf.help,
-		verbose: flags.boolean({
-			default: false,
-			char: 'v',
-			description: 'No-op since release v12.0.0',
-		}),
-	};
-
-	public static authenticated = true;
-	public static primary = true;
-
-	protected useAppWord = false;
-
-	public async run(_parserOutput?: ParserOutput<FlagsDef, {}>) {
-		_parserOutput ||= this.parse<FlagsDef, {}>(FleetsCmd);
-
-		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',
-				this.useAppWord ? 'app_name' : 'app_name => NAME',
-				'slug',
-				'device_type',
-				'online_devices',
-				'device_count',
-			]),
-		);
-	}
-}
-
-const appsToFleetsRenameMsg = appToFleetCmdMsg
-	.replace(/'app'/g, "'apps'")
-	.replace(/'fleet'/g, "'fleets'");
-
-export default class AppsCmd extends FleetsCmd {
-	public static description = stripIndent`
-		DEPRECATED alias for the 'fleets' command
-
-		${appsToFleetsRenameMsg
-			.split('\n')
-			.map((l) => `\t\t${l}`)
-			.join('\n')}
-
-		For command usage, see 'balena help fleets'
-	`;
-	public static examples = [];
-	public static usage = 'apps';
-	public static args = FleetsCmd.args;
-	public static flags = FleetsCmd.flags;
-	public static authenticated = FleetsCmd.authenticated;
-	public static primary = FleetsCmd.primary;
-
-	public async run() {
-		// call this.parse() before deprecation message to parse '-h'
-		const parserOutput = this.parse<FlagsDef, {}>(AppsCmd);
-		if (process.stderr.isTTY) {
-			console.error(warnify(appsToFleetsRenameMsg));
-		}
-		this.useAppWord = true;
-		await super.run(parserOutput);
-	}
-}

lib/commands/block/create.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2016-2021 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 {
+	organization?: string;
+	type?: string; // application device type
+	help: void;
+}
+
+interface ArgsDef {
+	name: string;
+}
+
+export default class BlockCreateCmd extends Command {
+	public static description = stripIndent`
+		Create an block.
+
+		Create a new balena block.
+
+		You can specify the organization the block should belong to using
+		the \`--organization\` option. The organization's handle, not its name,
+		should be provided. Organization handles can be listed with the
+		\`balena orgs\` command.
+
+		The block's default device type is specified with the \`--type\` option.
+		The \`balena devices supported\` command can be used to list the available
+		device types.
+
+		Interactive dropdowns will be shown for selection if no device type or
+		organization is specified and there are multiple options to choose from.
+		If there is a single option to choose from, it will be chosen automatically.
+		This interactive behavior can be disabled by explicitly specifying a device
+		type and organization.
+	`;
+
+	public static examples = [
+		'$ balena block create MyBlock',
+		'$ balena block create MyBlock --organization mmyorg',
+		'$ balena block create MyBlock -o myorg --type raspberry-pi',
+	];
+
+	public static args = [
+		{
+			name: 'name',
+			description: 'block name',
+			required: true,
+		},
+	];
+
+	public static usage = 'block create <name>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		organization: flags.string({
+			char: 'o',
+			description: 'handle of the organization the block should belong to',
+		}),
+		type: flags.string({
+			char: 't',
+			description:
+				'block 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>(
+			BlockCreateCmd,
+		);
+
+		// Ascertain device type
+		const deviceType =
+			options.type ||
+			(await (await import('../../utils/patterns')).selectDeviceType());
+
+		// Ascertain organization
+		const organization =
+			options.organization?.toLowerCase() || (await this.getOrganization());
+
+		// Create application
+		try {
+			const application = await getBalenaSdk().models.application.create({
+				name: params.name,
+				deviceType,
+				organization,
+				applicationClass: 'block',
+			});
+
+			// Output
+			console.log(
+				`Block created: slug "${application.slug}", device type "${deviceType}"`,
+			);
+		} catch (err) {
+			if ((err.message || '').toLowerCase().includes('unique')) {
+				// BalenaRequestError: Request error: "organization" and "app_name" must be unique.
+				throw new ExpectedError(
+					`Error: An app or block or fleet with the name "${params.name}" already exists in organization "${organization}".`,
+				);
+			} else if ((err.message || '').toLowerCase().includes('unauthorized')) {
+				// BalenaRequestError: Request error: Unauthorized
+				throw new ExpectedError(
+					`Error: You are not authorized to create blocks in organization "${organization}".`,
+				);
+			}
+
+			throw err;
+		}
+	}
+
+	async getOrganization() {
+		const { getOwnOrganizations } = await import('../../utils/sdk');
+		const organizations = await getOwnOrganizations(getBalenaSdk(), {
+			$select: ['name', 'handle'],
+		});
+
+		if (organizations.length === 0) {
+			// User is not a member of any organizations (should not happen).
+			throw new Error('This account is not a member of any organizations');
+		} else if (organizations.length === 1) {
+			// User is a member of only one organization - use this.
+			return organizations[0].handle;
+		} else {
+			// User is a member of multiple organizations -
+			const { selectOrganization } = await import('../../utils/patterns');
+			return selectOrganization(organizations);
+		}
+	}
+}

lib/commands/build.ts

@@ -20,24 +20,20 @@ import Command from '../command';
 import { getBalenaSdk } from '../utils/lazy';
 import * as cf from '../utils/common-flags';
 import * as compose from '../utils/compose';
-import type { Application, ApplicationType, BalenaSDK } from 'balena-sdk';
+import type { ApplicationType, BalenaSDK } from 'balena-sdk';
 import {
-	appToFleetFlagMsg,
 	buildArgDeprecation,
 	dockerignoreHelp,
 	registrySecretsHelp,
-	warnify,
 } 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';
-import { isV13 } from '../utils/version';
 
 interface FlagsDef extends ComposeCliFlags, DockerCliFlags {
 	arch?: string;
 	deviceType?: string;
-	application?: string;
 	fleet?: string;
 	source?: string; // Not part of command profile - source param copied here.
 	help: void;
@@ -96,7 +92,6 @@ ${dockerignoreHelp}
 			description: 'the type of device this build is for',
 			char: 'd',
 		}),
-		...(isV13() ? {} : { application: cf.application }),
 		fleet: cf.fleet,
 		...composeCliFlags,
 		...dockerCliFlags,
@@ -112,12 +107,7 @@ ${dockerignoreHelp}
 			BuildCmd,
 		);
 
-		if (options.application && process.stderr.isTTY) {
-			console.error(warnify(appToFleetFlagMsg));
-		}
-		options.application ||= options.fleet;
-
-		await Command.checkLoggedInIf(!!options.application);
+		await Command.checkLoggedInIf(!!options.fleet);
 
 		(await import('events')).defaultMaxListeners = 1000;
 
@@ -161,10 +151,8 @@ ${dockerignoreHelp}
 	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))
+			(opts.fleet == null && (opts.arch == null || opts.deviceType == null)) ||
+			(opts.fleet != null && (opts.arch != null || opts.deviceType != null))
 		) {
 			const { ExpectedError } = await import('../errors');
 			throw new ExpectedError(
@@ -189,9 +177,9 @@ ${dockerignoreHelp}
 	}
 
 	protected async getAppAndResolveArch(opts: FlagsDef) {
-		if (opts.application) {
+		if (opts.fleet) {
 			const { getAppWithArch } = await import('../utils/helpers');
-			const app = await getAppWithArch(opts.application);
+			const app = await getAppWithArch(opts.fleet);
 			opts.arch = app.arch;
 			opts.deviceType = app.is_for__device_type[0].slug;
 			return app;
@@ -220,7 +208,7 @@ ${dockerignoreHelp}
 	 *   buildEmulated
 	 *   buildOpts: arguments to forward to docker build command
 	 *
-	 * @param {DockerToolbelt} docker
+	 * @param {Dockerode} docker
 	 * @param {Logger} logger
 	 * @param {ComposeOpts} composeOpts
 	 * @param opts
@@ -230,7 +218,9 @@ ${dockerignoreHelp}
 		logger: import('../utils/logger'),
 		composeOpts: ComposeOpts,
 		opts: {
-			app?: Application;
+			app?: {
+				application_type: [Pick<ApplicationType, 'supports_multicontainer'>];
+			};
 			arch: string;
 			deviceType: string;
 			buildEmulated: boolean;
@@ -239,9 +229,14 @@ ${dockerignoreHelp}
 	) {
 		const { loadProject } = await import('../utils/compose_ts');
 
-		const project = await loadProject(logger, composeOpts);
+		const project = await loadProject(
+			logger,
+			composeOpts,
+			undefined,
+			opts.buildOpts.t,
+		);
 
-		const appType = (opts.app?.application_type as ApplicationType[])?.[0];
+		const appType = opts.app?.application_type?.[0];
 		if (
 			appType != null &&
 			project.descriptors.length > 1 &&
@@ -266,7 +261,6 @@ ${dockerignoreHelp}
 			inlineLogs: composeOpts.inlineLogs,
 			convertEol: composeOpts.convertEol,
 			dockerfilePath: composeOpts.dockerfilePath,
-			nogitignore: composeOpts.nogitignore,
 			multiDockerignore: composeOpts.multiDockerignore,
 		});
 	}

lib/commands/config/generate.ts

@@ -21,17 +21,16 @@ import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, getCliForm, stripIndent } from '../../utils/lazy';
 import {
 	applicationIdInfo,
-	appToFleetFlagMsg,
-	warnify,
+	devModeInfo,
+	secureBootInfo,
 } from '../../utils/messages';
-import { isV13 } from '../../utils/version';
-import type { PineDeferred } from 'balena-sdk';
+import type { BalenaSDK, PineDeferred } from 'balena-sdk';
 
 interface FlagsDef {
 	version: string; // OS version
-	application?: string;
-	app?: string; // application alias
 	fleet?: string;
+	dev?: boolean; // balenaOS development variant
+	secureBoot?: boolean;
 	device?: string;
 	deviceApiKey?: string;
 	deviceType?: string;
@@ -42,6 +41,8 @@ interface FlagsDef {
 	wifiSsid?: string;
 	wifiKey?: string;
 	appUpdatePollInterval?: string;
+	'provisioning-key-name'?: string;
+	'provisioning-key-expiry-date'?: string;
 	help: void;
 }
 
@@ -53,6 +54,10 @@ export default class ConfigGenerateCmd extends Command {
 
 		The target balenaOS version must be specified with the --version option.
 
+		${devModeInfo.split('\n').join('\n\t\t')}
+
+		${secureBootInfo.split('\n').join('\n\t\t')}
+
 		To configure an image for a fleet of mixed device types, use the --fleet option
 		alongside the --deviceType option to specify the target device type.
 
@@ -65,13 +70,13 @@ export default class ConfigGenerateCmd extends Command {
 	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 --deviceApiKey <existingDeviceKey>',
 		'$ balena config generate --device 7cf02a6 --version 2.12.7 --output config.json',
-		'$ balena config generate --fleet MyFleet --version 2.12.7',
-		'$ balena config generate --fleet myorg/myfleet --version 2.12.7',
-		'$ balena config generate --fleet MyFleet --version 2.12.7 --deviceType fincm3',
-		'$ balena config generate --fleet MyFleet --version 2.12.7 --output config.json',
-		'$ balena config generate --fleet MyFleet --version 2.12.7 --network wifi --wifiSsid mySsid --wifiKey abcdefgh --appUpdatePollInterval 15',
+		'$ balena config generate --fleet myorg/fleet --version 2.12.7 --dev',
+		'$ balena config generate --fleet myorg/fleet --version 2.12.7 --secureBoot',
+		'$ balena config generate --fleet myorg/fleet --version 2.12.7 --deviceType fincm3',
+		'$ balena config generate --fleet myorg/fleet --version 2.12.7 --output config.json',
+		'$ balena config generate --fleet myorg/fleet --version 2.12.7 --network wifi --wifiSsid mySsid --wifiKey abcdefgh --appUpdatePollInterval 15',
 	];
 
 	public static usage = 'config generate';
@@ -81,20 +86,17 @@ export default class ConfigGenerateCmd extends Command {
 			description: 'a balenaOS version',
 			required: true,
 		}),
-		...(isV13()
-			? {}
-			: {
-					application: {
-						...cf.application,
-						exclusive: ['app', 'fleet', 'device'],
-					},
-					app: { ...cf.app, exclusive: ['application', 'fleet', 'device'] },
-					appUpdatePollInterval: flags.string({
-						description: 'DEPRECATED alias for --updatePollInterval',
-					}),
-			  }),
-		fleet: { ...cf.fleet, exclusive: ['application', 'app', 'device'] },
-		device: { ...cf.device, exclusive: ['application', 'app', 'fleet'] },
+		fleet: { ...cf.fleet, exclusive: ['device'] },
+		dev: cf.dev,
+		secureBoot: cf.secureBoot,
+		device: {
+			...cf.device,
+			exclusive: [
+				'fleet',
+				'provisioning-key-name',
+				'provisioning-key-expiry-date',
+			],
+		},
 		deviceApiKey: flags.string({
 			description:
 				'custom device key - note that this is only supported on balenaOS 2.0.3+',
@@ -126,33 +128,48 @@ export default class ConfigGenerateCmd extends Command {
 		}),
 		appUpdatePollInterval: flags.string({
 			description:
-				'supervisor cloud polling interval in minutes (e.g. for variable updates)',
+				'supervisor cloud polling interval in minutes (e.g. for device variables)',
+		}),
+		'provisioning-key-name': flags.string({
+			description: 'custom key name assigned to generated provisioning api key',
+			exclusive: ['device'],
+		}),
+		'provisioning-key-expiry-date': flags.string({
+			description:
+				'expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)',
+			exclusive: ['device'],
 		}),
 		help: cf.help,
 	};
 
 	public static authenticated = true;
 
+	public async getApplication(balena: BalenaSDK, fleet: string) {
+		const { getApplication } = await import('../../utils/sdk');
+		return await getApplication(balena, fleet, {
+			$select: 'slug',
+			$expand: {
+				is_for__device_type: { $select: 'slug' },
+			},
+		});
+	}
+
 	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 application: Awaited<ReturnType<typeof this.getApplication>> | 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' } } },
-			);
+			const rawDevice = await balena.models.device.get(options.device, {
+				$expand: { is_of__device_type: { $select: 'slug' } },
+			});
 			if (!rawDevice.belongs_to__application) {
 				const { ExpectedError } = await import('../../errors');
 				throw new ExpectedError(stripIndent`
@@ -165,43 +182,51 @@ export default class ConfigGenerateCmd extends Command {
 			resourceDeviceType = device.is_of__device_type[0].slug;
 		} else {
 			// Disambiguate application (if is a number, it could either be an ID or a numerical name)
-			application = (await getApplication(balena, options.application!, {
-				$expand: {
-					is_for__device_type: { $select: 'slug' },
-				},
-			})) as ApplicationWithDeviceType;
+			application = await this.getApplication(balena, options.fleet!);
 			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,
-			);
-
+		if (options.fleet && options.deviceType) {
 			const helpers = await import('../../utils/helpers');
 			if (
-				!helpers.areDeviceTypesCompatible(appDeviceManifest, deviceManifest)
+				!(await helpers.areDeviceTypesCompatible(
+					resourceDeviceType,
+					deviceType,
+				))
 			) {
-				throw new balena.errors.BalenaInvalidDeviceType(
-					`Device type ${options.deviceType} is incompatible with fleet ${options.application}`,
+				const { ExpectedError } = await import('../../errors');
+				throw new ExpectedError(
+					`Device type ${options.deviceType} is incompatible with fleet ${options.fleet}`,
 				);
 			}
 		}
 
+		const deviceManifest =
+			await balena.models.config.getDeviceTypeManifestBySlug(deviceType);
+
+		const { validateSecureBootOptionAndWarn } = await import(
+			'../../utils/config'
+		);
+		await validateSecureBootOptionAndWarn(
+			options.secureBoot,
+			deviceType,
+			options.version,
+		);
+
 		// 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,
+			override: { ...options, app: options.fleet, application: options.fleet },
 		});
 		answers.version = options.version;
+		answers.developmentMode = options.dev;
+		answers.secureBoot = options.secureBoot;
+		answers.provisioningKeyName = options['provisioning-key-name'];
+		answers.provisioningKeyExpiryDate = options['provisioning-key-expiry-date'];
 
 		// Generate config
 		const { generateDeviceConfig, generateApplicationConfig } = await import(
@@ -244,19 +269,14 @@ export default class ConfigGenerateCmd extends Command {
 	protected async validateOptions(options: FlagsDef) {
 		const { ExpectedError } = await import('../../errors');
 
-		if ((options.application || options.app) && process.stderr.isTTY) {
-			console.error(warnify(appToFleetFlagMsg));
-		}
-		options.application ||= options.app || options.fleet;
-		// Prefer options.application over options.app
-		delete options.app;
-
-		if (options.device == null && options.application == null) {
+		if (options.device == null && options.fleet == null) {
 			throw new ExpectedError(this.missingDeviceOrAppMessage);
 		}
 
-		if (!options.application && options.deviceType) {
+		if (!options.fleet && options.deviceType) {
 			throw new ExpectedError(this.deviceTypeNotAllowedMessage);
 		}
+		const { validateDevOptionAndWarn } = await import('../../utils/config');
+		await validateDevOptionAndWarn(options.dev, options.version);
 	}
 }

lib/commands/config/inject.ts

@@ -21,7 +21,7 @@ import * as cf from '../../utils/common-flags';
 import { getVisuals, stripIndent } from '../../utils/lazy';
 
 interface FlagsDef {
-	type: string;
+	type?: string;
 	drive?: string;
 	help: void;
 }
@@ -32,15 +32,18 @@ interface ArgsDef {
 
 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 a balenaOS image or attached media.
 
-		Inject a config.json file to the mounted filesystem,
-		e.g. the SD card of a provisioned device or balenaOS image.
+		Inject a 'config.json' file to a balenaOS image file or attached SD card or
+		USB stick.
+
+		Documentation for the balenaOS 'config.json' file can be found at:
+		https://www.balena.io/docs/reference/OS/configuration/
 	`;
 
 	public static examples = [
-		'$ balena config inject my/config.json --type raspberrypi3',
-		'$ balena config inject my/config.json --type raspberrypi3 --drive /dev/disk2',
+		'$ balena config inject my/config.json',
+		'$ balena config inject my/config.json --drive /dev/disk2',
 	];
 
 	public static args = [
@@ -54,14 +57,12 @@ export default class ConfigInjectCmd extends Command {
 	public static usage = 'config inject <file>';
 
 	public static flags: flags.Input<FlagsDef> = {
-		type: cf.deviceType,
 		drive: cf.driveOrImg,
 		help: cf.help,
 	};
 
-	public static authenticated = true;
-
 	public static root = true;
+	public static offlineCompatible = true;
 
 	public async run() {
 		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
@@ -80,7 +81,7 @@ export default class ConfigInjectCmd extends Command {
 		);
 
 		const config = await import('balena-config-json');
-		await config.write(drive, options.type, configJSON);
+		await config.write(drive, '', configJSON);
 
 		console.info('Done');
 	}

lib/commands/config/read.ts

@@ -21,35 +21,39 @@ import * as cf from '../../utils/common-flags';
 import { getVisuals, stripIndent } from '../../utils/lazy';
 
 interface FlagsDef {
-	type: string;
+	type?: string;
 	drive?: string;
 	help: void;
+	json: boolean;
 }
 
 export default class ConfigReadCmd extends Command {
 	public static description = stripIndent`
-		Read the configuration of a device or OS image.
+		Read the config.json file of a balenaOS image or attached media.
 
-		Read the config.json file from the mounted filesystem,
-		e.g. the SD card of a provisioned device or balenaOS image.
+		Read the 'config.json' file of a balenaOS image file or attached SD card or
+		USB stick.
+
+		Documentation for the balenaOS 'config.json' file can be found at:
+		https://www.balena.io/docs/reference/OS/configuration/
 	`;
 
 	public static examples = [
-		'$ balena config read --type raspberrypi3',
-		'$ balena config read --type raspberrypi3 --drive /dev/disk2',
+		'$ balena config read',
+		'$ balena config read --drive /dev/disk2',
+		'$ balena config read --drive balena.img',
 	];
 
 	public static usage = 'config read';
 
 	public static flags: flags.Input<FlagsDef> = {
-		type: cf.deviceType,
 		drive: cf.driveOrImg,
 		help: cf.help,
+		json: cf.json,
 	};
 
-	public static authenticated = true;
-
 	public static root = true;
+	public static offlineCompatible = true;
 
 	public async run() {
 		const { flags: options } = this.parse<FlagsDef, {}>(ConfigReadCmd);
@@ -61,9 +65,13 @@ export default class ConfigReadCmd extends Command {
 		await safeUmount(drive);
 
 		const config = await import('balena-config-json');
-		const configJSON = await config.read(drive, options.type);
+		const configJSON = await config.read(drive, '');
 
-		const prettyjson = await import('prettyjson');
-		console.info(prettyjson.render(configJSON));
+		if (options.json) {
+			console.log(JSON.stringify(configJSON, null, 4));
+		} else {
+			const prettyjson = await import('prettyjson');
+			console.log(prettyjson.render(configJSON));
+		}
 	}
 }

lib/commands/config/reconfigure.ts

@@ -21,38 +21,47 @@ import * as cf from '../../utils/common-flags';
 import { getVisuals, stripIndent } from '../../utils/lazy';
 
 interface FlagsDef {
-	type: string;
+	type?: string;
 	drive?: string;
 	advanced: boolean;
 	help: void;
+	version?: string;
 }
 
 export default class ConfigReconfigureCmd extends Command {
 	public static description = stripIndent`
-		Interactively reconfigure a device or OS image.
+		Interactively reconfigure a balenaOS image file or attached media.
 
-		Interactively reconfigure a provisioned device or OS image.
+		Interactively reconfigure a balenaOS image file or attached media.
+
+		This command extracts the device UUID from the 'config.json' file of the
+		chosen balenaOS image file or attached media, and then passes the UUID as
+		the '--device' argument to the 'balena os configure' command.
+
+		For finer-grained or scripted control of the operation, use the
+		'balena config read' and 'balena os configure' commands separately.
 `;
 	public static examples = [
-		'$ balena config reconfigure --type raspberrypi3',
-		'$ balena config reconfigure --type raspberrypi3 --advanced',
-		'$ balena config reconfigure --type raspberrypi3 --drive /dev/disk2',
+		'$ balena config reconfigure',
+		'$ balena config reconfigure --drive /dev/disk3',
+		'$ balena config reconfigure --drive balena.img --advanced',
 	];
 
 	public static usage = 'config reconfigure';
 
 	public static flags: flags.Input<FlagsDef> = {
-		type: cf.deviceType,
 		drive: cf.driveOrImg,
 		advanced: flags.boolean({
 			description: 'show advanced commands',
 			char: 'v',
 		}),
 		help: cf.help,
+		version: flags.string({
+			description: 'balenaOS version, for example "2.32.0" or "2.44.0+rev1"',
+		}),
 	};
 
 	public static authenticated = true;
-
 	public static root = true;
 
 	public async run() {
@@ -65,10 +74,20 @@ export default class ConfigReconfigureCmd extends Command {
 		await safeUmount(drive);
 
 		const config = await import('balena-config-json');
-		const { uuid } = await config.read(drive, options.type);
+		const { uuid } = await config.read(drive, '');
 		await safeUmount(drive);
 
+		if (!uuid) {
+			const { ExpectedError } = await import('../../errors');
+			throw new ExpectedError(
+				`Error: UUID not found in 'config.json' file for '${drive}'`,
+			);
+		}
+
 		const configureCommand = ['os', 'configure', drive, '--device', uuid];
+		if (options.version) {
+			configureCommand.push('--version', options.version);
+		}
 		if (options.advanced) {
 			configureCommand.push('--advanced');
 		}

lib/commands/config/write.ts

@@ -21,7 +21,7 @@ import * as cf from '../../utils/common-flags';
 import { getVisuals, stripIndent } from '../../utils/lazy';
 
 interface FlagsDef {
-	type: string;
+	type?: string;
 	drive?: string;
 	help: void;
 }
@@ -33,16 +33,19 @@ interface ArgsDef {
 
 export default class ConfigWriteCmd extends Command {
 	public static description = stripIndent`
-		Write a key-value pair to configuration of a device or OS image.
+		Write a key-value pair to the config.json file of an OS image or attached media.
 
-		Write a key-value pair to the config.json file on the mounted filesystem,
-		e.g. the SD card of a provisioned device or balenaOS image.
+		Write a key-value pair to the 'config.json' file of a balenaOS image file or
+		attached SD card or USB stick.
+
+		Documentation for the balenaOS 'config.json' file can be found at:
+		https://www.balena.io/docs/reference/OS/configuration/
 	`;
 
 	public static examples = [
-		'$ balena config write --type raspberrypi3 username johndoe',
-		'$ balena config write --type raspberrypi3 --drive /dev/disk2 username johndoe',
-		'$ balena config write --type raspberrypi3 files.network/settings "..."',
+		'$ balena config write ntpServers "0.resinio.pool.ntp.org 1.resinio.pool.ntp.org"',
+		'$ balena config write --drive /dev/disk2 hostname custom-hostname',
+		'$ balena config write --drive balena.img os.network.connectivity.interval 300',
 	];
 
 	public static args = [
@@ -61,14 +64,12 @@ export default class ConfigWriteCmd extends Command {
 	public static usage = 'config write <key> <value>';
 
 	public static flags: flags.Input<FlagsDef> = {
-		type: cf.deviceType,
 		drive: cf.driveOrImg,
 		help: cf.help,
 	};
 
-	public static authenticated = true;
-
 	public static root = true;
+	public static offlineCompatible = true;
 
 	public async run() {
 		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
@@ -82,14 +83,14 @@ export default class ConfigWriteCmd extends Command {
 		await safeUmount(drive);
 
 		const config = await import('balena-config-json');
-		const configJSON = await config.read(drive, options.type);
+		const configJSON = await config.read(drive, '');
 
 		console.info(`Setting ${params.key} to ${params.value}`);
 		ConfigWriteCmd.updateConfigJson(configJSON, params.key, params.value);
 
 		await denyMount(drive, async () => {
 			await safeUmount(drive);
-			await config.write(drive, options.type, configJSON);
+			await config.write(drive, '', configJSON);
 		});
 
 		console.info('Done');

lib/commands/deploy.ts

@@ -16,7 +16,7 @@
  */
 
 import { flags } from '@oclif/command';
-import type { ImageDescriptor } from 'resin-compose-parse';
+import type { ImageDescriptor } from '@balena/compose/dist/parse';
 
 import Command from '../command';
 import { ExpectedError } from '../errors';
@@ -34,7 +34,7 @@ import type {
 	ComposeOpts,
 	Release as ComposeReleaseInfo,
 } from '../utils/compose-types';
-import type { DockerCliFlags } from '../utils/docker';
+import type { BuildOpts, DockerCliFlags } from '../utils/docker';
 import {
 	applyReleaseTagKeysAndValues,
 	buildProject,
@@ -43,15 +43,13 @@ import {
 	parseReleaseTagKeysAndValues,
 } from '../utils/compose_ts';
 import { dockerCliFlags } from '../utils/docker';
-import type {
-	Application,
-	ApplicationType,
-	DeviceType,
-	Release,
-} from 'balena-sdk';
+import type { ApplicationType, DeviceType, Release } from 'balena-sdk';
 
-interface ApplicationWithArch extends Application {
+interface ApplicationWithArch {
+	id: number;
 	arch: string;
+	is_for__device_type: [Pick<DeviceType, 'slug'>];
+	application_type: [Pick<ApplicationType, 'slug' | 'supports_multicontainer'>];
 }
 
 interface FlagsDef extends ComposeCliFlags, DockerCliFlags {
@@ -59,6 +57,8 @@ interface FlagsDef extends ComposeCliFlags, DockerCliFlags {
 	build: boolean;
 	nologupload: boolean;
 	'release-tag'?: string[];
+	draft: boolean;
+	note?: string;
 	help: void;
 }
 
@@ -100,6 +100,7 @@ ${dockerignoreHelp}
 	public static examples = [
 		'$ balena deploy myFleet',
 		'$ balena deploy myorg/myfleet --build --source myBuildDir/',
+		'$ balena deploy myorg/myfleet --build --source myBuildDir/ --note "this is the note for this release"',
 		'$ balena deploy myorg/myfleet myRepo/myImage',
 		'$ balena deploy myFleet myRepo/myImage --release-tag key1 "" key2 "value2 with spaces"',
 	];
@@ -136,6 +137,15 @@ ${dockerignoreHelp}
 			`,
 			multiple: true,
 		}),
+		draft: flags.boolean({
+			description: stripIndent`
+				Deploy the release as a draft. Draft releases are ignored
+				by the 'track latest' release policy but can be used through release pinning.
+				Draft releases can be marked as final through the API. Releases are created
+				as final by default unless this option is given.`,
+			default: false,
+		}),
+		note: flags.string({ description: 'The notes for this release' }),
 		...composeCliFlags,
 		...dockerCliFlags,
 		// NOTE: Not supporting -h for help, because of clash with -h in DockerCliFlags
@@ -213,6 +223,7 @@ ${dockerignoreHelp}
 			shouldPerformBuild: !!options.build,
 			shouldUploadLogs: !options.nologupload,
 			buildEmulated: !!options.emulated,
+			createAsDraft: options.draft,
 			buildOpts,
 		});
 		await applyReleaseTagKeysAndValues(
@@ -221,6 +232,9 @@ ${dockerignoreHelp}
 			releaseTagKeys,
 			releaseTagValues,
 		);
+		if (options.note) {
+			await sdk.models.release.setNote(release.id, options.note);
+		}
 	}
 
 	async deployProject(
@@ -235,7 +249,8 @@ ${dockerignoreHelp}
 			shouldPerformBuild: boolean;
 			shouldUploadLogs: boolean;
 			buildEmulated: boolean;
-			buildOpts: any; // arguments to forward to docker build command
+			buildOpts: BuildOpts;
+			createAsDraft: boolean;
 		},
 	) {
 		const _ = await import('lodash');
@@ -245,10 +260,15 @@ ${dockerignoreHelp}
 			'../utils/compose_ts'
 		);
 
-		const appType = (opts.app?.application_type as ApplicationType[])?.[0];
+		const appType = opts.app.application_type[0];
 
 		try {
-			const project = await loadProject(logger, composeOpts, opts.image);
+			const project = await loadProject(
+				logger,
+				composeOpts,
+				opts.image,
+				opts.buildOpts.t,
+			);
 			if (project.descriptors.length > 1 && !appType?.supports_multicontainer) {
 				throw new ExpectedError(
 					'Target fleet does not support multiple containers. Aborting!',
@@ -297,13 +317,12 @@ ${dockerignoreHelp}
 					projectName: project.name,
 					composition: compositionToBuild,
 					arch: opts.app.arch,
-					deviceType: (opts.app?.is_for__device_type as DeviceType[])?.[0].slug,
+					deviceType: opts.app.is_for__device_type[0].slug,
 					emulated: opts.buildEmulated,
 					buildOpts: opts.buildOpts,
 					inlineLogs: composeOpts.inlineLogs,
 					convertEol: composeOpts.convertEol,
 					dockerfilePath: composeOpts.dockerfilePath,
-					nogitignore: composeOpts.nogitignore,
 					multiDockerignore: composeOpts.multiDockerignore,
 				});
 				builtImagesByService = _.keyBy(builtImages, 'serviceName');
@@ -319,7 +338,7 @@ ${dockerignoreHelp}
 			);
 
 			let release: Release | ComposeReleaseInfo['release'];
-			if (appType?.is_legacy) {
+			if (appType.slug === 'legacy-v1' || appType.slug === 'legacy-v2') {
 				const { deployLegacy } = require('../utils/deploy-legacy');
 
 				const msg = getChalk().yellow(
@@ -367,6 +386,8 @@ ${dockerignoreHelp}
 					`Bearer ${auth}`,
 					apiEndpoint,
 					!opts.shouldUploadLogs,
+					composeOpts.projectPath,
+					opts.createAsDraft,
 				);
 			}
 

lib/commands/device/identify.ts

@@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
 import Command from '../../command';
 import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import { tryAsInteger } from '../../utils/validation';
 import { ExpectedError } from '../../errors';
 
 interface FlagsDef {
@@ -43,7 +42,6 @@ export default class DeviceIdentifyCmd extends Command {
 		{
 			name: 'uuid',
 			description: 'the uuid of the device to identify',
-			parse: (dev) => tryAsInteger(dev),
 			required: true,
 		},
 	];

lib/commands/device/index.ts

@@ -21,15 +21,12 @@ import Command from '../../command';
 import * as cf from '../../utils/common-flags';
 import { expandForAppName } from '../../utils/helpers';
 import { getBalenaSdk, getVisuals, stripIndent } from '../../utils/lazy';
-import { appToFleetOutputMsg, warnify } from '../../utils/messages';
-import { tryAsInteger } from '../../utils/validation';
-import { isV13 } from '../../utils/version';
 
 import type { Application, Release } from 'balena-sdk';
 
 interface ExtendedDevice extends DeviceWithDeviceType {
 	dashboard_url?: string;
-	application_name?: string;
+	fleet: string; // 'org/name' slug
 	device_type?: string;
 	commit?: string;
 	last_seen?: string;
@@ -46,7 +43,7 @@ interface ExtendedDevice extends DeviceWithDeviceType {
 
 interface FlagsDef {
 	help: void;
-	v13: boolean;
+	view: boolean;
 }
 
 interface ArgsDef {
@@ -59,13 +56,15 @@ export default class DeviceCmd extends Command {
 
 		Show information about a single device.
 		`;
-	public static examples = ['$ balena device 7cf02a6'];
+	public static examples = [
+		'$ balena device 7cf02a6',
+		'$ balena device 7cf02a6 --view',
+	];
 
 	public static args: Array<IArg<any>> = [
 		{
 			name: 'uuid',
 			description: 'the device uuid',
-			parse: (dev) => tryAsInteger(dev),
 			required: true,
 		},
 	];
@@ -74,7 +73,10 @@ export default class DeviceCmd extends Command {
 
 	public static flags: flags.Input<FlagsDef> = {
 		help: cf.help,
-		v13: cf.v13,
+		view: flags.boolean({
+			default: false,
+			description: 'open device dashboard page',
+		}),
 	};
 
 	public static authenticated = true;
@@ -84,7 +86,6 @@ export default class DeviceCmd extends Command {
 		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
 			DeviceCmd,
 		);
-		const useAppWord = !options.v13 && !isV13();
 
 		const balena = getBalenaSdk();
 
@@ -115,14 +116,22 @@ export default class DeviceCmd extends Command {
 			],
 			...expandForAppName,
 		})) as ExtendedDevice;
+
+		if (options.view) {
+			const open = await import('open');
+			const dashboardUrl = balena.models.device.getDashboardUrl(device.uuid);
+			await open(dashboardUrl, { wait: false });
+			return;
+		}
+
 		device.status = device.overall_status;
 
 		device.dashboard_url = balena.models.device.getDashboardUrl(device.uuid);
 
 		const belongsToApplication =
 			device.belongs_to__application as Application[];
-		device.application_name = belongsToApplication?.[0]
-			? belongsToApplication[0].app_name
+		device.fleet = belongsToApplication?.[0]
+			? belongsToApplication[0].slug
 			: 'N/a';
 
 		device.device_type = device.is_of__device_type[0].slug;
@@ -170,10 +179,6 @@ export default class DeviceCmd extends Command {
 			);
 		}
 
-		if (useAppWord && process.stderr.isTTY) {
-			console.error(warnify(appToFleetOutputMsg));
-		}
-
 		console.log(
 			getVisuals().table.vertical(device, [
 				`$${device.device_name}$`,
@@ -184,7 +189,7 @@ export default class DeviceCmd extends Command {
 				'ip_address',
 				'public_address',
 				'mac_address',
-				useAppWord ? 'application_name' : 'application_name => FLEET',
+				'fleet',
 				'last_seen',
 				'uuid',
 				'commit',

lib/commands/device/init.ts

@@ -19,17 +19,10 @@ import { flags } from '@oclif/command';
 import Command from '../../command';
 import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetFlagMsg,
-	warnify,
-} from '../../utils/messages';
+import { applicationIdInfo } from '../../utils/messages';
 import { runCommand } from '../../utils/helpers';
-import { isV13 } from '../../utils/version';
 
 interface FlagsDef {
-	application?: string;
-	app?: string;
 	fleet?: string;
 	yes: boolean;
 	advanced: boolean;
@@ -37,35 +30,53 @@ interface FlagsDef {
 	drive?: string;
 	config?: string;
 	help: void;
+	'provisioning-key-name'?: string;
+	'provisioning-key-expiry-date'?: string;
 }
 
 export default class DeviceInitCmd extends Command {
 	public static description = stripIndent`
 		Initialize a device with balenaOS.
 
-		Initialize a device by downloading the OS image of the specified fleet
-		and writing it to an SD Card.
+		Register a new device in the selected fleet, download the OS image for the
+		fleet's default device type, configure the image and write it to an SD card.
+		This command effectively combines several other balena CLI commands in one,
+		namely:
 
-		If the --fleet option is omitted, it will be prompted for interactively.
+		'balena device register'  
+		'balena os download'  
+		'balena os build-config' or 'balena config generate'  
+		'balena os configure'  
+		'balena os local flash'
+
+		Possible arguments for the '--fleet', '--os-version' and '--drive' options can
+		be listed respectively with the commands:
+
+		'balena fleets'  
+		'balena os versions'  
+		'balena util available-drives'
+
+		If the '--fleet' or '--drive' options are omitted, interactive menus will be
+		presented with values to choose from. If the '--os-version' option is omitted,
+		the latest released OS version for the fleet's default device type will be used.
 
 		${applicationIdInfo.split('\n').join('\n\t\t')}
+
+		Image configuration questions will be asked interactively unless a pre-configured
+		'config.json' file is provided with the '--config' option.  The file can be
+		generated with the 'balena config generate' or 'balena os build-config' commands.
 	`;
 
 	public static examples = [
 		'$ balena device init',
-		'$ balena device init --fleet MyFleet',
 		'$ balena device init -f myorg/myfleet',
+		'$ balena device init --fleet myFleet --os-version 2.101.7 --drive /dev/disk5 --config config.json --yes',
+		'$ balena device init --fleet myFleet --os-version 2.83.21+rev1.prod --drive /dev/disk5 --config config.json --yes',
 	];
 
 	public static usage = 'device init';
 
 	public static flags: flags.Input<FlagsDef> = {
-		...(isV13()
-			? {}
-			: {
-					application: cf.application,
-					app: cf.app,
-			  }),
 		fleet: cf.fleet,
 		yes: cf.yes,
 		advanced: flags.boolean({
@@ -85,6 +96,13 @@ export default class DeviceInitCmd extends Command {
 		config: flags.string({
 			description: 'path to the config JSON file, see `balena os build-config`',
 		}),
+		'provisioning-key-name': flags.string({
+			description: 'custom key name assigned to generated provisioning api key',
+		}),
+		'provisioning-key-expiry-date': flags.string({
+			description:
+				'expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)',
+		}),
 		help: cf.help,
 	};
 
@@ -105,32 +123,21 @@ export default class DeviceInitCmd extends Command {
 		const logger = await Command.getLogger();
 		const balena = getBalenaSdk();
 
-		if ((options.application || options.app) && process.stderr.isTTY) {
-			console.error(warnify(appToFleetFlagMsg));
-		}
-		// Consolidate application options
-		options.application ||= options.app || options.fleet;
-		delete options.app;
-
 		// Get application and
-		const application = (await getApplication(
-			balena,
-			options['application'] ||
-				(
-					await (await import('../../utils/patterns')).selectApplication()
-				).id,
-			{
-				$expand: {
-					is_for__device_type: {
-						$select: 'slug',
+		const application = options.fleet
+			? await getApplication(balena, options.fleet, {
+					$select: ['id', 'slug'],
+					$expand: {
+						is_for__device_type: {
+							$select: 'slug',
+						},
 					},
-				},
-			},
-		)) as ApplicationWithDeviceType;
+			  })
+			: await (await import('../../utils/patterns')).selectApplication();
 
 		// Register new device
 		const deviceUuid = balena.models.device.generateUniqueKey();
-		console.info(`Registering to ${application.app_name}: ${deviceUuid}`);
+		console.info(`Registering to ${application.slug}: ${deviceUuid}`);
 		await balena.models.device.register(application.id, deviceUuid);
 		const device = await balena.models.device.get(deviceUuid);
 
@@ -173,6 +180,21 @@ export default class DeviceInitCmd extends Command {
 		} else if (options.advanced) {
 			configureCommand.push('--advanced');
 		}
+
+		if (options['provisioning-key-name']) {
+			configureCommand.push(
+				'--provisioning-key-name',
+				options['provisioning-key-name'],
+			);
+		}
+
+		if (options['provisioning-key-expiry-date']) {
+			configureCommand.push(
+				'--provisioning-key-expiry-date',
+				options['provisioning-key-expiry-date'],
+			);
+		}
+
 		await runCommand(configureCommand);
 	}
 

lib/commands/device/local-mode.ts

@@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
 import Command from '../../command';
 import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import { tryAsInteger } from '../../utils/validation';
 
 interface FlagsDef {
 	enable: boolean;
@@ -52,7 +51,6 @@ export default class DeviceLocalModeCmd extends Command {
 		{
 			name: 'uuid',
 			description: 'the uuid of the device to manage',
-			parse: (dev) => tryAsInteger(dev),
 			required: true,
 		},
 	];

lib/commands/device/move.ts

@@ -17,25 +17,20 @@
 
 import type { flags } from '@oclif/command';
 import type { IArg } from '@oclif/parser/lib/args';
-import type { Application, BalenaSDK } from 'balena-sdk';
+import type {
+	BalenaSDK,
+	Device,
+	DeviceType,
+	PineOptions,
+	PineTypedResult,
+} from 'balena-sdk';
 import Command from '../../command';
 import * as cf from '../../utils/common-flags';
 import { ExpectedError } from '../../errors';
 import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetFlagMsg,
-	warnify,
-} from '../../utils/messages';
-import { isV13 } from '../../utils/version';
-
-interface ExtendedDevice extends DeviceWithDeviceType {
-	application_name?: string;
-}
+import { applicationIdInfo } from '../../utils/messages';
 
 interface FlagsDef {
-	application?: string;
-	app?: string;
 	fleet?: string;
 	help: void;
 }
@@ -74,63 +69,61 @@ export default class DeviceMoveCmd extends Command {
 	public static usage = 'device move <uuid(s)>';
 
 	public static flags: flags.Input<FlagsDef> = {
-		...(isV13() ? {} : { app: cf.app, application: cf.application }),
 		fleet: cf.fleet,
 		help: cf.help,
 	};
 
 	public static authenticated = true;
 
+	private async getDevices(balena: BalenaSDK, deviceUuids: string[]) {
+		const deviceOptions = {
+			$select: 'belongs_to__application',
+			$expand: {
+				is_of__device_type: {
+					$select: 'is_of__cpu_architecture',
+					$expand: {
+						is_of__cpu_architecture: {
+							$select: 'slug',
+						},
+					},
+				},
+			},
+		} satisfies PineOptions<Device>;
+
+		// TODO: Refacor once `device.get()` accepts an array of uuids`
+		const devices = await Promise.all(
+			deviceUuids.map(
+				(uuid) =>
+					balena.models.device.get(uuid, deviceOptions) as Promise<
+						PineTypedResult<Device, typeof deviceOptions>
+					>,
+			),
+		);
+		return devices;
+	}
+
 	public async run() {
 		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
 			DeviceMoveCmd,
 		);
 
-		if ((options.application || options.app) && process.stderr.isTTY) {
-			console.error(warnify(appToFleetFlagMsg));
-		}
-		options.application ||= options.app || options.fleet;
-
 		const balena = getBalenaSdk();
 
-		const { tryAsInteger } = await import('../../utils/validation');
-		const { expandForAppName } = await import('../../utils/helpers');
+		// Split uuids string into array of uuids
+		const deviceUuids = params.uuid.split(',');
 
-		// Parse ids string into array of correct types
-		const deviceIds: Array<string | number> = params.uuid
-			.split(',')
-			.map((id) => tryAsInteger(id));
+		const devices = await this.getDevices(balena, deviceUuids);
 
-		// Get devices
-		const devices = await Promise.all(
-			deviceIds.map(
-				(uuid) =>
-					balena.models.device.get(
-						uuid,
-						expandForAppName,
-					) as Promise<ExtendedDevice>,
-			),
-		);
-
-		// Map application name for each device
-		for (const device of devices) {
-			const belongsToApplication =
-				device.belongs_to__application as Application[];
-			device.application_name = belongsToApplication?.[0]
-				? belongsToApplication[0].app_name
-				: 'N/a';
-		}
-
-		// Disambiguate application (if is a number, it could either be an ID or a numerical name)
+		// Disambiguate application
 		const { getApplication } = await import('../../utils/sdk');
 
 		// Get destination application
-		const application = options.application
-			? await getApplication(balena, options.application)
+		const application = options.fleet
+			? await getApplication(balena, options.fleet, { $select: ['id', 'slug'] })
 			: await this.interactivelySelectApplication(balena, devices);
 
 		// Move each device
-		for (const uuid of deviceIds) {
+		for (const uuid of deviceUuids) {
 			try {
 				await balena.models.device.move(uuid, application.id);
 				console.info(`Device ${uuid} was moved to fleet ${application.slug}`);
@@ -143,44 +136,60 @@ export default class DeviceMoveCmd extends Command {
 
 	async interactivelySelectApplication(
 		balena: BalenaSDK,
-		devices: ExtendedDevice[],
+		devices: Awaited<ReturnType<typeof this.getDevices>>,
 	) {
-		const [deviceDeviceTypes, deviceTypes] = await Promise.all([
-			Promise.all(
-				devices.map((device) =>
-					balena.models.device.getManifestBySlug(
-						device.is_of__device_type[0].slug,
-					),
+		const { getExpandedProp } = await import('../../utils/pine');
+		// deduplicate the slugs
+		const deviceCpuArchs = Array.from(
+			new Set(
+				devices.map(
+					(d) => d.is_of__device_type[0].is_of__cpu_architecture[0].slug,
 				),
 			),
-			balena.models.config.getDeviceTypes(),
-		]);
+		);
 
-		const compatibleDeviceTypes = deviceTypes.filter((dt) =>
-			deviceDeviceTypes.every(
-				(deviceDeviceType) =>
-					balena.models.os.isArchitectureCompatibleWith(
-						deviceDeviceType.arch,
-						dt.arch,
-					) &&
-					!!dt.isDependent === !!deviceDeviceType.isDependent &&
-					dt.state !== 'DISCONTINUED',
-			),
+		const deviceTypeOptions = {
+			$select: 'slug',
+			$expand: {
+				is_of__cpu_architecture: {
+					$select: 'slug',
+				},
+			},
+		} satisfies PineOptions<DeviceType>;
+		const deviceTypes = (await balena.models.deviceType.getAllSupported(
+			deviceTypeOptions,
+		)) as Array<PineTypedResult<DeviceType, typeof deviceTypeOptions>>;
+
+		const compatibleDeviceTypeSlugs = new Set(
+			deviceTypes
+				.filter((deviceType) => {
+					const deviceTypeArch = getExpandedProp(
+						deviceType.is_of__cpu_architecture,
+						'slug',
+					)!;
+					return deviceCpuArchs.every((deviceCpuArch) =>
+						balena.models.os.isArchitectureCompatibleWith(
+							deviceCpuArch,
+							deviceTypeArch,
+						),
+					);
+				})
+				.map((deviceType) => deviceType.slug),
 		);
 
 		const patterns = await import('../../utils/patterns');
 		try {
 			const application = await patterns.selectApplication(
 				(app) =>
-					compatibleDeviceTypes.some(
-						(dt) => dt.slug === app.is_for__device_type[0].slug,
-					) &&
-					devices.some((device) => device.application_name !== app.app_name),
+					compatibleDeviceTypeSlugs.has(app.is_for__device_type[0].slug) &&
+					devices.some(
+						(device) => device.belongs_to__application.__id !== app.id,
+					),
 				true,
 			);
 			return application;
 		} catch (err) {
-			if (deviceDeviceTypes.length) {
+			if (!compatibleDeviceTypeSlugs.size) {
 				throw new ExpectedError(
 					`${err.message}\nDo all devices have a compatible architecture?`,
 				);

lib/commands/device/os-update.ts

@@ -20,7 +20,6 @@ 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 { tryAsInteger } from '../../utils/validation';
 import type { Device } from 'balena-sdk';
 import { ExpectedError } from '../../errors';
 
@@ -47,6 +46,7 @@ export default class DeviceOsUpdateCmd extends Command {
 		`;
 	public static examples = [
 		'$ balena device os-update 23c73a1',
+		'$ balena device os-update 23c73a1 --version 2.101.7',
 		'$ balena device os-update 23c73a1 --version 2.31.0+rev1.prod',
 	];
 
@@ -54,7 +54,6 @@ export default class DeviceOsUpdateCmd extends Command {
 		{
 			name: 'uuid',
 			description: 'the uuid of the device to update',
-			parse: (dev) => tryAsInteger(dev),
 			required: true,
 		},
 	];

lib/commands/device/pin.ts

@@ -0,0 +1,103 @@
+/**
+ * @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 } from '../../utils/lazy';
+import { getExpandedProp } from '../../utils/pine';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	uuid: string;
+	releaseToPinTo?: string;
+}
+
+export default class DevicePinCmd extends Command {
+	public static description = stripIndent`
+		Pin a device to a release.
+
+		Pin a device to a release.
+
+		Note, if the commit is omitted, the currently pinned release will be printed, with instructions for how to see a list of releases
+		`;
+	public static examples = [
+		'$ balena device pin 7cf02a6',
+		'$ balena device pin 7cf02a6 91165e5',
+	];
+
+	public static args: Array<IArg<any>> = [
+		{
+			name: 'uuid',
+			description: 'the uuid of the device to pin to a release',
+			required: true,
+		},
+		{
+			name: 'releaseToPinTo',
+			description: 'the commit of the release for the device to get pinned to',
+		},
+	];
+
+	public static usage = 'device pin <uuid> [releaseToPinTo]';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(DevicePinCmd);
+
+		const balena = getBalenaSdk();
+
+		const device = await balena.models.device.get(params.uuid, {
+			$expand: {
+				should_be_running__release: {
+					$select: 'commit',
+				},
+				belongs_to__application: {
+					$select: 'slug',
+				},
+			},
+		});
+
+		const pinnedRelease = getExpandedProp(
+			device.should_be_running__release,
+			'commit',
+		);
+		const appSlug = getExpandedProp(device.belongs_to__application, 'slug');
+
+		const releaseToPinTo = params.releaseToPinTo;
+
+		if (!releaseToPinTo) {
+			console.log(
+				`${
+					pinnedRelease
+						? `This device is currently pinned to ${pinnedRelease}.`
+						: 'This device is not currently pinned to any release.'
+				} \n\nTo see a list of all releases this device can be pinned to, run \`balena releases ${appSlug}\`.`,
+			);
+		} else {
+			await balena.models.device.pinToRelease(params.uuid, releaseToPinTo);
+		}
+	}
+}

lib/commands/device/public-url.ts

@@ -21,7 +21,6 @@ import Command from '../../command';
 import { ExpectedError } from '../../errors';
 import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import { tryAsInteger } from '../../utils/validation';
 
 interface FlagsDef {
 	enable: boolean;
@@ -32,8 +31,6 @@ interface FlagsDef {
 
 interface ArgsDef {
 	uuid: string;
-	// Optional hidden arg to support old command format
-	legacyUuid?: string;
 }
 
 export default class DevicePublicUrlCmd extends Command {
@@ -43,9 +40,6 @@ export default class DevicePublicUrlCmd extends Command {
 		This command will output the current public URL for the
 		specified device.  It can also enable or disable the URL,
 		or output the enabled status, using the respective options.
-
-		The old command style 'balena device public-url enable <uuid>'
-		is deprecated, but still supported.
 	`;
 
 	public static examples = [
@@ -59,15 +53,8 @@ export default class DevicePublicUrlCmd extends Command {
 		{
 			name: 'uuid',
 			description: 'the uuid of the device to manage',
-			parse: (dev) => tryAsInteger(dev),
 			required: true,
 		},
-		{
-			// Optional hidden arg to support old command format
-			name: 'legacyUuid',
-			parse: (dev) => tryAsInteger(dev),
-			hidden: true,
-		},
 	];
 
 	public static usage = 'device public-url <uuid>';
@@ -95,25 +82,6 @@ export default class DevicePublicUrlCmd extends Command {
 			DevicePublicUrlCmd,
 		);
 
-		// Legacy command format support.
-		// Previously this command used the following format
-		// (changed due to oclif technicalities):
-		//   `balena device public-url enable|disable|status <uuid>`
-		if (params.legacyUuid) {
-			const action = params.uuid;
-			if (!['enable', 'disable', 'status'].includes(action)) {
-				throw new ExpectedError(
-					`Unexpected arguments: ${params.uuid} ${params.legacyUuid}`,
-				);
-			}
-
-			options.enable = action === 'enable';
-			options.disable = action === 'disable';
-			options.status = action === 'status';
-			params.uuid = params.legacyUuid;
-			delete params.legacyUuid;
-		}
-
 		const balena = getBalenaSdk();
 
 		if (options.enable) {

lib/commands/device/purge.ts

@@ -63,17 +63,14 @@ export default class DevicePurgeCmd extends Command {
 	public async run() {
 		const { args: params } = this.parse<FlagsDef, ArgsDef>(DevicePurgeCmd);
 
-		const { tryAsInteger } = await import('../../utils/validation');
 		const balena = getBalenaSdk();
 		const ux = getCliUx();
 
-		const deviceIds = params.uuid.split(',').map((id) => {
-			return tryAsInteger(id);
-		});
+		const deviceUuids = params.uuid.split(',');
 
-		for (const deviceId of deviceIds) {
-			ux.action.start(`Purging data from device ${deviceId}`);
-			await balena.models.device.purge(deviceId);
+		for (const uuid of deviceUuids) {
+			ux.action.start(`Purging data from device ${uuid}`);
+			await balena.models.device.purge(uuid);
 			ux.action.stop();
 		}
 	}

lib/commands/device/reboot.ts

@@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
 import Command from '../../command';
 import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import { tryAsInteger } from '../../utils/validation';
 
 interface FlagsDef {
 	force: boolean;
@@ -43,7 +42,6 @@ export default class DeviceRebootCmd extends Command {
 		{
 			name: 'uuid',
 			description: 'the uuid of the device to reboot',
-			parse: (dev) => tryAsInteger(dev),
 			required: true,
 		},
 	];

lib/commands/device/register.ts

@@ -25,6 +25,7 @@ import { applicationIdInfo } from '../../utils/messages';
 
 interface FlagsDef {
 	uuid?: string;
+	deviceType?: string;
 	help: void;
 }
 
@@ -47,6 +48,7 @@ export default class DeviceRegisterCmd extends Command {
 		'$ balena device register MyFleet',
 		'$ balena device register MyFleet --uuid <uuid>',
 		'$ balena device register myorg/myfleet --uuid <uuid>',
+		'$ balena device register myorg/myfleet --uuid <uuid> --deviceType <deviceTypeSlug>',
 	];
 
 	public static args: Array<IArg<any>> = [ca.fleetRequired];
@@ -58,6 +60,10 @@ export default class DeviceRegisterCmd extends Command {
 			description: 'custom uuid',
 			char: 'u',
 		}),
+		deviceType: flags.string({
+			description:
+				"device type slug (run 'balena devices supported' for possible values)",
+		}),
 		help: cf.help,
 	};
 
@@ -72,12 +78,18 @@ export default class DeviceRegisterCmd extends Command {
 
 		const balena = getBalenaSdk();
 
-		const application = await getApplication(balena, params.fleet);
+		const application = await getApplication(balena, params.fleet, {
+			$select: ['id', 'slug'],
+		});
 		const uuid = options.uuid ?? balena.models.device.generateUniqueKey();
 
-		console.info(`Registering to ${application.app_name}: ${uuid}`);
+		console.info(`Registering to ${application.slug}: ${uuid}`);
 
-		const result = await balena.models.device.register(application.id, uuid);
+		const result = await balena.models.device.register(
+			application.id,
+			uuid,
+			options.deviceType,
+		);
 
 		return result && result.uuid;
 	}

lib/commands/device/rename.ts

@@ -20,7 +20,6 @@ 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 { tryAsInteger } from '../../utils/validation';
 
 interface FlagsDef {
 	help: void;
@@ -48,7 +47,6 @@ export default class DeviceRenameCmd extends Command {
 		{
 			name: 'uuid',
 			description: 'the uuid of the device to rename',
-			parse: (dev) => tryAsInteger(dev),
 			required: true,
 		},
 		{

lib/commands/device/restart.ts

@@ -82,24 +82,21 @@ export default class DeviceRestartCmd extends Command {
 			DeviceRestartCmd,
 		);
 
-		const { tryAsInteger } = await import('../../utils/validation');
 		const balena = getBalenaSdk();
 		const ux = getCliUx();
 
-		const deviceIds = params.uuid.split(',').map((id) => {
-			return tryAsInteger(id);
-		});
+		const deviceUuids = params.uuid.split(',');
 		const serviceNames = options.service?.split(',');
 
-		// Iterate sequentially through deviceIds.
+		// Iterate sequentially through deviceUuids.
 		// We may later want to add a batching feature,
 		// so that n devices are processed in parallel
-		for (const deviceId of deviceIds) {
-			ux.action.start(`Restarting services on device ${deviceId}`);
+		for (const uuid of deviceUuids) {
+			ux.action.start(`Restarting services on device ${uuid}`);
 			if (serviceNames) {
-				await this.restartServices(balena, deviceId, serviceNames);
+				await this.restartServices(balena, uuid, serviceNames);
 			} else {
-				await this.restartAllServices(balena, deviceId);
+				await this.restartAllServices(balena, uuid);
 			}
 			ux.action.stop();
 		}
@@ -107,7 +104,7 @@ export default class DeviceRestartCmd extends Command {
 
 	async restartServices(
 		balena: BalenaSDK,
-		deviceId: number | string,
+		deviceUuid: string,
 		serviceNames: string[],
 	) {
 		const { ExpectedError, instanceOf } = await import('../../errors');
@@ -116,7 +113,7 @@ export default class DeviceRestartCmd extends Command {
 		// Get device
 		let device: DeviceWithServiceDetails<CurrentServiceWithCommit>;
 		try {
-			device = await balena.models.device.getWithServiceDetails(deviceId, {
+			device = await balena.models.device.getWithServiceDetails(deviceUuid, {
 				$expand: {
 					is_running__release: { $select: 'commit' },
 				},
@@ -124,7 +121,7 @@ export default class DeviceRestartCmd extends Command {
 		} catch (e) {
 			const { BalenaDeviceNotFound } = await import('balena-errors');
 			if (instanceOf(e, BalenaDeviceNotFound)) {
-				throw new ExpectedError(`Device ${deviceId} not found.`);
+				throw new ExpectedError(`Device ${deviceUuid} not found.`);
 			} else {
 				throw e;
 			}
@@ -136,7 +133,7 @@ export default class DeviceRestartCmd extends Command {
 		serviceNames.forEach((service) => {
 			if (!device.current_services[service]) {
 				throw new ExpectedError(
-					`Service ${service} not found on device ${deviceId}.`,
+					`Service ${service} not found on device ${deviceUuid}.`,
 				);
 			}
 		});
@@ -155,7 +152,7 @@ export default class DeviceRestartCmd extends Command {
 			if (serviceContainer) {
 				restartPromises.push(
 					balena.models.device.restartService(
-						deviceId,
+						deviceUuid,
 						serviceContainer.image_id,
 					),
 				);
@@ -166,32 +163,32 @@ export default class DeviceRestartCmd extends Command {
 			await Promise.all(restartPromises);
 		} catch (e) {
 			if (e.message.toLowerCase().includes('no online device')) {
-				throw new ExpectedError(`Device ${deviceId} is not online.`);
+				throw new ExpectedError(`Device ${deviceUuid} is not online.`);
 			} else {
 				throw e;
 			}
 		}
 	}
 
-	async restartAllServices(balena: BalenaSDK, deviceId: number | string) {
+	async restartAllServices(balena: BalenaSDK, deviceUuid: string) {
 		// Note: device.restartApplication throws `BalenaDeviceNotFound: Device not found` if device not online.
 		// Need to use device.get first to distinguish between non-existant and offline devices.
 		// Remove this workaround when SDK issue resolved: https://github.com/balena-io/balena-sdk/issues/649
 		const { instanceOf, ExpectedError } = await import('../../errors');
 		try {
-			const device = await balena.models.device.get(deviceId);
+			const device = await balena.models.device.get(deviceUuid);
 			if (!device.is_online) {
-				throw new ExpectedError(`Device ${deviceId} is not online.`);
+				throw new ExpectedError(`Device ${deviceUuid} is not online.`);
 			}
 		} catch (e) {
 			const { BalenaDeviceNotFound } = await import('balena-errors');
 			if (instanceOf(e, BalenaDeviceNotFound)) {
-				throw new ExpectedError(`Device ${deviceId} not found.`);
+				throw new ExpectedError(`Device ${deviceUuid} not found.`);
 			} else {
 				throw e;
 			}
 		}
 
-		await balena.models.device.restartApplication(deviceId);
+		await balena.models.device.restartApplication(deviceUuid);
 	}
 }

lib/commands/device/rm.ts

@@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
 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;
@@ -84,7 +83,7 @@ export default class DeviceRmCmd extends Command {
 		// Remove
 		for (const uuid of uuids) {
 			try {
-				await balena.models.device.remove(tryAsInteger(uuid));
+				await balena.models.device.remove(uuid);
 			} catch (err) {
 				console.info(`${err.message}, uuid: ${uuid}`);
 				process.exitCode = 1;

lib/commands/device/shutdown.ts

@@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
 import Command from '../../command';
 import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import { tryAsInteger } from '../../utils/validation';
 import { ExpectedError } from '../../errors';
 
 interface FlagsDef {
@@ -44,7 +43,6 @@ export default class DeviceShutdownCmd extends Command {
 		{
 			name: 'uuid',
 			description: 'the uuid of the device to shutdown',
-			parse: (dev) => tryAsInteger(dev),
 			required: true,
 		},
 	];

lib/commands/device/track-fleet.ts

@@ -0,0 +1,63 @@
+/**
+ * @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 } from '../../utils/lazy';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	uuid: string;
+}
+
+export default class DeviceTrackFleetCmd extends Command {
+	public static description = stripIndent`
+		Make a device track the fleet's pinned release.
+
+		Make a device track the fleet's pinned release.
+		`;
+	public static examples = ['$ balena device track-fleet 7cf02a6'];
+
+	public static args: Array<IArg<any>> = [
+		{
+			name: 'uuid',
+			description: "the uuid of the device to make track the fleet's release",
+			required: true,
+		},
+	];
+
+	public static usage = 'device track-fleet <uuid>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(DeviceTrackFleetCmd);
+
+		const balena = getBalenaSdk();
+
+		await balena.models.device.trackApplicationRelease(params.uuid);
+	}
+}

lib/commands/devices/index.ts

@@ -20,32 +20,28 @@ import Command from '../../command';
 import * as cf from '../../utils/common-flags';
 import { expandForAppName } from '../../utils/helpers';
 import { getBalenaSdk, getVisuals, stripIndent } from '../../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetFlagMsg,
-	appToFleetOutputMsg,
-	jsonInfo,
-	warnify,
-} from '../../utils/messages';
-import { isV13 } from '../../utils/version';
+import { applicationIdInfo, jsonInfo } from '../../utils/messages';
 
-import type { Application } from 'balena-sdk';
-
-interface ExtendedDevice extends DeviceWithDeviceType {
-	dashboard_url?: string;
-	application_name?: string | null;
-	device_type?: string | null;
-}
+import type { Device, PineOptions } from 'balena-sdk';
 
 interface FlagsDef {
-	application?: string;
-	app?: string;
 	fleet?: string;
 	help: void;
 	json: boolean;
-	v13: boolean;
 }
 
+const devicesSelectFields = {
+	$select: [
+		'id',
+		'uuid',
+		'device_name',
+		'status',
+		'is_online',
+		'supervisor_version',
+		'os_version',
+	],
+} satisfies PineOptions<Device>;
+
 export default class DevicesCmd extends Command {
 	public static description = stripIndent`
 		List all devices.
@@ -67,83 +63,57 @@ export default class DevicesCmd extends Command {
 	public static usage = 'devices';
 
 	public static flags: flags.Input<FlagsDef> = {
-		...(isV13()
-			? {}
-			: {
-					application: {
-						...cf.application,
-						exclusive: ['app', 'fleet', 'v13'],
-					},
-					app: { ...cf.app, exclusive: ['application', 'fleet', 'v13'] },
-			  }),
-		fleet: { ...cf.fleet, exclusive: ['app', 'application'] },
+		fleet: cf.fleet,
 		json: cf.json,
 		help: cf.help,
-		v13: cf.v13,
 	};
 
 	public static primary = true;
 
 	public static authenticated = true;
 
-	protected useAppWord = false;
-	protected hasWarned = false;
-
 	public async run() {
 		const { flags: options } = this.parse<FlagsDef, {}>(DevicesCmd);
-		this.useAppWord = !options.fleet && !options.v13 && !isV13();
 
 		const balena = getBalenaSdk();
+		const devicesOptions = {
+			...devicesSelectFields,
+			...expandForAppName,
+			$orderby: { device_name: 'asc' },
+		} satisfies PineOptions<Device>;
 
-		if (
-			(options.application || options.app) &&
-			!options.json &&
-			process.stderr.isTTY
-		) {
-			this.hasWarned = true;
-			console.error(warnify(appToFleetFlagMsg));
-		}
-		// Consolidate application options
-		options.application ||= options.app || options.fleet;
+		const devices = (
+			await (async () => {
+				if (options.fleet != null) {
+					const { getApplication } = await import('../../utils/sdk');
+					const application = await getApplication(balena, options.fleet, {
+						$select: 'slug',
+						$expand: {
+							owns__device: devicesOptions,
+						},
+					});
+					return application.owns__device;
+				}
 
-		let devices;
+				return await balena.pine.get({
+					resource: 'device',
+					options: devicesOptions,
+				});
+			})()
+		).map((device) => ({
+			...device,
+			dashboard_url: balena.models.device.getDashboardUrl(device.uuid),
+			fleet: device.belongs_to__application?.[0]?.slug || null,
+			uuid: options.json ? device.uuid : device.uuid.slice(0, 7),
+			device_type: device.is_of__device_type?.[0]?.slug || null,
+		}));
 
-		if (options.application != null) {
-			const { getApplication } = await import('../../utils/sdk');
-			const application = await getApplication(balena, options.application);
-			devices = (await balena.models.device.getAllByApplication(
-				application.id,
-				expandForAppName,
-			)) as ExtendedDevice[];
-		} else {
-			devices = (await balena.models.device.getAll(
-				expandForAppName,
-			)) as ExtendedDevice[];
-		}
-
-		devices = devices.map(function (device) {
-			device.dashboard_url = balena.models.device.getDashboardUrl(device.uuid);
-
-			const belongsToApplication =
-				device.belongs_to__application as Application[];
-			device.application_name = belongsToApplication?.[0]?.app_name || null;
-
-			device.uuid = options.json ? device.uuid : device.uuid.slice(0, 7);
-
-			device.device_type = device.is_of__device_type?.[0]?.slug || null;
-			return device;
-		});
-
-		const jName = this.useAppWord ? 'application_name' : 'fleet_name';
-		const tName = this.useAppWord ? 'APPLICATION NAME' : 'FLEET';
-		const fields = [
+		const fields: Array<keyof (typeof devices)[number]> = [
 			'id',
 			'uuid',
 			'device_name',
 			'device_type',
-			options.json
-				? `application_name => ${jName}`
-				: `application_name => ${tName}`,
+			'fleet',
 			'status',
 			'is_online',
 			'supervisor_version',
@@ -156,9 +126,6 @@ export default class DevicesCmd extends Command {
 			const mapped = devices.map((device) => pickAndRename(device, fields));
 			console.log(JSON.stringify(mapped, null, 4));
 		} else {
-			if (!this.hasWarned && this.useAppWord && process.stderr.isTTY) {
-				console.error(warnify(appToFleetOutputMsg));
-			}
 			const _ = await import('lodash');
 			console.log(
 				getVisuals().table.horizontal(

lib/commands/devices/supported.ts

@@ -15,39 +15,25 @@
  * limitations under the License.
  */
 import { flags } from '@oclif/command';
+import type * as BalenaSdk from 'balena-sdk';
 import * as _ from 'lodash';
 import Command from '../../command';
 
 import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, getVisuals, stripIndent } from '../../utils/lazy';
 import { CommandHelp } from '../../utils/oclif-utils';
-import { isV13 } from '../../utils/version';
 
 interface FlagsDef {
-	discontinued: boolean;
 	help: void;
 	json?: boolean;
-	verbose?: boolean;
 }
 
-const deprecatedInfo = isV13()
-	? ''
-	: `
-The --verbose option may add extra columns/fields to the output. Currently
-this includes the "STATE" column which is DEPRECATED and whose values are one
-of 'new', 'released' or 'discontinued'. However, 'discontinued' device types
-are only listed if the '--discontinued' option is also used, and this option
-is also DEPRECATED.
-`
-			.split('\n')
-			.join(`\n\t\t`);
-
 export default class DevicesSupportedCmd extends Command {
 	public static description = stripIndent`
 		List the supported device types (like 'raspberrypi3' or 'intel-nuc').
 
 		List the supported device types (like 'raspberrypi3' or 'intel-nuc').
-		${deprecatedInfo}
+
 		The --json option is recommended when scripting the output of this command,
 		because the JSON format is less likely to change and it better represents data
 		types like lists and empty strings (for example, the ALIASES column contains a
@@ -56,8 +42,7 @@ export default class DevicesSupportedCmd extends Command {
 `;
 	public static examples = [
 		'$ balena devices supported',
-		'$ balena devices supported --verbose',
-		'$ balena devices supported -vj',
+		'$ balena devices supported --json',
 	];
 
 	public static usage = (
@@ -66,82 +51,48 @@ export default class DevicesSupportedCmd extends Command {
 	).trim();
 
 	public static flags: flags.Input<FlagsDef> = {
-		discontinued: flags.boolean({
-			description: isV13()
-				? 'No effect (DEPRECATED)'
-				: 'include "discontinued" device types (DEPRECATED)',
-		}),
 		help: cf.help,
 		json: flags.boolean({
 			char: 'j',
 			description: 'produce JSON output instead of tabular output',
 		}),
-		verbose: flags.boolean({
-			char: 'v',
-			description: isV13()
-				? 'No effect (DEPRECATED)'
-				: 'add extra columns in the tabular output (DEPRECATED)',
-		}),
 	};
 
 	public async run() {
 		const { flags: options } = this.parse<FlagsDef, {}>(DevicesSupportedCmd);
-		const [dts, configDTs] = await Promise.all([
-			getBalenaSdk().models.deviceType.getAllSupported({
-				$expand: { is_of__cpu_architecture: { $select: 'slug' } },
-				$select: ['slug', 'name'],
-			}),
-			getBalenaSdk().models.config.getDeviceTypes(),
-		]);
-		const dtsBySlug = _.keyBy(dts, (dt) => dt.slug);
-		const configDTsBySlug = _.keyBy(configDTs, (dt) => dt.slug);
-		const discontinuedDTs = isV13()
-			? []
-			: configDTs.filter((dt) => dt.state === 'DISCONTINUED');
-		const discontinuedDTsBySlug = _.keyBy(discontinuedDTs, (dt) => dt.slug);
-		// set of slugs from models.deviceType.getAllSupported() plus slugs of
-		// discontinued device types as per models.config.getDeviceTypes()
-		const slugsOfInterest = new Set([
-			...Object.keys(dtsBySlug),
-			...Object.keys(discontinuedDTsBySlug),
-		]);
+		const pineOptions = {
+			$select: ['slug', 'name'],
+			$expand: {
+				is_of__cpu_architecture: { $select: 'slug' },
+				device_type_alias: {
+					$select: 'is_referenced_by__alias',
+					$orderby: { is_referenced_by__alias: 'asc' },
+				},
+			},
+		} satisfies BalenaSdk.PineOptions<BalenaSdk.DeviceType>;
+		const dts = (await getBalenaSdk().models.deviceType.getAllSupported(
+			pineOptions,
+		)) as Array<
+			BalenaSdk.PineTypedResult<BalenaSdk.DeviceType, typeof pineOptions>
+		>;
 		interface DT {
 			slug: string;
 			aliases: string[];
 			arch: string;
-			state?: string; // to be removed in CLI v13
 			name: string;
 		}
-		let deviceTypes: DT[] = [];
-		for (const slug of slugsOfInterest) {
-			const configDT: Partial<typeof configDTs[0]> =
-				configDTsBySlug[slug] || {};
-			if (configDT.state === 'DISCONTINUED' && !options.discontinued) {
-				continue;
-			}
-			const dt: Partial<typeof dts[0]> = dtsBySlug[slug] || {};
-			const aliases = (configDT.aliases || []).filter(
-				(alias) => alias !== slug,
-			);
-			deviceTypes.push({
-				slug,
+		let deviceTypes = dts.map((dt): DT => {
+			const aliases = dt.device_type_alias
+				.map((dta) => dta.is_referenced_by__alias)
+				.filter((alias) => alias !== dt.slug);
+			return {
+				slug: dt.slug,
 				aliases: options.json ? aliases : [aliases.join(', ')],
-				arch:
-					(dt.is_of__cpu_architecture as any)?.[0]?.slug ||
-					configDT.arch ||
-					'n/a',
-				// 'BETA' renamed to 'NEW'
-				// https://www.flowdock.com/app/rulemotion/i-cli/threads/1svvyaf8FAZeSdG4dPJc4kHOvJU
-				state: isV13()
-					? undefined
-					: (configDT.state || 'NEW').replace('BETA', 'NEW'),
-				name: dt.name || configDT.name || 'N/A',
-			});
-		}
-		const fields =
-			options.verbose && !isV13()
-				? ['slug', 'aliases', 'arch', 'state', 'name']
-				: ['slug', 'aliases', 'arch', 'name'];
+				arch: dt.is_of__cpu_architecture[0]?.slug || 'n/a',
+				name: dt.name || 'N/A',
+			};
+		});
+		const fields = ['slug', 'aliases', 'arch', 'name'];
 		deviceTypes = _.sortBy(deviceTypes, fields);
 		if (options.json) {
 			console.log(JSON.stringify(deviceTypes, null, 4));

lib/commands/env/add.ts

@@ -21,15 +21,9 @@ import Command from '../../command';
 import { ExpectedError } from '../../errors';
 import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, stripIndent } from '../../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetFlagMsg,
-	warnify,
-} from '../../utils/messages';
-import { isV13 } from '../../utils/version';
+import { applicationIdInfo } from '../../utils/messages';
 
 interface FlagsDef {
-	application?: string;
 	fleet?: string;
 	device?: string; // device UUID
 	help: void;
@@ -101,11 +95,8 @@ export default class EnvAddCmd extends Command {
 	public static usage = 'env add <name> [value]';
 
 	public static flags: flags.Input<FlagsDef> = {
-		...(isV13()
-			? {}
-			: { application: { ...cf.application, exclusive: ['fleet', 'device'] } }),
-		fleet: { ...cf.fleet, exclusive: ['application', 'device'] },
-		device: { ...cf.device, exclusive: ['application', 'fleet'] },
+		fleet: { ...cf.fleet, exclusive: ['device'] },
+		device: { ...cf.device, exclusive: ['fleet'] },
 		help: cf.help,
 		quiet: cf.quiet,
 		service: cf.service,
@@ -117,11 +108,7 @@ export default class EnvAddCmd extends Command {
 		);
 		const cmd = this;
 
-		if (options.application && process.stderr.isTTY) {
-			console.error(warnify(appToFleetFlagMsg));
-		}
-		options.application ||= options.fleet;
-		if (!options.application && !options.device) {
+		if (!options.fleet && !options.device) {
 			throw new ExpectedError(
 				'Either the --fleet or the --device option must be specified',
 			);
@@ -163,16 +150,16 @@ export default class EnvAddCmd extends Command {
 		}
 
 		const varType = isConfigVar ? 'configVar' : 'envVar';
-		if (options.application) {
-			for (const app of options.application.split(',')) {
+		if (options.fleet) {
+			for (const appSlug of await resolveFleetSlugs(balena, options.fleet)) {
 				try {
 					await balena.models.application[varType].set(
-						app,
+						appSlug,
 						params.name,
 						params.value,
 					);
 				} catch (err) {
-					console.error(`${err.message}, fleet: ${app}`);
+					console.error(`${err.message}, fleet: ${appSlug}`);
 					process.exitCode = 1;
 				}
 			}
@@ -193,6 +180,25 @@ export default class EnvAddCmd extends Command {
 	}
 }
 
+// TODO: Stop accepting application names in the next major
+// and just drop this in favor of doing the .split(',') directly.
+async function resolveFleetSlugs(
+	balena: BalenaSdk.BalenaSDK,
+	fleetOption: string,
+) {
+	const fleetSlugs: string[] = [];
+	const { getFleetSlug } = await import('../../utils/sdk');
+	for (const appNameOrSlug of fleetOption.split(',')) {
+		try {
+			fleetSlugs.push(await getFleetSlug(balena, appNameOrSlug));
+		} catch (err) {
+			console.error(`${err.message}, fleet: ${appNameOrSlug}`);
+			process.exitCode = 1;
+		}
+	}
+	return fleetSlugs;
+}
+
 /**
  * Add service variables for a device or fleet.
  */
@@ -201,18 +207,18 @@ async function setServiceVars(
 	params: ArgsDef,
 	options: FlagsDef,
 ) {
-	if (options.application) {
-		for (const app of options.application.split(',')) {
+	if (options.fleet) {
+		for (const appSlug of await resolveFleetSlugs(sdk, options.fleet)) {
 			for (const service of options.service!.split(',')) {
 				try {
-					const serviceId = await getServiceIdForApp(sdk, app, service);
+					const serviceId = await getServiceIdForApp(sdk, appSlug, service);
 					await sdk.models.service.var.set(
 						serviceId,
 						params.name,
 						params.value!,
 					);
 				} catch (err) {
-					console.error(`${err.message}, fleet: ${app}`);
+					console.error(`${err.message}, fleet: ${appSlug}`);
 					process.exitCode = 1;
 				}
 			}
@@ -227,7 +233,7 @@ async function setServiceVars(
 					sdk,
 					uuid,
 					['id'],
-					['app_name'],
+					['slug'],
 				);
 			} catch (err) {
 				console.error(`${err.message}, device: ${uuid}`);
@@ -236,11 +242,7 @@ async function setServiceVars(
 			}
 			for (const service of options.service!.split(',')) {
 				try {
-					const serviceId = await getServiceIdForApp(
-						sdk,
-						app.app_name,
-						service,
-					);
+					const serviceId = await getServiceIdForApp(sdk, app.slug, service);
 					await sdk.models.device.serviceVar.set(
 						device.id,
 						serviceId,
@@ -261,11 +263,11 @@ async function setServiceVars(
  */
 async function getServiceIdForApp(
 	sdk: BalenaSdk.BalenaSDK,
-	appName: string,
+	appSlug: string,
 	serviceName: string,
 ): Promise<number> {
 	let serviceId: number | undefined;
-	const services = await sdk.models.service.getAllByApplication(appName, {
+	const services = await sdk.models.service.getAllByApplication(appSlug, {
 		$filter: { service_name: serviceName },
 	});
 	if (services.length > 0) {
@@ -273,7 +275,7 @@ async function getServiceIdForApp(
 	}
 	if (serviceId === undefined) {
 		throw new ExpectedError(
-			`Cannot find service ${serviceName} for fleet ${appName}`,
+			`Cannot find service ${serviceName} for fleet ${appSlug}`,
 		);
 	}
 	return serviceId;

lib/commands/env/rm.ts

@@ -91,8 +91,6 @@ export default class EnvRmCmd extends Command {
 		await confirm(
 			opt.yes || false,
 			'Are you sure you want to delete the environment variable?',
-			undefined,
-			true,
 		);
 
 		const balena = getBalenaSdk();

lib/commands/envs.ts

@@ -21,42 +21,33 @@ import Command from '../command';
 import { ExpectedError } from '../errors';
 import * as cf from '../utils/common-flags';
 import { getBalenaSdk, getVisuals, stripIndent } from '../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetFlagMsg,
-	appToFleetOutputMsg,
-	warnify,
-} from '../utils/messages';
-import { isV13 } from '../utils/version';
+import { applicationIdInfo } from '../utils/messages';
 
 interface FlagsDef {
-	application?: string;
 	fleet?: string;
 	config: boolean;
 	device?: string; // device UUID
 	json: boolean;
 	help: void;
 	service?: string; // service name
-	verbose: boolean;
-	v13: boolean;
 }
 
 interface EnvironmentVariableInfo extends SDK.EnvironmentVariableBase {
-	appName?: string | null; // application name
+	fleet?: string | null; // fleet slug
 	deviceUUID?: string; // device UUID
 	serviceName?: string; // service name
 }
 
 interface DeviceServiceEnvironmentVariableInfo
 	extends SDK.DeviceServiceEnvironmentVariable {
-	appName?: string; // application name
+	fleet?: string; // fleet slug
 	deviceUUID?: string; // device UUID
 	serviceName?: string; // service name
 }
 
 interface ServiceEnvironmentVariableInfo
 	extends SDK.ServiceEnvironmentVariable {
-	appName?: string; // application name
+	fleet?: string; // fleet slug
 	deviceUUID?: string; // device UUID
 	serviceName?: string; // service name
 }
@@ -96,8 +87,6 @@ export default class EnvsCmd extends Command {
 		in case the current user was removed from the fleet by the fleet's owner).
 
 		${applicationIdInfo.split('\n').join('\n\t\t')}
-
-		${appToFleetOutputMsg.split('\n').join('\n\t\t')}
 	`;
 
 	public static examples = [
@@ -115,57 +104,35 @@ export default class EnvsCmd extends Command {
 	public static usage = 'envs';
 
 	public static flags: flags.Input<FlagsDef> = {
-		...(isV13()
-			? {}
-			: {
-					all: flags.boolean({
-						default: false,
-						description: 'No-op since balena CLI v12.0.0.',
-						hidden: true,
-					}),
-					application: {
-						exclusive: ['device', 'fleet', 'v13'],
-						...cf.application,
-					},
-			  }),
-		fleet: { exclusive: ['device', 'application'], ...cf.fleet },
+		fleet: { ...cf.fleet, exclusive: ['device'] },
 		config: flags.boolean({
 			default: false,
 			char: 'c',
 			description: 'show configuration variables only',
 			exclusive: ['service'],
 		}),
-		device: { exclusive: ['fleet', 'application'], ...cf.device },
+		device: { ...cf.device, exclusive: ['fleet'] },
 		help: cf.help,
 		json: cf.json,
-		verbose: cf.verbose,
-		service: { exclusive: ['config'], ...cf.service },
-		v13: cf.v13,
+		service: { ...cf.service, exclusive: ['config'] },
 	};
 
-	protected useAppWord = false;
-	protected hasWarned = false;
-
 	public async run() {
 		const { flags: options } = this.parse<FlagsDef, {}>(EnvsCmd);
-		this.useAppWord = !options.fleet && !options.v13 && !isV13();
 
 		const variables: EnvironmentVariableInfo[] = [];
 
 		await Command.checkLoggedIn();
 
-		if (options.application && !options.json && process.stderr.isTTY) {
-			this.hasWarned = true;
-			console.error(warnify(appToFleetFlagMsg));
-		}
-		options.application ||= options.fleet;
-		if (!options.application && !options.device) {
+		if (!options.fleet && !options.device) {
 			throw new ExpectedError('Missing --fleet or --device option');
 		}
 
 		const balena = getBalenaSdk();
 
-		let appNameOrSlug = options.application;
+		let fleetSlug: string | undefined = options.fleet
+			? await (await import('../utils/sdk')).getFleetSlug(balena, options.fleet)
+			: undefined;
 		let fullUUID: string | undefined; // as oppposed to the short, 7-char UUID
 
 		if (options.device) {
@@ -174,27 +141,27 @@ export default class EnvsCmd extends Command {
 				balena,
 				options.device,
 				['uuid'],
-				['app_name'],
+				['slug'],
 			);
 			fullUUID = device.uuid;
 			if (app) {
-				appNameOrSlug = app.app_name;
+				fleetSlug = app.slug;
 			}
 		}
-		if (appNameOrSlug && options.service) {
-			await validateServiceName(balena, options.service, appNameOrSlug);
+		if (fleetSlug && options.service) {
+			await validateServiceName(balena, options.service, fleetSlug);
 		}
-		variables.push(...(await getAppVars(balena, appNameOrSlug, options)));
+		variables.push(...(await getAppVars(balena, fleetSlug, options)));
 		if (fullUUID) {
 			variables.push(
-				...(await getDeviceVars(balena, fullUUID, appNameOrSlug, options)),
+				...(await getDeviceVars(balena, fullUUID, fleetSlug, options)),
 			);
 		}
 		if (!options.json && variables.length === 0) {
 			const target =
 				(options.service ? `service "${options.service}" of ` : '') +
-				(options.application
-					? `fleet "${options.application}"`
+				(options.fleet
+					? `fleet "${options.fleet}"`
 					: `device "${options.device}"`);
 			throw new ExpectedError(`No environment variables found for ${target}`);
 		}
@@ -206,17 +173,14 @@ export default class EnvsCmd extends Command {
 		varArray: EnvironmentVariableInfo[],
 		options: FlagsDef,
 	) {
-		const fields = ['id', 'name', 'value'];
+		const fields = ['id', 'name', 'value', 'fleet'];
 
 		// Replace undefined app names with 'N/A' or null
 		varArray = varArray.map((i: EnvironmentVariableInfo) => {
-			i.appName = i.appName || (options.json ? null : 'N/A');
+			i.fleet ||= options.json ? null : 'N/A';
 			return i;
 		});
 
-		const jName = this.useAppWord ? 'appName' : 'fleetName';
-		const tName = this.useAppWord ? 'APPLICATION' : 'FLEET';
-		fields.push(options.json ? `appName => ${jName}` : `appName => ${tName}`);
 		if (options.device) {
 			fields.push(options.json ? 'deviceUUID' : 'deviceUUID => DEVICE');
 		}
@@ -229,9 +193,6 @@ export default class EnvsCmd extends Command {
 			const mapped = varArray.map((o) => pickAndRename(o, fields));
 			this.log(JSON.stringify(mapped, null, 4));
 		} else {
-			if (!this.hasWarned && this.useAppWord && process.stderr.isTTY) {
-				console.error(warnify(appToFleetOutputMsg));
-			}
 			this.log(
 				getVisuals().table.horizontal(
 					_.sortBy(varArray, (v: SDK.EnvironmentVariableBase) => v.name),
@@ -245,14 +206,14 @@ export default class EnvsCmd extends Command {
 async function validateServiceName(
 	sdk: SDK.BalenaSDK,
 	serviceName: string,
-	appName: string,
+	fleetSlug: string,
 ) {
-	const services = await sdk.models.service.getAllByApplication(appName, {
+	const services = await sdk.models.service.getAllByApplication(fleetSlug, {
 		$filter: { service_name: serviceName },
 	});
 	if (services.length === 0) {
 		throw new ExpectedError(
-			`Service "${serviceName}" not found for fleet "${appName}"`,
+			`Service "${serviceName}" not found for fleet "${fleetSlug}"`,
 		);
 	}
 }
@@ -266,17 +227,17 @@ async function validateServiceName(
  */
 async function getAppVars(
 	sdk: SDK.BalenaSDK,
-	appNameOrSlug: string | undefined,
+	fleetSlug: string | undefined,
 	options: FlagsDef,
 ): Promise<EnvironmentVariableInfo[]> {
 	const appVars: EnvironmentVariableInfo[] = [];
-	if (!appNameOrSlug) {
+	if (!fleetSlug) {
 		return appVars;
 	}
 	const vars = await sdk.models.application[
 		options.config ? 'configVar' : 'envVar'
-	].getAllByApplication(appNameOrSlug);
-	fillInInfoFields(vars, appNameOrSlug);
+	].getAllByApplication(fleetSlug);
+	fillInInfoFields(vars, fleetSlug);
 	appVars.push(...vars);
 	if (!options.config) {
 		const pineOpts: SDK.PineOptions<SDK.ServiceEnvironmentVariable> = {
@@ -292,10 +253,10 @@ async function getAppVars(
 			};
 		}
 		const serviceVars = await sdk.models.service.var.getAllByApplication(
-			appNameOrSlug,
+			fleetSlug,
 			pineOpts,
 		);
-		fillInInfoFields(serviceVars, appNameOrSlug);
+		fillInInfoFields(serviceVars, fleetSlug);
 		appVars.push(...serviceVars);
 	}
 	return appVars;
@@ -308,7 +269,7 @@ async function getAppVars(
 async function getDeviceVars(
 	sdk: SDK.BalenaSDK,
 	fullUUID: string,
-	appNameOrSlug: string | undefined,
+	fleetSlug: string | undefined,
 	options: FlagsDef,
 ): Promise<EnvironmentVariableInfo[]> {
 	const printedUUID = options.json ? fullUUID : options.device!;
@@ -317,7 +278,7 @@ async function getDeviceVars(
 		const deviceConfigVars = await sdk.models.device.configVar.getAllByDevice(
 			fullUUID,
 		);
-		fillInInfoFields(deviceConfigVars, appNameOrSlug, printedUUID);
+		fillInInfoFields(deviceConfigVars, fleetSlug, printedUUID);
 		deviceVars.push(...deviceConfigVars);
 	} else {
 		const pineOpts: SDK.PineOptions<SDK.DeviceServiceEnvironmentVariable> = {
@@ -338,13 +299,13 @@ async function getDeviceVars(
 			fullUUID,
 			pineOpts,
 		);
-		fillInInfoFields(deviceServiceVars, appNameOrSlug, printedUUID);
+		fillInInfoFields(deviceServiceVars, fleetSlug, printedUUID);
 		deviceVars.push(...deviceServiceVars);
 
 		const deviceEnvVars = await sdk.models.device.envVar.getAllByDevice(
 			fullUUID,
 		);
-		fillInInfoFields(deviceEnvVars, appNameOrSlug, printedUUID);
+		fillInInfoFields(deviceEnvVars, fleetSlug, printedUUID);
 		deviceVars.push(...deviceEnvVars);
 	}
 	return deviceVars;
@@ -360,7 +321,7 @@ function fillInInfoFields(
 		| EnvironmentVariableInfo[]
 		| DeviceServiceEnvironmentVariableInfo[]
 		| ServiceEnvironmentVariableInfo[],
-	appNameOrSlug?: string,
+	fleetSlug?: string,
 	deviceUUID?: string,
 ) {
 	for (const envVar of varArray) {
@@ -374,7 +335,7 @@ function fillInInfoFields(
 					?.installs__service as SDK.Service[]
 			)[0]?.service_name;
 		}
-		envVar.appName = appNameOrSlug;
+		envVar.fleet = fleetSlug;
 		envVar.serviceName = envVar.serviceName || '*';
 		envVar.deviceUUID = deviceUUID || '*';
 	}

lib/commands/fleet/create.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2021 Balena Ltd.
+ * Copyright 2016-2021 Balena Ltd.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,135 @@
  * limitations under the License.
  */
 
-import { FleetCreateCmd } from '../app/create';
+import { flags } from '@oclif/command';
 
-export default FleetCreateCmd;
+import Command from '../../command';
+import { ExpectedError } from '../../errors';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+
+interface FlagsDef {
+	organization?: string;
+	type?: string; // application device type
+	help: void;
+}
+
+interface ArgsDef {
+	name: string;
+}
+
+export default class FleetCreateCmd extends Command {
+	public static description = stripIndent`
+		Create a fleet.
+
+		Create a new balena fleet.
+
+		You can specify the organization the fleet should belong to using
+		the \`--organization\` option. The organization's handle, not its name,
+		should be provided. Organization handles can be listed with the
+		\`balena orgs\` command.
+
+		The fleet's default device type is specified with the \`--type\` option.
+		The \`balena devices supported\` command can be used to list the available
+		device types.
+
+		Interactive dropdowns will be shown for selection if no device type or
+		organization is specified and there are multiple options to choose from.
+		If there is a single option to choose from, it will be chosen automatically.
+		This interactive behavior can be disabled by explicitly specifying a device
+		type and organization.
+	`;
+
+	public static examples = [
+		'$ balena fleet create MyFleet',
+		'$ balena fleet create MyFleet --organization mmyorg',
+		'$ balena fleet create MyFleet -o myorg --type raspberry-pi',
+	];
+
+	public static args = [
+		{
+			name: 'name',
+			description: 'fleet name',
+			required: true,
+		},
+	];
+
+	public static usage = 'fleet create <name>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		organization: flags.string({
+			char: 'o',
+			description: 'handle of the organization the fleet should belong to',
+		}),
+		type: flags.string({
+			char: 't',
+			description:
+				'fleet 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>(
+			FleetCreateCmd,
+		);
+
+		// Ascertain device type
+		const deviceType =
+			options.type ||
+			(await (await import('../../utils/patterns')).selectDeviceType());
+
+		// Ascertain organization
+		const organization =
+			options.organization?.toLowerCase() || (await this.getOrganization());
+
+		// Create application
+		try {
+			const application = await getBalenaSdk().models.application.create({
+				name: params.name,
+				deviceType,
+				organization,
+			});
+
+			// Output
+			console.log(
+				`Fleet created: slug "${application.slug}", device type "${deviceType}"`,
+			);
+		} catch (err) {
+			if ((err.message || '').toLowerCase().includes('unique')) {
+				// BalenaRequestError: Request error: "organization" and "app_name" must be unique.
+				throw new ExpectedError(
+					`Error: An app or block or fleet with the name "${params.name}" already exists in organization "${organization}".`,
+				);
+			} else if ((err.message || '').toLowerCase().includes('unauthorized')) {
+				// BalenaRequestError: Request error: Unauthorized
+				throw new ExpectedError(
+					`Error: You are not authorized to create fleets in organization "${organization}".`,
+				);
+			}
+
+			throw err;
+		}
+	}
+
+	async getOrganization() {
+		const { getOwnOrganizations } = await import('../../utils/sdk');
+		const organizations = await getOwnOrganizations(getBalenaSdk(), {
+			$select: ['name', 'handle'],
+		});
+
+		if (organizations.length === 0) {
+			// User is not a member of any organizations (should not happen).
+			throw new Error('This account is not a member of any organizations');
+		} else if (organizations.length === 1) {
+			// User is a member of only one organization - use this.
+			return organizations[0].handle;
+		} else {
+			// User is a member of multiple organizations -
+			const { selectOrganization } = await import('../../utils/patterns');
+			return selectOrganization(organizations);
+		}
+	}
+}

lib/commands/fleet/index.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2021 Balena Ltd.
+ * Copyright 2016-2021 Balena Ltd.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,90 @@
  * limitations under the License.
  */
 
-import { FleetCmd } from '../app';
+import type { flags as flagsType } from '@oclif/command';
+import { flags } from '@oclif/command';
 
-export default FleetCmd;
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import * as ca from '../../utils/common-args';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { applicationIdInfo } from '../../utils/messages';
+import type { DataOutputOptions } from '../../framework';
+
+interface FlagsDef extends DataOutputOptions {
+	help: void;
+	view: boolean;
+}
+
+interface ArgsDef {
+	fleet: string;
+}
+
+export default class FleetCmd extends Command {
+	public static description = stripIndent`
+		Display information about a single fleet.
+
+		Display detailed information about a single fleet.
+
+		${applicationIdInfo.split('\n').join('\n\t\t')}
+`;
+	public static examples = [
+		'$ balena fleet MyFleet',
+		'$ balena fleet myorg/myfleet',
+		'$ balena fleet myorg/myfleet --view',
+	];
+
+	public static args = [ca.fleetRequired];
+
+	public static usage = 'fleet <fleet>';
+
+	public static flags: flagsType.Input<FlagsDef> = {
+		help: cf.help,
+		view: flags.boolean({
+			default: false,
+			description: 'open fleet dashboard page',
+		}),
+		...cf.dataOutputFlags,
+	};
+
+	public static authenticated = true;
+	public static primary = true;
+
+	public async run() {
+		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
+			FleetCmd,
+		);
+
+		const { getApplication } = await import('../../utils/sdk');
+
+		const balena = getBalenaSdk();
+
+		const application = await getApplication(balena, params.fleet, {
+			$expand: {
+				is_for__device_type: { $select: 'slug' },
+				should_be_running__release: { $select: 'commit' },
+			},
+		});
+
+		if (options.view) {
+			const open = await import('open');
+			const dashboardUrl = balena.models.application.getDashboardUrl(
+				application.id,
+			);
+			await open(dashboardUrl, { wait: false });
+			return;
+		}
+
+		const outputApplication = {
+			...application,
+			device_type: application.is_for__device_type[0].slug,
+			commit: application.should_be_running__release[0]?.commit,
+		};
+
+		await this.outputData(
+			outputApplication,
+			['app_name', 'id', 'device_type', 'slug', 'commit'],
+			options,
+		);
+	}
+}

lib/commands/fleet/pin.ts

@@ -0,0 +1,100 @@
+/**
+ * @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 } from '../../utils/lazy';
+import { getExpandedProp } from '../../utils/pine';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	slug: string;
+	releaseToPinTo?: string;
+}
+
+export default class FleetPinCmd extends Command {
+	public static description = stripIndent`
+		Pin a fleet to a release.
+
+		Pin a fleet to a release.
+
+		Note, if the commit is omitted, the currently pinned release will be printed, with instructions for how to see a list of releases
+		`;
+	public static examples = [
+		'$ balena fleet pin myfleet',
+		'$ balena fleet pin myorg/myfleet 91165e5',
+	];
+
+	public static args: Array<IArg<any>> = [
+		{
+			name: 'slug',
+			description: 'the slug of the fleet to pin to a release',
+			required: true,
+		},
+		{
+			name: 'releaseToPinTo',
+			description: 'the commit of the release for the fleet to get pinned to',
+		},
+	];
+
+	public static usage = 'fleet pin <slug> [releaseToPinTo]';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(FleetPinCmd);
+
+		const balena = getBalenaSdk();
+
+		const fleet = await balena.models.application.get(params.slug, {
+			$expand: {
+				should_be_running__release: {
+					$select: 'commit',
+				},
+			},
+		});
+
+		const pinnedRelease = getExpandedProp(
+			fleet.should_be_running__release,
+			'commit',
+		);
+
+		const releaseToPinTo = params.releaseToPinTo;
+		const slug = params.slug;
+
+		if (!releaseToPinTo) {
+			console.log(
+				`${
+					pinnedRelease
+						? `This fleet is currently pinned to ${pinnedRelease}.`
+						: 'This fleet is not currently pinned to any release.'
+				} \n\nTo see a list of all releases this fleet can be pinned to, run \`balena releases ${slug}\`.`,
+			);
+		} else {
+			await balena.models.application.pinToRelease(slug, releaseToPinTo);
+		}
+	}
+}

lib/commands/fleet/purge.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2021 Balena Ltd.
+ * 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.
@@ -15,6 +15,69 @@
  * limitations under the License.
  */
 
-import { FleetPurgeCmd } from '../app/purge';
+import type { flags } from '@oclif/command';
 
-export default FleetPurgeCmd;
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import * as ca from '../../utils/common-args';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { applicationIdInfo } from '../../utils/messages';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	fleet: string;
+}
+
+export default class FleetPurgeCmd extends Command {
+	public static description = stripIndent`
+		Purge data from a fleet.
+
+		Purge data from all devices belonging to a fleet.
+		This will clear the fleet's '/data' directory.
+
+		${applicationIdInfo.split('\n').join('\n\t\t')}
+	`;
+
+	public static examples = [
+		'$ balena fleet purge MyFleet',
+		'$ balena fleet purge myorg/myfleet',
+	];
+
+	public static args = [ca.fleetRequired];
+
+	public static usage = 'fleet purge <fleet>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(FleetPurgeCmd);
+
+		const { getApplication } = await import('../../utils/sdk');
+
+		const balena = getBalenaSdk();
+
+		// balena.models.application.purge only accepts a numeric id
+		// so we must first fetch the app to get it's id,
+		const application = await getApplication(balena, params.fleet, {
+			$select: 'id',
+		});
+
+		try {
+			await balena.models.application.purge(application.id);
+		} 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/fleet/rename.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2021 Balena Ltd.
+ * 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.
@@ -15,6 +15,135 @@
  * limitations under the License.
  */
 
-import { FleetRenameCmd } from '../app/rename';
+import type { flags } from '@oclif/command';
 
-export default FleetRenameCmd;
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import * as ca from '../../utils/common-args';
+import { getBalenaSdk, stripIndent, getCliForm } from '../../utils/lazy';
+import { applicationIdInfo } from '../../utils/messages';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	fleet: string;
+	newName?: string;
+}
+
+export default class FleetRenameCmd extends Command {
+	public static description = stripIndent`
+		Rename a fleet.
+
+		Rename a fleet.
+
+		Note, if the \`newName\` parameter is omitted, it will be
+		prompted for interactively.
+
+		${applicationIdInfo.split('\n').join('\n\t\t')}
+	`;
+
+	public static examples = [
+		'$ balena fleet rename OldName',
+		'$ balena fleet rename OldName NewName',
+		'$ balena fleet rename myorg/oldname NewName',
+	];
+
+	public static args = [
+		ca.fleetRequired,
+		{
+			name: 'newName',
+			description: 'the new name for the fleet',
+		},
+	];
+
+	public static usage = 'fleet rename <fleet> [newName]';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(FleetRenameCmd);
+
+		const { validateApplicationName } = await import('../../utils/validation');
+		const { ExpectedError } = await import('../../errors');
+
+		const balena = getBalenaSdk();
+
+		// Disambiguate target application (if params.params is a number, it could either be an ID or a numerical name)
+		const { getApplication } = await import('../../utils/sdk');
+		const application = await getApplication(balena, params.fleet, {
+			$select: ['id', 'app_name', 'slug'],
+			$expand: {
+				application_type: {
+					$select: 'slug',
+				},
+			},
+		});
+
+		// Check app exists
+		if (!application) {
+			throw new ExpectedError(`Error: fleet ${params.fleet} not found.`);
+		}
+
+		// Check app supports renaming
+		const appType = application.application_type[0];
+		if (appType.slug === 'legacy-v1' || appType.slug === 'legacy-v2') {
+			throw new ExpectedError(
+				`Fleet ${params.fleet} is of 'legacy' type, and cannot be renamed.`,
+			);
+		}
+
+		// Ascertain new name
+		const newName =
+			params.newName ||
+			(await getCliForm().ask({
+				message: 'Please enter the new name for this fleet:',
+				type: 'input',
+				validate: validateApplicationName,
+			})) ||
+			'';
+
+		// Check they haven't used slug in new name
+		if (newName.includes('/')) {
+			throw new ExpectedError(
+				`New fleet name cannot include '/', please check that you are not specifying fleet slug.`,
+			);
+		}
+
+		// Rename
+		try {
+			await balena.models.application.rename(application.id, newName);
+		} catch (e) {
+			// BalenaRequestError: Request error: "organization" and "app_name" must be unique.
+			if ((e.message || '').toLowerCase().includes('unique')) {
+				throw new ExpectedError(`Error: fleet ${newName} already exists.`);
+			}
+			// BalenaRequestError: Request error: App name may only contain [a-zA-Z0-9_-].
+			if ((e.message || '').toLowerCase().includes('name may only contain')) {
+				throw new ExpectedError(
+					`Error: new fleet name may only include characters [a-zA-Z0-9_-].`,
+				);
+			}
+			throw e;
+		}
+
+		// Get application again, to be sure of results
+		const renamedApplication = await getApplication(balena, application.id, {
+			$select: ['app_name', 'slug'],
+		});
+
+		// Output result
+		console.log(`Fleet renamed`);
+		console.log('From:');
+		console.log(`\tname: ${application.app_name}`);
+		console.log(`\tslug: ${application.slug}`);
+		console.log('To:');
+		console.log(`\tname: ${renamedApplication.app_name}`);
+		console.log(`\tslug: ${renamedApplication.slug}`);
+	}
+}

lib/commands/fleet/restart.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2021 Balena Ltd.
+ * 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.
@@ -15,6 +15,58 @@
  * limitations under the License.
  */
 
-import { FleetRestartCmd } from '../app/restart';
+import type { flags } from '@oclif/command';
 
-export default FleetRestartCmd;
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import * as ca from '../../utils/common-args';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { applicationIdInfo } from '../../utils/messages';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	fleet: string;
+}
+
+export default class FleetRestartCmd extends Command {
+	public static description = stripIndent`
+		Restart a fleet.
+
+		Restart all devices belonging to a fleet.
+
+		${applicationIdInfo.split('\n').join('\n\t\t')}
+	`;
+
+	public static examples = [
+		'$ balena fleet restart MyFleet',
+		'$ balena fleet restart myorg/myfleet',
+	];
+
+	public static args = [ca.fleetRequired];
+
+	public static usage = 'fleet restart <fleet>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(FleetRestartCmd);
+
+		const { getApplication } = await import('../../utils/sdk');
+
+		const balena = getBalenaSdk();
+
+		// Disambiguate application
+		const application = await getApplication(balena, params.fleet, {
+			$select: 'slug',
+		});
+
+		await balena.models.application.restart(application.slug);
+	}
+}

lib/commands/fleet/rm.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2021 Balena Ltd.
+ * 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.
@@ -15,6 +15,72 @@
  * limitations under the License.
  */
 
-import { FleetRmCmd } from '../app/rm';
+import type { flags } from '@oclif/command';
 
-export default FleetRmCmd;
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import * as ca from '../../utils/common-args';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { applicationIdInfo } from '../../utils/messages';
+
+interface FlagsDef {
+	yes: boolean;
+	help: void;
+}
+
+interface ArgsDef {
+	fleet: string;
+}
+
+export default class FleetRmCmd extends Command {
+	public static description = stripIndent`
+		Remove a fleet.
+
+		Permanently remove a fleet.
+
+		The --yes option may be used to avoid interactive confirmation.
+
+		${applicationIdInfo.split('\n').join('\n\t\t')}
+	`;
+
+	public static examples = [
+		'$ balena fleet rm MyFleet',
+		'$ balena fleet rm MyFleet --yes',
+		'$ balena fleet rm myorg/myfleet',
+	];
+
+	public static args = [ca.fleetRequired];
+
+	public static usage = 'fleet rm <fleet>';
+
+	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>(
+			FleetRmCmd,
+		);
+
+		const { confirm } = await import('../../utils/patterns');
+		const { getApplication } = await import('../../utils/sdk');
+		const balena = getBalenaSdk();
+
+		// Confirm
+		await confirm(
+			options.yes ?? false,
+			`Are you sure you want to delete fleet ${params.fleet}?`,
+		);
+
+		// Disambiguate application (if is a number, it could either be an ID or a numerical name)
+		const application = await getApplication(balena, params.fleet, {
+			$select: 'slug',
+		});
+
+		// Remove
+		await balena.models.application.remove(application.slug);
+	}
+}

lib/commands/fleet/track-latest.ts

@@ -0,0 +1,66 @@
+/**
+ * @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 } from '../../utils/lazy';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	slug: string;
+}
+
+export default class FleetTrackLatestCmd extends Command {
+	public static description = stripIndent`
+		Make this fleet track the latest release.
+
+		Make this fleet track the latest release.
+		`;
+	public static examples = [
+		'$ balena fleet track-latest myorg/myfleet',
+		'$ balena fleet track-latest myfleet',
+	];
+
+	public static args: Array<IArg<any>> = [
+		{
+			name: 'slug',
+			description: 'the slug of the fleet to make track the latest release',
+			required: true,
+		},
+	];
+
+	public static usage = 'fleet track-latest <slug>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(FleetTrackLatestCmd);
+
+		const balena = getBalenaSdk();
+
+		await balena.models.application.trackLatestRelease(params.slug);
+	}
+}

lib/commands/fleets.ts

@@ -15,6 +15,80 @@
  * limitations under the License.
  */
 
-import { FleetsCmd } from './apps';
+import { flags } from '@oclif/command';
 
-export default FleetsCmd;
+import Command from '../command';
+import * as cf from '../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../utils/lazy';
+import type { DataSetOutputOptions } from '../framework';
+
+interface ExtendedApplication extends ApplicationWithDeviceType {
+	device_count: number;
+	online_devices: number;
+	device_type?: string;
+}
+
+interface FlagsDef extends DataSetOutputOptions {
+	help: void;
+	verbose?: boolean;
+}
+
+export default class FleetsCmd extends Command {
+	public static description = stripIndent`
+		List all fleets.
+
+		List all your balena fleets.
+
+		For detailed information on a particular fleet, use
+		\`balena fleet <fleet>\`
+	`;
+
+	public static examples = ['$ balena fleets'];
+
+	public static usage = 'fleets';
+
+	public static flags: flags.Input<FlagsDef> = {
+		...cf.dataSetOutputFlags,
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+	public static primary = true;
+
+	public async run() {
+		const { flags: options } = this.parse<FlagsDef, {}>(FleetsCmd);
+
+		const balena = getBalenaSdk();
+
+		// Get applications
+		const applications =
+			(await balena.models.application.getAllDirectlyAccessible({
+				$select: ['id', 'app_name', 'slug'],
+				$expand: {
+					is_for__device_type: { $select: 'slug' },
+					owns__device: { $select: 'is_online' },
+				},
+			})) as ExtendedApplication[];
+
+		// Add extended properties
+		applications.forEach((application) => {
+			application.device_count = application.owns__device?.length ?? 0;
+			application.online_devices =
+				application.owns__device?.filter((d) => d.is_online).length || 0;
+			application.device_type = application.is_for__device_type[0].slug;
+		});
+
+		await this.outputData(
+			applications,
+			[
+				'id',
+				'app_name',
+				'slug',
+				'device_type',
+				'device_count',
+				'online_devices',
+			],
+			options,
+		);
+	}
+}

lib/commands/internal/osinit.ts

@@ -63,6 +63,7 @@ export default class OsinitCmd extends Command {
 
 	public static hidden = true;
 	public static root = true;
+	public static offlineCompatible = true;
 
 	public async run() {
 		const { args: params } = this.parse<{}, ArgsDef>(OsinitCmd);

lib/commands/join.ts

@@ -21,10 +21,8 @@ import * as cf from '../utils/common-flags';
 import { getBalenaSdk, stripIndent } from '../utils/lazy';
 import { applicationIdInfo } from '../utils/messages';
 import { parseAsLocalHostnameOrIp } from '../utils/validation';
-import { isV13 } from '../utils/version';
 
 interface FlagsDef {
-	application?: string;
 	fleet?: string;
 	pollInterval?: number;
 	help?: void;
@@ -77,7 +75,6 @@ export default class JoinCmd extends Command {
 	public static usage = 'join [deviceIpOrHostname]';
 
 	public static flags: flags.Input<FlagsDef> = {
-		...(isV13() ? {} : { application: cf.application }),
 		fleet: cf.fleet,
 		pollInterval: flags.integer({
 			description: 'the interval in minutes to check for updates',
@@ -101,7 +98,7 @@ export default class JoinCmd extends Command {
 			logger,
 			sdk,
 			params.deviceIpOrHostname,
-			options.application || options.fleet,
+			options.fleet,
 			options.pollInterval,
 		);
 	}

lib/commands/local/configure.ts

@@ -56,6 +56,7 @@ export default class LocalConfigureCmd extends Command {
 	};
 
 	public static root = true;
+	public static offlineCompatible = true;
 
 	public async run() {
 		const { args: params } = this.parse<FlagsDef, ArgsDef>(LocalConfigureCmd);
@@ -96,7 +97,7 @@ export default class LocalConfigureCmd extends Command {
 
 	readonly CONNECTIONS_FOLDER = '/system-connections';
 
-	getConfigurationSchema(bootPartition: number, connectionFileName?: string) {
+	getConfigurationSchema(bootPartition?: number, connectionFileName?: string) {
 		connectionFileName ??= 'resin-wifi';
 		return {
 			mapper: [
@@ -112,6 +113,12 @@ export default class LocalConfigureCmd extends Command {
 					},
 					domain: [['config_json', 'hostname']],
 				},
+				{
+					template: {
+						developmentMode: '{{developmentMode}}',
+					},
+					domain: [['config_json', 'developmentMode']],
+				},
 				{
 					template: {
 						wifi: {
@@ -162,6 +169,13 @@ export default class LocalConfigureCmd extends Command {
 			name: 'networkKey',
 			default: data.networkKey,
 		},
+		{
+			message:
+				'Enable development mode? (Open ports and root access - Not for production!)',
+			type: 'confirm',
+			name: 'developmentMode',
+			default: false,
+		},
 		{
 			message: 'Do you want to set advanced settings?',
 			type: 'confirm',
@@ -235,9 +249,9 @@ export default class LocalConfigureCmd extends Command {
 	async prepareConnectionFile(target: string) {
 		const _ = await import('lodash');
 		const imagefs = await import('balena-image-fs');
-		const helpers = await import('../../utils/helpers');
+		const { getBootPartition } = await import('balena-config-json');
 
-		const bootPartition = await helpers.getBootPartition(target);
+		const bootPartition = await getBootPartition(target);
 
 		const files = await imagefs.interact(target, bootPartition, async (_fs) => {
 			return await promisify(_fs.readdir)(this.CONNECTIONS_FOLDER);

lib/commands/local/flash.ts

@@ -20,12 +20,7 @@ import type { BlockDevice } from 'etcher-sdk/build/source-destination';
 import Command from '../../command';
 import { ExpectedError } from '../../errors';
 import * as cf from '../../utils/common-flags';
-import {
-	getChalk,
-	getCliForm,
-	getVisuals,
-	stripIndent,
-} from '../../utils/lazy';
+import { getChalk, getVisuals, stripIndent } from '../../utils/lazy';
 
 interface FlagsDef {
 	yes: boolean;
@@ -70,6 +65,8 @@ export default class LocalFlashCmd extends Command {
 		help: cf.help,
 	};
 
+	public static offlineCompatible = true;
+
 	public async run() {
 		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
 			LocalFlashCmd,
@@ -93,24 +90,15 @@ export default class LocalFlashCmd extends Command {
 			}
 		}
 
-		const { sourceDestination, multiWrite } = await import('etcher-sdk');
-
 		const drive = await this.getDrive(options);
 
-		const yes =
-			options.yes ||
-			(await getCliForm().ask({
-				message: 'This will erase the selected drive. Are you sure?',
-				type: 'confirm',
-				name: 'yes',
-				default: false,
-			}));
-
-		if (!yes) {
-			console.log(getChalk().red.bold('Aborted image flash'));
-			process.exit(0);
-		}
+		const { confirm } = await import('../../utils/patterns');
+		await confirm(
+			options.yes,
+			'This will erase the selected drive. Are you sure?',
+		);
 
+		const { sourceDestination, multiWrite } = await import('etcher-sdk');
 		const file = new sourceDestination.File({
 			path: params.image,
 		});

lib/commands/login.ts

@@ -187,7 +187,7 @@ ${messages.reachingOut}`);
 			if (loginType === 'register') {
 				const open = await import('open');
 				const signupUrl = `https://dashboard.${balenaUrl}/signup`;
-				open(signupUrl, { wait: false });
+				await open(signupUrl, { wait: false });
 				throw new ExpectedError(`Please sign up at ${signupUrl}`);
 			}
 

lib/commands/note.ts

@@ -88,6 +88,6 @@ export default class NoteCmd extends Command {
 
 		const balena = getBalenaSdk();
 
-		return balena.models.device.note(options.device!, params.note);
+		return balena.models.device.setNote(options.device, params.note);
 	}
 }

lib/commands/orgs.ts

@@ -46,7 +46,9 @@ export default class OrgsCmd extends Command {
 		const { getOwnOrganizations } = await import('../utils/sdk');
 
 		// Get organizations
-		const organizations = await getOwnOrganizations(getBalenaSdk());
+		const organizations = await getOwnOrganizations(getBalenaSdk(), {
+			$select: ['name', 'handle'],
+		});
 
 		// Display
 		console.log(

lib/commands/os/build-config.ts

@@ -35,10 +35,10 @@ interface ArgsDef {
 
 export default class OsBuildConfigCmd extends Command {
 	public static description = stripIndent`
-		Build an OS config and save it to a JSON file.
+		Prepare a configuration file for use by the 'os configure' command.
 
-		Interactively generate an OS config once, so that the generated config
-		file can be used in \`balena os configure\`, skipping the interactive part.
+		Interactively generate a configuration file that can then be used as
+		non-interactive input by the 'balena os configure' command.
 	`;
 
 	public static examples = [

lib/commands/os/configure.ts

@@ -25,30 +25,30 @@ import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, stripIndent, getCliForm } from '../../utils/lazy';
 import {
 	applicationIdInfo,
-	appToFleetFlagMsg,
-	warnify,
+	devModeInfo,
+	secureBootInfo,
 } from '../../utils/messages';
-import { isV13 } from '../../utils/version';
 
 const CONNECTIONS_FOLDER = '/system-connections';
 
 interface FlagsDef {
 	advanced?: boolean;
-	application?: string;
-	app?: string;
 	fleet?: string;
 	config?: string;
 	'config-app-update-poll-interval'?: number;
 	'config-network'?: string;
 	'config-wifi-key'?: string;
 	'config-wifi-ssid'?: string;
+	dev?: boolean; // balenaOS development variant
+	secureBoot?: boolean;
 	device?: string; // device UUID
-	'device-api-key'?: string;
 	'device-type'?: string;
 	help?: void;
 	version?: string;
 	'system-connection': string[];
 	'initial-device-name'?: string;
+	'provisioning-key-name'?: string;
+	'provisioning-key-expiry-date'?: string;
 }
 
 interface ArgsDef {
@@ -57,17 +57,17 @@ interface ArgsDef {
 
 interface Answers {
 	appUpdatePollInterval: number; // in minutes
+	developmentMode?: boolean; // balenaOS development variant
+	secureBoot?: boolean;
 	deviceType: string; // e.g. "raspberrypi3"
 	network: 'ethernet' | 'wifi';
 	version: string; // e.g. "2.32.0+rev1"
 	wifiSsid?: string;
 	wifiKey?: string;
+	provisioningKeyName?: string;
+	provisioningKeyExpiryDate?: string;
 }
 
-const deviceApiKeyDeprecationMsg = stripIndent`
-	The --device-api-key option is deprecated and will be removed in a future release.
-	A suitable key is automatically generated or fetched if this option is omitted.`;
-
 export default class OsConfigureCmd extends Command {
 	public static description = stripIndent`
 		Configure a previously downloaded balenaOS image.
@@ -81,18 +81,20 @@ export default class OsConfigureCmd extends Command {
 		2. A given \`config.json\` file specified with the \`--config\` option.
 		3. User input through interactive prompts (text menus).
 
-		The --device-type option may be used to override the fleet's default device
-		type, in case of a fleet with mixed device types.
+		The --device-type option is used to override the fleet's default device type,
+		in case of a fleet with mixed device types.
 
-		The --system-connection (-c) option can be used to inject NetworkManager connection
+		${devModeInfo.split('\n').join('\n\t\t')}
+
+		${secureBootInfo.split('\n').join('\n\t\t')}
+
+		The --system-connection (-c) option is used to inject NetworkManager connection
 		profiles for additional network interfaces, such as cellular/GSM or additional
 		WiFi or ethernet connections. This option may be passed multiple times in case there
 		are multiple files to inject. See connection profile examples and reference at:
 		https://www.balena.io/docs/reference/OS/network/2.x/
 		https://developer.gnome.org/NetworkManager/stable/ref-settings.html
 
-		${deviceApiKeyDeprecationMsg.split('\n').join('\n\t\t')}
-
 		${applicationIdInfo.split('\n').join('\n\t\t')}
 
 		Note: This command is currently not supported on Windows natively. Windows users
@@ -103,7 +105,6 @@ export default class OsConfigureCmd extends Command {
 
 	public static examples = [
 		'$ balena os configure ../path/rpi3.img --device 7cf02a6',
-		'$ balena os configure ../path/rpi3.img --device 7cf02a6 --device-api-key <existingDeviceKey>',
 		'$ balena os configure ../path/rpi3.img --fleet myorg/myfleet',
 		'$ balena os configure ../path/rpi3.img --fleet MyFleet --version 2.12.7',
 		'$ balena os configure ../path/rpi3.img -f MyFinFleet --device-type raspberrypi3',
@@ -126,25 +127,11 @@ export default class OsConfigureCmd extends Command {
 			description:
 				'ask advanced configuration questions (when in interactive mode)',
 		}),
-		...(isV13()
-			? {}
-			: {
-					application: {
-						...cf.application,
-						exclusive: ['app', 'fleet', 'device'],
-					},
-					app: {
-						...cf.app,
-						exclusive: ['application', 'fleet', 'device'],
-					},
-			  }),
-		fleet: {
-			...cf.fleet,
-			exclusive: ['app', 'application', 'device'],
-		},
+		fleet: { ...cf.fleet, exclusive: ['device'] },
 		config: flags.string({
 			description:
 				'path to a pre-generated config.json file to be injected in the OS image',
+			exclusive: ['provisioning-key-name', 'provisioning-key-expiry-date'],
 		}),
 		'config-app-update-poll-interval': flags.integer({
 			description:
@@ -160,12 +147,16 @@ export default class OsConfigureCmd extends Command {
 		'config-wifi-ssid': flags.string({
 			description: 'WiFi SSID (network name) (non-interactive configuration)',
 		}),
-		device: { exclusive: ['app', 'application', 'fleet'], ...cf.device },
-		'device-api-key': flags.string({
-			char: 'k',
-			description:
-				'custom device API key (DEPRECATED and only supported with balenaOS 2.0.3+)',
-		}),
+		dev: cf.dev,
+		secureBoot: cf.secureBoot,
+		device: {
+			...cf.device,
+			exclusive: [
+				'fleet',
+				'provisioning-key-name',
+				'provisioning-key-expiry-date',
+			],
+		},
 		'device-type': flags.string({
 			description:
 				'device type slug (e.g. "raspberrypi3") to override the fleet device type',
@@ -184,17 +175,24 @@ export default class OsConfigureCmd extends Command {
 			description:
 				"paths to local files to place into the 'system-connections' directory",
 		}),
+		'provisioning-key-name': flags.string({
+			description: 'custom key name assigned to generated provisioning api key',
+			exclusive: ['config', 'device'],
+		}),
+		'provisioning-key-expiry-date': flags.string({
+			description:
+				'expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)',
+			exclusive: ['config', 'device'],
+		}),
 		help: cf.help,
 	};
 
+	public static authenticated = true;
+
 	public async run() {
 		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
 			OsConfigureCmd,
 		);
-		if ((options.application || options.app) && process.stderr.isTTY) {
-			console.error(warnify(appToFleetFlagMsg));
-		}
-		options.application ||= options.app || options.fleet;
 
 		await validateOptions(options);
 
@@ -221,12 +219,12 @@ export default class OsConfigureCmd extends Command {
 			};
 			deviceTypeSlug = device.is_of__device_type[0].slug;
 		} else {
-			app = (await getApplication(balena, options.application!, {
+			app = (await getApplication(balena, options.fleet!, {
 				$expand: {
 					is_for__device_type: { $select: 'slug' },
 				},
 			})) as ApplicationWithDeviceType;
-			await checkDeviceTypeCompatibility(balena, options, app);
+			await checkDeviceTypeCompatibility(options, app);
 			deviceTypeSlug =
 				options['device-type'] || app.is_for__device_type[0].slug;
 		}
@@ -242,25 +240,39 @@ export default class OsConfigureCmd extends Command {
 			configJson = JSON.parse(rawConfig);
 		}
 
+		const osVersion =
+			options.version ||
+			(await getOsVersionFromImage(params.image, deviceTypeManifest, devInit));
+
+		const { validateDevOptionAndWarn } = await import('../../utils/config');
+		await validateDevOptionAndWarn(options.dev, osVersion);
+
+		const { validateSecureBootOptionAndWarn } = await import(
+			'../../utils/config'
+		);
+		await validateSecureBootOptionAndWarn(
+			options.secureBoot,
+			deviceTypeSlug,
+			osVersion,
+		);
+
 		const answers: Answers = await askQuestionsForDeviceType(
 			deviceTypeManifest,
 			options,
 			configJson,
 		);
-		if (options.application) {
+		if (options.fleet) {
 			answers.deviceType = deviceTypeSlug;
 		}
-		answers.version =
-			options.version ||
-			(await getOsVersionFromImage(params.image, deviceTypeManifest, devInit));
+		answers.version = osVersion;
+		answers.developmentMode = options.dev;
+		answers.secureBoot = options.secureBoot;
+		answers.provisioningKeyName = options['provisioning-key-name'];
+		answers.provisioningKeyExpiryDate = options['provisioning-key-expiry-date'];
 
 		if (_.isEmpty(configJson)) {
 			if (device) {
-				configJson = await generateDeviceConfig(
-					device,
-					options['device-api-key'],
-					answers,
-				);
+				configJson = await generateDeviceConfig(device, undefined, answers);
 			} else {
 				configJson = await generateApplicationConfig(app!, answers);
 			}
@@ -300,7 +312,8 @@ export default class OsConfigureCmd extends Command {
 				}),
 			);
 
-			const bootPartition = await helpers.getBootPartition(params.image);
+			const { getBootPartition } = await import('balena-config-json');
+			const bootPartition = await getBootPartition(params.image);
 
 			const imagefs = await import('balena-image-fs');
 
@@ -320,23 +333,16 @@ export default class OsConfigureCmd extends Command {
 async function validateOptions(options: FlagsDef) {
 	// The 'device' and 'application' options are declared "exclusive" in the oclif
 	// flag definitions above, so oclif will enforce that they are not both used together.
-	if (!options.device && !options.application) {
+	if (!options.device && !options.fleet) {
 		throw new ExpectedError(
 			"Either the '--device' or the '--fleet' option must be provided",
 		);
 	}
-	if (!options.application && options['device-type']) {
+	if (!options.fleet && options['device-type']) {
 		throw new ExpectedError(
 			"The '--device-type' option can only be used in conjunction with the '--fleet' option",
 		);
 	}
-	if (options['device-api-key']) {
-		console.error(stripIndent`
-			-------------------------------------------------------------------------------------------
-			Warning: ${deviceApiKeyDeprecationMsg.split('\n').join('\n\t\t\t')}
-			-------------------------------------------------------------------------------------------
-		`);
-	}
 
 	await Command.checkLoggedIn();
 }
@@ -374,19 +380,21 @@ async function getOsVersionFromImage(
  * @param app Balena SDK Application model object
  */
 async function checkDeviceTypeCompatibility(
-	sdk: BalenaSdk.BalenaSDK,
 	options: FlagsDef,
-	app: ApplicationWithDeviceType,
+	app: {
+		is_for__device_type: [Pick<BalenaSdk.DeviceType, 'slug'>];
+	},
 ) {
 	if (options['device-type']) {
-		const [appDeviceType, optionDeviceType] = await Promise.all([
-			sdk.models.device.getManifestBySlug(app.is_for__device_type[0].slug),
-			sdk.models.device.getManifestBySlug(options['device-type']),
-		]);
 		const helpers = await import('../../utils/helpers');
-		if (!helpers.areDeviceTypesCompatible(appDeviceType, optionDeviceType)) {
+		if (
+			!(await helpers.areDeviceTypesCompatible(
+				app.is_for__device_type[0].slug,
+				options['device-type'],
+			))
+		) {
 			throw new ExpectedError(
-				`Device type ${options['device-type']} is incompatible with fleet ${options.application}`,
+				`Device type ${options['device-type']} is incompatible with fleet ${options.fleet}`,
 			);
 		}
 	}
@@ -411,7 +419,13 @@ async function askQuestionsForDeviceType(
 	options: FlagsDef,
 	configJson?: import('../../utils/config').ImgConfig,
 ): Promise<Answers> {
-	const answerSources: any[] = [camelifyConfigOptions(options)];
+	const answerSources: any[] = [
+		{
+			...camelifyConfigOptions(options),
+			app: options.fleet,
+			application: options.fleet,
+		},
+	];
 	const defaultAnswers: Partial<Answers> = {};
 	const questions: any = deviceType.options;
 	let extraOpts: { override: object } | undefined;

lib/commands/os/download.ts

@@ -34,30 +34,35 @@ export default class OsDownloadCmd extends Command {
 	public static description = stripIndent`
 		Download an unconfigured OS image.
 
-		Download an unconfigured OS image for a certain device type.
-		Check available types with \`balena devices supported\`
+		Download an unconfigured OS image for the specified device type.
+		Check available device types with 'balena devices supported'.
 
 		Note: Currently this command only works with balenaCloud, not openBalena.
 		If using openBalena, please download the OS from: https://www.balena.io/os/
 
-		If version is not specified the newest stable (non-pre-release) version of OS
-		is downloaded (if available), otherwise the newest version (if all existing
-		versions for the given device type are pre-release).
+		The '--version' option is used to select the balenaOS version. If omitted,
+		the latest released version is downloaded (and if only pre-release versions
+		exist, the latest pre-release version is downloaded).
 
-		You can pass \`--version menu\` to pick the OS version from the interactive menu
-		of all available versions.
+		Use '--version menu' or '--version menu-esr' to interactively select the
+		OS version. The latter lists ESR versions which are only available for
+		download on Production and Enterprise plans. See also:
+		https://www.balena.io/docs/reference/OS/extended-support-release/
 
-		To download a development image append \`.dev\` to the version or select from
-		the interactive menu.
+		Development images can be selected by appending \`.dev\` to the version.
 `;
 	public static examples = [
 		'$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img',
+		'$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2.101.7',
+		'$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2022.7.0',
+		'$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version ^2.90.0',
 		'$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2.60.1+rev1',
 		'$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2.60.1+rev1.dev',
-		'$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version ^2.60.0',
+		'$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version 2021.10.2.prod',
 		'$ 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',
+		'$ balena os download raspberrypi3 -o ../foo/bar/raspberry-pi.img --version menu-esr',
 	];
 
 	public static args = [
@@ -78,11 +83,13 @@ export default class OsDownloadCmd extends Command {
 		}),
 		version: flags.string({
 			description: stripIndent`
-				exact version number, or a valid semver range,
+				version number (ESR or non-ESR versions),
+				or semver range (non-ESR versions only),
 				or 'latest' (includes pre-releases),
-				or 'default' (excludes pre-releases if at least one stable version is available),
+				or 'default' (excludes pre-releases if at least one released version is available),
 				or 'recommended' (excludes pre-releases, will fail if only pre-release versions are available),
-				or 'menu' (will show the interactive menu)
+				or 'menu' (interactive menu, non-ESR versions),
+				or 'menu-esr' (interactive menu, ESR versions)
 				`,
 		}),
 		help: cf.help,
@@ -93,12 +100,48 @@ export default class OsDownloadCmd extends Command {
 			OsDownloadCmd,
 		);
 
+		// balenaOS ESR versions require user authentication
+		if (options.version) {
+			const { isESR } = await import('balena-image-manager');
+			if (options.version === 'menu-esr' || isESR(options.version)) {
+				try {
+					await OsDownloadCmd.checkLoggedIn();
+				} catch (e) {
+					const { ExpectedError, NotLoggedInError } = await import(
+						'../../errors'
+					);
+					if (e instanceof NotLoggedInError) {
+						throw new ExpectedError(stripIndent`
+							${e.message}
+							User authentication is required to download balenaOS ESR versions.`);
+					}
+					throw e;
+				}
+			}
+		}
+
 		const { downloadOSImage } = await import('../../utils/cloud');
 
 		try {
 			await downloadOSImage(params.type, options.output, options.version);
 		} catch (e) {
 			e.deviceTypeSlug = params.type;
+			e.message ||= '';
+			if (
+				e.code === 'BalenaRequestError' ||
+				e.message.toLowerCase().includes('no such version')
+			) {
+				const version = options.version || '';
+				if (
+					!version.endsWith('.dev') &&
+					!version.endsWith('.prod') &&
+					/^v?\d+\.\d+\.\d+/.test(version)
+				) {
+					e.message += `
+** Hint: some OS releases require specifying the full OS version including
+** the '.prod' or '.dev' suffix, e.g. '--version 2021.10.2.prod'`;
+				}
+			}
 			throw e;
 		}
 	}

lib/commands/os/initialize.ts

@@ -42,7 +42,9 @@ export default class OsInitializeCmd extends Command {
 		Initialize an os image for a device.
 
 		Initialize an os image for a device with a previously
-		configured operating system image.
+		configured operating system image and flash the
+		an external storage drive or the device's storage
+		medium depending on the device type.
 		${INIT_WARNING_MESSAGE}
 	`;
 
@@ -92,7 +94,6 @@ export default class OsInitializeCmd extends Command {
 				options.yes,
 				`This will erase ${answers.drive}. Are you sure?`,
 				`Going to erase ${answers.drive}.`,
-				true,
 			);
 			const { safeUmount } = await import('../../utils/umount');
 			await safeUmount(answers.drive);

lib/commands/os/versions.ts

@@ -18,9 +18,10 @@
 import { flags } from '@oclif/command';
 import Command from '../../command';
 import * as cf from '../../utils/common-flags';
-import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { stripIndent } from '../../utils/lazy';
 
 interface FlagsDef {
+	esr?: boolean;
 	help: void;
 }
 
@@ -34,6 +35,9 @@ export default class OsVersionsCmd extends Command {
 
 		Show the available balenaOS versions for the given device type.
 		Check available types with \`balena devices supported\`.
+
+		balenaOS ESR versions can be listed with the '--esr' option. See also:
+		https://www.balena.io/docs/reference/OS/extended-support-release/
 	`;
 
 	public static examples = ['$ balena os versions raspberrypi3'];
@@ -50,16 +54,22 @@ export default class OsVersionsCmd extends Command {
 
 	public static flags: flags.Input<FlagsDef> = {
 		help: cf.help,
+		esr: flags.boolean({
+			description: 'select balenaOS ESR versions',
+			default: false,
+		}),
 	};
 
 	public async run() {
-		const { args: params } = this.parse<FlagsDef, ArgsDef>(OsVersionsCmd);
+		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
+			OsVersionsCmd,
+		);
 
-		const { versions: vs, recommended } =
-			await getBalenaSdk().models.os.getSupportedVersions(params.type);
+		const { formatOsVersion, getOsVersions } = await import(
+			'../../utils/cloud'
+		);
+		const vs = await getOsVersions(params.type, !!options.esr);
 
-		vs.forEach((v) => {
-			console.log(`v${v}` + (v === recommended ? ' (recommended)' : ''));
-		});
+		console.log(vs.map((v) => formatOsVersion(v)).join('\n'));
 	}
 }

lib/commands/preload.ts

@@ -24,29 +24,24 @@ import {
 	getVisuals,
 	stripIndent,
 } from '../utils/lazy';
-import {
-	applicationIdInfo,
-	appToFleetFlagMsg,
-	warnify,
-} from '../utils/messages';
+import { applicationIdInfo } from '../utils/messages';
 import type { DockerConnectionCliFlags } from '../utils/docker';
 import { dockerConnectionCliFlags } from '../utils/docker';
 import { parseAsInteger } from '../utils/validation';
-import { isV13 } from '../utils/version';
 
 import { flags } from '@oclif/command';
 import * as _ from 'lodash';
 import type {
 	Application,
 	BalenaSDK,
-	DeviceTypeJson,
 	PineExpand,
+	PineOptions,
+	PineTypedResult,
 	Release,
 } from 'balena-sdk';
 import type { Preloader } from 'balena-preload';
 
 interface FlagsDef extends DockerConnectionCliFlags {
-	app?: string;
 	fleet?: string;
 	commit?: string;
 	'splash-image'?: string;
@@ -105,7 +100,6 @@ export default class PreloadCmd extends Command {
 	public static usage = 'preload <image>';
 
 	public static flags: flags.Input<FlagsDef> = {
-		...(isV13() ? {} : { app: cf.application }),
 		fleet: cf.fleet,
 		commit: flags.string({
 			description: `\
@@ -169,11 +163,6 @@ Can be repeated to add multiple certificates.\
 			PreloadCmd,
 		);
 
-		if (options.app && process.stderr.isTTY) {
-			console.error(warnify(appToFleetFlagMsg));
-		}
-		options.app ||= options.fleet;
-
 		const balena = getBalenaSdk();
 		const balenaPreload = await import('balena-preload');
 		const visuals = getVisuals();
@@ -200,18 +189,12 @@ Can be repeated to add multiple certificates.\
 
 		// balena-preload currently does not work with numerical app IDs
 		// Load app here, and use app slug from hereon
-		if (options.app && !options.app.includes('/')) {
-			// Disambiguate application (if is a number, it could either be an ID or a numerical name)
-			const { getApplication } = await import('../utils/sdk');
-			const application = await getApplication(balena, options.app);
-			if (!application) {
-				throw new ExpectedError(`Fleet not found: ${options.app}`);
-			}
-			options.app = application.slug;
-		}
+		const fleetSlug: string | undefined = options.fleet
+			? await (await import('../utils/sdk')).getFleetSlug(balena, options.fleet)
+			: undefined;
 
 		const progressBars: {
-			[key: string]: ReturnType<typeof getVisuals>['Progress'];
+			[key: string]: InstanceType<ReturnType<typeof getVisuals>['Progress']>;
 		} = {};
 
 		const progressHandler = function (event: {
@@ -225,7 +208,7 @@ Can be repeated to add multiple certificates.\
 		};
 
 		const spinners: {
-			[key: string]: ReturnType<typeof getVisuals>['Spinner'];
+			[key: string]: InstanceType<ReturnType<typeof getVisuals>['Spinner']>;
 		} = {};
 
 		const spinnerHandler = function (event: { name: string; action: string }) {
@@ -244,15 +227,12 @@ Can be repeated to add multiple certificates.\
 			? 'latest'
 			: options.commit;
 		const image = params.image;
-		const appId = options.app;
-
 		const splashImage = options['splash-image'];
 		const additionalSpace = options['additional-space'];
-
 		const dontCheckArch = options['dont-check-arch'] || false;
 		const pinDevice = options['pin-device-to-release'] || false;
 
-		if (dontCheckArch && !appId) {
+		if (dontCheckArch && !fleetSlug) {
 			throw new ExpectedError(
 				'You need to specify a fleet if you disable the architecture check.',
 			);
@@ -269,9 +249,9 @@ Can be repeated to add multiple certificates.\
 		const dockerUtils = await import('../utils/docker');
 		const docker = await dockerUtils.getDocker(options);
 		const preloader = new balenaPreload.Preloader(
-			null,
+			undefined,
 			docker,
-			appId,
+			fleetSlug,
 			commit,
 			image,
 			splashImage,
@@ -288,10 +268,17 @@ Can be repeated to add multiple certificates.\
 			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);
-				});
+				preloader
+					.cleanup()
+					.then(() => {
+						// calling process.exit() won't inform parent process of signal
+						process.kill(process.pid, signal);
+					})
+					.catch((e) => {
+						if (process.env.DEBUG) {
+							console.error(e);
+						}
+					});
 				return false;
 			}
 		});
@@ -308,7 +295,7 @@ Can be repeated to add multiple certificates.\
 				preloader.on('error', reject);
 				resolve(
 					this.prepareAndPreload(preloader, balena, {
-						appId,
+						slug: fleetSlug,
 						commit,
 						pinDevice,
 					}),
@@ -328,10 +315,9 @@ Can be repeated to add multiple certificates.\
 		}
 	}
 
-	readonly applicationExpandOptions: PineExpand<Application> = {
+	readonly applicationExpandOptions = {
 		owns__release: {
 			$select: ['id', 'commit', 'end_timestamp', 'composition'],
-			$orderby: [{ end_timestamp: 'desc' }, { id: 'desc' }],
 			$expand: {
 				contains__image: {
 					$select: ['image'],
@@ -345,77 +331,74 @@ Can be repeated to add multiple certificates.\
 			$filter: {
 				status: 'success',
 			},
+			$orderby: [{ end_timestamp: 'desc' }, { id: 'desc' }],
 		},
 		should_be_running__release: {
 			$select: 'commit',
 		},
-	};
-
-	allDeviceTypes: DeviceTypeJson.DeviceType[];
-	async getDeviceTypes() {
-		if (this.allDeviceTypes === undefined) {
-			const balena = getBalenaSdk();
-			const deviceTypes = await balena.models.config.getDeviceTypes();
-			this.allDeviceTypes = _.sortBy(deviceTypes, 'name');
-		}
-		return this.allDeviceTypes;
-	}
+	} satisfies PineExpand<Application>;
 
 	isCurrentCommit(commit: string) {
 		return commit === 'latest' || commit === 'current';
 	}
 
-	async getDeviceTypesWithSameArch(deviceTypeSlug: string) {
-		const deviceTypes = await this.getDeviceTypes();
-		const deviceType = _.find(deviceTypes, { slug: deviceTypeSlug });
-		if (!deviceType) {
-			throw new Error(`Device type "${deviceTypeSlug}" not found in API query`);
-		}
-		return _(deviceTypes).filter({ arch: deviceType.arch }).map('slug').value();
-	}
-
 	async getApplicationsWithSuccessfulBuilds(deviceTypeSlug: string) {
 		const balena = getBalenaSdk();
 
-		const deviceTypes = await this.getDeviceTypesWithSameArch(deviceTypeSlug);
-		// TODO: remove the explicit types once https://github.com/balena-io/balena-sdk/pull/889 gets merged
-		return balena.pine.get<
-			Application,
-			Array<
-				ApplicationWithDeviceType & {
-					should_be_running__release: [Release?];
-				}
-			>
-		>({
-			resource: 'my_application',
-			options: {
-				$filter: {
-					is_for__device_type: {
-						$any: {
-							$alias: 'dt',
-							$expr: {
-								dt: {
-									slug: { $in: deviceTypes },
-								},
-							},
-						},
-					},
-					owns__release: {
-						$any: {
-							$alias: 'r',
-							$expr: {
-								r: {
-									status: 'success',
+		try {
+			await balena.models.deviceType.get(deviceTypeSlug);
+		} catch {
+			throw new Error(`Device type "${deviceTypeSlug}" not found in API query`);
+		}
+		const options = {
+			$select: ['id', 'slug', 'should_track_latest_release'],
+			$expand: this.applicationExpandOptions,
+			$filter: {
+				// get the apps that are of the same arch as the device type of the image
+				is_for__device_type: {
+					$any: {
+						$alias: 'dt',
+						$expr: {
+							dt: {
+								is_of__cpu_architecture: {
+									$any: {
+										$alias: 'ioca',
+										$expr: {
+											ioca: {
+												is_supported_by__device_type: {
+													$any: {
+														$alias: 'isbdt',
+														$expr: {
+															isbdt: {
+																slug: deviceTypeSlug,
+															},
+														},
+													},
+												},
+											},
+										},
+									},
 								},
 							},
 						},
 					},
 				},
-				$expand: this.applicationExpandOptions,
-				$select: ['id', 'app_name', 'should_track_latest_release'],
-				$orderby: 'app_name asc',
+				owns__release: {
+					$any: {
+						$alias: 'r',
+						$expr: {
+							r: {
+								status: 'success',
+							},
+						},
+					},
+				},
 			},
-		});
+			$orderby: 'slug asc',
+		} satisfies PineOptions<Application>;
+		return (await balena.models.application.getAllDirectlyAccessible(
+			options,
+		)) as Array<PineTypedResult<Application, typeof options>>;
 	}
 
 	async selectApplication(deviceTypeSlug: string) {
@@ -439,7 +422,7 @@ Can be repeated to add multiple certificates.\
 			message: 'Select a fleet',
 			type: 'list',
 			choices: applications.map((app) => ({
-				name: app.app_name,
+				name: app.slug,
 				value: app,
 			})),
 		});
@@ -465,7 +448,7 @@ Can be repeated to add multiple certificates.\
 	}
 
 	async offerToDisableAutomaticUpdates(
-		application: Application,
+		application: Pick<Application, 'id' | 'should_track_latest_release'>,
 		commit: string,
 		pinDevice: boolean,
 	) {
@@ -514,28 +497,28 @@ Would you like to disable automatic updates for this fleet now?\
 		});
 	}
 
-	async getAppWithReleases(balenaSdk: BalenaSDK, appId: string | number) {
+	async getAppWithReleases(balenaSdk: BalenaSDK, slug: string) {
 		const { getApplication } = await import('../utils/sdk');
 
-		return (await getApplication(balenaSdk, appId, {
+		return await getApplication(balenaSdk, slug, {
 			$expand: this.applicationExpandOptions,
-		})) as Application & { should_be_running__release: [Release?] };
+		});
 	}
 
 	async prepareAndPreload(
 		preloader: Preloader,
 		balenaSdk: BalenaSDK,
 		options: {
-			appId?: string;
+			slug?: string;
 			commit?: string;
 			pinDevice: boolean;
 		},
 	) {
 		await preloader.prepare();
 
-		const application = options.appId
-			? await this.getAppWithReleases(balenaSdk, options.appId)
-			: await this.selectApplication(preloader.config.deviceType);
+		const application = options.slug
+			? await this.getAppWithReleases(balenaSdk, options.slug)
+			: await this.selectApplication(preloader.config!.deviceType);
 
 		let commit: string; // commit hash or the strings 'latest' or 'current'
 
@@ -546,7 +529,7 @@ Would you like to disable automatic updates for this fleet now?\
 			if (this.isCurrentCommit(options.commit)) {
 				if (!appCommit) {
 					throw new Error(
-						`Unexpected empty commit hash for fleet ID "${application.id}"`,
+						`Unexpected empty commit hash for fleet slug "${application.slug}"`,
 					);
 				}
 				// handle `--commit current` (and its `--commit latest` synonym)

lib/commands/push.ts

@@ -22,8 +22,7 @@ import { getBalenaSdk, stripIndent } from '../utils/lazy';
 import { dockerignoreHelp, registrySecretsHelp } from '../utils/messages';
 import type { BalenaSDK } from 'balena-sdk';
 import { ExpectedError, instanceOf } from '../errors';
-import { isV13 } from '../utils/version';
-import { RegistrySecrets } from 'resin-multibuild';
+import { RegistrySecrets } from '@balena/compose/dist/multibuild';
 import { lowercaseIfSlug } from '../utils/normalization';
 import {
 	applyReleaseTagKeysAndValues,
@@ -47,17 +46,16 @@ interface FlagsDef {
 	pull: boolean;
 	'noparent-check': boolean;
 	'registry-secrets'?: string;
-	gitignore?: boolean;
-	nogitignore?: boolean;
 	nolive: boolean;
 	detached: boolean;
 	service?: string[];
 	system: boolean;
 	env?: string[];
-	'convert-eol'?: boolean;
 	'noconvert-eol': boolean;
 	'multi-dockerignore': boolean;
 	'release-tag'?: string[];
+	draft: boolean;
+	note?: string;
 	help: void;
 }
 
@@ -100,6 +98,7 @@ export default class PushCmd extends Command {
 		'$ balena push myFleet',
 		'$ balena push myFleet --source <source directory>',
 		'$ balena push myFleet -s <source directory>',
+		'$ balena push myFleet --source <source directory> --note "this is the note for this release"',
 		'$ balena push myFleet --release-tag key1 "" key2 "value2 with spaces"',
 		'$ balena push myorg/myfleet',
 		'',
@@ -179,7 +178,7 @@ export default class PushCmd extends Command {
 			description: stripIndent`
 				Don't run a live session on this push. The filesystem will not be monitored,
 				and changes will not be synchronized to any running containers. Note that both
-				this flag and --detached and required to cause the process to end once the
+				this flag and --detached are required to cause the process to end once the
 				initial build has completed.`,
 			default: false,
 		}),
@@ -217,16 +216,6 @@ export default class PushCmd extends Command {
 			`,
 			multiple: true,
 		}),
-		...(isV13()
-			? {}
-			: {
-					'convert-eol': flags.boolean({
-						description: 'No-op and deprecated since balena CLI v12.0.0',
-						char: 'l',
-						hidden: true,
-						default: false,
-					}),
-			  }),
 		'noconvert-eol': flags.boolean({
 			description: `Don't convert line endings from CRLF (Windows format) to LF (Unix format).`,
 			default: false,
@@ -236,27 +225,6 @@ export default class PushCmd extends Command {
 				'Have each service use its own .dockerignore file. See "balena help push".',
 			char: 'm',
 			default: false,
-			exclusive: ['gitignore'],
-		}),
-		...(isV13()
-			? {}
-			: {
-					nogitignore: flags.boolean({
-						description:
-							'No-op (default behavior) since balena CLI v12.0.0. See "balena help push".',
-						char: 'G',
-						hidden: true,
-						default: false,
-					}),
-			  }),
-		gitignore: flags.boolean({
-			description: stripIndent`
-		Consider .gitignore files in addition to the .dockerignore file. This reverts
-		to the CLI v11 behavior/implementation (deprecated) if compatibility is
-		required until your project can be adapted.`,
-			char: 'g',
-			default: false,
-			exclusive: ['multi-dockerignore'],
 		}),
 		'release-tag': flags.string({
 			description: stripIndent`
@@ -267,6 +235,15 @@ export default class PushCmd extends Command {
 			multiple: true,
 			exclusive: ['detached'],
 		}),
+		draft: flags.boolean({
+			description: stripIndent`
+				Instruct the builder to create the release as a draft. Draft releases are ignored
+				by the 'track latest' release policy but can be used through release pinning.
+				Draft releases can be marked as final through the API. Releases are created
+				as final by default unless this option is given.`,
+			default: false,
+		}),
+		note: flags.string({ description: 'The notes for this release' }),
 		help: cf.help,
 	};
 
@@ -351,7 +328,7 @@ export default class PushCmd extends Command {
 		]);
 
 		const application = await getApplication(sdk, appNameOrSlug, {
-			$select: ['app_name', 'slug'],
+			$select: 'slug',
 		});
 
 		const opts = {
@@ -362,13 +339,13 @@ export default class PushCmd extends Command {
 			registrySecrets,
 			headless: options.detached,
 			convertEol: !options['noconvert-eol'],
+			isDraft: options.draft,
 		};
 		const args = {
 			appSlug: application.slug,
 			source: options.source,
 			auth: token,
 			baseUrl,
-			nogitignore: !options.gitignore,
 			sdk,
 			opts,
 		};
@@ -380,6 +357,9 @@ export default class PushCmd extends Command {
 				releaseTagKeys,
 				releaseTagValues,
 			);
+			if (options.note) {
+				await sdk.models.release.setNote(releaseId, options.note);
+			}
 		} else if (releaseTagKeys.length > 0) {
 			throw new Error(stripIndent`
 				A release ID could not be parsed out of the builder's output.
@@ -394,7 +374,7 @@ export default class PushCmd extends Command {
 		registrySecrets: RegistrySecrets,
 	) {
 		// Check for invalid options
-		const remoteOnlyOptions: Array<keyof FlagsDef> = ['release-tag'];
+		const remoteOnlyOptions: Array<keyof FlagsDef> = ['release-tag', 'draft'];
 		this.checkInvalidOptions(
 			remoteOnlyOptions,
 			options,
@@ -412,7 +392,6 @@ export default class PushCmd extends Command {
 				multiDockerignore: options['multi-dockerignore'],
 				nocache: options.nocache,
 				pull: options.pull,
-				nogitignore: !options.gitignore,
 				noParentCheck: options['noparent-check'],
 				nolive: options.nolive,
 				detached: options.detached,

lib/commands/release/finalize.ts

@@ -0,0 +1,86 @@
+/**
+ * @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 {
+	commitOrId: string | number;
+}
+
+export default class ReleaseFinalizeCmd extends Command {
+	public static description = stripIndent`
+		Finalize a release.
+
+		Finalize a release. Releases can be "draft" or "final", and this command
+		changes a draft release into a final release. Draft releases can be created
+		with the \`--draft\` option of the \`balena build\` or \`balena deploy\`
+		commands.
+
+		Draft releases are not automatically deployed to devices tracking the latest
+		release. For a draft release to be deployed to a device, the device should be
+		explicity pinned to that release. Conversely, final releases may trigger immediate
+		deployment to unpinned devices (subject to a device's  polling period) and, for
+		this reason, final releases cannot be changed back to draft status.
+`;
+	public static examples = [
+		'$ balena release finalize a777f7345fe3d655c1c981aa642e5555',
+		'$ balena release finalize 1234567',
+	];
+
+	public static usage = 'release finalize <commitOrId>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static args = [
+		{
+			name: 'commitOrId',
+			description: 'the commit or ID of the release to finalize',
+			required: true,
+			parse: (commitOrId: string) => tryAsInteger(commitOrId),
+		},
+	];
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(ReleaseFinalizeCmd);
+
+		const balena = getBalenaSdk();
+
+		const release = await balena.models.release.get(params.commitOrId, {
+			$select: ['id', 'is_final'],
+		});
+
+		if (release.is_final) {
+			console.log(`Release ${params.commitOrId} is already finalized!`);
+			return;
+		}
+
+		await balena.models.release.finalize(release.id);
+		console.log(`Release ${params.commitOrId} finalized`);
+	}
+}

lib/commands/release/index.ts

@@ -0,0 +1,128 @@
+/**
+ * @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 * as BalenaSdk from 'balena-sdk';
+import jsyaml = require('js-yaml');
+import { tryAsInteger } from '../../utils/validation';
+
+interface FlagsDef {
+	help: void;
+	composition?: boolean;
+}
+
+interface ArgsDef {
+	commitOrId: string | number;
+}
+
+export default class ReleaseCmd extends Command {
+	public static description = stripIndent`
+		Get info for a release.
+`;
+	public static examples = [
+		'$ balena release a777f7345fe3d655c1c981aa642e5555',
+		'$ balena release 1234567',
+	];
+
+	public static usage = 'release <commitOrId>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+		composition: flags.boolean({
+			default: false,
+			char: 'c',
+			description: 'Return the release composition',
+		}),
+	};
+
+	public static args = [
+		{
+			name: 'commitOrId',
+			description: 'the commit or ID of the release to get information',
+			required: true,
+			parse: (commitOrId: string) => tryAsInteger(commitOrId),
+		},
+	];
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
+			ReleaseCmd,
+		);
+
+		const balena = getBalenaSdk();
+		if (options.composition) {
+			await this.showComposition(params.commitOrId, balena);
+		} else {
+			await this.showReleaseInfo(params.commitOrId, balena);
+		}
+	}
+
+	async showComposition(
+		commitOrId: string | number,
+		balena: BalenaSdk.BalenaSDK,
+	) {
+		const release = await balena.models.release.get(commitOrId, {
+			$select: 'composition',
+		});
+
+		console.log(jsyaml.dump(release.composition));
+	}
+
+	async showReleaseInfo(
+		commitOrId: string | number,
+		balena: BalenaSdk.BalenaSDK,
+	) {
+		const fields: Array<keyof BalenaSdk.Release> = [
+			'id',
+			'commit',
+			'created_at',
+			'status',
+			'semver',
+			'is_final',
+			'build_log',
+			'start_timestamp',
+			'end_timestamp',
+		];
+
+		const release = await balena.models.release.get(commitOrId, {
+			$select: fields,
+			$expand: {
+				release_tag: {
+					$select: ['tag_key', 'value'],
+				},
+			},
+		});
+
+		const tagStr = release
+			.release_tag!.map((t) => `${t.tag_key}=${t.value}`)
+			.join('\n');
+
+		const _ = await import('lodash');
+		const values = _.mapValues(
+			release,
+			(val) => val ?? 'N/a',
+		) as Dictionary<string>;
+		values['tags'] = tagStr;
+
+		console.log(getVisuals().table.vertical(values, [...fields, 'tags']));
+	}
+}

lib/commands/release/invalidate.ts

@@ -0,0 +1,83 @@
+/**
+ * @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 {
+	commitOrId: string | number;
+}
+
+export default class ReleaseInvalidateCmd extends Command {
+	public static description = stripIndent`
+		Invalidate a release.
+
+		Invalidate a release.
+
+		Invalid releases are not automatically deployed to devices tracking the latest
+		release. For an invalid release to be deployed to a device, the device should be
+		explicity pinned to that release.
+`;
+	public static examples = [
+		'$ balena release invalidate a777f7345fe3d655c1c981aa642e5555',
+		'$ balena release invalidate 1234567',
+	];
+
+	public static usage = 'release invalidate <commitOrId>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static args = [
+		{
+			name: 'commitOrId',
+			description: 'the commit or ID of the release to invalidate',
+			required: true,
+			parse: (commitOrId: string) => tryAsInteger(commitOrId),
+		},
+	];
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(
+			ReleaseInvalidateCmd,
+		);
+
+		const balena = getBalenaSdk();
+
+		const release = await balena.models.release.get(params.commitOrId, {
+			$select: ['id', 'is_invalidated'],
+		});
+
+		if (release.is_invalidated) {
+			console.log(`Release ${params.commitOrId} is already invalidated!`);
+			return;
+		}
+
+		await balena.models.release.setIsInvalidated(release.id, true);
+		console.log(`Release ${params.commitOrId} invalidated`);
+	}
+}

lib/commands/release/validate.ts

@@ -0,0 +1,80 @@
+/**
+ * @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 {
+	commitOrId: string | number;
+}
+
+export default class ReleaseValidateCmd extends Command {
+	public static description = stripIndent`
+		Validate a release.
+
+		Validate a release.
+
+		Valid releases are automatically deployed to devices tracking the latest
+		release if they are finalized.
+`;
+	public static examples = [
+		'$ balena release validate a777f7345fe3d655c1c981aa642e5555',
+		'$ balena release validate 1234567',
+	];
+
+	public static usage = 'release validate <commitOrId>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static args = [
+		{
+			name: 'commitOrId',
+			description: 'the commit or ID of the release to validate',
+			required: true,
+			parse: (commitOrId: string) => tryAsInteger(commitOrId),
+		},
+	];
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(ReleaseValidateCmd);
+
+		const balena = getBalenaSdk();
+
+		const release = await balena.models.release.get(params.commitOrId, {
+			$select: ['id', 'is_invalidated'],
+		});
+
+		if (!release.is_invalidated) {
+			console.log(`Release ${params.commitOrId} is already validated!`);
+			return;
+		}
+
+		await balena.models.release.setIsInvalidated(release.id, false);
+		console.log(`Release ${params.commitOrId} validated`);
+	}
+}

lib/commands/releases.ts

@@ -0,0 +1,87 @@
+/**
+ * @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 { applicationNameNote } from '../utils/messages';
+import type * as BalenaSdk from 'balena-sdk';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	fleet: string;
+}
+
+export default class ReleasesCmd extends Command {
+	public static description = stripIndent`
+		List all releases of a fleet.
+
+		List all releases of the given fleet.
+
+		${applicationNameNote.split('\n').join('\n\t\t')}
+`;
+	public static examples = ['$ balena releases myorg/myfleet'];
+
+	public static usage = 'releases <fleet>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static args = [
+		{
+			name: 'fleet',
+			description: 'fleet name or slug (preferred)',
+			required: true,
+		},
+	];
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(ReleasesCmd);
+
+		const fields: Array<keyof BalenaSdk.Release> = [
+			'id',
+			'commit',
+			'created_at',
+			'status',
+			'semver',
+			'is_final',
+		];
+
+		const balena = getBalenaSdk();
+		const { getFleetSlug } = await import('../utils/sdk');
+
+		const releases = await balena.models.release.getAllByApplication(
+			await getFleetSlug(balena, params.fleet),
+			{ $select: fields },
+		);
+
+		const _ = await import('lodash');
+		console.log(
+			getVisuals().table.horizontal(
+				releases.map((rel) => _.mapValues(rel, (val) => val ?? 'N/a')),
+				fields,
+			),
+		);
+	}
+}

lib/commands/scan.ts

@@ -16,7 +16,6 @@
  */
 
 import { flags } from '@oclif/command';
-import type { LocalBalenaOsDevice } from 'balena-sync';
 import Command from '../command';
 import * as cf from '../utils/common-flags';
 import { getCliUx, stripIndent } from '../utils/lazy';
@@ -68,10 +67,11 @@ export default class ScanCmd extends Command {
 
 	public static primary = true;
 	public static root = true;
+	public static offlineCompatible = true;
 
 	public async run() {
 		const _ = await import('lodash');
-		const { discover } = await import('balena-sync');
+		const { discoverLocalBalenaOsDevices } = await import('../utils/discover');
 		const prettyjson = await import('prettyjson');
 		const dockerUtils = await import('../utils/docker');
 
@@ -87,8 +87,7 @@ export default class ScanCmd extends Command {
 		const ux = getCliUx();
 		ux.action.start('Scanning for local balenaOS devices');
 
-		const localDevices: LocalBalenaOsDevice[] =
-			await discover.discoverLocalBalenaOsDevices(discoverTimeout);
+		const localDevices = await discoverLocalBalenaOsDevices(discoverTimeout);
 		const engineReachableDevices: boolean[] = await Promise.all(
 			localDevices.map(async ({ address }: { address: string }) => {
 				const docker = await dockerUtils.createClient({
@@ -105,7 +104,7 @@ export default class ScanCmd extends Command {
 			}),
 		);
 
-		const developmentDevices: LocalBalenaOsDevice[] = localDevices.filter(
+		const developmentDevices = localDevices.filter(
 			(_localDevice, index) => engineReachableDevices[index],
 		);
 
@@ -115,18 +114,15 @@ export default class ScanCmd extends Command {
 			_.isEqual,
 		);
 
-		const productionDevicesInfo = _.map(
-			productionDevices,
-			(device: LocalBalenaOsDevice) => {
-				return {
-					host: device.host,
-					address: device.address,
-					osVariant: 'production',
-					dockerInfo: undefined,
-					dockerVersion: undefined,
-				};
-			},
-		);
+		const productionDevicesInfo = productionDevices.map((device) => {
+			return {
+				host: device.host,
+				address: device.address,
+				osVariant: 'production',
+				dockerInfo: undefined,
+				dockerVersion: undefined,
+			};
+		});
 
 		// Query devices for info
 		const devicesInfo = await Promise.all(

lib/commands/ssh.ts

@@ -20,7 +20,6 @@ import Command from '../command';
 import * as cf from '../utils/common-flags';
 import { getBalenaSdk, stripIndent } from '../utils/lazy';
 import { parseAsInteger, validateLocalHostnameOrIp } from '../utils/validation';
-import * as BalenaSdk from 'balena-sdk';
 
 interface FlagsDef {
 	port?: number;
@@ -77,8 +76,7 @@ export default class SshCmd extends Command {
 	public static args = [
 		{
 			name: 'fleetOrDevice',
-			description:
-				'fleet name/slug/id, device uuid, or address of local device',
+			description: 'fleet name/slug, device uuid, or address of local device',
 			required: true,
 		},
 		{
@@ -117,6 +115,7 @@ export default class SshCmd extends Command {
 	};
 
 	public static primary = true;
+	public static offlineCompatible = true;
 
 	public async run() {
 		const { args: params, flags: options } = this.parse<FlagsDef, ArgsDef>(
@@ -127,8 +126,8 @@ export default class SshCmd extends Command {
 		if (validateLocalHostnameOrIp(params.fleetOrDevice)) {
 			const { performLocalDeviceSSH } = await import('../utils/device/ssh');
 			return await performLocalDeviceSSH({
-				address: params.fleetOrDevice,
-				port: options.port,
+				hostname: params.fleetOrDevice,
+				port: options.port || 'local',
 				forceTTY: options.tty,
 				verbose: options.verbose,
 				service: params.service,
@@ -144,18 +143,13 @@ export default class SshCmd extends Command {
 		const useProxy = !!proxyConfig && !options.noproxy;
 
 		// this will be a tunnelled SSH connection...
+		await Command.checkNotUsingOfflineMode();
 		await Command.checkLoggedIn();
 		const deviceUuid = await getOnlineTargetDeviceUuid(
 			sdk,
 			params.fleetOrDevice,
 		);
 
-		const device = await sdk.models.device.get(deviceUuid, {
-			$select: ['id', 'supervisor_version', 'is_online'],
-		});
-
-		const deviceId = device.id;
-		const supervisorVersion = device.supervisor_version;
 		const { which } = await import('../utils/which');
 
 		const [whichProxytunnel, username, proxyUrl] = await Promise.all([
@@ -207,19 +201,15 @@ export default class SshCmd extends Command {
 		// that we know exists and is accessible
 		let containerId: string | undefined;
 		if (params.service != null) {
-			containerId = await this.getContainerId(
-				sdk,
+			const { getContainerIdForService } = await import('../utils/device/ssh');
+			containerId = await getContainerIdForService({
 				deviceUuid,
-				params.service,
-				{
-					port: options.port,
-					proxyCommand,
-					proxyUrl: proxyUrl || '',
-					username: username!,
-				},
-				supervisorVersion,
-				deviceId,
-			);
+				hostname: `ssh.${proxyUrl}`,
+				port: options.port || 'cloud',
+				proxyCommand,
+				service: params.service,
+				username: username!,
+			});
 		}
 
 		let accessCommand: string;
@@ -228,158 +218,14 @@ export default class SshCmd extends Command {
 		} else {
 			accessCommand = `host ${deviceUuid}`;
 		}
-
-		const command = this.generateVpnSshCommand({
-			uuid: deviceUuid,
-			command: accessCommand,
-			verbose: options.verbose,
-			port: options.port,
+		const { runRemoteCommand } = await import('../utils/ssh');
+		await runRemoteCommand({
+			cmd: accessCommand,
+			hostname: `ssh.${proxyUrl}`,
+			port: options.port || 'cloud',
 			proxyCommand,
-			proxyUrl: proxyUrl || '',
-			username: username!,
+			username,
+			verbose: options.verbose,
 		});
-
-		const { spawnSshAndThrowOnError } = await import('../utils/ssh');
-		return spawnSshAndThrowOnError(command);
-	}
-
-	async getContainerId(
-		sdk: BalenaSdk.BalenaSDK,
-		uuid: string,
-		serviceName: string,
-		sshOpts: {
-			port?: number;
-			proxyCommand?: string[];
-			proxyUrl: string;
-			username: string;
-		},
-		version?: string,
-		id?: number,
-	): Promise<string> {
-		const semver = await import('balena-semver');
-
-		if (version == null || id == null) {
-			const device = await sdk.models.device.get(uuid, {
-				$select: ['id', 'supervisor_version'],
-			});
-			version = device.supervisor_version;
-			id = device.id;
-		}
-
-		let containerId: string | undefined;
-		if (semver.gte(version, '8.6.0')) {
-			const apiUrl = await sdk.settings.get('apiUrl');
-			// TODO: Move this into the SDKs device model
-			const request = await sdk.request.send({
-				method: 'POST',
-				url: '/supervisor/v2/containerId',
-				baseUrl: apiUrl,
-				body: {
-					method: 'GET',
-					deviceId: id,
-				},
-			});
-			if (request.status !== 200) {
-				throw new Error(
-					`There was an error connecting to device ${uuid}, HTTP response code: ${request.status}.`,
-				);
-			}
-			const body = request.body;
-			if (body.status !== 'success') {
-				throw new Error(
-					`There was an error communicating with device ${uuid}.\n\tError: ${body.message}`,
-				);
-			}
-			containerId = body.services[serviceName];
-		} else {
-			console.error(stripIndent`
-			Using legacy method to detect container ID. This will be slow.
-			To speed up this process, please update your device to an OS
-			which has a supervisor version of at least v8.6.0.
-		`);
-			// We need to execute a balena ps command on the device,
-			// and parse the output, looking for a specific
-			// container
-			const childProcess = await import('child_process');
-			const { escapeRegExp } = await import('lodash');
-			const { which } = await import('../utils/which');
-			const { deviceContainerEngineBinary } = await import(
-				'../utils/device/ssh'
-			);
-
-			const sshBinary = await which('ssh');
-			const sshArgs = this.generateVpnSshCommand({
-				uuid,
-				verbose: false,
-				port: sshOpts.port,
-				command: `host ${uuid} "${deviceContainerEngineBinary}" ps --format "{{.ID}} {{.Names}}"`,
-				proxyCommand: sshOpts.proxyCommand,
-				proxyUrl: sshOpts.proxyUrl,
-				username: sshOpts.username,
-			});
-
-			if (process.env.DEBUG) {
-				console.error(`[debug] [${sshBinary}, ${sshArgs.join(', ')}]`);
-			}
-			const subProcess = childProcess.spawn(sshBinary, sshArgs, {
-				stdio: [null, 'pipe', null],
-			});
-			const containers = await new Promise<string>((resolve, reject) => {
-				const output: string[] = [];
-				subProcess.stdout.on('data', (chunk) => output.push(chunk.toString()));
-				subProcess.on('close', (code: number) => {
-					if (code !== 0) {
-						reject(
-							new Error(
-								`Non-zero error code when looking for service container: ${code}`,
-							),
-						);
-					} else {
-						resolve(output.join(''));
-					}
-				});
-			});
-
-			const lines = containers.split('\n');
-			const regex = new RegExp(`\\/?${escapeRegExp(serviceName)}_\\d+_\\d+`);
-			for (const container of lines) {
-				const [cId, name] = container.split(' ');
-				if (regex.test(name)) {
-					containerId = cId;
-					break;
-				}
-			}
-		}
-
-		if (containerId == null) {
-			throw new Error(
-				`Could not find a service ${serviceName} on device ${uuid}.`,
-			);
-		}
-		return containerId;
-	}
-
-	generateVpnSshCommand(opts: {
-		uuid: string;
-		command: string;
-		verbose: boolean;
-		port?: number;
-		username: string;
-		proxyUrl: string;
-		proxyCommand?: string[];
-	}) {
-		return [
-			...(opts.verbose ? ['-vvv'] : []),
-			'-t',
-			...['-o', 'LogLevel=ERROR'],
-			...['-o', 'StrictHostKeyChecking=no'],
-			...['-o', 'UserKnownHostsFile=/dev/null'],
-			...(opts.proxyCommand && opts.proxyCommand.length
-				? ['-o', `ProxyCommand=${opts.proxyCommand.join(' ')}`]
-				: []),
-			...(opts.port ? ['-p', opts.port.toString()] : []),
-			`${opts.username}@ssh.${opts.proxyUrl}`,
-			opts.command,
-		];
 	}
 }