From b1897a512d42ce2fe3fec859cd375524637f8fce Mon Sep 17 00:00:00 2001 From: Paulo Castro Date: Fri, 18 Sep 2020 15:35:36 +0100 Subject: [PATCH] Style "balena CLI" as "balenaCLI" and "balena cloud" as "balenaCloud" Change-type: patch --- .github/ISSUE_TEMPLATE.md | 8 +-- CONTRIBUTING.md | 2 +- INSTALL-LINUX.md | 8 ++- INSTALL-MAC.md | 4 +- INSTALL-WINDOWS.md | 4 +- README.md | 57 ++++++++--------- TROUBLESHOOTING.md | 70 +++++++++----------- automation/capitanodoc/capitanodoc.ts | 6 +- automation/capitanodoc/utils.ts | 2 +- doc/cli.markdown | 92 +++++++++++++-------------- lib/actions-oclif/envs.ts | 2 +- lib/actions-oclif/os/configure.ts | 6 +- lib/actions-oclif/push.ts | 9 ++- lib/actions-oclif/settings.ts | 2 +- lib/actions-oclif/version.ts | 4 +- lib/auth/index.ts | 2 +- lib/auth/pages/error.ejs | 4 +- lib/auth/pages/success.ejs | 4 +- lib/events.ts | 2 +- lib/utils/compose.js | 6 +- lib/utils/compose_ts.ts | 6 +- lib/utils/helpers.ts | 2 +- lib/utils/messages.ts | 4 +- lib/utils/remote-build.ts | 2 +- lib/utils/sudo.ts | 2 +- package.json | 2 +- tests/commands/help.spec.ts | 4 +- 27 files changed, 155 insertions(+), 161 deletions(-) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 3049f086..876eee61 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,7 +1,7 @@ # About this issue tracker -*The balena CLI (Command Line Interface) is a tool used to interact with the balena platform. +*balenaCLI (Command Line Interface) is a tool used to interact with the balena platform. This GitHub issue tracker is used for bug reports and feature requests regarding the CLI tool. General and troubleshooting questions (such as setting up your project to work with a balenalib base image) are encouraged to be posted to the [balena @@ -11,8 +11,8 @@ community can both contribute and benefit from the answers.* *Please also check that this issue is not a duplicate. If there is another issue describing the same problem or feature please add comments to the existing issue.* -*Thank you for your time and effort creating the issue report, and helping us improve the -balena CLI!* +*Thank you for your time and effort creating the issue report, and helping us improve +balenaCLI!* --- @@ -63,7 +63,7 @@ fixed it. # Specifications -- **balena CLI version:** e.g. 1.2.3 (output of the `"balena version -a"` command) +- **balenaCLI version:** e.g. 1.2.3 (output of the `"balena version -a"` command) - **Cloud backend: openBalena or balenaCloud?** If unsure, it will be balenaCloud - **Operating system version:** e.g. Windows 10, Ubuntu 18.04, macOS 10.14.5 - **32/64 bit OS and processor:** e.g. 32-bit Windows on 64-bit Intel processor diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9cc60e8b..02c8139d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -The balena CLI is an open source project and your contribution is welcome! +balenaCLI is an open source project and your contribution is welcome! * Install the dependencies listed in the [NPM Installation](./INSTALL.md#npm-installation) section of the `INSTALL.md` file. Check the section [Additional diff --git a/INSTALL-LINUX.md b/INSTALL-LINUX.md index 90e3bcf6..d9d3e4e2 100644 --- a/INSTALL-LINUX.md +++ b/INSTALL-LINUX.md @@ -15,7 +15,13 @@ Selected operating system: **Linux** `balena-cli` folder. 3. Add the `balena-cli` folder to the system's `PATH` environment variable. There are several - ways of achieving this on Linux: See this [StackOverflow post](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix). + ways of achieving this on Linux: See this [StackOverflow post](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix). Close and reopen the terminal window + so that the changes to PATH can take effect. + +4. Check that the installation was successful by running the following commands on a + command terminal: + * `balena version` - should print balenaCLI's version + * `balena help` - should print a list of available commands No further steps are required to run most balenaCLI commands. The `balena ssh`, `scan`, `build`, `deploy` and `preload` commands may require additional software to be installed, as described diff --git a/INSTALL-MAC.md b/INSTALL-MAC.md index 00888599..00ab6f5d 100644 --- a/INSTALL-MAC.md +++ b/INSTALL-MAC.md @@ -18,8 +18,8 @@ Selected operating system: **macOS** 3. Check that the installation was successful by running the following commands on a command terminal: - * `balena version` - should print the installed CLI version - * `balena help` - should print the balenaCLI help + * `balena version` - should print balenaCLI's version + * `balena help` - should print a list of available commands No further steps are required to run most balenaCLI commands. The `balena ssh`, `build`, `deploy` and `preload` commands may require additional software to be installed, as described below. diff --git a/INSTALL-WINDOWS.md b/INSTALL-WINDOWS.md index 2ffff701..fe1c82f9 100644 --- a/INSTALL-WINDOWS.md +++ b/INSTALL-WINDOWS.md @@ -18,8 +18,8 @@ Selected operating system: **Windows** 3. Check that the installation was successful by running the following commands on a command terminal: - * `balena version` - should print the installed CLI version - * `balena help` - should print the balenaCLI help + * `balena version` - should print balenaCLI's version + * `balena help` - should print a list of available commands No further steps are required to run most balenaCLI commands. The `balena ssh`, `scan`, `build`, `deploy`, `preload` and `os configure` commands may require additional software to be installed, as diff --git a/README.md b/README.md index bfb21ce1..72336b15 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,30 @@ -# balena CLI +# balenaCLI -The official balena CLI tool. +The official balena Command Line Interface. [![npm version](https://badge.fury.io/js/balena-cli.svg)](http://badge.fury.io/js/balena-cli) [![dependencies](https://david-dm.org/balena-io/balena-cli.svg)](https://david-dm.org/balena-io/balena-cli) ## About -The balena CLI (Command-Line Interface) allows you to interact with the balenaCloud and the -[balena API](https://www.balena.io/docs/reference/api/overview/) through a terminal window -on Linux, macOS or Windows. You can also write shell scripts around it, or import its Node.js -modules to use it programmatically. -As an [open-source project on GitHub](https://github.com/balena-io/balena-cli/), your contribution -is also welcome! +balenaCLI is a Command Line Interface for [balenaCloud](https://www.balena.io/cloud/) or +[openBalena](https://www.balena.io/open/). It is a software tool available for Windows, macOS and +Linux, used through a command prompt / terminal window. It can be used interactively or invoked in +scripts. balenaCLI builds on the [balena API](https://www.balena.io/docs/reference/api/overview/) +and the [balena SDK](https://www.balena.io/docs/reference/sdk/node-sdk/), and can also be directly +imported in Node.js applications. balenaCLI is an [open-source project on +GitHub](https://github.com/balena-io/balena-cli/), and your contribution is also welcome! ## Installation -Check the [balena CLI installation instructions on GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md). +Check the [balenaCLI installation instructions on +GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md). -## Getting Started - -### Choosing a shell (command prompt/terminal) +## Choosing a shell (command prompt/terminal) On **Windows,** the standard Command Prompt (`cmd.exe`) and [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6) -are supported. We are aware of users also having a good experience with alternative shells, -including: +are supported. Alternative shells include: * [MSYS2](https://www.msys2.org/): * Install additional packages with the command: @@ -43,17 +42,17 @@ including: [comment](https://github.com/balena-io/balena-cli/issues/598#issuecomment-556513098). * Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL). In this case, a Linux distribution like Ubuntu is installed via the Microsoft Store, and a - balena CLI release **for Linux** is recommended. See - [FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using balena - CLI with WSL and Docker Desktop for Windows. + balenaCLI release **for Linux** should be selected. See + [FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using balenaCLI + with WSL and Docker Desktop for Windows. -On **macOS** and **Linux,** the standard terminal window is supported. _Optionally,_ `bash` command +On **macOS** and **Linux,** the standard terminal window is supported. Optionally, `bash` command auto completion may be enabled by copying the [balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash) file to your system's `bash_completion` directory: check [Docker's command completion guide](https://docs.docker.com/compose/completion/) for system setup instructions. -### Logging in +## Logging in Several CLI commands require access to your balenaCloud account, for example in order to push a new release to your application. Those commands require creating a CLI login session by running: @@ -62,7 +61,7 @@ new release to your application. Those commands require creating a CLI login ses $ balena login ``` -### Proxy support +## Proxy support HTTP(S) proxies can be configured through any of the following methods, in precedence order (from higher to lower): @@ -88,7 +87,7 @@ HTTP(S) proxies can be configured through any of the following methods, in prece * The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as `BALENARC_PROXY`. -#### Proxy setup for balena ssh +### Proxy setup for balena ssh In order to work behind a proxy server, the `balena ssh` command requires the [`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) to be installed. @@ -103,11 +102,11 @@ server, it should be configured with the following rules in the `squid.conf` fil `acl SSL_ports port 22` `acl Safe_ports port 22` -#### Proxy exclusion +### Proxy exclusion The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations from proxying. -> * This feature requires balena CLI version 11.30.8 or later. In the case of the npm [installation +> * This feature requires balenaCLI version 11.30.8 or later. In the case of the npm [installation > option](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md), it also requires > Node.js version 10.16.0 or later. > * To exclude a `balena ssh` target from proxying (IP address or `.local` hostname), the @@ -136,7 +135,7 @@ address like `192.168.1.2`. ## Command reference documentation The full CLI command reference is available [on the web](https://www.balena.io/docs/reference/cli/ -) or by running `balena help` and `balena help --verbose`. +) or by running `balena help --verbose`. ## Support, FAQ and troubleshooting @@ -149,19 +148,19 @@ If you come across any problems or would like to get in touch: ## Deprecation policy -The balena CLI uses [semver versioning](https://semver.org/), with the concepts +balenaCLI uses [semver versioning](https://semver.org/), with the concepts of major, minor and patch version releases. -The latest release of the previous major version of the balena CLI will remain -compatible with the balenaCloud backend services for one year from the date when -the next major version is released. For example, balena CLI v10.17.5, as the +The latest release of a major version of balenaCLI 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, balenaCLI v10.17.5, as the latest v10 release, would remain compatible with the balenaCloud backend for one year from the date when v11.0.0 is released. At the end of this period, the older major version is considered deprecated and some of the functionality that depends on balenaCloud services may stop working at any time. -Users are encouraged to regularly update the balena CLI to the latest version. +Users are encouraged to regularly update balenaCLI to the latest version. ## Contributing (including editing documentation files) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index a17c6e45..314e4105 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -1,62 +1,50 @@ -# FAQ & Troubleshooting +# balenaCLI FAQ & Troubleshooting -This document contains some common issues, questions and answers related to the balena CLI. - -## Where is my configuration file? +## Where is balenaCLI's configuration file located? The per-user configuration file lives in `$HOME/.balenarc.yml` or `%UserProfile%\_balenarc.yml`, in Unix based operating systems and Windows respectively. -The balena CLI also attempts to read a `balenarc.yml` file in the current directory, which takes +balenaCLI also attempts to read a `balenarc.yml` file in the current directory, which takes precedence over the per-user configuration file. -## How do I point the balena CLI to staging? +## How do I point balenaCLI to the staging environment? -The easiest way is to set the `BALENARC_BALENA_URL=balena-staging.com` environment variable. +Set the `BALENARC_BALENA_URL=balena-staging.com` environment variable, or add +`balenaUrl: balena-staging.com` to balenaCLI's configuration file. -Alternatively, you can edit your configuration file and set `balenaUrl: balena-staging.com` to -persist this setting. +## How do I make balenaCLI persist data in another directory? -## How do I make the balena CLI persist data in another directory? +balenaCLI persists the session token, as well as cached assets, to `$HOME/.balena` or +`%UserProfile%\_balena`. This directory can be changed by setting an environment variable, +`BALENARC_DATA_DIRECTORY=/opt/balena`, or by adding `dataDirectory: /opt/balena` to balenaCLI's +configuration file, replacing `/opt/balena` with the desired directory. -The balena CLI persists your session token, as well as cached images in `$HOME/.balena` or -`%UserProfile%\_balena`. +## After burning to an SD card, my device doesn't boot -Pointing the balena CLI to persist data in another location is necessary in certain environments, -like a server, where there is no home directory, or a device running balenaOS, which erases all -data after a restart. +Check whether the downloaded image is incomplete (download was interrupted) or corrupted. -You can accomplish this by setting `BALENARC_DATA_DIRECTORY=/opt/balena` or adding `dataDirectory: -/opt/balena` to your configuration file, replacing `/opt/balena` with your desired directory. +Try clearing the cache (`%HOME/.balena/cache` or `C:\Users\\_balena\cache`) and running the +command again. -## After burning to an sdcard, my device doesn't boot +## I get a permission error when burning to an SD card -- The downloaded image is not complete (download was interrupted). +Check whether the SD card is locked (a physical switch on the side of the card). -Please clean the cache (`%HOME/.balena/cache` or `C:\Users\\_balena\cache`) and run the command again. In the future, the CLI will check that the image is not complete and clean the cache for you. +## I get EINVAL errors on Cygwin -## I get a permission error when burning to an sdcard - -- The SDCard is locked. - -### I get EINVAL errors on Cygwin - -The errors look something like this: +The errors may look something like this: ``` net.js:156 this._handle.open(options.fd); ^ Error: EINVAL, invalid argument - at new Socket (net.js:156:18) - at process.stdin (node.js:664:19) - at Object.Interface.createInterface (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\node_modules\readline2\index.js:31:43) - at PromptUI.UI (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\lib\ui\baseUI.js:23:40) - at new PromptUI (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\lib\ui\prompt.js:26:8) - at Object.promptModule [as prompt] (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\lib\inquirer.js:27:14) ``` -- Some interactive widgets don't work on `Cygwin`. If you're running Windows, it's preferrable that you use `cmd.exe`, as `Cygwin` is [not official supported by Node.js](https://github.com/chjj/blessed/issues/56#issuecomment-42671945). +Some interactive widgets don't work on `Cygwin`. On Windows, PowerShell or `cmd.exe` are better +supported. Alternative shells are [listed in the README +file](./README.md#choosing-a-shell-command-promptterminal). ## I get `Invalid MBR boot signature` when configuring a device @@ -76,7 +64,9 @@ Or in Windows: ## I get `EACCES: permission denied` when logging in -The balena CLI stores the session token in `$HOME/.balena` or `C:\Users\\_balena` in UNIX based operating systems and Windows respectively. This error usually indicates that the user doesn't have permissions over that directory, which can happen if you ran the balena CLI as `root`, and thus the directory got owned by him. +balenaCLI stores the session token in `$HOME/.balena` or `C:\Users\\_balena` in UNIX based +operating systems and Windows respectively. This error usually indicates that the user doesn't have +permissions over that directory, which can happen if balenaCLI was executed as the `root` user. Try resetting the ownership by running: @@ -86,7 +76,7 @@ $ sudo chown -R $HOME/.balena ## Broken line wrapping / cursor behavior with `balena ssh` -Users sometimes come across broken line wrapping or cursor behavior in text terminals, for example when long command lines are typed in a `balena ssh` session, or when using text editors like `vim` or `nano`. This is not something specific to the balena CLI, being also a commonly reported issue with standard remote terminal tools like `ssh` or `telnet`. It is often a remote shell configuration issue (files like `/etc/profile`, `~/.bash_profile`, `~/.bash_login`, `~/.profile` and the like), including UTF-8 misconfiguration, the use of unsupported ASCII control characters in shell prompt formatting (e.g. the `$PS1` env var) or the output of tools or log files that use colored text. The issue can sometimes be fixed by resizing the client terminal window, or by running one or more of the following commands on the shell: +Users sometimes come across broken line wrapping or cursor behavior in text terminals, for example when long command lines are typed in a `balena ssh` session, or when using text editors like `vim` or `nano`. This is not something specific to balenaCLI, being also a commonly reported issue with standard remote terminal tools like `ssh` or `telnet`. It is often a remote shell configuration issue (files like `/etc/profile`, `~/.bash_profile`, `~/.bash_login`, `~/.profile` and the like), including UTF-8 misconfiguration, the use of unsupported ASCII control characters in shell prompt formatting (e.g. the `$PS1` env var) or the output of tools or log files that use colored text. The issue can sometimes be fixed by resizing the client terminal window, or by running one or more of the following commands on the shell: ```sh export TERMINAL=linux @@ -112,10 +102,10 @@ If nothing seems to help, consider also using a different client-side terminal a ## "Docker seems to be unavailable" error when using Windows Subsystem for Linux (WSL) When running on WSL, the recommendation is to install a CLI release for Linux, like the standalone -zip package for Linux. However, commands like "balena build" that contact a local Docker daemon, -like the Docker Desktop for Windows, will try to reach Docker at the Unix socket path -`/var/run/docker.sock`, while Docker Desktop for Windows uses a Windows named pipe at -`//./pipe/docker_engine` (which the Linux CLI on WSL cannot use). A solution is: +zip package for Linux. However, commands like "balena build" will, by default, attempt to reach the +Docker daemon at the Unix socket path `/var/run/docker.sock`, while Docker Desktop for Windows uses +a Windows named pipe at `//./pipe/docker_engine` (which the Linux CLI on WSL cannot use). A +solution is: - Open the Docker Desktop for Windows settings panel and tick the checkbox _"Expose daemon on tcp://localhost:2375 without TLS"._ - On the WSL command line, set an env var: diff --git a/automation/capitanodoc/capitanodoc.ts b/automation/capitanodoc/capitanodoc.ts index bf1a930d..8d1efdcf 100644 --- a/automation/capitanodoc/capitanodoc.ts +++ b/automation/capitanodoc/capitanodoc.ts @@ -26,7 +26,7 @@ import { MarkdownFileParser } from './utils'; * some content to this object. */ const capitanoDoc = { - title: 'Balena CLI Documentation', + title: 'balenaCLI Documentation', introduction: '', categories: [ { @@ -191,7 +191,9 @@ export async function getCapitanoDoc(): Promise { return match && match[2]; }), mdParser.getSectionOfTitle('Installation'), - mdParser.getSectionOfTitle('Getting Started'), + mdParser.getSectionOfTitle('Choosing a shell (command prompt/terminal)'), + mdParser.getSectionOfTitle('Logging in'), + mdParser.getSectionOfTitle('Proxy support'), mdParser.getSectionOfTitle('Support, FAQ and troubleshooting'), mdParser.getSectionOfTitle('Deprecation policy'), ]); diff --git a/automation/capitanodoc/utils.ts b/automation/capitanodoc/utils.ts index 8108d263..1b5c09b3 100644 --- a/automation/capitanodoc/utils.ts +++ b/automation/capitanodoc/utils.ts @@ -57,7 +57,7 @@ export class MarkdownFileParser { * Extract the lines of a markdown document section with the given title. * For example, consider this sample markdown document: * ``` - * # balena CLI + * # balenaCLI * * ## Introduction * Lorem ipsum dolor sit amet, consectetur adipiscing elit, diff --git a/doc/cli.markdown b/doc/cli.markdown index 09f266d9..a53b7081 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -1,24 +1,23 @@ -# Balena CLI Documentation +# balenaCLI Documentation -The balena CLI (Command-Line Interface) allows you to interact with the balenaCloud and the -[balena API](https://www.balena.io/docs/reference/api/overview/) through a terminal window -on Linux, macOS or Windows. You can also write shell scripts around it, or import its Node.js -modules to use it programmatically. -As an [open-source project on GitHub](https://github.com/balena-io/balena-cli/), your contribution -is also welcome! +balenaCLI is a Command Line Interface for [balenaCloud](https://www.balena.io/cloud/) or +[openBalena](https://www.balena.io/open/). It is a software tool available for Windows, macOS and +Linux, used through a command prompt / terminal window. It can be used interactively or invoked in +scripts. balenaCLI builds on the [balena API](https://www.balena.io/docs/reference/api/overview/) +and the [balena SDK](https://www.balena.io/docs/reference/sdk/node-sdk/), and can also be directly +imported in Node.js applications. balenaCLI is an [open-source project on +GitHub](https://github.com/balena-io/balena-cli/), and your contribution is also welcome! ## Installation -Check the [balena CLI installation instructions on GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md). +Check the [balenaCLI installation instructions on +GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md). -## Getting Started - -### Choosing a shell (command prompt/terminal) +## Choosing a shell (command prompt/terminal) On **Windows,** the standard Command Prompt (`cmd.exe`) and [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6) -are supported. We are aware of users also having a good experience with alternative shells, -including: +are supported. Alternative shells include: * [MSYS2](https://www.msys2.org/): * Install additional packages with the command: @@ -36,17 +35,17 @@ including: [comment](https://github.com/balena-io/balena-cli/issues/598#issuecomment-556513098). * Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL). In this case, a Linux distribution like Ubuntu is installed via the Microsoft Store, and a - balena CLI release **for Linux** is recommended. See - [FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using balena - CLI with WSL and Docker Desktop for Windows. + balenaCLI release **for Linux** should be selected. See + [FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using balenaCLI + with WSL and Docker Desktop for Windows. -On **macOS** and **Linux,** the standard terminal window is supported. _Optionally,_ `bash` command +On **macOS** and **Linux,** the standard terminal window is supported. Optionally, `bash` command auto completion may be enabled by copying the [balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash) file to your system's `bash_completion` directory: check [Docker's command completion guide](https://docs.docker.com/compose/completion/) for system setup instructions. -### Logging in +## Logging in Several CLI commands require access to your balenaCloud account, for example in order to push a new release to your application. Those commands require creating a CLI login session by running: @@ -55,7 +54,7 @@ new release to your application. Those commands require creating a CLI login ses $ balena login ``` -### Proxy support +## Proxy support HTTP(S) proxies can be configured through any of the following methods, in precedence order (from higher to lower): @@ -81,7 +80,7 @@ HTTP(S) proxies can be configured through any of the following methods, in prece * The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as `BALENARC_PROXY`. -#### Proxy setup for balena ssh +### Proxy setup for balena ssh In order to work behind a proxy server, the `balena ssh` command requires the [`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) to be installed. @@ -96,11 +95,11 @@ server, it should be configured with the following rules in the `squid.conf` fil `acl SSL_ports port 22` `acl Safe_ports port 22` -#### Proxy exclusion +### Proxy exclusion The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations from proxying. -> * This feature requires balena CLI version 11.30.8 or later. In the case of the npm [installation +> * This feature requires balenaCLI version 11.30.8 or later. In the case of the npm [installation > option](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md), it also requires > Node.js version 10.16.0 or later. > * To exclude a `balena ssh` target from proxying (IP address or `.local` hostname), the @@ -137,19 +136,19 @@ If you come across any problems or would like to get in touch: ## Deprecation policy -The balena CLI uses [semver versioning](https://semver.org/), with the concepts +balenaCLI uses [semver versioning](https://semver.org/), with the concepts of major, minor and patch version releases. -The latest release of the previous major version of the balena CLI will remain -compatible with the balenaCloud backend services for one year from the date when -the next major version is released. For example, balena CLI v10.17.5, as the +The latest release of a major version of balenaCLI 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, balenaCLI v10.17.5, as the latest v10 release, would remain compatible with the balenaCloud backend for one year from the date when v11.0.0 is released. At the end of this period, the older major version is considered deprecated and some of the functionality that depends on balenaCloud services may stop working at any time. -Users are encouraged to regularly update the balena CLI to the latest version. +Users are encouraged to regularly update balenaCLI to the latest version. # CLI Command Reference @@ -882,7 +881,7 @@ Examples: #### --all -No-op since balena CLI v12.0.0. +No-op since balenaCLI v12.0.0. #### -a, --application APPLICATION @@ -1243,7 +1242,7 @@ show additional commands ## version -Display version information for the balena CLI and/or Node.js. +Display version information for balenaCLI and/or Node.js. 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 @@ -1691,7 +1690,7 @@ A suitable key is automatically generated or fetched if this option is omitted. Note: This command is currently not supported on Windows natively. Windows users are advised to install the Windows Subsystem for Linux (WSL) with Ubuntu, and use -the Linux release of the balena CLI: +the Linux release of balenaCLI: https://docs.microsoft.com/en-us/windows/wsl/about Examples: @@ -2064,8 +2063,7 @@ Docker host TLS key file ## push <applicationOrDevice> -start a build on the remote balena cloud builders, -or a local mode balena device. +Start a build on the remote balenaCloud builders, or a local mode balena device. When building on the balenaCloud servers, the given source directory will be sent to the remote server. This can be used as a drop-in replacement for the @@ -2111,7 +2109,7 @@ secrets.json file exists in the balena directory (usually $HOME/.balena), this file will be used instead. DOCKERIGNORE AND GITIGNORE FILES -By default, the balena CLI will use a single ".dockerignore" file (if any) at +By default, balenaCLI will use a single ".dockerignore" file (if any) at the project root (--source directory) in order to decide which source files to exclude from the "build context" (tar stream) sent to balenaCloud, Docker daemon or balenaEngine. In a microservices (multicontainer) application, the @@ -2136,7 +2134,7 @@ compatibility with the standard docker-compose tool, while still allowing a root .dockerignore file (at the overall project root) to filter files and folders that are outside service subdirectories. -Balena CLI releases older than v12.0.0 also took .gitignore files into account. +balenaCLI releases older than v12.0.0 also took .gitignore files into account. This behavior is deprecated, but may still be enabled with the --gitignore (-g) option if compatibility is required. This option is mutually exclusive with --multi-dockerignore (-m) and will be removed in the CLI's next major version @@ -2263,7 +2261,7 @@ left hand side of the = character will be treated as the variable name. #### -l, --convert-eol -No-op and deprecated since balena CLI v12.0.0 +No-op and deprecated since balenaCLI v12.0.0 #### --noconvert-eol @@ -2275,7 +2273,7 @@ Have each service use its own .dockerignore file. See "balena help push". #### -G, --nogitignore -No-op (default behavior) since balena CLI v12.0.0. See "balena help push". +No-op (default behavior) since balenaCLI v12.0.0. See "balena help push". #### -g, --gitignore @@ -2287,7 +2285,7 @@ required until your project can be adapted. ## settings -Use this command to display current balena CLI settings. +Use this command to display current balenaCLI settings. Examples: @@ -2387,7 +2385,7 @@ secrets.json file exists in the balena directory (usually $HOME/.balena), this file will be used instead. DOCKERIGNORE AND GITIGNORE FILES -By default, the balena CLI will use a single ".dockerignore" file (if any) at +By default, balenaCLI will use a single ".dockerignore" file (if any) at the project root (--source directory) in order to decide which source files to exclude from the "build context" (tar stream) sent to balenaCloud, Docker daemon or balenaEngine. In a microservices (multicontainer) application, the @@ -2412,7 +2410,7 @@ compatibility with the standard docker-compose tool, while still allowing a root .dockerignore file (at the overall project root) to filter files and folders that are outside service subdirectories. -Balena CLI releases older than v12.0.0 also took .gitignore files into account. +balenaCLI releases older than v12.0.0 also took .gitignore files into account. This behavior is deprecated, but may still be enabled with the --gitignore (-g) option if compatibility is required. This option is mutually exclusive with --multi-dockerignore (-m) and will be removed in the CLI's next major version @@ -2477,7 +2475,7 @@ Alternative Dockerfile name/path, relative to the source folder #### --logs -No-op and deprecated since balena CLI v12.0.0. Build logs are now shown by default. +No-op and deprecated since balenaCLI v12.0.0. Build logs are now shown by default. #### --nologs @@ -2495,7 +2493,7 @@ Have each service use its own .dockerignore file. See "balena help build". #### -G, --nogitignore -No-op (default behavior) since balena CLI v12.0.0. See "balena help build". +No-op (default behavior) since balenaCLI v12.0.0. See "balena help build". #### --noparent-check @@ -2507,7 +2505,7 @@ Path to a YAML or JSON file with passwords for a private Docker registry #### -l, --convert-eol -No-op and deprecated since balena CLI v12.0.0 +No-op and deprecated since balenaCLI v12.0.0 #### --noconvert-eol @@ -2609,7 +2607,7 @@ secrets.json file exists in the balena directory (usually $HOME/.balena), this file will be used instead. DOCKERIGNORE AND GITIGNORE FILES -By default, the balena CLI will use a single ".dockerignore" file (if any) at +By default, balenaCLI will use a single ".dockerignore" file (if any) at the project root (--source directory) in order to decide which source files to exclude from the "build context" (tar stream) sent to balenaCloud, Docker daemon or balenaEngine. In a microservices (multicontainer) application, the @@ -2634,7 +2632,7 @@ compatibility with the standard docker-compose tool, while still allowing a root .dockerignore file (at the overall project root) to filter files and folders that are outside service subdirectories. -Balena CLI releases older than v12.0.0 also took .gitignore files into account. +balenaCLI releases older than v12.0.0 also took .gitignore files into account. This behavior is deprecated, but may still be enabled with the --gitignore (-g) option if compatibility is required. This option is mutually exclusive with --multi-dockerignore (-m) and will be removed in the CLI's next major version @@ -2700,7 +2698,7 @@ Alternative Dockerfile name/path, relative to the source folder #### --logs -No-op and deprecated since balena CLI v12.0.0. Build logs are now shown by default. +No-op and deprecated since balenaCLI v12.0.0. Build logs are now shown by default. #### --nologs @@ -2718,7 +2716,7 @@ Have each service use its own .dockerignore file. See "balena help build". #### -G, --nogitignore -No-op (default behavior) since balena CLI v12.0.0. See "balena help build". +No-op (default behavior) since balenaCLI v12.0.0. See "balena help build". #### --noparent-check @@ -2730,7 +2728,7 @@ Path to a YAML or JSON file with passwords for a private Docker registry #### -l, --convert-eol -No-op and deprecated since balena CLI v12.0.0 +No-op and deprecated since balenaCLI v12.0.0 #### --noconvert-eol diff --git a/lib/actions-oclif/envs.ts b/lib/actions-oclif/envs.ts index 85eb2e9a..e89b2a7f 100644 --- a/lib/actions-oclif/envs.ts +++ b/lib/actions-oclif/envs.ts @@ -161,7 +161,7 @@ export default class EnvsCmd extends Command { ? { all: flags.boolean({ description: stripIndent` - No-op since balena CLI v12.0.0.`, + No-op since balenaCLI v12.0.0.`, hidden: true, }), } diff --git a/lib/actions-oclif/os/configure.ts b/lib/actions-oclif/os/configure.ts index b095dcb4..954d3887 100644 --- a/lib/actions-oclif/os/configure.ts +++ b/lib/actions-oclif/os/configure.ts @@ -90,7 +90,7 @@ export default class OsConfigureCmd extends Command { Note: This command is currently not supported on Windows natively. Windows users are advised to install the Windows Subsystem for Linux (WSL) with Ubuntu, and use - the Linux release of the balena CLI: + the Linux release of balenaCLI: https://docs.microsoft.com/en-us/windows/wsl/about `; public static examples = [ @@ -297,11 +297,11 @@ async function validateOptions(options: FlagsDef) { throw new ExpectedError(stripIndent` Unsupported platform error: the 'balena os configure' command currently requires the Windows Subsystem for Linux in order to run on Windows. It was tested with - the Ubuntu 18.04 distribution from the Microsoft Store. With WSL, a balena CLI + the Ubuntu 18.04 distribution from the Microsoft Store. With WSL, a balenaCLI release for Linux (rather than Windows) should be installed: for example, the standalone zip package for Linux. (It is possible to have both a Windows CLI release and a Linux CLI release installed simultaneously.) For more information - on WSL and the balena CLI installation options, please check: + on WSL and the balenaCLI installation options, please check: - https://docs.microsoft.com/en-us/windows/wsl/about - https://github.com/balena-io/balena-cli/blob/master/INSTALL.md `); diff --git a/lib/actions-oclif/push.ts b/lib/actions-oclif/push.ts index e4fb13ff..d66d0f42 100644 --- a/lib/actions-oclif/push.ts +++ b/lib/actions-oclif/push.ts @@ -55,10 +55,9 @@ interface ArgsDef { export default class PushCmd extends Command { public static description = stripIndent` - Start a remote build on the balena cloud build servers or a local mode device. + Start a remote build on the balenaCloud build servers or a local mode device. - start a build on the remote balena cloud builders, - or a local mode balena device. + Start a build on the remote balenaCloud builders, or a local mode balena device. When building on the balenaCloud servers, the given source directory will be sent to the remote server. This can be used as a drop-in replacement for the @@ -196,7 +195,7 @@ export default class PushCmd extends Command { multiple: true, }), 'convert-eol': flags.boolean({ - description: 'No-op and deprecated since balena CLI v12.0.0', + description: 'No-op and deprecated since balenaCLI v12.0.0', char: 'l', hidden: true, }), @@ -211,7 +210,7 @@ export default class PushCmd extends Command { }), nogitignore: flags.boolean({ description: - 'No-op (default behavior) since balena CLI v12.0.0. See "balena help push".', + 'No-op (default behavior) since balenaCLI v12.0.0. See "balena help push".', char: 'G', hidden: true, }), diff --git a/lib/actions-oclif/settings.ts b/lib/actions-oclif/settings.ts index 68b77bd0..62acbf01 100644 --- a/lib/actions-oclif/settings.ts +++ b/lib/actions-oclif/settings.ts @@ -28,7 +28,7 @@ export default class SettingsCmd extends Command { public static description = stripIndent` Print current settings. - Use this command to display current balena CLI settings. + Use this command to display current balenaCLI settings. `; public static examples = ['$ balena settings']; diff --git a/lib/actions-oclif/version.ts b/lib/actions-oclif/version.ts index bc41fe91..dfe554c7 100644 --- a/lib/actions-oclif/version.ts +++ b/lib/actions-oclif/version.ts @@ -32,9 +32,9 @@ export interface JsonVersions { export default class VersionCmd extends Command { public static description = stripIndent` - Display version information for the balena CLI and/or Node.js. + Display version information for balenaCLI and/or Node.js. - Display version information for the balena CLI and/or Node.js. + Display version information for balenaCLI and/or Node.js. 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 diff --git a/lib/auth/index.ts b/lib/auth/index.ts index f7d71da1..e716f7b2 100644 --- a/lib/auth/index.ts +++ b/lib/auth/index.ts @@ -22,7 +22,7 @@ import { LoginServer } from './server'; */ /** - * @summary Login to the balena CLI using the web dashboard + * @summary Login to balenaCLI using the web dashboard * @function * @public * diff --git a/lib/auth/pages/error.ejs b/lib/auth/pages/error.ejs index 8f6c82b8..42059cff 100644 --- a/lib/auth/pages/error.ejs +++ b/lib/auth/pages/error.ejs @@ -3,7 +3,7 @@ - Balena CLI - Error + balenaCLI - Error @@ -13,7 +13,7 @@

Something went wrong


-

The balena CLI login was not successful.

+

The balenaCLI login was not successful.



Get help in our forums diff --git a/lib/auth/pages/success.ejs b/lib/auth/pages/success.ejs index bf187af0..f849a39c 100644 --- a/lib/auth/pages/success.ejs +++ b/lib/auth/pages/success.ejs @@ -3,7 +3,7 @@ - Balena CLI - Success + balenaCLI - Success @@ -13,7 +13,7 @@

Success!


-

The balena CLI login was successful.

+

The balenaCLI login was successful.

You may now close this page and return to the command prompt.

diff --git a/lib/events.ts b/lib/events.ts index b3fda1a5..a12e2de1 100644 --- a/lib/events.ts +++ b/lib/events.ts @@ -34,7 +34,7 @@ interface CachedUsername { } /** - * Mixpanel.com analytics tracking (information on balena CLI usage). + * Mixpanel.com analytics tracking (information on balenaCLI usage). * * @param commandSignature A string like, for example: * "push " diff --git a/lib/utils/compose.js b/lib/utils/compose.js index 027956d1..f9139e2c 100644 --- a/lib/utils/compose.js +++ b/lib/utils/compose.js @@ -36,7 +36,7 @@ export function appendOptions(opts) { { signature: 'logs', description: - 'No-op and deprecated since balena CLI v12.0.0. Build logs are now shown by default.', + 'No-op and deprecated since balenaCLI v12.0.0. Build logs are now shown by default.', boolean: true, }, { @@ -63,7 +63,7 @@ export function appendOptions(opts) { }, { signature: 'nogitignore', - description: `No-op (default behavior) since balena CLI v12.0.0. See "balena help build".`, + description: `No-op (default behavior) since v12.0.0. See "balena help build".`, boolean: true, alias: 'G', }, @@ -82,7 +82,7 @@ export function appendOptions(opts) { }, { signature: 'convert-eol', - description: 'No-op and deprecated since balena CLI v12.0.0', + description: 'No-op and deprecated since v12.0.0', boolean: true, alias: 'l', }, diff --git a/lib/utils/compose_ts.ts b/lib/utils/compose_ts.ts index ee0521ec..095b5418 100644 --- a/lib/utils/compose_ts.ts +++ b/lib/utils/compose_ts.ts @@ -918,7 +918,7 @@ export const composeCliFlags: flags.Input = { }), logs: flags.boolean({ description: - 'No-op and deprecated since balena CLI v12.0.0. Build logs are now shown by default.', + 'No-op and deprecated since balenaCLI v12.0.0. Build logs are now shown by default.', }), nologs: flags.boolean({ description: @@ -937,7 +937,7 @@ export const composeCliFlags: flags.Input = { char: 'm', }), nogitignore: flags.boolean({ - description: `No-op (default behavior) since balena CLI v12.0.0. See "balena help build".`, + description: `No-op (default behavior) since balenaCLI v12.0.0. See "balena help build".`, char: 'G', }), 'noparent-check': flags.boolean({ @@ -950,7 +950,7 @@ export const composeCliFlags: flags.Input = { char: 'R', }), 'convert-eol': flags.boolean({ - description: 'No-op and deprecated since balena CLI v12.0.0', + description: 'No-op and deprecated since balenaCLI v12.0.0', char: 'l', }), 'noconvert-eol': flags.boolean({ diff --git a/lib/utils/helpers.ts b/lib/utils/helpers.ts index 5f652f52..671e61f3 100644 --- a/lib/utils/helpers.ts +++ b/lib/utils/helpers.ts @@ -69,7 +69,7 @@ export function stateToString(state: OperationState) { * bash/sh and the Windows cmd.exe in relation to escape characters. * @param msg Optional message for the user, before the password prompt * @param stderr Optional stream to which stderr should be piped - * @param isCLIcmd (default: true) Whether the command array is a balena CLI command + * @param isCLIcmd (default: true) Whether the command array is a balenaCLI command * (e.g. ['internal', 'osinit', ...]), in which case process.argv[0] and argv[1] are * added as necessary, depending on whether the CLI is running as a standalone zip * package (with Node built in). diff --git a/lib/utils/messages.ts b/lib/utils/messages.ts index 03096e82..b70bec9f 100644 --- a/lib/utils/messages.ts +++ b/lib/utils/messages.ts @@ -69,7 +69,7 @@ this file will be used instead.`; export const dockerignoreHelp = `\ DOCKERIGNORE AND GITIGNORE FILES -By default, the balena CLI will use a single ".dockerignore" file (if any) at +By default, balenaCLI will use a single ".dockerignore" file (if any) at the project root (--source directory) in order to decide which source files to exclude from the "build context" (tar stream) sent to balenaCloud, Docker daemon or balenaEngine. In a microservices (multicontainer) application, the @@ -94,7 +94,7 @@ compatibility with the standard docker-compose tool, while still allowing a root .dockerignore file (at the overall project root) to filter files and folders that are outside service subdirectories. -Balena CLI releases older than v12.0.0 also took .gitignore files into account. +balenaCLI releases older than v12.0.0 also took .gitignore files into account. This behavior is deprecated, but may still be enabled with the --gitignore (-g) option if compatibility is required. This option is mutually exclusive with --multi-dockerignore (-m) and will be removed in the CLI's next major version diff --git a/lib/utils/remote-build.ts b/lib/utils/remote-build.ts index 9aa08a03..dc8ffa66 100644 --- a/lib/utils/remote-build.ts +++ b/lib/utils/remote-build.ts @@ -384,7 +384,7 @@ async function getRemoteBuildStream( if (process.stdout.isTTY) { const visuals = getVisuals(); uploadSpinner = new visuals.Spinner( - 'Uploading source package to balena cloud', + 'Uploading source package to balenaCloud', ); exitOnError = (error: Error): never => { uploadSpinner.stop(); diff --git a/lib/utils/sudo.ts b/lib/utils/sudo.ts index 680f087d..fcac36eb 100644 --- a/lib/utils/sudo.ts +++ b/lib/utils/sudo.ts @@ -31,7 +31,7 @@ import { stripIndent } from './lazy'; * differences between bash/sh and the Windows cmd.exe in relation to escape * characters. * @param stderr Optional stream to which stderr should be piped - * @param isCLIcmd (default: true) Whether the command array is a balena CLI command + * @param isCLIcmd (default: true) Whether the command array is a balenaCLI command * (e.g. ['internal', 'osinit', ...]), in which case process.argv[0] and argv[1] are * added as necessary, depending on whether the CLI is running as a standalone zip * package (with Node built in). diff --git a/package.json b/package.json index 2bffa0f0..99f1767e 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "balena-cli", "version": "12.22.0", - "description": "The official balena CLI tool", + "description": "The official balena Command Line Interface", "main": "./build/app.js", "homepage": "https://github.com/balena-io/balena-cli", "repository": { diff --git a/tests/commands/help.spec.ts b/tests/commands/help.spec.ts index 2dc95952..9fe2149e 100644 --- a/tests/commands/help.spec.ts +++ b/tests/commands/help.spec.ts @@ -26,7 +26,7 @@ $ balena [COMMAND] [OPTIONS] PRIMARY COMMANDS login login to balena - push start a remote build on the balena cloud build servers or a local mode device + push start a remote build on the balenaCloud build servers or a local mode device logs show device logs ssh [service] SSH into the host or application container of a device apps list all applications @@ -87,7 +87,7 @@ ADDITIONAL COMMANDS tag set [value] set a tag on an application, device or release tags list all tags for an application, device or release util available-drives list available drives - version display version information for the balena CLI and/or Node.js + version display version information for balenaCLI and/or Node.js whoami display account information for current user `;