ExternalVendorCode/balena-cli
1
0
Fork 0
mirror of https://github.com/balena-io/balena-cli.git synced 2024-12-18 21:27:51 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Unify the CLI instructions between capitanodoc.ts and README.md, move

Browse Source 
the installation instructions to INSTALL.md, and update the markdown
generation scripts.

Change-type: minor
Signed-off-by: Paulo Castro <paulo@balena.io>
This commit is contained in:
Paulo Castro 2019-04-18 16:49:17 +01:00
parent 37bd6be77b
commit 2ad0b60aeb
10 changed files with 591 additions and 382 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
INSTALL.md Normal file
View File

@ -0,0 +1,113 @@
# balena CLI Installation Instructions
The easiest and recommended way of installing the CLI on all platforms (Windows, Linux, macOS) is
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)
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
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.
3. Add the `balena-cli` folder to the system's `PATH` environment variable. See instructions for:
[Windows](https://www.computerhope.com/issues/ch000549.htm) |
[Linux](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix) |
[macOS](https://stackoverflow.com/questions/22465332/setting-path-environment-variable-in-osx-permanently).
Check that the installation was successful by opening or re-opening a command terminal window
(so that the PATH environment variable changes take effect), and running these commands:
* `balena` - should print the balena CLI help
* `balena version` - should print the installed CLI version
To update the CLI to a new version, download a new release zip file and replace the previous
installation folder. To uninstall, simply delete the folder and edit the PATH environment variable
as described above.
## NPM Installation
If you are a Node.js developer, you may wish to install the balena CLI through [npm](https://www.npmjs.com).
The npm installation involves building native (platform-specific) binary modules, which require
some additional development tools to be installed first:
* Node.js version 6 or above (**soon version 8 or above**)
* Python 2.7
* g++ compiler
* make
* git
* Under Windows, the `windows-build-tools` npm package should be installed too, running the
following command in an administrator console (available as 'Command Prompt (Admin)' when
pressing Windows+X in Windows 7+) :
`npm install -g --production windows-build-tools`
With those in place, the CLI installation command is:
```sh
$ npm install balena-cli -g --production --unsafe-perm
```
`--unsafe-perm` is only required on systems where the global install directory is not user-writable.
This allows npm install steps to download and save prebuilt native binaries. You may be able to omit it,
especially if you're using a user-managed node install such as [nvm](https://github.com/creationix/nvm).
## 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
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.
* 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
for proxy configuration instructions.
* 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.
## Configuring SSH keys
The `balena ssh` command requires a 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
[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
> 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 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
the CLI itself:
```bash
# Windows 10 (cmd.exe prompt) example:
$ balena key add MyKey %userprofile%\.ssh\id_rsa.pub
# Linux / macOS example:
$ balena key add MyKey ~/.ssh/id_rsa.pub
```
* To generate a new key, you can follow [GitHub's documentation](https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent),
skipping the step about adding the key to your GitHub account, and instead adding the key to
your balena account as described above.

175
README.md
View File

@ -1,142 +1,87 @@
balena CLI # balena CLI
=========
> The official balena CLI tool. The official balena CLI tool.
[![npm version](https://badge.fury.io/js/balena-cli.svg)](http://badge.fury.io/js/balena-cli) [![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) [![dependencies](https://david-dm.org/balena-io/balena-cli.svg)](https://david-dm.org/balena-io/balena-cli)
[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/balena-io/chat) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/balena-io/chat)
Getting Started ## About
---------------
The easiest and recommended way of installing the CLI on all platforms (Linux, MacOS, Windows) The balena CLI (Command-Line Interface) allows you to interact with the balenaCloud and the
is to use the Standalone Install described below. Some specific CLI commands like `balena ssh` [balena API](https://www.balena.io/docs/reference/api/overview/) through a terminal window
and `balena sync` have additional dependencies: see section Additional Dependencies. 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!
> **Windows users:** we now have a [YouTube video tutorial](https://www.youtube.com/watch?v=j3JoA1EINUA) ## Installation
for installing and getting started with the balena CLI on Windows!
### Standalone install Check the [balena CLI installation instructions on GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md).
* Download the latest zip for your OS from https://github.com/balena-io/balena-cli/releases. ## Getting Started
* Extract the contents, putting the `balena-cli` folder somewhere appropriate for your system (e.g. `C:/balena-cli`, `/usr/local/lib/balena-cli`, etc).
* Add the `balena-cli` folder to your `PATH` ([Windows instructions](https://www.computerhope.com/issues/ch000549.htm), [Linux instructions](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix), [OSX instructions](https://stackoverflow.com/questions/22465332/setting-path-environment-variable-in-osx-permanently))
* Running `balena` in a fresh command line should print the balena CLI help. See Windows Support
section below for some notes regarding the shell.
To update the CLI to a new version, simply download a new release and replace the extracted folder. ### Choosing a shell (command prompt/terminal)
### NPM install On Linux and MacOS, `bash` is the standard and recommended shell for use with the balena CLI.
If you are a Node.js developer, you may wish to install the balena CLI through npm[https://www.npmjs.com]. The npm installation involves building native (platform-specific) binary modules, for which there are some pre-requisites: > **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`.
* Node.js version 6 or above (**soon version 8 or above**) On Windows, we support the standard Windows Command Prompt (`cmd.exe`) and the Windows
* Python 2.7 [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6).
* g++ compiler We are aware of users also having a good experience with alternative shells, including:
* make
* git
* Under Windows, the `windows-build-tools` npm package should be installed too, running the
following command in an administrator console (available as 'Command Prompt (Admin)' when
pressing Windows+X in Windows 7+) :
`npm install -g --production windows-build-tools`
With those in place, the CLI installation command is: * Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
(a.k.a. Microsoft's "bash for Windows 10").
```sh
$ npm install balena-cli -g --production --unsafe-perm
```
`--unsafe-perm` is only required on systems where the global install directory is not user-writable.
This allows npm install steps to download and save prebuilt native binaries. You may be able to omit it,
especially if you're using a user-managed node install such as [nvm](https://github.com/creationix/nvm).
### 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 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 released an OpenSSH version of ssh for Windows 10, which we understand is
automatically installed through Windows Update, but can be manually installed too.
More information [here](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 also need [`proxytunnel`](http://proxytunnel.sourceforge.net/) installed (available as `proxytunnel` package for Ubuntu, for example).
* The `balena sync` command 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: use MinGW as described in the Windows Support section.
### Windows Support
We aim at supporting 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).
Some CLI commands like `balena sync` and `balena ssh` have not been thoroughly tested with the standard Windows shells. We are aware of users 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/). * [Git for Windows](https://git-for-windows.github.io/).
* [MinGW](http://www.mingw.org) * [MinGW](http://www.mingw.org): install the `msys-rsync` and `msys-openssh` packages too.
1. Install [MinGW](http://www.mingw.org).
2. Install the `msys-rsync` and `msys-openssh` packages.
3. Add MinGW to the `%PATH%` if this hasn't been done by the installer already. The location where the binaries are places is usually `C:\MinGW\msys\1.0\bin`, but it can vary if you selected a different location in the installer.
4. Copy your SSH keys to `%homedrive%%homepath\.ssh`.
5. If you need `ssh` to work behind the proxy you also need to install [proxytunnel](http://proxytunnel.sourceforge.net/)
### Login ### 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:
```sh ```sh
$ balena login $ balena login
``` ```
_(Typically useful, but not strictly required for all commands)_ ### Proxy support
### Run commands HTTP(S) proxies can be configured through any of the following methods, in order of preference:
Take a look at the full command documentation at [https://balena.io/docs/tools/cli/](https://balena.io/docs/tools/cli/#table-of-contents * Set the \`BALENARC_PROXY\` environment variable in URL format (with protocol, host, port, and
), or by running `balena help`. 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).
* Alternatively, set the conventional \`https_proxy\` / \`HTTPS_PROXY\` / \`http_proxy\` / \`HTTP_PROXY\`
environment variable (in the same standard URL format).
### Bash completions To get a proxy to work with the `balena ssh` command, check the
[installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md).
Optionally you can enable tab completions for the bash shell, enabling the shell to provide additional context and automatically complete arguments to`balena`. To enable bash completions, copy the `balena-completion.bash` file to the default bash completions directory (usually `/etc/bash_completion.d/`) or append it to the end of `~/.bash_completion`. ## Command reference documentation
FAQ 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`.
### Where is my configuration file? ## Support, FAQ and troubleshooting
The per-user configuration file lives in `$HOME/.balenarc.yml` or `%UserProfile%\_balenarc.yml`, in Unix based operating systems and Windows respectively. If you come across any problems or would like to get in touch:
The balena CLI also attempts to read a `balenarc.yml` file in the current directory, which takes precedence over the per-user configuration file. * 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).
* For bug reports or feature requests,
[have a look at the GitHub issues or create a new one](https://github.com/balena-io/balena-cli/issues/).
### How do I point the balena CLI to staging? ## Contributing
The easiest way is to set the `BALENARC_BALENA_URL=balena-staging.com` environment variable. The balena CLI is an open source project and your contribution is welcome!
Alternatively, you can edit your configuration file and set `balenaUrl: balena-staging.com` to persist this setting.
### How do I make the balena CLI persist data in another directory?
The balena CLI persists your session token, as well as cached images in `$HOME/.balena` or `%UserProfile%\_balena`.
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.
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.
Support
-------
If you're having any problems or would like to get in touch:
* Check our [troubleshooting guide](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
* For bug reports or feature requests, have a look at the GitHub issues or
create a new one at: https://github.com/balena-io/balena-cli/issues/
Development guidelines
----------------------
The CLI was originally written in [CoffeeScript](https://coffeescript.org), but we have decided to The CLI was originally written in [CoffeeScript](https://coffeescript.org), but we have decided to
migrate to [TypeScript](https://www.typescriptlang.org/) in order to take advantage of static migrate to [TypeScript](https://www.typescriptlang.org/) in order to take advantage of static
@ -146,12 +91,20 @@ maintenance work or the implementation of new features.
After cloning this repository and running `npm install` you can build the CLI using `npm run build`. After cloning this repository and running `npm install` you can build the CLI using `npm run build`.
You can then run the generated build using `./bin/balena`. You can then run the generated build using `./bin/balena`.
In order to ease development: In order to ease development:
* you can build the CLI using the `npm run build:fast` variant which skips some of the build steps or * you can build the CLI using the `npm run build:fast` variant which skips some of the build steps or
* you can use `./bin/balena-dev` which live transpiles the sources of the CLI. * you can use `./bin/balena-dev` which live transpiles the sources of the CLI.
In either case, before opening a PR make sure to also test your changes after doing a full build with `npm run build`. In either case, before opening a PR be sure to also test your changes with `npm test`.
License ## Note on editing this README document
-------
The project is licensed under the Apache 2.0 license. This file is edited/created by hand, but it is then automatically parsed to extract selected
subsections for the [CLI's web documentation page](https://www.balena.io/docs/reference/cli/).
The code that parses this file is in [`automation/capitanodoc/capitanodoc.ts`
](https://github.com/balena-io/balena-cli/blob/master/automation/capitanodoc/capitanodoc.ts).
## License
The project is licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).
A copy is also available in the LICENSE file in this repository.

40
TROUBLESHOOTING.md
View File

@ -1,15 +1,41 @@
Troubleshooting # FAQ & Troubleshooting
===============
This document contains common issues related to the balena CLI, and how to fix them. This document contains some common issues, questions and answers related to the balena CLI.
### After burning to an sdcard, my device doesn't boot ## Where is my configuration file?
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
precedence over the per-user configuration file.
## How do I point the balena CLI to staging?
The easiest way is to set the `BALENARC_BALENA_URL=balena-staging.com` environment variable.
Alternatively, you can edit your configuration file and set `balenaUrl: balena-staging.com` to
persist this setting.
## How do I make the balena CLI persist data in another directory?
The balena CLI persists your session token, as well as cached images in `$HOME/.balena` or
`%UserProfile%\_balena`.
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.
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.
## After burning to an sdcard, my device doesn't boot
- The downloaded image is not complete (download was interrupted). - The downloaded image is not complete (download was interrupted).
Please clean the cache (`%HOME/.balena/cache` or `C:\Users\<user>\_balena\cache`) and run the command again. In the future, the CLI will check that the image is not complete and clean the cache for you. Please clean the cache (`%HOME/.balena/cache` or `C:\Users\<user>\_balena\cache`) and run the command again. In the future, the CLI will check that the image is not complete and clean the cache for you.
### I get a permission error when burning to an sdcard ## I get a permission error when burning to an sdcard
- The SDCard is locked. - The SDCard is locked.
@ -32,7 +58,7 @@ Error: EINVAL, invalid argument
- 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`. 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).
### I get `Invalid MBR boot signature` when configuring a device ## I get `Invalid MBR boot signature` when configuring a device
This error, accompanied with something like: `Expected 0xAA55, but saw 0x29FE` usually indicates a corrupted device operating system image in the cache, due to bad a internet connection during the download process. This error, accompanied with something like: `Expected 0xAA55, but saw 0x29FE` usually indicates a corrupted device operating system image in the cache, due to bad a internet connection during the download process.
@ -48,7 +74,7 @@ Or in Windows:
> del /s /q %UserProfile%\_balena\cache > del /s /q %UserProfile%\_balena\cache
``` ```
### I get `EACCES: permission denied` when logging in ## I get `EACCES: permission denied` when logging in
The balena CLI stores the session token in `$HOME/.balena` or `C:\Users\<user>\_balena` in UNIX based operating systems and Windows respectively. This error usually indicates that the user doesn't have permissions over that directory, which can happen if you ran the balena CLI as `root`, and thus the directory got owned by him. The balena CLI stores the session token in `$HOME/.balena` or `C:\Users\<user>\_balena` in UNIX based operating systems and Windows respectively. This error usually indicates that the user doesn't have permissions over that directory, which can happen if you ran the balena CLI as `root`, and thus the directory got owned by him.

152
automation/capitanodoc/capitanodoc.ts Normal file
View File

@ -0,0 +1,152 @@
/**
* @license
* Copyright 2019 Balena Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as path from 'path';
import { MarkdownFileParser } from './utils';
/**
* This is the skeleton of CLI documentation/reference web page at:
* https://www.balena.io/docs/reference/cli/
*
* The `getCapitanoDoc` function in this module parses README.md and adds
* some content to this object.
*/
const capitanoDoc = {
title: 'Balena CLI Documentation',
introduction: '',
categories: [
{
title: 'API keys',
files: ['build/actions/api-key.js'],
},
{
title: 'Application',
files: ['build/actions/app.js'],
},
{
title: 'Authentication',
files: ['build/actions/auth.js'],
},
{
title: 'Device',
files: ['build/actions/device.js'],
},
{
title: 'Environment Variables',
files: ['build/actions/environment-variables.js'],
},
{
title: 'Tags',
files: ['build/actions/tags.js'],
},
{
title: 'Help',
files: ['build/actions/help.js'],
},
{
title: 'Information',
files: ['build/actions/info.js'],
},
{
title: 'Keys',
files: ['build/actions/keys.js'],
},
{
title: 'Logs',
files: ['build/actions/logs.js'],
},
{
title: 'Sync',
files: ['build/actions/sync.js'],
},
{
title: 'SSH',
files: ['build/actions/ssh.js', 'build/actions/tunnel.js'],
},
{
title: 'Notes',
files: ['build/actions/notes.js'],
},
{
title: 'OS',
files: ['build/actions/os.js'],
},
{
title: 'Config',
files: ['build/actions/config.js'],
},
{
title: 'Preload',
files: ['build/actions/preload.js'],
},
{
title: 'Push',
files: ['build/actions/push.js'],
},
{
title: 'Settings',
files: ['build/actions/settings.js'],
},
{
title: 'Local',
files: ['build/actions/local/index.js'],
},
{
title: 'Deploy',
files: ['build/actions/build.js', 'build/actions/deploy.js'],
},
{
title: 'Platform',
files: ['build/actions/join.js', 'build/actions/leave.js'],
},
{
title: 'Utilities',
files: ['build/actions/util.js'],
},
],
};
/**
* Modify and return the `capitanoDoc` object above in order to render the
* CLI documentation/reference web page at:
* https://www.balena.io/docs/reference/cli/
*
* This function parses the README.md file to extract relevant sections
* for the documentation web page.
*/
export async function getCapitanoDoc(): Promise<typeof capitanoDoc> {
const readmePath = path.join(__dirname, '..', '..', 'README.md');
const mdParser = new MarkdownFileParser(readmePath);
return Promise.all([
mdParser.getSectionOfTitle('About').then((sectionLines: string) => {
// delete the title of the 'About' section for the web page
const match = /^(#+)\s+.+?\n\s*([^]*)/.exec(sectionLines);
if (!match || match.length < 3) {
throw new Error(`Error parsing section title`);
}
// match[1] has the title, match[2] has the rest
return match && match[2];
}),
mdParser.getSectionOfTitle('Installation'),
mdParser.getSectionOfTitle('Getting Started'),
mdParser.getSectionOfTitle('Support, FAQ and troubleshooting'),
]).then((sections: string[]) => {
capitanoDoc.introduction = sections.join('\n');
return capitanoDoc;
});
}

34
automation/capitanodoc/index.ts
View File

@ -17,17 +17,23 @@
import * as _ from 'lodash'; import * as _ from 'lodash';
import * as path from 'path'; import * as path from 'path';
import capitanodoc = require('../../capitanodoc'); import { getCapitanoDoc } from './capitanodoc';
import { Category, Document } from './doc-types'; import { Category, Document } from './doc-types';
import * as markdown from './markdown'; import * as markdown from './markdown';
const result: Document = { /**
* Generates the markdown document (as a string) for the CLI documentation
* page on the web: https://www.balena.io/docs/reference/cli/
*/
export async function renderMarkdown(): Promise<string> {
const capitanodoc = await getCapitanoDoc();
const result: Document = {
title: capitanodoc.title, title: capitanodoc.title,
introduction: capitanodoc.introduction, introduction: capitanodoc.introduction,
categories: [], categories: [],
}; };
for (const commandCategory of capitanodoc.categories) { for (const commandCategory of capitanodoc.categories) {
const category: Category = { const category: Category = {
title: commandCategory.title, title: commandCategory.title,
commands: [], commands: [],
@ -48,6 +54,24 @@ for (const commandCategory of capitanodoc.categories) {
} }
result.categories.push(category); result.categories.push(category);
}
return markdown.render(result);
} }
console.log(markdown.render(result)); /**
* 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);
});
}
printMarkdown();

2
automation/capitanodoc/markdown.ts
View File

@ -66,7 +66,7 @@ function getAnchor(command: Command) {
} }
export function renderToc(categories: Category[]) { export function renderToc(categories: Category[]) {
let result = `# Table of contents\n`; let result = `# CLI Command Reference\n`;
for (const category of categories) { for (const category of categories) {
result += `\n- ${category.title}\n\n`; result += `\n- ${category.title}\n\n`;

89
automation/capitanodoc/utils.ts
View File

@ -16,7 +16,9 @@
*/ */
import { OptionDefinition } from 'capitano'; import { OptionDefinition } from 'capitano';
import * as ent from 'ent'; import * as ent from 'ent';
import * as fs from 'fs';
import * as _ from 'lodash'; import * as _ from 'lodash';
import * as readline from 'readline';
export function getOptionPrefix(signature: string) { export function getOptionPrefix(signature: string) {
if (signature.length > 1) { if (signature.length > 1) {
@ -47,3 +49,90 @@ export function parseSignature(option: OptionDefinition) {
return ent.encode(result); return ent.encode(result);
} }
export class MarkdownFileParser {
constructor(public mdFilePath: string) {}
/**
* Extract the lines of a markdown document section with the given title.
* For example, consider this sample markdown document:
* ```
* # balena CLI
*
* ## Introduction
* Lorem ipsum dolor sit amet, consectetur adipiscing elit,
*
* ## Getting Started
* sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
*
* ### Prerequisites
* - Foo
* - Bar
*
* ## Support
* Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
* ```
*
* Calling getSectionOfTitle('Getting Started') for the markdown doc above
* returns everything from line '## Getting Started' (included) to line
* '## Support' (excluded). This method counts the number of '#' characters
* to determine that subsections should be included as part of the parent
* section.
*
* @param title The section title without '#' chars, eg. 'Getting Started'
*/
public async getSectionOfTitle(
title: string,
includeSubsections = true,
): Promise<string> {
let foundSectionLines: string[];
let foundSectionLevel = 0;
const rl = readline.createInterface({
input: fs.createReadStream(this.mdFilePath),
crlfDelay: Infinity,
});
rl.on('line', line => {
// try to match a line like "## Getting Started", where the number
// of '#' characters is the sectionLevel ('##' -> 2), and the
// sectionTitle is "Getting Started"
const match = /^(#+)\s+(.+)/.exec(line);
if (match) {
const sectionLevel = match[1].length;
const sectionTitle = match[2];
// If the target section had already been found: append a line, or end it
if (foundSectionLines) {
if (!includeSubsections || sectionLevel <= foundSectionLevel) {
// end previously found section
rl.close();
}
} else if (sectionTitle === title) {
// found the target section
foundSectionLevel = sectionLevel;
foundSectionLines = [];
}
}
if (foundSectionLines) {
foundSectionLines.push(line);
}
});
return await new Promise((resolve, reject) => {
rl.on('close', () => {
if (foundSectionLines) {
resolve(foundSectionLines.join('\n'));
} else {
reject(
new Error(
`Markdown section not found: title="${title}" file="${
this.mdFilePath
}"`,
),
);
}
});
});
}
}

172
capitanodoc.ts
View File

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

157
doc/cli.markdown
View File

@ -1,85 +1,75 @@
# Balena CLI Documentation # Balena CLI Documentation
This tool allows you to interact with the balena api from the comfort of your command line. 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!
Please make sure your system meets the requirements as specified in the [README](https://github.com/balena-io/balena-cli). ## Installation
## Install the CLI Check the [balena CLI installation instructions on GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md).
### Dependencies ## Getting Started
Before installing the Balena CLI from npm, make sure you have the following dependencies installed: ### Choosing a shell (command prompt/terminal)
* make On Linux and MacOS, `bash` is the standard and recommended shell for use with the balena CLI.
* g++ compiler
* Python 2.7
* git
For example, to install these packages on a Debian-based Linux operating systems: > **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
$ sudo apt-get install g++ make python git --yes [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:
* 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.
### 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:
```sh
$ balena login
``` ```
**NOTE**: If you are installing the stand-alone binary CLI, you will not need to install these dependencies. ### Proxy support
### Npm install HTTP(S) proxies can be configured through any of the following methods, in order of preference:
The best supported way to install the CLI is from npm: * Set the \`BALENARC_PROXY\` environment variable in URL format (with protocol, host, port, and
optionally basic auth).
$ npm install balena-cli -g --production --unsafe-perm * 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:
`--unsafe-perm` is only required on systems where the global install directory is not user-writable. * a string in URL format, or
This allows npm install steps to download and save prebuilt native binaries. You may be able to omit it, * an object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control).
especially if you're using a user-managed node install such as [nvm](https://github.com/creationix/nvm). * Alternatively, set the conventional \`https_proxy\` / \`HTTPS_PROXY\` / \`http_proxy\` / \`HTTP_PROXY\`
### Standalone install
Alternatively, if you don't have a node or pre-gyp environment, you can still install the CLI as a standalone
binary. **This is in experimental and may not work perfectly yet in all environments**, but works well in
initial cross-platform testing, so it may be useful, and we'd love your feedback if you hit any issues.
To install the CLI as a standalone binary:
* Download the latest zip for your OS from https://github.com/balena-io/balena-cli/releases.
* Extract the contents, putting the `balena-cli` folder somewhere appropriate for your system (e.g. `C:/balena-cli`, `/usr/local/lib/balena-cli`, etc).
* Add the `balena-cli` folder to your `PATH`. (
[Windows instructions](https://www.computerhope.com/issues/ch000549.htm),
[Linux instructions](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix),
[OSX instructions](https://stackoverflow.com/questions/22465332/setting-path-environment-variable-in-osx-permanently))
* Running `balena` in a fresh command line should print the balena CLI help.
To update in future, simply download a new release and replace the extracted folder.
Have any problems, or see any unexpected behaviour? Please file an issue!
## Getting started
Once you have the CLI installed, you'll need to log in, so it can access everything in your balena account.
To authenticate yourself, run:
$ balena login
You now have access to all the commands referenced below.
## Proxy support
The CLI does support HTTP(S) proxies.
You can configure the proxy using several methods (in order of their precedence):
* set the `BALENARC_PROXY` environment variable in the URL format (with protocol, host, port, and optionally the basic auth),
* use the [balena config file](https://www.npmjs.com/package/balena-settings-client#documentation) (project-specific or user-level)
and set the `proxy` setting. This can be:
* a string in the URL format,
* or an object following [this format](https://www.npmjs.com/package/global-tunnel-ng#options), which allows more control,
* or set the conventional `https_proxy` / `HTTPS_PROXY` / `http_proxy` / `HTTP_PROXY`
environment variable (in the same standard URL format). environment variable (in the same standard URL format).
# Table of contents To get a proxy to work with the `balena ssh` command, check the
[installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md).
- Api keys ## Support, FAQ and troubleshooting
If you come across any problems or would like to get in touch:
* 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).
* For bug reports or feature requests,
[have a look at the GitHub issues or create a new one](https://github.com/balena-io/balena-cli/issues/).
# CLI Command Reference
- API keys
- [api-key generate &#60;name&#62;](#api-key-generate-name) - [api-key generate &#60;name&#62;](#api-key-generate-name)
@ -155,6 +145,7 @@ environment variable (in the same standard URL format).
- SSH - SSH
- [ssh [uuid]](#ssh-uuid) - [ssh [uuid]](#ssh-uuid)
- [tunnel &#60;uuid&#62;](#tunnel-uuid)
- Notes - Notes
@ -212,7 +203,7 @@ environment variable (in the same standard URL format).
- [util available-drives](#util-available-drives) - [util available-drives](#util-available-drives)
# Api keys # API keys
## api-key generate &#60;name&#62; ## api-key generate &#60;name&#62;
@ -1022,6 +1013,38 @@ don't use the proxy configuration for this connection. Only makes sense if you'v
run command non-interactively, do not automatically suggest devices to connect to if UUID not found run command non-interactively, do not automatically suggest devices to connect to if UUID not found
## tunnel &#60;uuid&#62;
Use this command to open local ports which tunnel to listening ports on your balenaOS device.
For example, you could open port 8080 on your local machine to connect to your managed balenaOS
device running a web server listening on port 3000.
You can tunnel multiple ports at any given time.
Examples:
# map remote port 22222 to localhost:22222
$ balena tunnel abcde12345 -p 22222
# map remote port 22222 to localhost:222
$ balena tunnel abcde12345 -p 22222:222
# map remote port 22222 to any address on your host machine, port 22222
$ balena tunnel abcde12345 -p 22222:0.0.0.0
# map remote port 22222 to any address on your host machine, port 222
$ balena tunnel abcde12345 -p 22222:0.0.0.0:222
# multiple port tunnels can be specified at any one time
$ balena tunnel abcde12345 -p 8080:3000 -p 8081:9000
### Options
#### --port, -p &#60;port&#62;
The mapping of remote to local ports.
# Notes # Notes
## note &#60;|note&#62; ## note &#60;|note&#62;

5
lib/utils/messages.ts
View File

@ -9,8 +9,9 @@ create a new one at: https://github.com/balena-io/balena-cli/issues/\
`; `;
const debugHint = `\ const debugHint = `\
Additional information may be available in debug mode. Prefix the command Additional information may be available by setting a DEBUG=1 environment
line with DEBUG=1, i.e.: DEBUG=1 balena ... variable: "set DEBUG=1" on a Windows command prompt, or "export DEBUG=1"
on Linux or macOS.\n
`; `;
export const getHelp = `${DEBUG_MODE ? '' : debugHint}\ export const getHelp = `${DEBUG_MODE ? '' : debugHint}\