diff --git a/.resinci.yml b/.resinci.yml new file mode 100644 index 00000000..769f34b3 --- /dev/null +++ b/.resinci.yml @@ -0,0 +1,36 @@ +--- +npm: + platforms: + - name: linux + os: alpine + architecture: x86_64 + node_versions: + - "8" + - "10" + - name: linux + os: alpine + architecture: x86 + node_versions: + - "8" + - "10" + - name: darwin + os: macos + architecture: x86_64 + node_versions: + - "8" + - "10" + - name: windows + os: windows + architecture: x86_64 + node_versions: + - "8" + - "10" + - name: windows + os: windows + architecture: x86 + node_versions: + - "8" + - "10" + +docker: + publish: false diff --git a/INSTALL.md b/INSTALL.md index f7b6ad09..c5633114 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -4,13 +4,13 @@ The easiest and recommended way of installing the CLI on all platforms (Windows, to use the [Standalone Installation](#standalone-installation) described below. Some specific CLI commands have a few extra installation steps: see section [Additional Dependencies](#additional-dependencies). -> **Windows users:** we now have a [YouTube video tutorial](https://www.youtube.com/watch?v=j3JoA1EINUA) +> **Windows users:** We now have a [YouTube video tutorial](https://www.youtube.com/watch?v=j3JoA1EINUA) for installing and getting started with the balena CLI on Windows! ## Standalone Installation 1. Download the latest zip file for your OS from https://github.com/balena-io/balena-cli/releases. - (Note that "[darwin](https://en.wikipedia.org/wiki/Darwin_(operating_system))" is the + (Note that "[Darwin](https://en.wikipedia.org/wiki/Darwin_(operating_system))" is the appropriate zip file for macOS.) 2. Extract the zip file contents to any folder you choose. The extracted contents will include a `balena-cli` folder. @@ -31,7 +31,7 @@ as described above. ## NPM Installation -If you are a Node.js developer, you may wish to install the balena CLI through [npm](https://www.npmjs.com). +If you are a Node.js developer, you may wish to install the balena CLI via [npm](https://www.npmjs.com). The npm installation involves building native (platform-specific) binary modules, which require some additional development tools to be installed first: @@ -58,16 +58,16 @@ especially if you're using a user-managed node install such as [nvm](https://git ## Additional Dependencies * The `balena ssh` command requires a recent version of the `ssh` command-line tool to be available: - * MacOS and Linux usually already have it installed. Otherwise, search for the available packages + * macOS and Linux usually already have it installed. Otherwise, search for the available packages on your specific Linux distribution, or for the Mac consider the [Xcode command-line tools](https://developer.apple.com/xcode/features/) or [homebrew](https://brew.sh/). - * Microsoft started distributing a ssh client with Windows 10, which we understand is - automatically installed through Windows Update, but can be manually installed too - ([more information](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)). - For other versions of Windows, there are several ssh/OpenSSH clients provided by 3rd parties. + * Microsoft started distributing an SSH client with Windows 10, which we understand is + automatically installed through Windows Update, but can be manually installed too + ([more information](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)). + For other versions of Windows, there are several ssh/OpenSSH clients provided by 3rd parties. - * If you need `ssh` to work behind a proxy, you will also need to install + * If you need SSH to work behind a proxy, you will also need to install [`proxytunnel`](http://proxytunnel.sourceforge.net/) (available as a `proxytunnel` package for Ubuntu, for example). Check the [README](https://github.com/balena-io/balena-cli/blob/master/README.md) file @@ -75,27 +75,27 @@ especially if you're using a user-managed node install such as [nvm](https://git * The `balena sync` command (deprecated) currently requires `rsync` (>= 2.6.9) to be installed: * Linux: `apt-get install rsync` - * MacOS: [Xcode command-line tools](https://developer.apple.com/xcode/features/) or [homebrew](https://brew.sh/) - * Windows: one option is to use the [MinGW](http://www.mingw.org) shell and install the `msys-rsync` package. - Check the README file for other shell options under Windows. + * macOS: [Xcode command-line tools](https://developer.apple.com/xcode/features/) or [homebrew](https://brew.sh/) + * Windows: One option is to use the [MinGW](http://www.mingw.org) shell and install the + `msys-rsync` package. Check the README file for other shell options under Windows. ## Configuring SSH keys -The `balena ssh` command requires a SSH key to be added to your balena account. If you had +The `balena ssh` command requires an SSH key to be added to your balena account. If you had already added a SSH key in order to [deploy with 'git push'](https://www.balena.io/docs/learn/getting-started/raspberrypi3/nodejs/#adding-an-ssh-key), then you are probably done and may skip this section. You can check whether you already have -a SSH key in your balena account with the `balena keys` command, or by visiting the +an SSH key in your balena account with the `balena keys` command, or by visiting the [balena web dashboard](https://dashboard.balena-cloud.com/), clicking on your name -> Preferences -> SSH Keys. -> Note: a "SSH key" actually consists of a public/private key pair. A typical name for the private +> Note: An "SSH key" actually consists of a public/private key pair. A typical name for the private > key file is "id_rsa", and a typical name for the public key file is "id_rsa.pub". Both key files > are saved to your computer (with the private key optionally protected by a password), but only > the public key is saved to your balena account. This means that if you change computers or > otherwise lose the private key, _you cannot recover the private key through your balena account._ > You can however add new keys, and delete the old ones. -If you don't have a SSH key in you balena account: +If you don't have an SSH key in your balena account: * If you have an existing SSH key in your computer that you would like to use, you can add it to your balena account through the balena web dashboard (Preferences -> SSH Keys), or through diff --git a/README.md b/README.md index 99d13f7b..60ac4ee8 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The official balena CLI tool. 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 +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! @@ -23,27 +23,26 @@ Check the [balena CLI installation instructions on GitHub](https://github.com/ba ### Choosing a shell (command prompt/terminal) -On Linux and MacOS, `bash` is the standard and recommended shell for use with the balena CLI. - -> **bash command auto completion** -`bash` command auto completion can be enabled by copying the -[balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash) -file to the default bash completions directory (usually `/etc/bash_completion.d/`), or by appending -it to `~/.bash_completion`. - -On Windows, we support the standard Windows Command Prompt (`cmd.exe`) and the Windows -[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6). -We are aware of users also having a good experience with alternative shells, including: +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: * Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (a.k.a. Microsoft's "bash for Windows 10"). * [Git for Windows](https://git-for-windows.github.io/). * [MinGW](http://www.mingw.org): install the `msys-rsync` and `msys-openssh` packages too. +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 -Several CLI commands require access to your balenaCloud account, for example in order to push -a new release to your app. Those commands require creating a CLI login session by running: +Several CLI commands require access to your balenaCloud account, for example in order to push a +new release to your application. Those commands require creating a CLI login session by running: ```sh $ balena login @@ -57,8 +56,8 @@ HTTP(S) proxies can be configured through any of the following methods, in order optionally basic auth). * Alternatively, use the [balena config file](https://www.npmjs.com/package/balena-settings-client#documentation) (project-specific or user-level) and set the \`proxy\` setting. It can be: - * a string in URL format, or - * an object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control). + * A string in URL format, or + * An object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control). * Alternatively, set the conventional \`https_proxy\` / \`HTTPS_PROXY\` / \`http_proxy\` / \`HTTP_PROXY\` environment variable (in the same standard URL format). diff --git a/automation/capitanodoc/capitanodoc.ts b/automation/capitanodoc/capitanodoc.ts index dc9660e2..423d5dbb 100644 --- a/automation/capitanodoc/capitanodoc.ts +++ b/automation/capitanodoc/capitanodoc.ts @@ -132,7 +132,7 @@ const capitanoDoc = { export async function getCapitanoDoc(): Promise { const readmePath = path.join(__dirname, '..', '..', 'README.md'); const mdParser = new MarkdownFileParser(readmePath); - return Promise.all([ + const sections: string[] = await Promise.all([ mdParser.getSectionOfTitle('About').then((sectionLines: string) => { // delete the title of the 'About' section for the web page const match = /^(#+)\s+.+?\n\s*([^]*)/.exec(sectionLines); @@ -145,8 +145,7 @@ export async function getCapitanoDoc(): Promise { mdParser.getSectionOfTitle('Installation'), mdParser.getSectionOfTitle('Getting Started'), mdParser.getSectionOfTitle('Support, FAQ and troubleshooting'), - ]).then((sections: string[]) => { - capitanoDoc.introduction = sections.join('\n'); - return capitanoDoc; - }); + ]); + capitanoDoc.introduction = sections.join('\n'); + return capitanoDoc; } diff --git a/automation/capitanodoc/index.ts b/automation/capitanodoc/index.ts index 22a308c2..d0d08864 100644 --- a/automation/capitanodoc/index.ts +++ b/automation/capitanodoc/index.ts @@ -40,7 +40,6 @@ export async function renderMarkdown(): Promise { }; for (const file of commandCategory.files) { - // tslint:disable-next-line:no-var-requires const actions: any = require(path.join(process.cwd(), file)); if (actions.signature) { @@ -63,15 +62,13 @@ export async function renderMarkdown(): Promise { * Print the CLI docs markdown to stdout. * See package.json for how the output is redirected to a file. */ -function printMarkdown() { - renderMarkdown() - .then((mdDocs: string) => { - console.log(mdDocs); - }) - .catch((error: Error) => { - console.error(error); - process.exit(1); - }); +async function printMarkdown() { + try { + console.log(await renderMarkdown()); + } catch (error) { + console.error(error); + process.exit(1); + } } printMarkdown(); diff --git a/doc/cli.markdown b/doc/cli.markdown index 2270ce31..23ac7c90 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -2,7 +2,7 @@ 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 +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! @@ -15,27 +15,26 @@ Check the [balena CLI installation instructions on GitHub](https://github.com/ba ### Choosing a shell (command prompt/terminal) -On Linux and MacOS, `bash` is the standard and recommended shell for use with the balena CLI. - -> **bash command auto completion** -`bash` command auto completion can be enabled by copying the -[balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash) -file to the default bash completions directory (usually `/etc/bash_completion.d/`), or by appending -it to `~/.bash_completion`. - -On Windows, we support the standard Windows Command Prompt (`cmd.exe`) and the Windows -[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6). -We are aware of users also having a good experience with alternative shells, including: +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: * Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (a.k.a. Microsoft's "bash for Windows 10"). * [Git for Windows](https://git-for-windows.github.io/). * [MinGW](http://www.mingw.org): install the `msys-rsync` and `msys-openssh` packages too. +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 -Several CLI commands require access to your balenaCloud account, for example in order to push -a new release to your app. Those commands require creating a CLI login session by running: +Several CLI commands require access to your balenaCloud account, for example in order to push a +new release to your application. Those commands require creating a CLI login session by running: ```sh $ balena login @@ -49,8 +48,8 @@ HTTP(S) proxies can be configured through any of the following methods, in order optionally basic auth). * Alternatively, use the [balena config file](https://www.npmjs.com/package/balena-settings-client#documentation) (project-specific or user-level) and set the \`proxy\` setting. It can be: - * a string in URL format, or - * an object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control). + * A string in URL format, or + * An object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control). * Alternatively, set the conventional \`https_proxy\` / \`HTTPS_PROXY\` / \`http_proxy\` / \`HTTP_PROXY\` environment variable (in the same standard URL format).